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 <bold>required</bold> 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

All Methods Instance Methods Abstract Methods
`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`