Skip to main content
Jump to: navigation, search

Difference between revisions of "Riena/Getting Started with injecting services and extensions"

m (Injecting Services)
(Injecting Extensions)
Line 78: Line 78:
 
<pre>
 
<pre>
 
/**
 
/**
  * Interface for a SubModuleType extension that defines how an activated
+
  * Interface for a SubModule extension that defines how an activated submodule
  * submodule appears in the work area.
+
  * appears in the work area.
 
  */
 
  */
 
@ExtensionInterface
 
@ExtensionInterface
public interface ISubModuleTypeDefinition extends ITypeDefinition {
+
public interface ISubModuleExtension {
  
 
/**
 
/**
 
* @return A controller that controlles the UI widgets in the view through
 
* @return A controller that controlles the UI widgets in the view through
*        ridgets (see org.eclipse.riena.ui.ridgets.IRidget)
+
*        ridgets (see org.eclipse.riena.ui.internal.ridgets.IRidget)
 
*/
 
*/
 
IController createController();
 
IController createController();
Line 106: Line 106:
 
String getView();
 
String getView();
  
 +
/**
 +
* Return the contributing bundle of the extension.
 +
*
 +
* @return The contributing bundle
 +
*/
 
Bundle getContributingBundle();
 
Bundle getContributingBundle();
 +
 +
/**
 +
* @return The type part of the ID of a navigation node.
 +
* @see NavigationNodeId#getTypeId()
 +
*/
 +
String getTypeId();
  
 
}
 
}
Line 113: Line 124:
 
That gets injected into:
 
That gets injected into:
 
<pre>
 
<pre>
public class PresentationExtensionInjectionHelper<E extends ITypeDefinition> {
+
public class SubModuleExtensionInjectionHelper {
 +
private ISubModuleExtension[] data;
  
private E[] data;
+
public void update(ISubModuleExtension[] data) {
 
+
public void update(E[] data) {
+
 
this.data = data.clone();
 
this.data = data.clone();
 
 
}
 
}
  
public E[] getData() {
+
public ISubModuleExtension[] getData() {
 
return data.clone();
 
return data.clone();
 
}
 
}
 
 
}
 
}
 
</pre>
 
</pre>
Line 131: Line 139:
 
by executing:
 
by executing:
 
<pre>
 
<pre>
Inject.extension("org.eclipse.riena.navigation.subModuleType").useType(ISubModuleTypeDefinition.class).into(target).andStart(Activator.getDefault().getContext());
+
Inject.extension("org.eclipse.riena.navigation.subModuleType").useType(ISubModuleExtension .class).into(target).andStart(Activator.getDefault().getContext());
 
</pre>
 
</pre>
where <code>target</code> is an instance of <code>PresentationExtensionInjectionHelper</code>.
+
where <code>target</code> is an instance of <code>SubModuleExtensionInjectionHelper </code>.
  
 
[[Category:Riena]]
 
[[Category:Riena]]

Revision as of 02:14, 22 October 2008

Riena Project > Getting Started> Getting Started with Injecting Services and Extensions

Getting Started with Injecting Services and Extensions

The Idea of Injecting Services and Extensions in Riena

Services and extensions are the main building blocks of Eclipse RCP applications. There is a long list of discussions and debates about when to use services and when to use extensions. So, we will not add another discussion here. We think that both are useful and have their permission.

One problem with both of them is that using them requires a lot of code that respects their life cycle and is quite error prone. Most of this code is embedded within the code that needs other services or extensions. This approach does not clearly separate concerns and it makes unit testing more difficult.

A common solution for this problem is the use of dependency injection frameworks such as Spring (http://springframework.org/) or HiveMind (http://hivemind.apache.org/).

Within Riena we are using a simple to use approach to inject services and extensions into objects (pojos). Our approach is code based, i.e. no xml configuration files. Furthermore we are using fluent interfaces (http://en.wikipedia.org/wiki/Fluent_interface) and conventions to simplify the injection definitions.

Injecting Services

The service injection allows to inject services into target objects (pojos). The selection of the services that should be injected can either be done by service ranking or by using a filter expression. Service ranking is property of a service that might be supplied when registering a service [1]. The default service ranking is 0 (i.e. when it is not supplied). Riena defines most of it services with a ranking of -100. This has the effect, that services defined with the default ranking (not specifying a ranking) will override a Riena service when the get selected when service ranking is specified.

Inject.service("org.eclipse.riena.sample.app.common.model.ICustomerSearch").useRanking().into(target).andStart(context);

or shorter

Inject.service(ICustomerSearch.class).useRanking().into(target).andStart(context);

where ´target´ is the pojo that gets a service injected. Within the target the following is necessary:

..
public void bind(ICustomerSearch service) {
	this.service = service;
}

public void unbind(ICustomerSearch service) {
	this.service = null;
}
..

The other possibility is to use an RFC 1960-based filter expression to select the services that should be injected.

Inject.service(ISomeService.class).into(target).andStart(context);
Inject.service("org.eclpse.riena.ISomService").useFilter("(remote=true)").into(target).bind("register").unbind("unregister").andStart(context);

The andStart() method starts the injector. From now on the service injector will track the specified services and when services come and go they will be injected into or removed from the pojos. The method names for injecting/removing can be specified with the bind() and unbind() methods. If they are not defined default method names will be used. When service ranking is used there will always be only one or no service that gets injected. When the filter based approach is used multiple services or no service can be injected. In the case for multiple services the bind/unbind methods will be called multiple times. In this case the target object has to keep track of the injected services.

To stop the injection it ispossible to call the stop() method on the injector any time. This causes all injected services to be unbound. However, when a bundle stops that is associated with an injector via the andStart() method all injected services will be stopped as well.

Injecting Extensions

Extensions get injected into pojos as instances of an interface. The interfaces need only to declare the getters. Dynamic proxies will be created for the interfaces which map the data from the extensions. A few simple rules are used for the mapping from extensions to the interfaces (lightweight xml/java mapping). Extension properties. i.e. attributes, sub-elements and element value can then accessed by getters in the interface definition. It is only necessary to define the interfaces for the mapping.

The extension injector does not evaluate the extension schema, so it can only trust that the extension and the interface match with regards to a few basic rules:

  • one interface maps to one extension element type
  • the interface has to be annotated with @ExtensionInterface
  • interface methods can contain getters prefixed with:
    • get...
    • is...
    • create...
  • Such prefixed methods enforce a default mapping to attribute or element names, i.e. the remainder of the methods name is interpreted as the attribute or element name. A simple name mangling is performed, e.g for the method getDatabaseURL the mapping looks for the attribute name databaseURL.

To enforce another name mapping a method can be annotated with @MapName("name"). The name specifies the name of the element or attribute. The extension element´s content can be retrieved by annotating the method with @MapContent(). The return type must be String. The method names of such annotated methods can be arbitrary

  • The return type of a method indicates how the value of an attribute will be converted. If the return type is
    • a primitive type or java.lang.String than the mapping converts the attribute's value to the corresponding type.
    • an interface or an array of interfaces annotated with @ExtensionInterface than the mapping tries to resolve to a nested element or to nested elements.
    • org.osgi.framework.Bundle than the method returns the contributing bundle.
    • java.lang.Class than the attribute is interpreted as a class name and a class instance will be returned.
    • and finally if none of the above matches the mapping tries to create an new instance of the attribute´s value (interpreted as class name) each time it is called. If the extension attribute is not defined null will be returned.

Extension injecting examples:

Inject.extension("extpoint1").into(target).andStart(context);
Inject.extension("extpoint2").useType(interface).into(target).bind("configure").doNotReplaceSymbols().andStart(context);
Inject.extension("extpoint3").expectExactly(1).into(target).andStart(context);

A sample interface from Riena:

/**
 * Interface for a SubModule extension that defines how an activated submodule
 * appears in the work area.
 */
@ExtensionInterface
public interface ISubModuleExtension {

	/**
	 * @return A controller that controlles the UI widgets in the view through
	 *         ridgets (see org.eclipse.riena.ui.internal.ridgets.IRidget)
	 */
	IController createController();

	/**
	 * Indicates whether the view is shared i.e. whether one instance of the
	 * view should be used for all submodule instances.
	 * 
	 * @return true if the specified view should be a shared view, false
	 *         otherwise
	 */
	boolean isShared();

	/**
	 * @return For the SWT-based Riena UI this is the ID of the view associated
	 *         with the submodule. Must match the ID field of an
	 *         "org.eclipse.ui.view" extension.
	 */
	String getView();

	/**
	 * Return the contributing bundle of the extension.
	 * 
	 * @return The contributing bundle
	 */
	Bundle getContributingBundle();

	/**
	 * @return The type part of the ID of a navigation node.
	 * @see NavigationNodeId#getTypeId()
	 */
	String getTypeId();

}

That gets injected into:

public class SubModuleExtensionInjectionHelper {
	private ISubModuleExtension[] data;

	public void update(ISubModuleExtension[] data) {
		this.data = data.clone();
	}

	public ISubModuleExtension[] getData() {
		return data.clone();
	}
}

by executing:

Inject.extension("org.eclipse.riena.navigation.subModuleType").useType(ISubModuleExtension .class).into(target).andStart(Activator.getDefault().getContext());

where target is an instance of SubModuleExtensionInjectionHelper .

Back to the top