Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 97D1A200C2A for ; Tue, 14 Feb 2017 08:08:13 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 966D0160B52; Tue, 14 Feb 2017 07:08:13 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 32C9A160B5F for ; Tue, 14 Feb 2017 08:08:11 +0100 (CET) Received: (qmail 68686 invoked by uid 500); 14 Feb 2017 07:08:10 -0000 Mailing-List: contact commits-help@felix.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@felix.apache.org Delivered-To: mailing list commits@felix.apache.org Received: (qmail 68670 invoked by uid 99); 14 Feb 2017 07:08:10 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 14 Feb 2017 07:08:10 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id BA57D3A0634 for ; Tue, 14 Feb 2017 07:08:09 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1006733 [2/6] - in /websites/staging/felix/trunk/content: ./ apidocs/dependencymanager.annotations/r9/ apidocs/dependencymanager.annotations/r9/org/ apidocs/dependencymanager.annotations/r9/org/apache/ apidocs/dependencymanager.annotations... Date: Tue, 14 Feb 2017 07:08:09 -0000 To: commits@felix.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20170214070809.BA57D3A0634@svn01-us-west.apache.org> archived-at: Tue, 14 Feb 2017 07:08:13 -0000 Added: websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/AspectService.html ============================================================================== --- websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/AspectService.html (added) +++ websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/AspectService.html Tue Feb 14 07:08:08 2017 @@ -0,0 +1,548 @@ + + + + + +AspectService + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
org.apache.felix.dm.annotation.api
+

Annotation Type AspectService

+
+
+
+
    +
  • +
    +
    +
    @Retention(value=CLASS)
+ @Target(value=TYPE)
+public @interface AspectService
    +
    Annotates an Aspect service. Aspects allow you to define an interceptor, or chain of interceptors + for a service (to add features like caching or logging, etc ...). The dependency manager intercepts + the original service, and allows you to execute some code before invoking the original service ... + The aspect will be applied to any service that matches the specified interface and filter and + will be registered with the same interface and properties as the original service, plus any + extra properties you supply here. It will also inherit all dependencies, + and if you declare the original service as a member it will be injected. + +

    For "add", "change", "remove" callbacks, the following method signatures are supported: + + 

    
+ (Component comp, ServiceReference ref, Service service)
+ (Component comp, ServiceReference ref, Object service)
+ (Component comp, ServiceReference ref)
+ (Component comp, Service service)
+ (Component comp, Object service)
+ (Component comp)
+ (Component comp, Map properties, Service service)
+ (ServiceReference ref, Service service)
+ (ServiceReference ref, Object service)
+ (ServiceReference ref)
+ (Service service)
+ (Service service, Map propeerties)
+ (Map properties, Service, service)
+ (Service service, Dictionary properties)
+ (Dictionary properties, Service service)
+ (Object service)
+
    + +

    For "swap" callbacks, the following method signatures are supported: + + 

    
+ (Service old, Service replace)
+ (Object old, Object replace)
+ (ServiceReference old, Service old, ServiceReference replace, Service replace)
+ (ServiceReference old, Object old, ServiceReference replace, Object replace)
+ (Component comp, Service old, Service replace)
+ (Component comp, Object old, Object replace)
+ (Component comp, ServiceReference old, Service old, ServiceReference replace, Service replace)
+ (Component comp, ServiceReference old, Object old, ServiceReference replace, Object replace)
+ (ServiceReference old, ServiceReference replace)
+ (Component comp, ServiceReference old, ServiceReference replace)
+
    + +

    Usage Examples

    + +

    Here, the AspectService is registered into the OSGI registry each time an InterceptedService + is found from the registry. The AspectService class intercepts the InterceptedService, and decorates + its "doWork()" method. This aspect uses a rank with value "10", meaning that it will intercept some + other eventual aspects with lower ranks. The Aspect also uses a service property (param=value), and + include eventual service properties found from the InterceptedService: +

    + 
    + 
+ @AspectService(ranking=10))
+ @Property(name="param", value="value")
+ class AspectService implements InterceptedService {
+     // The service we are intercepting (injected by reflection)
+     protected InterceptedService intercepted;
+   
+     public void doWork() {
+        intercepted.doWork();
+     }
+ }
+
    +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Required Element Summary

      + + + + + + + + + + +
      Required Elements 
      Modifier and TypeRequired Element and Description
      intranking +
      Sets the ranking of this aspect.
      +
      +
      • +
    + +
      +
    • + + +

      Optional Element Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Optional Elements 
      Modifier and TypeOptional Element and Description
      java.lang.Stringadded +
      The callback method to be invoked when the original service is available.
      +
      java.lang.Stringchanged +
      The callback method to be invoked when the original service properties have changed.
      +
      java.lang.StringfactoryMethod +
      Sets the static method used to create the AspectService implementation instance.
      +
      java.lang.Stringfield +
      Sets the field name where to inject the original service.
      +
      java.lang.Stringfilter +
      Sets the filter condition to use with the service interface this aspect is applying to.
      +
      Property[]properties +
      Sets Additional properties to use with the aspect service registration
      +
      java.lang.Stringremoved +
      The callback method to invoke when the service is lost.
      +
      java.lang.Class<?>service +
      Sets the service interface to apply the aspect to.
      +
      java.lang.Stringswap +
      name of the callback method to invoke on swap.
      +
      +
      • +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Element Detail

      + + + +
        +
      • +

        ranking

        +
        public abstract int ranking
        +
        Sets the ranking of this aspect. Since aspects are chained, the ranking defines the order in which they are chained. + Chain ranking is implemented as a service ranking so service lookups automatically retrieve the top of the chain.
        +
        +
        Returns:
        +
        the aspect service rank
        +
        +
        • +
      +
      • +
    + +
      +
    • + + +
        +
      • +

        service

        +
        public abstract java.lang.Class<?> service
        +
        Sets the service interface to apply the aspect to. By default, the directly implemented interface is used.
        +
        +
        Returns:
        +
        the service aspect
        +
        +
        +
        Default:
        +
        java.lang.Object.class
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        filter

        +
        public abstract java.lang.String filter
        +
        Sets the filter condition to use with the service interface this aspect is applying to.
        +
        +
        Returns:
        +
        the service aspect filter
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        properties

        +
        public abstract Property[] properties
        +
        Sets Additional properties to use with the aspect service registration
        +
        +
        Returns:
        +
        the aspect service properties.
        +
        +
        +
        Default:
        +
        {}
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        field

        +
        public abstract java.lang.String field
        +
        Sets the field name where to inject the original service. By default, the original service is injected + in any attributes in the aspect implementation that are of the same type as the aspect interface.
        +
        +
        Returns:
        +
        the field used to inject the original service
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        added

        +
        public abstract java.lang.String added
        +
        The callback method to be invoked when the original service is available. This attribute can't be mixed with + the field attribute.
        +
        +
        Returns:
        +
        the add callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        changed

        +
        public abstract java.lang.String changed
        +
        The callback method to be invoked when the original service properties have changed. When this attribute is used, + then the added attribute must also be used.
        +
        +
        Returns:
        +
        the changed callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        removed

        +
        public abstract java.lang.String removed
        +
        The callback method to invoke when the service is lost. When this attribute is used, then the added attribute + must also be used.
        +
        +
        Returns:
        +
        the remove callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        swap

        +
        public abstract java.lang.String swap
        +
        name of the callback method to invoke on swap.
        +
        +
        Returns:
        +
        the swap callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factoryMethod

        +
        public abstract java.lang.String factoryMethod
        +
        Sets the static method used to create the AspectService implementation instance. The + default constructor of the annotated class is used. The factoryMethod can be used to provide a specific + aspect implements, like a DynamicProxy.
        +
        +
        Returns:
        +
        the aspect service factory method
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + Added: websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleAdapterService.html ============================================================================== --- websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleAdapterService.html (added) +++ websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleAdapterService.html Tue Feb 14 07:08:08 2017 @@ -0,0 +1,398 @@ + + + + + +BundleAdapterService + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
org.apache.felix.dm.annotation.api
+

Annotation Type BundleAdapterService

+
+
+
+
    +
  • +
    +
    +
    @Retention(value=CLASS)
+ @Target(value=TYPE)
+public @interface BundleAdapterService
    +
    Annotates a bundle adapter service class. Bundle adapters are similar to AdapterService, + but instead of adapting a service, they adapt a bundle with a certain set of states (STARTED|INSTALLED|...), + and provide a service on top of it.

    + The bundle adapter will be applied to any bundle that matches the specified bundle state mask and + filter conditions, which may match some of the bundle OSGi manifest headers. For each matching + bundle an adapter will be created based on the adapter implementation class. The adapter will be + registered with the specified interface and with service properties found from the original bundle + OSGi manifest headers plus any extra properties you supply here. + If you declare the original bundle as a member it will be injected. + +

    Usage Examples

    + +

    In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time + an active bundle containing a "Video-Path" manifest header is detected: + +

    + 
    + @BundleAdapterService(filter = "(Video-Path=*)", stateMask = Bundle.ACTIVE, propagate=true)
+ public class VideoPlayerImpl implements VideoPlayer {
+     Bundle bundle; // Injected by reflection
+     
+     void play() {
+         URL mpegFile = bundle.getEntry(bundle.getHeaders().get("Video-Path"));
+         // play the video provided by the bundle ...
+     }
+     
+     void stop() {}
+ }
+
    +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Required Element Summary

      + + + + + + + + + + +
      Required Elements 
      Modifier and TypeRequired Element and Description
      java.lang.Stringfilter +
      The filter used to match a given bundle.
      +
      +
      • +
    + +
      +
    • + + +

      Optional Element Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Optional Elements 
      Modifier and TypeOptional Element and Description
      java.lang.StringfactoryMethod +
      Sets the static method used to create the BundleAdapterService implementation instance.
      +
      booleanpropagate +
      Specifies if manifest headers from the bundle should be propagated to the service properties.
      +
      Property[]properties +
      Additional properties to use with the service registration
      +
      java.lang.Class<?>[]provides +
      The interface(s) to use when registering adapters.
      +
      intstateMask +
      the bundle state mask to apply
      +
      +
      • +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Element Detail

      + + + +
        +
      • +

        filter

        +
        public abstract java.lang.String filter
        +
        The filter used to match a given bundle.
        +
        +
        Returns:
        +
        the bundle adapter filter
        +
        +
        • +
      +
      • +
    + +
      +
    • + + +
        +
      • +

        provides

        +
        public abstract java.lang.Class<?>[] provides
        +
        The interface(s) to use when registering adapters. By default, the interface(s) directly implemented + by the annotated class is (are) used.
        +
        +
        Returns:
        +
        the interface(s) to use when registering adapters
        +
        +
        +
        Default:
        +
        {}
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        properties

        +
        public abstract Property[] properties
        +
        Additional properties to use with the service registration
        +
        +
        Returns:
        +
        the bundle adapter properties
        +
        +
        +
        Default:
        +
        {}
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        stateMask

        +
        public abstract int stateMask
        +
        the bundle state mask to apply
        +
        +
        Returns:
        +
        the bundle state mask to apply
        +
        +
        +
        Default:
        +
        38
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        propagate

        +
        public abstract boolean propagate
        +
        Specifies if manifest headers from the bundle should be propagated to the service properties.
        +
        +
        Returns:
        +
        the propagation flag
        +
        +
        +
        Default:
        +
        true
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factoryMethod

        +
        public abstract java.lang.String factoryMethod
        +
        Sets the static method used to create the BundleAdapterService implementation instance.
        +
        +
        Returns:
        +
        the factory method
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + Added: websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleDependency.html ============================================================================== --- websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleDependency.html (added) +++ websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/BundleDependency.html Tue Feb 14 07:08:08 2017 @@ -0,0 +1,422 @@ + + + + + +BundleDependency + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Field | 
    • +
  • Required | 
    • +
  • Optional
    • +
+ +
+ + +
+ + +
+
org.apache.felix.dm.annotation.api
+

Annotation Type BundleDependency

+
+
+
+
    +
  • +
    +
    +
    @Retention(value=CLASS)
+ @Target(value=METHOD)
+public @interface BundleDependency
    +
    Annotates a class or method for a bundle dependency. A bundle dependency allows you to + depend on a bundle in a certain set of states (INSTALLED|RESOLVED|STARTED|...), as + indicated by a state mask. You can also use a filter condition that is matched against + all manifest entries. When applied on a class field, optional unavailable dependencies + are injected with a NullObject. + +

    Usage Examples

    + +

    In the following example, the "SCR" Component allows to track + all bundles containing a specific "Service-Component" OSGi header, in order to load + and manage all Declarative Service components specified in the SCR xml documents referenced by the header: + +

    + 
    + @Component
+ public class SCR {
+     @BundleDependency(required = false,
+                       removed = "unloadServiceComponents", 
+                       filter = "(Service-Component=*)"
+                       stateMask = Bundle.ACTIVE)
+     void loadServiceComponents(Bundle b) {
+         String descriptorPaths = (String) b.getHeaders().get("Service-Component");
+         // load all service component specified in the XML descriptorPaths files ...
+     }
+
+     void unloadServiceComponents(Bundle b) {
+         // unload all service component we loaded from our "loadServiceComponents" method.
+     }
+ }
+
    +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Optional Element Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Optional Elements 
      Modifier and TypeOptional Element and Description
      java.lang.Stringchanged +
      Returns the callback method to be invoked when the service have changed.
      +
      java.lang.Stringfilter +
      Returns the filter dependency
      +
      java.lang.Stringname +
      The name used when dynamically configuring this dependency from the init method.
      +
      booleanpropagate +
      Specifies if the manifest headers from the bundle should be propagated to + the service properties.
      +
      java.lang.Stringremoved +
      Returns the callback method to invoke when the service is lost.
      +
      booleanrequired +
      Returns whether the dependency is required or not.
      +
      intstateMask +
      Returns the bundle state mask
      +
      +
      • +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Element Detail

      + + + +
        +
      • +

        changed

        +
        public abstract java.lang.String changed
        +
        Returns the callback method to be invoked when the service have changed.
        +
        +
        Returns:
        +
        the change callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        removed

        +
        public abstract java.lang.String removed
        +
        Returns the callback method to invoke when the service is lost.
        +
        +
        Returns:
        +
        the remove callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        required

        +
        public abstract boolean required
        +
        Returns whether the dependency is required or not.
        +
        +
        Returns:
        +
        the required flag
        +
        +
        +
        Default:
        +
        true
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        filter

        +
        public abstract java.lang.String filter
        +
        Returns the filter dependency
        +
        +
        Returns:
        +
        the filter
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        stateMask

        +
        public abstract int stateMask
        +
        Returns the bundle state mask
        +
        +
        Returns:
        +
        the state mask
        +
        +
        +
        Default:
        +
        38
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        propagate

        +
        public abstract boolean propagate
        +
        Specifies if the manifest headers from the bundle should be propagated to + the service properties.
        +
        +
        Returns:
        +
        the propagation flag
        +
        +
        +
        Default:
        +
        false
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        name

        +
        public abstract java.lang.String name
        +
        The name used when dynamically configuring this dependency from the init method. + Specifying this attribute allows to dynamically configure the dependency + filter and required flag from the Service's init method. + All unnamed dependencies will be injected before the init() method; so from the init() method, you can + then pick up whatever information needed from already injected (unnamed) dependencies, and configure dynamically + your named dependencies, which will then be calculated once the init() method returns. + +

        See Init annotation for an example usage of a dependency dynamically configured from the init method.

        +
        +
        Returns:
        +
        the dependency name used to dynamically configure the dependency from the init callback
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Field | 
    • +
  • Required | 
    • +
  • Optional
    • +
+ +
+ + +
+ + + Added: websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Component.html ============================================================================== --- websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Component.html (added) +++ websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Component.html Tue Feb 14 07:08:08 2017 @@ -0,0 +1,570 @@ + + + + + +Component + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + +
+
org.apache.felix.dm.annotation.api
+

Annotation Type Component

+
+
+
+
    +
  • +
    +
    +
    @Retention(value=CLASS)
+ @Target(value=TYPE)
+public @interface Component
    +
    Annotates an OSGi Component class with its dependencies. Components are the main building + blocks for OSGi applications. They can publish themselves as a service, and/or they can have + dependencies. These dependencies will influence their life cycle as component will only be + activated when all required dependencies are available. + By default, all directly implemented interfaces are registered into the OSGi registry, + and the component is instantiated automatically, when the component bundle is started and + when the component dependencies are available. If you need to take control of when and how + much component instances must be created, then you can use the factoryName + annotation attribute.

    + If a factoryName attribute is set, the component is not started automatically + during bundle startup, and a org.apache.felix.dm.runtime.api.ComponentFactory + object is registered into the OSGi registry on behalf of the component. This ComponentFactory + can then be used by another component in order to instantiate multiple instances of the component + (DM ComponentFactory are really similar to DS ComponentFactory). + +

    Usage Examples

    + + Here is a sample showing a X component, which depends on a configuration dependency: +
    + + 
    + /**
+   * This component will be activated once the bundle is started and when all required dependencies
+   * are available.
+   */
+ @Component
+ class X implements Z {
+     @ConfigurationDependency(pid="MyPid")
+     void configure(Dictionary conf) {
+          // Configure or reconfigure our component.
+     }
+   
+     @Start
+     void start() {
+         // Our component is starting and is about to be registered in the OSGi registry as a Z service.
+     }
+   
+     public void doService() {
+         // ...
+     }   
+ }
+
    +
    + + Here is a sample showing how a Y component may dynamically instantiate several X component instances, + using the factoryName() attribute: +
    + + 
    +  /**
+    * All component instances will be created/updated/removed by the "Y" component
+    */
+  @Component(factoryName="MyComponentFactory", factoryConfigure="configure")
+  class X implements Z {                 
+      void configure(Dictionary conf) {
+          // Configure or reconfigure our component. The conf is provided by the factory,
+          // and all public properties (which don't start with a dot) are propagated with the
+          // service properties specified in the properties annotation attribute.
+      }
+ 
+      @ServiceDependency
+      void bindOtherService(OtherService other) {
+          // store this require dependency
+      }
+      
+      @Start
+      void start() {
+          // Our component is starting and is about to be registered in the OSGi registry as a Z service.
+      } 
+      
+      public void doService() {
+          // ...
+      }   
+  }
+ 
+  import import org.apache.felix.dm.runtime.api.ComponentFactory;
+
+  /**
+    * This class will instantiate some X component instances
+    */
+  @Component 
+  class Y {
+      @ServiceDependency(filter="(" + Component.FACTORY_NAME + "=MyComponentFactory)")
+      ComponentFactory _XFactory;
+    
+      @Start
+      void start() {
+          // Instantiate a X component instance
+          Dictionary instance1Conf = new Hashtable() {{ put("foo", "bar1"); }};
+          ComponentInstance instance1 = _XFactory.newInstance(instance1Conf);
+      
+          // Instantiate another X component instance
+          Dictionary instance2Conf = new Hashtable() {{ put("foo2", "bar2"); }};
+          ComponentInstance instance2 = _XFactory.newInstance(instance2Conf);
+      
+          // Update the first X component instance
+          instance1Conf = new Hashtable() {{ put("foo", "bar1 modified"); }};
+          instance1.update(instance1Conf);
+          
+          // Instantiate a third X instance, by explicitly providing the implementation object
+          Dictionary instance3Conf = new Hashtable() {{ put(Component.FACTORY_INSTANCE, new X()); }};
+          ComponentInstance instance3 = _XFactory.newInstance(instance3Conf);
+      
+          // Destroy x1/x2/x3 components
+          instance1.dispose();
+          instance2.dispose();
+          instance3.dispose();
+      }
+  }
+
    + +
    +
    • +
+
+
+
    +
  • + +
      +
    • + + +

      Field Summary

      + + + + + + + + + + + + + + +
      Fields 
      Modifier and TypeFields and Description
      static java.lang.StringFACTORY_INSTANCE +
      Key used when providing an implementation when using a Component Factory .
      +
      static java.lang.StringFACTORY_NAME +
      Service property name used to match a given Component Factory.
      +
      +
      • +
    + +
      +
    • + + +

      Optional Element Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Optional Elements 
      Modifier and TypeOptional Element and Description
      java.lang.StringfactoryConfigure +
      Sets "configure" callback method name to be called with the factory configuration.
      +
      java.lang.StringfactoryMethod +
      Sets the static method used to create the components implementation instance.
      +
      java.lang.StringfactoryName +
      Returns the name of the ComponentFactory used to dynamically instantiate this component.
      +
      java.lang.StringfactorySet +
      Deprecated.  +
      use factoryName() instead of a factorySet.
      +
      +
      Property[]properties +
      Sets list of provided service properties.
      +
      java.lang.Class<?>[]provides +
      Sets list of provided interfaces.
      +
      +
      • +
    +
    • +
+
+
+
    +
  • + + +
      +
    • + + +
        +
      • +

        FACTORY_INSTANCE

        +
        public static final java.lang.String FACTORY_INSTANCE
        +
        Key used when providing an implementation when using a Component Factory .
        +
        +
        See Also:
        +
        factoryName()
        +
        +
        • +
      +
      • +
    + +
      +
    • + + +

      Element Detail

      + + + +
        +
      • +

        provides

        +
        public abstract java.lang.Class<?>[] provides
        +
        Sets list of provided interfaces. By default, the directly implemented interfaces are provided.
        +
        +
        Returns:
        +
        the provided interfaces
        +
        +
        +
        Default:
        +
        {}
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        properties

        +
        public abstract Property[] properties
        +
        Sets list of provided service properties. Since R7 version, Property annotation is repeatable and you can directly + apply it on top of the component class multiple times, instead of using the Component properties attribute.
        +
        +
        Returns:
        +
        the component properties.
        +
        +
        +
        Default:
        +
        {}
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factorySet

        +
        public abstract java.lang.String factorySet
        +
        Deprecated. use factoryName() instead of a factorySet.
        +
        Returns the name of the Factory Set used to dynamically instantiate this component. + When you set this attribute, a java.util.Set<java.lang.Dictionary> OSGi Service will + be provided with a dm.factory.name service property matching your specified factorySet attribute. + This Set will be provided once the component bundle is started, even if required dependencies are not available, and the + Set will be unregistered from the OSGi registry once the component bundle is stopped or being updated.

        + So, basically, another component may then be injected with this set in order to dynamically instantiate some component instances: +

          +
        • Each time a new Dictionary is added into the Set, then a new instance of the annotated component will be instantiated.
          • +
        • Each time an existing Dictionary is re-added into the Set, then the corresponding component instance will be updated.
          • +
        • Each time an existing Dictionary is removed from the Set, then the corresponding component instance will be destroyed.
          • +
        + +

        The dictionary registered in the Set will be provided to the created component instance using a callback method that you can + optionally specify in the factoryConfigure() attribute. Each public properties from that dictionary + (which don't start with a dot) will be propagated along with the annotated component service properties. + +

        Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created, + using the "dm.factory.instance" key.

        +
        +
        Returns:
        +
        the factory set name
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factoryName

        +
        public abstract java.lang.String factoryName
        +
        Returns the name of the ComponentFactory used to dynamically instantiate this component. + When you set this attribute, a org.apache.felix.dm.runtime.api.ComponentFactory OSGi Service will + be provided with a dm.factory.name service property matching your specified factoryName attribute. + + The ComponentFactory will be provided once the component bundle is started, even if required dependencies are not available, and the + ComponentFactory will be unregistered from the OSGi registry once the component bundle is stopped or being updated.

        + So, another component may then be injected with this ComponentFactory in order to dynamically instantiate some component instances: + +

        The dictionary passed to the ComponentFactory.newInstance method will be provided to the created component instance using a callback + method that you can optionally specify in the factoryConfigure() attribute. Each public properties from that dictionary + (which don't start with a dot) will be propagated along with the annotated component service properties. + +

        Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created, + using a "dm.runtime.factory.instance" key.

        +
        +
        Returns:
        +
        the factory name
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factoryConfigure

        +
        public abstract java.lang.String factoryConfigure
        +
        Sets "configure" callback method name to be called with the factory configuration. This attribute only makes sense if the + factoryName() attribute is used. If specified, then this attribute references a callback method, which is called + for providing the configuration supplied by the factory that instantiated this component. The current component service properties will be + also updated with all public properties (which don't start with a dot).
        +
        +
        Returns:
        +
        the factory configure callback name
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
      +
    • + + +
        +
      • +

        factoryMethod

        +
        public abstract java.lang.String factoryMethod
        +
        Sets the static method used to create the components implementation instance.
        +
        +
        Returns:
        +
        the factory method used to instantiate the component
        +
        +
        +
        Default:
        +
        ""
        +
        +
        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+ + +
+ + +
+ + + Added: websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Composition.html ============================================================================== --- websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Composition.html (added) +++ websites/staging/felix/trunk/content/apidocs/dependencymanager.annotations/r9/org/apache/felix/dm/annotation/api/Composition.html Tue Feb 14 07:08:08 2017 @@ -0,0 +1,208 @@ + + + + + +Composition + + + + + + + + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Field | 
    • +
  • Required | 
    • +
  • Optional
    • +
+
    +
  • Detail: 
    • +
  • Field | 
    • +
  • Element
    • +
+
+ + +
+ + +
+
org.apache.felix.dm.annotation.api
+

Annotation Type Composition

+
+
+
+
    +
  • +
    +
    +
    @Retention(value=CLASS)
+ @Target(value=METHOD)
+public @interface Composition
    +
    Annotates a method returning the list of objects which are part of a Component implementation. + When implementing complex Components, you often need to use more than one object instances. + Moreover, several of these instances might want to have dependencies injected, as well as lifecycle + callbacks invoked, like the methods annotated with Init, Start, Stop, + Destroy annotations. In such cases you can tell the dependency manager which instances to + consider, by annotating a method in your Component, returning a list of objects which are part + of the implementation. +

    + This annotation may be applied on a method which is part of class annotated with either a Component, + AspectService, AdapterService, FactoryConfigurationAdapterService or + ResourceAdapterService annotation. + +

    Usage Examples

    + +

    Here, the "MyComponent" component is composed of the Helper class, which is also injected with + service dependencies. The lifecycle callbacks are also invoked in the Helper (if the Helper defines + them): +

    + 
    +
+ class Helper {
+     LogService logService; // Injected
+     void start() {} // lifecycle callback
+     void bind(OtherService otherService) {} // injected
+ }
+ 
+ @Component
+ class MyComponent {
+     // Helper which will also be injected with our service dependencies
+     private Helper helper = new Helper();
+      
+     @Composition
+     Object[] getComposition() {
+         return new Object[] { this, helper }; 
+     }
+
+     @ServiceDependency
+     private LogService logService; // Helper.logService will be also be injected, if defined.
+     
+     @Start
+     void start() {} // the Helper.start() method will also be called, if defined
+     
+     @ServiceDependency
+     void bind(OtherService otherService) {} // the Helper.bind() method will also be called, if defined     
+ }
+
    +
    +
    • +
+
+
+ + +
+ + +
Skip navigation links
+ + + + +
+
+ + + +
+ +
+
+
    +
  • Summary: 
    • +
  • Field | 
    • +
  • Required | 
    • +
  • Optional
    • +
+
    +
  • Detail: 
    • +
  • Field | 
    • +
  • Element
    • +
+
+ + +
+ + +