Bootstrapping the Registry

- Services, Interfaces, Descriptors -

The first step is to define the service interface:

- + Bootstrapping the Registry + + +

Before you can access the configuration points and services defined in + your application's module deployment descriptors, you need a registry; here we'll + describe how to construct the registry.

The key class here is &api.RegistryBuilder;, which contains code for + locating and parsing the module deployment descriptors and constructing a + registry from the combined data. The descriptors are all found on the class path; they'll include + the descriptors for HiveMind itself with descriptors packaged into your application's JARs. +

+ + + As HiveMind grows in popularity, we may start to see + third party frameworks come bundled with + HiveMind module deployment descriptors ... but it's too soon for that, now. + + +

Let's examine how all this comes together. The layout of the project is + shown below.

+ Service Interfaces and Implementations +

The first step is to define the service interface:

+ -

Next we need an implementation for that service:

- Next we need an implementation for that service:

+ -

Finally, we need the HiveMind module deployment descriptor, - hivemodule.sdl. This file is in Simple Data - Language format (though equivalent XML is supported if the file - is named hivemodule.xml).

- + The example includes three additional interfaces and matching implementations: + for a Subtracter, Multiplier, Divider, and lastly, a Calculator that combines them + together: +

+ + + +

+The Calculator implementation will require some wiring; it expects that each of the other four +services (Adder, Substracter, Multiplier and Divider) will be plugged into it: +

+ + + +

+ +

+ Module Deployment Descriptor +

Finally, we need the HiveMind module deployment descriptor, + hivemodule.sdl. This file is in Simple Data + Language format (though equivalent XML is supported if the file + is named hivemodule.xml).

+ +

+ The module descriptor creates each of the services in terms of + an interface, and an implementation. In addition, each service gets its + own logging interceptor. +

+ -

Here we've chosen to have the module id, hivemind.examples - , match the package name but that is not an absolute requirement.

- Building the Registry -

Before your code can access any services (or configuration points), it - must construct the registry.

- Here we've chosen to have the module id, hivemind.examples, + match the package name but that is not an absolute requirement.

+ +

+ The interesting part is the use of the &hivemind.BuilderFactory; to construct + the Calculator service and connect it to the other four services. +

+ Building the Registry +

Before your code can access any services (or configuration points), it + must construct the &api.Registry;. The Registry is the applications gateway into the services + and configurations managed by HiveMind.

+ -

Building the registry requires four steps:

Create a &api.ClassResolver; instance. DefaultClassResolver uses the - thread's context class loader.
Create a &api.RegistryBuilder; instance.
Invoke processModules() to find and parse all HiveMind - module deployment descriptors visible on the classpath (as - META-INF/hivemodule.sdl or META-INF/hivemodule.xml - ). Here, this will be the master HiveMind module descriptor (for the - hivemind module), and the descriptor for this example - module. You could invoke processModule() to parse - additional deployment descriptors stored in unusual locations.
Invoke constructRegistry() to integrate and validate - all the information in all of the HiveMind module deployment - descriptors and produce a &api.Registry; from it.

Alternately, the static method - constructDefaultRegistry() can be invoked. It's just those same - four lines of code.

Now that we have the registry, we can use the full id of the Adder - service, hivemind.examples.Adder, to get the service - implementation. We pass in the class that we'll be casting the service - to ... this allows HiveMind to produce a more meaningful error than a - ClassCastException.

Using the reference to the Adder service, we can finally invoke the - add() method.

- Building the Example -

Building and running the example using Ant is a snap; all the details - are in the build.xml:

- + System.out.println("Inputs " + arg0 + " and " + arg1); + + System.out.println("Add : " + c.add(arg0, arg1)); + System.out.println("Subtract: " + c.subtract(arg0, arg1)); + System.out.println("Multiply: " + c.multiply(arg0, arg1)); + System.out.println("Divide : " + c.divide(arg0, arg1)); + } +} +]]> +

&api.RegistryBuilder; contains a static method for constructing a Registry, which + is suitable for most situations.

Now that we have the registry, we can use the fully qualified id of the Calculator + service, hivemind.examples.Calculator, to get the service + implementation. We pass in the class that we'll be casting the service + to ... this allows HiveMind to produce a more meaningful error than a + ClassCastException.

Using the reference to the Calculator service, we can finally invoke the + add(), subtract(), multiply() + and divide() methods.

+ Building the Example +

Building and running the example using Ant is a snap; all the details + are in the build.xml:

+ + - + + + + - + + + + + + - + + - + + + + + + @@ -173,30 +310,81 @@ - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - Adding 11 and 23, should get 34. - + -]]> -

The important part is to package both the classes and the HiveMind - module deployment descriptor into the JAR. The latter is accomplished - using the <metainf> element.

The only other oddity was to add src/conf to the runtime - classpath; this is to include the log4j.properties - configuration file; otherwise Log4J will write console errors about - missing configuration.

- + +]]> +

The important part is to package both the classes and the HiveMind + module deployment descriptor into the JAR.

The only other oddity was to add src/conf to the runtime + classpath; this is to include the log4j.properties + configuration file; otherwise Log4J will write console errors about + missing configuration.