Difference between revisions of "Riena Getting Started with Wiring"

Latest revision as of 03:40, 8 July 2011

{{#eclipseproject:rt.riena}}

Please read Riena Getting Started with injecting services and extensions first before you continue reading this page. A basic understanding of Riena's injection mechanism is necessary for understanding Riena's wiring mechanism.

Use case: Why Wiring?

In Eclipse-RCP-based applications, components often start their life cycle because they were contributed as an executable extension org.eclipse.core.runtime.IConfigurationElement.createExecutableExtension(String).

Who or what is responsible for injecting the required services and/or extensions into these objects? And how to know what to inject? Moreover it is often desirable not to invoke an Inject.… sentence within the classes that need injecting.

The answer to these questions is Wiring. With the following sentence it is possible to initiate the wiring, i.e. perform all the necessary injections of services and extensions.

Wire.instance(object).andStart(context);

Well, that looks really easy, but you may wonder how it works? This is the topic of the next section.

Specifying a wiring

There are two ways of specifying what needs to be done: Introducing a dedicated class responsible for the wiring, and annotating a method that requires injection.

Wiring through a dedicated class

This option is the most flexible but least convenient way. The class that needs to have services or extensions injected (i.e. the target class) specifies, using an annotation, another class that be responsible for the wiring:

@WireWith(SSLConfigurationWiring.class)
public class SSLConfiguration {
 
	public void configure(ISSLProperties properties) {
	...
	}
}

The actual wiring is then performed by the class defined in the annotation, implementing the methods wire(...) and unwire(...):

public class SSLConfigurationWiring extends AbstractWiring {
	private ExtensionInjector sslInjector;
 
	@Override
	public void unwire(Object bean, BundleContext context) {
		sslInjector.stop();
	}
 
	@Override
	public void wire(Object bean, BundleContext context) {
		sslInjector = Inject.extension("org.eclipse.riena.communication.core.ssl").expectingMinMax(0, 1).into(bean).update(
				"configure").andStart(context);
	}
}

Here we use Riena's well-known Inject.… to perform the necessary injections. Note how we explicitly specify that the update method shall be named "configure".

This approach is the most flexible because within the wire(...) and unwire(...) methods you can do anything you like. When you do not need this flexibility, you can use a simpler approach, described in the following section.

Wiring through annotations

The same wiring can be done with:

public class SSLConfiguration {
 
	@InjectExtension(id = "org.eclipse.riena.communication.core.ssl", min = 0, max = 1)
	public void configure(ISSLProperties properties) {
	...
	}
}

You might ask: That's all? Yes, it is. Under the hood it will do exactly the same as the previous less-convenient approach. For example, there is no longer any need to specify how the update method needs to be called, because we denote this by annotating the method to be used, in this case configure(...).

If the extension point ID is defined as a constant named "ID" in the extension interface:

@ExtensionInterface
public interface ISSLProperties {
 
	String ID = "org.eclipse.riena.communication.core.ssl";
	...
}

… wiring can be even more concise:

public class SSLConfiguration {
 
	@InjectExtension(min = 0, max = 1)
	public void configure(ISSLProperties properties) {
	...
	}
}

Of course, you can use corresponding annotations for injecting services through wiring as well. The shortest form is:

public class CustomerSearchSubModuleController extends SubModuleController {
 
	@InjectService()
	public void bind(ICustomerSearch service) {
	...
	}
 
	public void unbind(ICustomerSearch service) {
	...
	}
}

This will inject the ICustomerSearch service into the annotated bind(...) method. The unbind(...) method's name is deduced from the name of the annotated bind method by prefixing it with "un". You can also specify explicitly the service class or name, the unbind method name and other properties with parameters of the annotation.

Back to our use case

If you define executable extensions that need to be wired, you don't need to care. Just provide your class with the approach that suits your needs best. And Riena's extension injector will automatically do the wiring.

Of course you can initiate wiring everywhere you want by explicitly calling Wire.…

Wrap-up

Riena's wiring simplifies writing components that need services or extensions injected. Especially when those components start their life cycle through executable extensions.