Page History

...

iPOJO is a service component model aiming to simplify OSGiâ„¢ applications development. iPOJO is based on the POJO concepts. A POJO is a simple Java class without any dependency on its runtime environment. In iPOJO, POJO are encapsulated in a container managing the relation between the POJO and the external world. This container keeps separate the POJO from the external world. Moreover, this container is flexible and extensible.
Basically, iPOJO contains two main concepts: Component Type and Component Instance. A component type is a type of component. A component type defines its implementation class, its creation policy, and its container. A component instance is a configured instance of a component type. This instance is created with the component type factory. A component instance inherits of all component type characteristics but has a unique name, and owns a configuration (set of <key, value>).

Above these concepts, iPOJO runtime will manage component type factories and component instances. Each component instance is managed separately. (but the factory can delete them).

A component type declares its container configuration. Each component instance owns its container conform to the component type container configuration. An iPOJO container is composed by an "InstanceManager", encapsulating the POJO, on which are plugged Handlers. A handler manages one non functional concern. Handlers participate to the component instance lifecycle; can interact with the POJO; can manage relations with external entity like database, or other POJOs ...

iPOJO is an extensible model allowing developer to manage other non functional concerns. Indeed, handlers can be developed singly, without modifying the iPOJO core. At runtime, iPOJO will look for each handler needed by a component instance and plug an instance of each (needed) handler on the container. So iPOJO containers are flexible, light and adaptable to each component. When a needed handler cannot be found, the component instance management failed.

An external handler is identified by a Namespace. This namespace matches with the class name (qualified name) implementing the handler behavior. This namespace will be used by developers to refer to the external handler (when he configures its component type) and by iPOJO to instantiate the handler object.

...

public void configure(InstanceManager im, Element metadata, Dictionary config) {
 // First parse the metadata to check if the log handler level
		
 // Get all Namespace:log element from the metadata
 Element[] log_elements = metadata.getElements("log", NAMESPACE);
		
 // if no element found, return 
 if(log_elements.length == 0) { return; } 
 else {
	// If an element match, parse the level attribute of the first element
	if(log_elements[0].containsAttribute("level")) {
		String l = log_elements[0].getAttribute("level");
		if(l.equalsIgnoreCase("info")){level=LogService.LOG_INFO; }
		else if(l.equalsIgnoreCase("error")){level=LogService.LOG_ERROR; }
       	else {level=LogService.LOG_WARNING;}
	}
			
// Register on the instance manager, to be a part of the component                  // instance container
	manager = im;
	context = manager.getContext();  // Store the bundle context
	manager.register(this);
   }
}

...

Note: do not forget to unget all used services and to release all service objects.

The isValid and stateChanged methods

The isValid method returns the handler validity. In our case, the handler is valid if a log service is available.

...

This method begins by parsing the component type metadata. The handler needs a properties element from its namespace. According to the result, the configure method can return immediately or parse the file attribute (to get the properties file path). Then, it builds a field list (String array) to register to field notification. By registering with a field array, the handler will be a part of the component instance container and will be notified of field access.

The start and stop methods

The start method does nothing, but need to be implemented.

The stop method stores properties inside the properties file.

GetterCallback and SetterCallback methods

...

public void configure(InstanceManager inst, Element meta, Dictionary conf) {
  manager = inst;
  Element[] prop_element = meta.getElements("Properties", NAMESPACE); 
  if(prop_element.length == 0) { return; }
  else {
	if(prop_element[0].containsElement("file")) { 
        file_name = prop_element[0].getAttribute("file"); 
       }
	else { return; }
	// Load the file and register the field
	File file = new File(file_name);
	try {
	  InputStream is = new FileInputStream(file);
	  props.load(is);
	} catch (FileNotFoundException e) { e.printStackTrace(); return; } 
	  catch (IOException e) { e.printStackTrace(); return ; }
	// Register to field notification
	Enumeration e = props.propertyNames();
	String[] fields = new String[props.size()];
	for(int i=0; i < fields.length; i++) {fields[i]=(String)e.nextElement();}
	manager.register(this, fields);
  }
}

The start and stop methods

The start method does nothing, but need to be implemented.

public void start() { }

The stop method stores properties inside the properties file.

public void stop() {
 File file = new File(file_name);
 try {
   OutputStream os = new FileOutputStream(file);
   props.store(os, "written by " + NAMESPACE);
 } catch (FileNotFoundException e) { e.printStackTrace(); } 
   catch (IOException e) { e.printStackTrace(); }
}

GetterCallback and SetterCallback methods

The getterCallback method is called when the POJO need a field value. When called, the method needs to return the stored value.
The setterCallback method is called when the POJO modifies a field value. If the new value if null, the handler will remove this properties from the property list.

public void setterCallback(String fieldName, Object value) {
 // Store the new value in props (if not null) else remove the property
 if(value != null) { props.put(fieldName, value); }
 else { props.remove(fieldName); }
}
	
public Object getterCallback(String fieldName, Object value) {
  if(props.containsKey(fieldName)) { return props.get(fieldName); }
  else { return value; }
}

Handler packaging

This handler needs to be packaged inside a bundle exporting the package "org.apache.felix.ipojo.properties.handler". The bundle will import the "org.apache.felix.ipojo" packages.

...

Note: the file path need to used
instead of \

Conclusion

In this document, we present how-to develop handler for you components. We describe two small examples : a log handler and a properties handler. See the handler proposition section of the iPOJO documentation to see available handlers or to propose your own handler.