Binding Components in Rhino

The Binder is a tool supplied with the Sentinel SDK.

It is able to ‘bind’ various components together once they have been deployed into the Rhino.

It makes use of the bindings features introduced in Rhino 2.4.0.

When a module is built, bindings meta-data is created in the target/generated/bindings directory. The bindings meta-data file(s) are then archived and published with the module.

The archive itself is created in target/artifacts, and whether or not it is published is declared in the publications section of a modules ivy.xml file.

Bindings meta-data is produced from the Java annotations in a feature’s source files.

It may be useful to review the content of the generated bindings meta-data files when developing a module.

Here is an example for a Sentinel POJO feature:

In the example above, it can be seen that the POJO feature has:

Specific annotations are required in Sentinel feature source file(s) for bindings to successfully occur.

Annotations in the feature source are read when a feature is built, and make their way into the bindings meta-data.

These annotations indicate which type of Sentinel service a feature should be bound into.

Sentinel supports two mechanisms for explicitly declaring which Sentinel services a feature should be bound into:

The binder will consider @BinderTargets annotations first. For features which do not declare a ‘@BinderTargets’ annotation, the binder will choose the target services based on SLEE references to the relevant SPI library/SBB part.

Modules must publish their bindings archive to the ‘slee-binding’ Ivy configuration.

When modules depend on other modules, typically they should include the ‘slee-binding’ Ivy configuration in their dependencies. This is so that the binder can traverse a graph of modules, binding all of them.

So for example, in the case of a related set of modules, such as a feature, a profile for configuring that feature, and a library containing shared session state fields, the Ivy dependencies from the feature must contain slee-binding.

Here is an example of a features ivy.xml file where the feature depends on a profile and mapper:

The SLEE annotation processor is executed when a module is built. It produces both component deployment descriptor files, and bindings meta-data files.

It can be configured to generate “outwards” component references in:

The Sentinel SDK uses the second of the three options — outwards references in modules are included in both the deployment descriptor and bindings meta-data files.

Sentinel Services themselves are published without any feature or mapper references. This allows features to be added and removed through bindings.

Rhino 2.4.0.x and later enables bindings to be used in place of deployment descriptor references.

The binder that ships with the Sentinel SDK applies bindings to a subset of those available in the platform. Specifically binding is used in the Sentinel SDK for:

There are two commands that the binder takes - bind or bind-with-deps.

The bind command attempts to bind a single module, whereas bind-with-deps walks the Ivy dependency hierarchy reading the slee-binding Ivy configuration. Each command may require Rhino to make component copies. The bind-with-deps command will perform multiple bindings within a single 'block of work', and so create only one copy of a Service. Whereas if bind is run many times, then multiple copies may be taken.

Walking the Ivy graph, short cutting when finding a Profile or Library.

In this dependency graph there are five modules. Starting from the root:

The Ivy configurations as part of the dependencies are shown in text on the diagram, next to the dependency line. The important thing to note is that all modules are using the 'slee-binding' configuration in their dependencies. This means that the binder can traverse the module structure.

Assume that bind-with-deps is invoked pointing to Module A. The binder will read module A and classify it as a group module. It will then look at the dependencies of Module A finding B and C. B and C are analysed as being POJO Feature modules. Their dependencies are followed to module D. This module is a Profile module. The binder does not ask Rhino to apply bindings to Profile modules, so evaluation of Module D is exited and Module D’s dependencies are not analysed.

The binder is able to classify modules based on their publications and dependencies. To see if there are any bindings present the binder scans the publications of the module, looking for a zip file with the filename ending in 'bindings.zip' published with "type=binding" conf of "slee-binding". If there is a bindings archive present, the binder determines the component type by reading the bindings meta-data contained in the archive. In the case that there is no bindings archive present, the binder queries the Ivy dependencies of the component seeing if they have bindings information present. If any module (either directly or indirectly) depended on by this module publishes bindings, then this module has its type set to 'group'.

Component binding can be undone. This is referred to as 'unbinding'.

There are two targets to unbind modules, these are unbind and unbind-all.

The unbind target functions on a single module, based on the current working directory.

Its behaviour is to unapply the bindings from any Services, and then to undeploy the bindings descriptor from Rhino.

The unbind-all target functions on a directory structure of modules, looking for all modules that are located in subdirectories of the current working directory. It then invokes unbind on each. It is often used in conjunction with bind-with-deps for group modules that a user has defined themselves.