Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java')
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java136
1 files changed, 108 insertions, 28 deletions
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java
index e7f072364..d44af93dc 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Component.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2011, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2011, 2015). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -28,9 +28,9 @@ import java.lang.annotation.Target;
* The annotated class is the implementation class of the Component.
*
* <p>
- * This annotation is not processed at runtime by a Service Component Runtime
- * implementation. It must be processed by tools and used to add a Component
- * Description to the bundle.
+ * This annotation is not processed at runtime by Service Component Runtime. It
+ * must be processed by tools and used to add a Component Description to the
+ * bundle.
*
* @see "The component element of a Component Description."
* @author $Id$
@@ -82,11 +82,16 @@ public @interface Component {
* component instance.
*
* <p>
- * If {@code true}, this Component uses the OSGi ServiceFactory concept. If
- * {@code false} or not specified, this Component does not use the OSGi
- * ServiceFactory concept.
+ * This element is ignored when the {@link #scope()} element does not have
+ * the default value. If {@code true}, this Component uses
+ * {@link ServiceScope#BUNDLE bundle} service scope. If {@code false} or not
+ * specified, this Component uses {@link ServiceScope#SINGLETON singleton}
+ * service scope. If the {@link #factory()} element is specified or the
+ * {@link #immediate()} element is specified with {@code true}, this element
+ * can only be specified with {@code false}.
*
- * @see "The servicefactory attribute of the service element of a Component Description."
+ * @see "The scope attribute of the service element of a Component Description."
+ * @deprecated Since 1.3. Replaced by {@link #scope()}.
*/
boolean servicefactory() default false;
@@ -95,8 +100,8 @@ public @interface Component {
* is started.
*
* <p>
- * If {@code true}, this Component is enabled. If {@code false} or not
- * specified, this Component is disabled.
+ * If {@code true} or not specified, this Component is enabled. If
+ * {@code false}, this Component is disabled.
*
* @see "The enabled attribute of the component element of a Component Description."
*/
@@ -110,13 +115,13 @@ public @interface Component {
* If {@code true}, this Component must be immediately activated upon
* becoming satisfied. If {@code false}, activation of this Component is
* delayed. If this property is specified, its value must be {@code false}
- * if the {@link #factory} property is also specified or must be
- * {@code true} if the {@link #service} property is specified with an empty
- * value.
+ * if the {@link #factory()} property is also specified or must be
+ * {@code true} if the {@link #service()} property is specified with an
+ * empty value.
*
* <p>
- * If not specified, the default is {@code false} if the {@link #factory}
- * property is specified or the {@link #service} property is not specified
+ * If not specified, the default is {@code false} if the {@link #factory()}
+ * property is specified or the {@link #service()} property is not specified
* or specified with a non-empty value and {@code true} otherwise.
*
* @see "The immediate attribute of the component element of a Component Description."
@@ -127,13 +132,14 @@ public @interface Component {
* Properties for this Component.
*
* <p>
- * Each property string is specified as {@code "key=value"}. The type of the
- * property value can be specified in the key as {@code key:type=value}. The
- * type must be one of the property types supported by the type attribute of
- * the property element of a Component Description.
+ * Each property string is specified as {@code "name=value"}. The type of
+ * the property value can be specified in the name as
+ * {@code name:type=value}. The type must be one of the property types
+ * supported by the type attribute of the property element of a Component
+ * Description.
*
* <p>
- * To specify a property with multiple values, use multiple key, value
+ * To specify a property with multiple values, use multiple name, value
* pairs. For example, {@code "foo=bar", "foo=baz"}.
*
* @see "The property element of a Component Description."
@@ -174,8 +180,18 @@ public @interface Component {
* Configuration object where the PID equals the name of the component.
*
* <p>
- * If not specified, the {@link ConfigurationPolicy#OPTIONAL OPTIONAL}
- * configuration policy is used.
+ * If not specified, the configuration policy is based upon whether the
+ * component is also annotated with the Meta Type
+ * {@link org.osgi.service.metatype.annotations.Designate Designate}
+ * annotation.
+ * <ul>
+ * <li>Not annotated with {@code Designate} - The configuration policy is
+ * {@link ConfigurationPolicy#OPTIONAL OPTIONAL}.</li>
+ * <li>Annotated with {@code Designate(factory=false)} - The configuration
+ * policy is {@link ConfigurationPolicy#OPTIONAL OPTIONAL}.</li>
+ * <li>Annotated with {@code Designate(factory=true)} - The configuration
+ * policy is {@link ConfigurationPolicy#REQUIRE REQUIRE}.</li>
+ * </ul>
*
* @see "The configuration-policy attribute of the component element of a Component Description."
* @since 1.1
@@ -183,18 +199,82 @@ public @interface Component {
ConfigurationPolicy configurationPolicy() default ConfigurationPolicy.OPTIONAL;
/**
- * The configuration PID for the configuration of this Component.
+ * The configuration PIDs for the configuration of this Component.
*
* <p>
- * Allows the configuration PID for this Component to be different than the
- * name of this Component.
+ * Each value specifies a configuration PID for this Component.
*
* <p>
- * If not specified, the name of this Component is used as the configuration
- * PID of this Component.
+ * If no value is specified, the name of this Component is used as the
+ * configuration PID of this Component.
+ *
+ * <p>
+ * A special string (<code>{@value #NAME}</code>) can be used to specify the
+ * name of the component as a configuration PID. The {@code NAME} constant
+ * holds this special string. For example:
+ *
+ * <pre>
+ * &#64;Component(configurationPid={"com.acme.system", Component.NAME})
+ * </pre>
+ *
+ * Tools creating a Component Description from this annotation must replace
+ * the special string with the actual name of this Component.
*
* @see "The configuration-pid attribute of the component element of a Component Description."
* @since 1.2
*/
- String configurationPid() default "";
+ String[] configurationPid() default NAME;
+
+ /**
+ * Special string representing the name of this Component.
+ *
+ * <p>
+ * This string can be used in {@link #configurationPid()} to specify the
+ * name of the component as a configuration PID. For example:
+ *
+ * <pre>
+ * &#64;Component(configurationPid={"com.acme.system", Component.NAME})
+ * </pre>
+ *
+ * Tools creating a Component Description from this annotation must replace
+ * the special string with the actual name of this Component.
+ *
+ * @since 1.3
+ */
+ String NAME = "$";
+
+ /**
+ * The service scope for the service of this Component.
+ *
+ * <p>
+ * If not specified (and the deprecated {@link #servicefactory()} element is
+ * not specified), the {@link ServiceScope#SINGLETON singleton} service
+ * scope is used. If the {@link #factory()} element is specified or the
+ * {@link #immediate()} element is specified with {@code true}, this element
+ * can only be specified with the {@link ServiceScope#SINGLETON singleton}
+ * service scope.
+ *
+ * @see "The scope attribute of the service element of a Component Description."
+ * @since 1.3
+ */
+ ServiceScope scope() default ServiceScope.DEFAULT;
+
+ /**
+ * The lookup strategy references of this Component.
+ *
+ * <p>
+ * To access references using the lookup strategy, {@link Reference}
+ * annotations are specified naming the reference and declaring the type of
+ * the referenced service. The referenced service can be accessed using one
+ * of the {@code locateService} methods of {@code ComponentContext}.
+ *
+ * <p>
+ * To access references using the event strategy, bind methods are annotated
+ * with {@link Reference}. To access references using the field strategy,
+ * fields are annotated with {@link Reference}.
+ *
+ * @see "The reference element of a Component Description."
+ * @since 1.3
+ */
+ Reference[] reference() default {};
}

Back to the top