org.apache.felix.ipojo
Class IPojoFactory

java.lang.Object
  extended by org.apache.felix.ipojo.IPojoFactory
All Implemented Interfaces:
Factory, ManagedServiceFactory
Direct Known Subclasses:
ComponentFactory

public abstract class IPojoFactory
extends Object
implements Factory, 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 List INSTANCE_NAME
          The list of the managed instance name.
protected  ComponentTypeDescription m_componentDesc
          The component type description exposed by the Factory service.
protected  Map m_componentInstances
          The list of the managed instance managers.
protected  Element m_componentMetadata
          The component type metadata.
protected  BundleContext m_context
          The bundle context reference.
protected  String m_factoryName
          The factory name.
protected  boolean m_isPublic
          Is the factory public (exposed as services).
protected  List m_listeners
          The list of factory state listeners.
protected  Logger m_logger
          The logger for the factory.
protected  List m_requiredHandlers
          The list of required handlers.
protected  ServiceRegistration m_sr
          The service registration of this factory (Factory & ManagedServiceFactory).
protected  int m_state
          The factory state.
protected  String m_version
          The version of the component type.
 
Fields inherited from interface org.apache.felix.ipojo.Factory
INVALID, VALID
 
Constructor Summary
IPojoFactory(BundleContext context, Element metadata)
          Creates an iPOJO Factory.
 
Method Summary
 void addFactoryStateListener(FactoryStateListener listener)
          Adds a factory listener.
 void checkAcceptability(Dictionary conf)
          Checks if the configuration is acceptable.
protected  void computeDescription()
          Computes the component type description.
protected  void computeFactoryState()
          Computes factory state.
 ComponentInstance createComponentInstance(Dictionary configuration)
          Creates an instance.
 ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext)
          Creates an instance in the specified service context.
abstract  ComponentInstance createInstance(Dictionary config, IPojoContext context, HandlerManager[] handlers)
          Creates an instance.
 void deleted(String name)
          Deletes an instance.
 void disposed(ComponentInstance instance)
          Callback called by instance when disposed.
protected  String generateName()
          Helper method generating a new unique name.
 BundleContext getBundleContext()
          Gets the bundle context of the factory.
abstract  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  String getFactoryName()
          Computes the factory name.
protected  HandlerManager getHandler(IPojoFactory.RequiredHandler req, ServiceContext context)
          Returns the handler object for the given required handler.
protected  BundleContext getIPOJOBundleContext()
          Gets the iPOJO Bundle Context.
 Logger getLogger()
          Gets the logger used by instances created by the current factory.
 List getMissingHandlers()
          Computes the list of missing handlers.
 String getName()
          Gets the factory name.
abstract  List getRequiredHandlerList()
          Computes the required handler list.
 List getRequiredHandlers()
          Gets the list of required handlers.
 int getState()
          Gets the actual factory state.
 boolean isAcceptable(Dictionary conf)
          Checks if the configuration is acceptable.
protected  boolean match(IPojoFactory.RequiredHandler req, ServiceReference ref)
          Checks if the given handler identifier and the service reference match.
 void reconfigure(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(String name, 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 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 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 BundleContext m_context
The bundle context reference.


m_factoryName

protected 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 List m_requiredHandlers
The list of required handlers.


m_listeners

protected List 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 String m_version
The version of the component type.


m_sr

protected 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(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 String getFactoryName()
    Computes the factory name. Each sub-type must override this method.

    Returns:
    the factory name.

    getRequiredHandlerList

    public abstract List getRequiredHandlerList()
    Computes the required handler list. Each sub-type must override this method.

    Returns:
    the required handler list

    createInstance

    public abstract ComponentInstance createInstance(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(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(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 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 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 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 String getName()
    Gets the factory name. This name is immutable once set.

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

    getRequiredHandlers

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


    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.


    restart

    public void restart()
    For testing purpose ONLY. This method recomputes the required handler list.


    getIPOJOBundleContext

    protected final BundleContext getIPOJOBundleContext()
    Gets the iPOJO Bundle Context.

    Returns:
    the iPOJO Bundle Context

    updated

    public void updated(String name,
                        Dictionary properties)
                 throws ConfigurationException
    Creates or updates an instance.

    Specified by:
    updated in interface ManagedServiceFactory
    Parameters:
    name - the name of the instance
    properties - the new configuration of the instance
    Throws:
    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(String name)
    Deletes an instance.

    Specified by:
    deleted in interface 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,
                            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 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


    Copyright © 2013 The Apache Software Foundation. All Rights Reserved.