...

How to use iPOJO annotations

iPOJO defines several annotations to help developer to define their componentsYou can use annotations to define your component types. This page presents an example of iPOJO annotation and describes provided supported annotations.

...

Getting iPOJO Annotations:

...

<dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.apache.felix.ipojo.annotations</artifactId>
      <version>1.28.0</version>
</dependency>

...

• name : defines the component type name (optional, default = the class name)
• immediate: defines the component type as immediate (optional, default = "false")
• architecture: enable the architecture exposition (optional, default = "false")
• propagation: enable configuration property propagation (on provided services) (optional, default = "false")
• managedservice : set the Managed Service PID. (optional, default = no PID (i.e. the managed service will not be exposed)).
• factory_method factoryMethod : set the factory-method. The specified method must be a static method and return a pojo object.(optional, default = iPOJO uses the 'regular' constructor).
• public_factory publicFactory : set if the component type is public. (optional, default = true).

...

• specifications: defines the provided interface (optional, default = all implemented interfaces)
• strategy : the service object creation strategy. Possible values : SINGLETON, SERVICE, METHOD, INSTANCE or the strategy class name. With SINGLETON there is only one POJO per component instance, SERVICE means OSGi Service factory, METHOD delegates the creation to the factory-method of the component, INSTANCE creates one service object per requiring instance. For other strategies, specify the qualified name of the CreationStrategy class. (optional, default = SINGLETON)

@Requires

Goal: Defines a service dependency
Target: Field
Attributes:

• Filter: defines the LDAP filter (optional)
• Optional: defines if the dependency is optional (optional, default = "false")
• Id: defines the dependency Id (useful to identify bind & unbind methods) (optional, default = field name) (if a dependency with the same id is already created (by a @bind or @unbind annotation), it merges the dependencies).
• Nullable: enable or disable the Null Object injection when the dependency is optional and no providers are available (optional, default = "true")
• Default-Implementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)
• Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
• Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
• From : defines the specific provider to use
• Specification : the required service specification. This attribute is required for Collection field. (optional, default = annotated field type).

@ServiceProperty

Goal: Defines a service property
Target: Field
Attributes:

• name: property name (optional, default=field name
• value: property value (optional, default=no value)
• mandatory : is the property mandatory? (optional, default=false)

@Property

Goal: Defines a property
Target: Field or Method
Attributes:

• name: property name (optional, default=field name computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name))
• value: property value (optional, default=no value)
• mandatory : is the property mandatory? (optional, default=false)

Wiki Markup
@Updated *\[ News in the 1.3.0-SNAPSHOT version \]*

Goal: Defines method called when a reconfiguration is completed.
Target: a method (receiving a dictionary in argument)

@Bind

• properties : array containing @StaticServiceProperties defining service properties not attached to fields.

<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>OSGi Service Factory</b>
	</div>
	</div>
	<div class="box-blue-content">
The <tt>SERVICE</tt> strategy refers to the OSGi service factory. So, one service object per asking bundle will be created.
	</div>
	<div class="box-blue-footer"></div>
</div>

<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Changes between the 1.0.0 and the 1.2.0</b>
	</div>
	</div>
	<div class="box-blue-content">
The <tt>factory</tt> attribute became <tt>strategy</tt>. A third policy is now available (<tt>instance</tt>) allowing to create one service object per asking instance. Moreover, it is also possible to indicates the <tt>CreationStrategy</tt> class name. 
	</div>
	<div class="box-blue-footer"></div>
</div>

@Requires

Goal: Defines a service dependency
Target: Field
Attributes:

• Filter: defines the LDAP filter (optional)
• Optional: defines if the dependency is optional (optional, default = "false")
• Id: defines the dependency Id (useful to identify bind & unbind methods) (optional, default = field name) (if a dependency with the same id is already created (by a @bind or @unbind annotation), it merges the dependencies).
• Nullable: enable or disable the Null Object injection when the dependency is optional and no providers are available (optional, default = "true")
• Defaultimplementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)
• Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
• Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
• From : defines the specific provider to use
• Specification : the required service specification. This attribute is required for Collection field. (optional, default = annotated field type).
• Proxy : enables / disables the proxy injection (enabled by default)

@ServiceProperty

Goal: Defines a service property
Target: Field
Attributes:

• name: property name (optional, default=field name
• value: property value (optional, default=no value)
• mandatory : is the property mandatory? (optional, default=false)

<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Mandatory property</b>
	</div>
	</div>
	<div class="box-blue-content">
A mandatory property must receive a value either from the component type description (<tt>value</tt> attribute, or the instance configuration.
	</div>
	<div class="box-blue-footer"></div>
</div>

@ServiceController

Goal: Control the service exposition
Target: Field (Boolean)
Attributes:

• value : the default value. If set to false, it disables the initial exposition
• specification : set the target of the controller, must be an exposed service interface. By default, the controller targets all services.

@Property

Goal: Defines a property
Target: Field or Method
Attributes:

• name: property name (optional, default=field name computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name))
• value: property value (optional, default=no value)
• mandatory : is the property mandatory? (optional, default=false)

<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Field and Method</b>
	</div>
	</div>
	<div class="box-blue-content">
If another property with the same name is defined the method or the field is added to the existing property.
	</div>
	<div class="box-blue-footer"></div>
</div>

@Updated

Goal: Defines method called when a reconfiguration is completed.
Target: a method (receiving a dictionary in argument)

@Bind

Goal: Defines a bind method
Target: Method
Attributes:

• Id: Dependency Id, if the id is already defines in a "@requires " or "@unbind" annotation, it adds this method as a bind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "bind" (for instance "bindFoo" will have the "Foo" id))
• Specification : required dependency (optional)
• Aggregate : is the dependency an aggregate dependency (optional, default= "false")
• Optional: is the dependency an optional dependency (optional, default= "false")
• Filter: dependency LDAP filter (optional)
• Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
• Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
• From : defines the specific provider to use

@Unbind

Goal: Defines an unbind Goal: Defines a bind method
Target: Method
Attributes:

• Id: Dependency Id, if the id is already defines in a "@requires" or "@unbind@bind" annotation, it adds this method as a bind an unbind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "bindunbind" (for instance "bindFoounbindFoo" will have the "Foo" id))
• Specification : required dependency (optional)
• Aggregate : is the dependency an aggregate dependency (optional, default= "false")
• Optional: is the dependency an optional dependency (optional, default= "false")
• Filter: dependency LDAP filter (optional)
• Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
• Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
• From : defines the specific provider to use

...

@Modified

Goal: Defines an unbind method modified method, called when a bound service is udpated.
Target: Method
Attributes:

• Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency. (optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))
• Specification : required dependency (optional)
• Aggregate : is the dependency an aggregate dependency (optional, default= "false")
• Optional: is the dependency an optional dependency (optional, default= "false")
• Filter: dependency LDAP filter (optional)
• Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority) (optional, default = "dynamic")
• Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
• From : defines the specific provider to use

...

@Validate

Goal: defines a validate lifecycle callback
Target: method

@Invalidate

Goal: defines a validate lifecycle callback
Target: method

@PostRegistration

Goal: defines a callback invoked after service registration. The callback must have the following signature : public void name(ServiceReference ref)
Target: method

@PostUnregistration

Goal: defines a validate lifecycle callbackcallback invoked after service unregistration. The callback must have the following signature : public void name(ServiceReference ref)
Target: method

...

@Instantiate

Goal: defines a validate lifecycle callback
Target: method declare a simple instance (this is equivalent to <instance component="..."></instance>
Target: class
Attribute:

• name: the instance name (optional)

Temporal Dependencies (external handler)

...

• filter : specify the dependency filter
• timeout : specify the dependency timeout (optional)
• onTimeout : specify the onTimeout action (null, nullable, empty-array, default-implementation (specify the class name in this case) (optional).
• specification : the required service specification. This attribute is required for Collection field. (optional, default = annotated field type).
• Proxy proxy : Inject a proxy instead of the real object. This allows passing this reference to collaborators. (Default = false)

...

It is possible to defines component type both in the metadata file (in XML) and by using annotation. However, if a component type defined by using annotations has the same name than a type define in the XML file, the XML descriptor override the annotation defined type. However, a warning message is launched during the manipulation.

Instance creation

The @Instantiate annotation allows creating an instance, but this declaration is limited:

• it does not support configuration
• it does not allow naming
• the instance is created in the global scope (so no composition)

Annotation can only be used to define component type. To define instances, you need to should use the XML descriptor. Instance can refer to annotated types by referring to their names.

...

External handlers can provides their own annotations. Using these annotations just requires to add them to your build path. To external handlers annotations, please refer to the external handler documentation.