org.apache.felix.ipojo
Class IPojoFactory

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

All Implemented Interfaces:

Factory, org.osgi.service.cm.ManagedServiceFactory

Direct Known Subclasses:

ComponentFactory

public abstract class IPojoFactory
extends java.lang.Object
implements Factory, org.osgi.service.cm.ManagedServiceFactory

This class defines common mechanisms of iPOJO component factories (i.e. component type). This class implements both the Factory and ManagedServiceFactory services.

Author:

Felix Project Team

Nested Class Summary

protected class

IPojoFactory.RequiredHandler Structure storing required handlers.

Field Summary

protected static java.util.List	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	m_componentInstances The list of the managed instance managers.
protected Element	m_componentMetadata The component type metadata.
protected org.osgi.framework.BundleContext	m_context The bundle context reference.
private boolean	m_described The flag indicating if this factory has already a computed description or not.
protected java.lang.String	m_factoryName The factory name.
private long	m_index The index used to generate instance name if not set.
protected boolean	m_isPublic Is the factory public (exposed as services).
protected java.util.List	m_listeners The list of factory state listeners.
protected Logger	m_logger The logger for the factory (and all component instances).
protected java.util.List	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

INVALID, VALID

Constructor Summary

IPojoFactory(org.osgi.framework.BundleContext context, Element metadata)
Creates an iPOJO Factory.

Method Summary

void	addFactoryStateListener(FactoryStateListener listener) Adds a factory listener.
void	checkAcceptability(java.util.Dictionary 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.
(package private) void	dispose() Destroys the factory.
void	disposed(ComponentInstance instance) Callback called by instance when disposed.
protected java.lang.String	generateName() Helper method generating a new unique name.
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.
ComponentTypeDescription	getComponentTypeDescription() Gets the component type description.
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.
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	getMissingHandlers() Computes the list of missing handlers.
java.lang.String	getName() Gets the factory name.
abstract java.util.List	getRequiredHandlerList() Computes the required handler list.
java.util.List	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	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 INSTANCE_NAME

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

m_componentDesc

protected ComponentTypeDescription m_componentDesc

The component type description exposed by the Factory service.

m_componentInstances

protected final java.util.Map 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 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 java.util.List m_requiredHandlers

The list of required handlers.

m_listeners

protected java.util.List m_listeners

The list of factory state listeners.

See Also:

FactoryStateListener

m_logger

protected final Logger m_logger

The logger for the factory (and all component instances).

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).

m_index

private long m_index

The index used to generate instance name if not set.

m_described

private boolean m_described

The flag indicating if this factory has already a computed description or not.

Constructor Detail

IPojoFactory

public IPojoFactory(org.osgi.framework.BundleContext context,
                    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 getRequiredHandlerList()

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

Returns:

the required handler list

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 {@link IPojoFactory#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 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()

getMissingHandlers

public java.util.List getMissingHandlers()

Computes the list of missing handlers. This method is called with the monitor lock.

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

Specified by:

getName in interface org.osgi.service.cm.ManagedServiceFactory

Returns:

the factory name.

See Also:

Factory.getName()

getRequiredHandlers

public java.util.List getRequiredHandlers()

Gets the list of required handlers. This method is synchronized to avoid the concurrent modification of the required handlers.

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()

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 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

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 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.

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.

Specified by:

updated in interface org.osgi.service.cm.ManagedServiceFactory

Parameters:

name - the name of the instance

properties - the new configuration of the instance

Throws:

org.osgi.service.cm.ConfigurationException - if the configuration is not consistent for this component type

See Also:

ManagedServiceFactory.updated(java.lang.String, java.util.Dictionary)

deleted

public void deleted(java.lang.String name)

Deletes an instance.

Specified by:

deleted in interface org.osgi.service.cm.ManagedServiceFactory

Parameters:

name - the name of the instance to delete

See Also:

ManagedServiceFactory.deleted(java.lang.String)

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)

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.

generateName

protected java.lang.String generateName()

Helper method generating a new unique name. This method is call when holding the lock to assert generated name unicity.

Returns:

a non already used name