Difference between revisions of "Riena Getting Started with Wiring"

Revision as of 08:53, 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?

There are two ways of specifying what needs to be done.

Wiring through a dedicated class

This option is the most flexible but also the least convenient way. The class that needs services or extensions injected has to specify, using an annotation, another class which is responsible for the wiring. The target class looks like this:

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

And 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.

There is another approach for when you do not need this flexibility, which we describe in the next section.

Wiring through annotations

The same wiring could 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. But, as mentioned before, what you gain in convenience you lose in flexibility. However under the hood it will do exactly the same as the previous less-convenient approach.

This can even be more simplified when 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";
	...
}

With that you can write:

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

You can, of course, also use annotations to specify wirings for service injection. 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 generated from the annotated bind method name 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.