org.apache.felix.ipojo

## Class IPojoFactory

- java.lang.Object
- - org.apache.felix.ipojo.IPojoFactory

All Implemented Interfaces:
  Factory

Direct Known Subclasses:
  ComponentFactory

    public abstract class IPojoFactory
    extends java.lang.Object
    implements Factory

This class defines common mechanisms of iPOJO component factories (i.e. component type). The factory is also tracking Factory configuration from the configuration admin to created / delete and update instances from this factory.

Author:
  Felix Project Team

### Nested Class Summary

Nested Classes
`static class` `IPojoFactory.DefaultNameGenerator` This generator implements the default naming strategy.
`static interface` `IPojoFactory.NameGenerator` Generate a unique name for a component instance.
`protected class` `IPojoFactory.RequiredHandler` Structure storing required handlers.
`static class` `IPojoFactory.RetryNameGenerator` This generator implements a retry naming strategy.

### Field Summary

Fields
`protected static java.util.List<java.lang.String>` `INSTANCE_NAME` The list of the managed instance name.
`protected ComponentTypeDescription` `m_componentDesc` The component type description exposed by the `Factory` service.
`protected java.util.Map<java.lang.String,ComponentInstance>` `m_componentInstances` The list of the managed instance managers.
`protected org.apache.felix.ipojo.metadata.Element` `m_componentMetadata` The component type metadata.
`protected org.osgi.framework.BundleContext` `m_context` The bundle context reference.
`protected java.lang.String` `m_factoryName` The factory name.
`protected boolean` `m_isPublic` Is the factory public (exposed as services).
`protected java.util.List<FactoryStateListener>` `m_listeners` The list of factory state listeners.
`protected Logger` `m_logger` The logger for the factory.
`protected java.util.List<IPojoFactory.RequiredHandler>` `m_requiredHandlers` The list of required handlers.
`protected org.osgi.framework.ServiceRegistration` `m_sr` The service registration of this factory (Factory & ManagedServiceFactory).
`protected int` `m_state` The factory state.
`protected java.lang.String` `m_version` The version of the component type.

### Fields inherited from interface org.apache.felix.ipojo.Factory

`FACTORY_VERSION_PROPERTY, INSTANCE_NAME_PROPERTY, INVALID, VALID`

### Constructor Summary

Constructors
Constructor and Description
`IPojoFactory(org.osgi.framework.BundleContext context, org.apache.felix.ipojo.metadata.Element metadata)` Creates an iPOJO Factory.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `addFactoryStateListener(FactoryStateListener listener)` Adds a factory listener.
`void` `checkAcceptability(java.util.Dictionary<java.lang.String,?> conf)` Checks if the configuration is acceptable.
`protected void` `computeDescription()` Computes the component type description.
`protected void` `computeFactoryState()` Computes factory state.
`ComponentInstance` `createComponentInstance(java.util.Dictionary configuration)` Creates an instance.
`ComponentInstance` `createComponentInstance(java.util.Dictionary configuration, ServiceContext serviceContext)` Creates an instance in the specified service context.
`abstract ComponentInstance` `createInstance(java.util.Dictionary config, IPojoContext context, HandlerManager[] handlers)` Creates an instance.
`void` `deleted(java.lang.String name)` Deletes an instance.
`void` `dispose()` Destroys the factory.
`void` `disposed(ComponentInstance instance)` Callback called by instance when disposed.
`org.osgi.framework.BundleContext` `getBundleContext()` Gets the bundle context of the factory.
`abstract java.lang.String` `getClassName()` Gets the factory class name.
`ComponentTypeDescription` `getComponentDescription()` Gets the component type description.
`org.apache.felix.ipojo.metadata.Element` `getComponentMetadata()` Gets the component metadata.
`ComponentTypeDescription` `getComponentTypeDescription()` Gets the component type description.
`org.apache.felix.ipojo.metadata.Element` `getDescription()` Gets the component type description (Element-Attribute form).
`abstract java.lang.String` `getFactoryName()` Computes the factory name.
`protected HandlerManager` `getHandler(IPojoFactory.RequiredHandler req, ServiceContext context)` Returns the handler object for the given required handler.
`ComponentInstance` `getInstanceByName(java.lang.String name)` Gets a component instance created by the current factory.
`java.util.List<ComponentInstance>` `getInstances()` Gets the list of instances created by the factory.
`java.util.List<java.lang.String>` `getInstancesNames()` Gets the list of the names of the instances created by the factory.
`protected org.osgi.framework.BundleContext` `getIPOJOBundleContext()` Gets the iPOJO Bundle Context.
`Logger` `getLogger()` Gets the logger used by instances created by the current factory.
`java.util.List<java.lang.String>` `getMissingHandlers()` Computes the list of missing handlers.
`java.lang.String` `getName()` Gets the factory name.
`abstract java.util.List<IPojoFactory.RequiredHandler>` `getRequiredHandlerList()` Computes the required handler list.
`java.util.List<java.lang.String>` `getRequiredHandlers()` Gets the list of required handlers.
`int` `getState()` Gets the actual factory state.
`boolean` `isAcceptable(java.util.Dictionary conf)` Checks if the configuration is acceptable.
`protected boolean` `match(IPojoFactory.RequiredHandler req, org.osgi.framework.ServiceReference<?> ref)` Checks if the given handler identifier and the service reference match.
`void` `reconfigure(java.util.Dictionary properties)` Reconfigures an existing instance.
`void` `removeFactoryStateListener(FactoryStateListener listener)` Removes a factory listener.
`void` `restart()` For testing purpose ONLY.
`void` `start()` Starts the factory.
`abstract void` `starting()` Starting method.
`void` `stop()` Stops all the instance managers.
`abstract void` `stopping()` Stopping method.
`void` `updated(java.lang.String name, java.util.Dictionary properties)` Creates or updates an instance.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.apache.felix.ipojo.Factory

`getVersion`

### Field Detail

#### INSTANCE_NAME

    protected static final java.util.List<java.lang.String> INSTANCE_NAME

The list of the managed instance name. This list is shared by all factories and is used to assert name uniqueness.

#### m_componentDesc

    protected ComponentTypeDescription m_componentDesc

The component type description exposed by the `Factory` service.

#### m_componentInstances

    protected final java.util.Map<java.lang.String,ComponentInstance> m_componentInstances

The list of the managed instance managers. The key of this map is the name (i.e. instance names) of the created instance

#### m_componentMetadata

    protected final org.apache.felix.ipojo.metadata.Element m_componentMetadata

The component type metadata.

#### m_context

    protected final org.osgi.framework.BundleContext m_context

The bundle context reference.

#### m_factoryName

    protected java.lang.String m_factoryName

The factory name. Could be the component class name if the factory name is not set. Immutable once set.

#### m_requiredHandlers

    protected final java.util.List<IPojoFactory.RequiredHandler> m_requiredHandlers

The list of required handlers.

#### m_listeners

    protected java.util.List<FactoryStateListener> m_listeners

The list of factory state listeners.

See Also:
  `FactoryStateListener`

#### m_logger

    protected final Logger m_logger

The logger for the factory.

#### m_isPublic

    protected final boolean m_isPublic

Is the factory public (exposed as services).

#### m_version

    protected final java.lang.String m_version

The version of the component type.

#### m_sr

    protected org.osgi.framework.ServiceRegistration m_sr

The service registration of this factory (Factory & ManagedServiceFactory).

See Also:
  `ManagedServiceFactory`, `Factory`

#### m_state

    protected int m_state

The factory state. Can be:
`Factory.INVALID`
`Factory.VALID`
The factory is invalid at the beginning. A factory becomes valid if every required handlers are available (i.e. can be created).

### Constructor Detail

#### IPojoFactory

    public IPojoFactory(org.osgi.framework.BundleContext context,
                        org.apache.felix.ipojo.metadata.Element metadata)
                 throws ConfigurationException

Creates an iPOJO Factory. At the end of this method, the required set of handler is computed. But the result is computed by a sub-class.

Parameters:
  `context` - the bundle context of the bundle containing the factory.
  `metadata` - the description of the component type.
Throws:
  `ConfigurationException` - if the element describing the factory is malformed.

### Method Detail

#### getComponentTypeDescription

    public ComponentTypeDescription getComponentTypeDescription()

Gets the component type description.

Returns:
  the component type description

#### addFactoryStateListener

    public void addFactoryStateListener(FactoryStateListener listener)

Adds a factory listener.

Specified by:
  `addFactoryStateListener` in interface `Factory`
Parameters:
  `listener` - the factory listener to add.
See Also:
  `Factory.addFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)`

#### getLogger

    public Logger getLogger()

Gets the logger used by instances created by the current factory.

Returns:
  the factory logger.

#### getFactoryName

    public abstract java.lang.String getFactoryName()

Computes the factory name. Each sub-type must override this method.

Returns:
  the factory name.

#### getRequiredHandlerList

    public abstract java.util.List<IPojoFactory.RequiredHandler> getRequiredHandlerList()
                                                                                 throws ConfigurationException

Computes the required handler list. Each sub-type must override this method.

Returns:
  the required handler list
Throws:
  `ConfigurationException` - when the list of handler cannot be computed.

#### createInstance

    public abstract ComponentInstance createInstance(java.util.Dictionary config,
                                                     IPojoContext context,
                                                     HandlerManager[] handlers)
                                              throws ConfigurationException

Creates an instance. This method is called with the monitor lock.

Parameters:
  `config` - the instance configuration
  `context` - the iPOJO context to use
  `handlers` - the handler array to use
Returns:
  the new component instance.
Throws:
  `ConfigurationException` - if the instance creation failed during the configuration process.

#### createComponentInstance

    public ComponentInstance createComponentInstance(java.util.Dictionary configuration)
                                              throws UnacceptableConfiguration,
                                                     MissingHandlerException,
                                                     ConfigurationException

Creates an instance. This method creates the instance in the global context.

Specified by:
  `createComponentInstance` in interface `Factory`
Parameters:
  `configuration` - the configuration of the created instance.
Returns:
  the created component instance.
Throws:
  `UnacceptableConfiguration` - if the given configuration is not consistent with the component type of this factory.
  `MissingHandlerException` - if an handler is unavailable when the instance is created.
  `ConfigurationException` - if the instance or type configuration are not correct.
See Also:
  `Factory.createComponentInstance(java.util.Dictionary)`

#### createComponentInstance

    public ComponentInstance createComponentInstance(java.util.Dictionary configuration,
                                                     ServiceContext serviceContext)
                                              throws UnacceptableConfiguration,
                                                     MissingHandlerException,
                                                     ConfigurationException

Creates an instance in the specified service context. This method is synchronized to assert the validity of the factory during the creation. Callbacks to sub-class and created instances need to be aware that they are holding the monitor lock. This method call the override `createInstance(Dictionary, IPojoContext, HandlerManager[])` method.

Specified by:
  `createComponentInstance` in interface `Factory`
Parameters:
  `configuration` - the configuration of the created instance.
  `serviceContext` - the service context to push for this instance.
Returns:
  the created component instance.
Throws:
  `UnacceptableConfiguration` - if the given configuration is not consistent with the component type of this factory.
  `MissingHandlerException` - if an handler is unavailable when creating the instance.
  `ConfigurationException` - if the instance configuration failed.
See Also:
  `Factory.createComponentInstance(java.util.Dictionary)`

#### getBundleContext

    public org.osgi.framework.BundleContext getBundleContext()

Gets the bundle context of the factory.

Specified by:
  `getBundleContext` in interface `Factory`
Returns:
  the bundle context of the factory.
See Also:
  `Factory.getBundleContext()`

#### getClassName

    public abstract java.lang.String getClassName()

Gets the factory class name.

Specified by:
  `getClassName` in interface `Factory`
Returns:
  the factory class name.
See Also:
  `Factory.getClassName()`

#### getComponentDescription

    public ComponentTypeDescription getComponentDescription()

Gets the component type description.

Specified by:
  `getComponentDescription` in interface `Factory`
Returns:
  the component type description object. `Null` if not already computed.

#### getDescription

    public org.apache.felix.ipojo.metadata.Element getDescription()

Gets the component type description (Element-Attribute form).

Specified by:
  `getDescription` in interface `Factory`
Returns:
  the component type description.
See Also:
  `Factory.getDescription()`

#### getComponentMetadata

    public org.apache.felix.ipojo.metadata.Element getComponentMetadata()

Gets the component metadata.

Specified by:
  `getComponentMetadata` in interface `Factory`
Returns:
  the component metadata
See Also:
  `Factory.getComponentMetadata()`

#### getInstances

    public java.util.List<ComponentInstance> getInstances()

Gets the list of instances created by the factory. The instances must be still alive.

Specified by:
  `getInstances` in interface `Factory`
Returns:
  the list of created (and living) instances
Since:
  1.11.0

#### getInstancesNames

    public java.util.List<java.lang.String> getInstancesNames()

Gets the list of the names of the instances created by the factory. The instances must be still alive.

Specified by:
  `getInstancesNames` in interface `Factory`
Returns:
  the list of the names of created (and living) instances
Since:
  1.11.0

#### getMissingHandlers

    public java.util.List<java.lang.String> getMissingHandlers()

Computes the list of missing handlers.

Specified by:
  `getMissingHandlers` in interface `Factory`
Returns:
  the list of missing handlers.
See Also:
  `Factory.getMissingHandlers()`

#### getName

    public java.lang.String getName()

Gets the factory name. This name is immutable once set.

Specified by:
  `getName` in interface `Factory`
Returns:
  the factory name.
See Also:
  `Factory.getName()`

#### getRequiredHandlers

    public java.util.List<java.lang.String> getRequiredHandlers()

Gets the list of required handlers. The required handler list cannot change.

Specified by:
  `getRequiredHandlers` in interface `Factory`
Returns:
  the list of required handlers.
See Also:
  `Factory.getRequiredHandlers()`

#### getState

    public int getState()

Gets the actual factory state. Must be synchronized as this state is dependent of handler availability.

Specified by:
  `getState` in interface `Factory`
Returns:
  the actual factory state.
See Also:
  `Factory.getState()`

#### getInstanceByName

    public ComponentInstance getInstanceByName(java.lang.String name)

Gets a component instance created by the current factory.

Parameters:
  `name` - the instance name
Returns:
  the component instance, null if not found

#### isAcceptable

    public boolean isAcceptable(java.util.Dictionary conf)

Checks if the configuration is acceptable.

Specified by:
  `isAcceptable` in interface `Factory`
Parameters:
  `conf` - the configuration to test.
Returns:
  `true` if the configuration is acceptable.
See Also:
  `Factory.isAcceptable(java.util.Dictionary)`

#### checkAcceptability

    public void checkAcceptability(java.util.Dictionary<java.lang.String,?> conf)
                            throws UnacceptableConfiguration,
                                   MissingHandlerException

Checks if the configuration is acceptable. This method checks the following assertions:
All handlers can be creates
The configuration does not override immutable properties
The configuration contains a value for every unvalued property

Parameters:
  `conf` - the configuration to test.
Throws:
  `UnacceptableConfiguration` - if the configuration is unacceptable.
  `MissingHandlerException` - if an handler is missing.

#### reconfigure

    public void reconfigure(java.util.Dictionary properties)
                     throws UnacceptableConfiguration,
                            MissingHandlerException

Reconfigures an existing instance. The acceptability of the configuration is checked before the reconfiguration. Moreover, the configuration must contain the 'instance.name' property specifying the instance to reconfigure. This method is synchronized to assert the validity of the factory during the reconfiguration.

Specified by:
  `reconfigure` in interface `Factory`
Parameters:
  `properties` - the new configuration to push.
Throws:
  `UnacceptableConfiguration` - if the new configuration is not consistent with the component type.
  `MissingHandlerException` - if the current factory is not valid.
See Also:
  `Factory.reconfigure(java.util.Dictionary)`

#### removeFactoryStateListener

    public void removeFactoryStateListener(FactoryStateListener listener)

Removes a factory listener.

Specified by:
  `removeFactoryStateListener` in interface `Factory`
Parameters:
  `listener` - the factory listener to remove.
See Also:
  `Factory.removeFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)`

#### stopping

    public abstract void stopping()

Stopping method. This method is call when the factory is stopping. This method is called when holding the lock on the factory.

#### stop

    public void stop()

Stops all the instance managers. This method calls the `stopping()` method, notifies listeners, and disposes created instances. Moreover, if the factory is public, services are also unregistered.

#### dispose

    public void dispose()

Destroys the factory. The factory cannot be restarted. Only the `Extender` can call this method.

#### starting

    public abstract void starting()

Starting method. This method is called when the factory is starting. This method is not called when holding the lock on the factory.

#### start

    public void start()

Starts the factory. Tries to compute the component type description, calls the `starting()` method, and published services if the factory is public.

#### restart

    public void restart()

For testing purpose ONLY. This method recomputes the required handler list.

#### getIPOJOBundleContext

    protected final org.osgi.framework.BundleContext getIPOJOBundleContext()

Gets the iPOJO Bundle Context.

Returns:
  the iPOJO Bundle Context

#### updated

    public void updated(java.lang.String name,
                        java.util.Dictionary properties)
                 throws org.osgi.service.cm.ConfigurationException

Creates or updates an instance. This method is used from the configuration tracker.

Parameters:
  `name` - the name of the instance
  `properties` - the new configuration of the instance
Throws:
  `org.osgi.service.cm.ConfigurationException`

#### deleted

    public void deleted(java.lang.String name)

Deletes an instance.

Parameters:
  `name` - the name of the instance to delete

#### disposed

    public void disposed(ComponentInstance instance)

Callback called by instance when disposed.

Parameters:
  `instance` - the destroyed instance

#### computeDescription

    protected void computeDescription()

Computes the component type description. To do this, it creates a 'ghost' instance of the handler and calls the `Handler.initializeComponentFactory(ComponentTypeDescription, Element)` method. The handler instance is then deleted. The factory must be valid when calling this method. This method is called with the lock.

#### computeFactoryState

    protected void computeFactoryState()

Computes factory state. The factory is valid if every required handler are available. If the factory becomes valid for the first time, the component type description is computed. This method is called when holding the lock on the current factory.

#### match

    protected boolean match(IPojoFactory.RequiredHandler req,
                            org.osgi.framework.ServiceReference<?> ref)

Checks if the given handler identifier and the service reference match. Does not need to be synchronized as the method does not use any fields.

Parameters:
  `req` - the handler identifier.
  `ref` - the service reference.
Returns:
  `true` if the service reference can fulfill the handler requirement

#### getHandler

    protected HandlerManager getHandler(IPojoFactory.RequiredHandler req,
                                        ServiceContext context)
                                 throws MissingHandlerException,
                                        UnacceptableConfiguration,
                                        ConfigurationException

Returns the handler object for the given required handler. The handler is instantiated in the given service context. This method is called with the lock.

Parameters:
  `req` - the handler to create.
  `context` - the service context in which the handler is created (same as the instance context).
Returns:
  the handler object.
Throws:
  `MissingHandlerException`
  `UnacceptableConfiguration`
  `ConfigurationException`