Difference between revisions of "Riena Getting Started with Wiring"

Revision as of 09:25, 25 January 2010

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:

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);
	}
}

This code uses the well-known Inject.… to perform the necessary injections. As mentioned before, this is the most flexible approach 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 next 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. But, as mentioned before, what you gain in convenience you lose in flexibility.

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. 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 name is deduced from the bind method name (which can be set through an annotation value) 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.