org.apache.felix.ipojo.extender

Interface DeclarationBuilderService

All Known Implementing Classes:

DefaultDeclarationBuilderService

public interface DeclarationBuilderService

This service provides a way for users to manage declarations through code. Notice that produced declarations are immutable once build. But it is possible to re-use a builder to share some configuration through instances.

     // Obtain the service through the service registry
     DeclarationBuilderService service = ...

     // Get a fresh instance builder
     DeclarationBuilder builder = service.newInstance("the.full.name.of.the.component.to.instantiate");

     DeclarationHandle handle = builder.name("a-unique-name") // Make sure name is unique for the expected type
                                       .configure()
                                           .property("a-property", "a-value")
                                           .property("another-property", "another-value")
                                           .build();

     // Push the InstanceDeclaration service in the registry
     handle.publish();
 

Except the InstanceBuilder.build() call, all methods are optional:

• InstanceBuilder.name(String): if no name is provided, a default one will be generated by iPOJO.
• InstanceBuilder.version(String): if no version is provided, the first un-versioned type will be used.
• InstanceBuilder.configure(): if no configuration is required, can be omitted.
• InstanceBuilder.type(String): can be used to change the required component type.
• InstanceBuilder.context(org.osgi.framework.BundleContext): by default, the bundle context used to register the created Declaration is the one of the caller. It can be changed though this method.

Once an instance handle has been created, its configuration (name, type, version and properties) is immutable. It can only be published (so that the framework will try to instantiate the instance) or retracted (framework will remove the instance). Notice that all created instances will appear as "coming from" the bundle that requires the DeclarationBuilderService service. Just like having a metadata.xml file in your bundle that declares your instances. It is possible to override this default behavior using InstanceBuilder.context(org.osgi.framework.BundleContext).

Since:

1.11.2

See Also:

InstanceDeclaration, TypeDeclaration, ExtensionDeclaration, InstanceBuilder, ConfigurationBuilder, DeclarationHandle

Method Summary

Modifier and Type	Method and Description
DeclarationHandle	newExtension(java.lang.String name, FactoryBuilder builder) Declares a new extension (supports new types like component, composite, handler).
InstanceBuilder	newInstance(java.lang.String type) Declares a new anonymous instance of a given type.
InstanceBuilder	newInstance(java.lang.String type, java.lang.String name) Declares a new instance of a given type.
InstanceBuilder	newInstance(java.lang.String type, java.lang.String name, java.lang.String version) Declares a new instance of a given type.
DeclarationHandle	newType(org.apache.felix.ipojo.metadata.Element description) Declares a new type using the given element description.

Method Detail

newInstance

InstanceBuilder newInstance(java.lang.String type)

Declares a new anonymous instance of a given type. Invoking this method is equivalent to invoking newInstance(type, null).

Parameters:

type - name of the component to be instantiated (cannot be null).

Returns:

a handle usable to publish / retract the declaration.

See Also:

InstanceDeclaration

newInstance

InstanceBuilder newInstance(java.lang.String type,
                            java.lang.String name)

Declares a new instance of a given type. Invoking this method is equivalent to invoking newInstance(type, name, null).

Parameters:

type - name of the component to be instantiated.

name - name of the new instance (can be null)

Returns:

a handle usable to publish / retract the declaration.

See Also:

InstanceDeclaration

newInstance

InstanceBuilder newInstance(java.lang.String type,
                            java.lang.String name,
                            java.lang.String version)

Declares a new instance of a given type.

Parameters:

type - name of the component to be instantiated.

name - name of the new instance (can be null)

version - version of the expected type (can be null)

Returns:

a handle usable to publish / retract the declaration.

See Also:

InstanceDeclaration

newExtension

DeclarationHandle newExtension(java.lang.String name,
                               FactoryBuilder builder)

Declares a new extension (supports new types like component, composite, handler).

Parameters:

name - name of the type to support (no namespace to be provided)

builder - associated factory builder

Returns:

a handle usable to publish / retract the declaration.

See Also:

IPojoFactory, ExtensionDeclaration

newType

DeclarationHandle newType(org.apache.felix.ipojo.metadata.Element description)

Declares a new type using the given element description.

Parameters:

description - description of the component type

Returns:

a handle usable to publish / retract the declaration.

See Also:

TypeDeclaration