[CONF] Apache Felix: How-to use iPOJO factories (page edited)

[confluence]

Page Edited : FELIX : How-to use iPOJO factories How-to use iPOJO factories has been edited by Clement Escoffier (Jan 27, 2007). (View changes) Content: iPOJO Factories Principles Clement Escoffier - [EMAIL PROTECTED] Update the : 2007-01-22 IPOJO defines a factory for each declared component type. These factories are used to create component instances. This document presents component type and component instance concepts, and how-to use factories is a metadata file and with the API. Preliminary Concepts Component Type A component type is a kind of instance template. If we compare component concepts with object oriented programming, component types are classes and component instances are objects. A component type is declared inside a metadata file (metadata.xml). The next snippet shows you a component type declaration: <component className="..." factory="MyFactory"> ... <!—handler configuration - -> ... </component> A component type is generally composed by: An implementation class (className) A factory name (factory) Handlers configuration (see handler guide) The factory attribute contains the factory name. This name is used to refer to the factory (and consequently to the component type). The factory attribute configuration can varies The factory attribute contains a name: this name will be used as factory name. The factory attribute contains "no" : the factory will be private The factory attribute is not declared: the class name is used as factory name. A private factory is no accessible outside the metadata file. To refer to the type, you need to use the class name. If the factory is public (not private), the factory is accessible outside the metadata file. Indeed, iPOJO will publish two services to access to the factory: org.apache.felix.ipojo.Factory : iPOJO Factory Interface org.osgi.service.cm.ManagedServiceFactory : Config Admin Interface The factory name will be used a service.pid property for these services. The service.pid is unique and persists between frmaework restarts. Component Instance A component instance is an instance of a component type. For example, if a component type declares providing and requiring services, the component instances, will expose and require services. Each factory can create several instances, but all these instances will be different entities, and will be independent. A component instance is characterized by: a component type an instance name (used to identify the instance) a configuration : a set of properties (<key, value>) A factory keeps a reference on each instance it creates. If the factory stops or goes away, all created instances stops and will be destroyed. To create an instance, the instance declaration gives the name and the configuration to the factory. However, the factory can refuse the creation if the configuration is not acceptable. An unacceptable configuration is a configuration not suitable with the component type. Reasons for unacceptable configuration are: the instance name is not set a property lacks inside the configuration a property value cannot be transform in the property type How-to declare instances inside metadata files A metadata file can declare instances from private (and contained) component type and from public (contained or not) factories. If a component type is private (factory attribute of the component type is "no"), the metadata file is the only way to create instances for this type. It is generally used when the component instance must be the unique instance of the type. Else, component instance can be declared either in the metadata file declaring the type, either in an external metadata file. If a declared instance targets an outside factory, the instance will be created only when the factory is available. Then, if the factory goes away, the instance stops, but if the factory comes back, the instance will be recreated. The next snippet shows how to declare an instance in the metadata: <instance component="component factory name" name = "instance name" > <property name="a property name" value="a string form of the value"/> <property name="another property name" value="the string form of the wanted value"/> </instance> The component type attribute contains the targeted factory name. The name attribute declares the instance name. The instance configuration is set by declaring a set of properties. A property is composed by a name and a value. The value is the string form of the wanted value. The iPOJO runtime will create the property object with this string. If an unacceptable configuration is set, the instance is not created, and an error message appears to the console (and in the Log Service if present). How-to use iPOJO factory service A public factory is exposed as an org.apache.felix.ipojo.Factory service. This service is accessible as any other OSGi™ service, and could be an iPOJO dependency too. This service used the following interfaces: Factory.java public interface Factory { /** * Create an instance manager (i.e. component type instance). * @param configuration : the configuration properties for this component. * @return the created instance manager. * @throw UnacceptableConfiguration if the given configuration is not consistent for the factory */ ComponentInstance createComponentInstance(Dictionary configuration) throw UnacceptableConfiguration; /** * Create an instance manager (i.e. component type instance). * This has these service interaction in the scope given in argument. * @param configuration : the configuration properties for this component. * @param serviceContext : the service context of the component. * @return the created instance manager. * @throw UnacceptableConfiguration if the given configuration is not consistent for the factory */ ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throw UnacceptableConfiguration; /** * Get the component type information containing provided service, configuration properties ... * @return the component type information. */ ComponentDescription getComponentDescription(); /** * Check if the given configuration is acceptable as a configuration of a component instance. * @param conf : the configuration to test * @return true if the configuration is acceptable */ boolean isAcceptable(Dictionary conf); /** * @return the name of the factory. */ String getName(); } The factory service contains two methods to create instances: With a service context: this method is only used with composite, and should not be used. Without the service context: the method takes in argument a Dictionary containing the configuration. One of the contained properties must be the instance name (the property key must be "name"). An instance is started automatically when created. However, the instance can be invalid, if handlers are not valid). To destroy an instance, invoke the stop method on the instance. How to use the ManagedServiceFactory to create instances The principle of the ManagedServiceFactory is the same as the iPOJO Factory Service. To have further information on it, read the OSGi R4 Compendium - Configuration Admin chapter. Conclusion This document has presented how to use iPOJO factories. If you have remarks or comments, do not hesitate do send me en email to [EMAIL PROTECTED]

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences