# HG changeset patch
# User Omair Majid <omajid@redhat.com>
# Date 1385423990 18000
# Node ID bfe13519288079e3bf07982178d13318cf469cee
# Parent  de7fe0a6a382251c628dee24dc10029968e9c714
Consumers should not implement a Service
Reviewed-by: neugens, vanaltj
Review-thread: http://icedtea.classpath.org/pipermail/thermostat/2013-November/008830.html

diff -r de7fe0a6a382 -r bfe135192880 annotations/src/main/java/com/redhat/thermostat/annotations/ExtensionPoint.java
--- a/annotations/src/main/java/com/redhat/thermostat/annotations/ExtensionPoint.java	Mon Nov 25 15:44:21 2013 -0500
+++ b/annotations/src/main/java/com/redhat/thermostat/annotations/ExtensionPoint.java	Mon Nov 25 18:59:50 2013 -0500
@@ -49,6 +49,8 @@
  * {@link BundleContext#registerService}.
  * <p>
  * This is the whiteboard pattern.
+ *
+ * @see Service
  */
 @Documented
 @Retention(RetentionPolicy.SOURCE)
diff -r de7fe0a6a382 -r bfe135192880 annotations/src/main/java/com/redhat/thermostat/annotations/Service.java
--- a/annotations/src/main/java/com/redhat/thermostat/annotations/Service.java	Mon Nov 25 15:44:21 2013 -0500
+++ b/annotations/src/main/java/com/redhat/thermostat/annotations/Service.java	Mon Nov 25 18:59:50 2013 -0500
@@ -48,8 +48,19 @@
  * {@link BundleContext#getService(ServiceReference)} or
  * {@link OSGIUtils#getService(Class)}.
  * <p>
+ * The annotation is meant for service providers that wish to export a new
+ * service via OSGi and not consumers, hence consumers must not mark their
+ * classes or interfaces as {@code @Service}, nor directly extend the classes or
+ * implement the interfaces marked as @Service. Only the bundle(s) that
+ * publishes the service interface/class should do that.
+ * <p>
+ * Consumers wanting to extend functionality should make use of
+ * {@code @ExtensionPoint}s instead.
+ * <p>
  * This does not infer any behaviour on a class; this is for documentation
  * purposes only.
+ *
+ * @see ExtensionPoint
  */
 @Documented
 @Retention(RetentionPolicy.SOURCE)