Annotated module classes
HiveMind 2 introduces a complete new way of defining modules. It doesn't requires xml at all, but bases on pure java and annotations.
This approach reduces the complexity of module definitions, allows better support of refactoring and debugging and simply
let the developer use what he is familiar with: java.
The new kind of modules are defined by a simple class whose methods represent services, configurations, contributions etc.
The following example shows how multiple services are defined and wired. The method bodies are used as factory methods for the construction of the service implementations:
That example code correponds with this xml module (besides the interceptors).
The calculator service is autowired but alternatively could be wired manually:
How to load an annotated module in a registry
There are different ways to reach this goal:
Build a registry from annotated modules only
If the whole registry is built from annotated modules then the use of an AnnotatedRegistryBuilder is most comfortable:
The AnnotatedRegistryBuilder is a specialization of RegistryBuilder that accepts
a variable list of classes or class names. It returns a special TypedRegistry implementation
that makes use of generics. Note the lack of any cast on the service retrieval!
Build a registry from mixed definition types
This code shows how to mix modules defined by xml with annotated modules:
Autoload an annotated module
Autoloading is triggered by a call to RegistryBuilder#autoDetectModules or RegistryBuilder#constructDefaultRegistry.
If this process is already triggered in an application (for example by using HiveMindServletFilter) then it's possible to prepare a library (jar, war) that
can just be dropped into the classpath whereas include modules are loaded automatically.
Create a class that implements the RegistryProvider interface:
Add all annotated module classes to the call to readModule,
and finally add the name of the class to the hivemind-providers attribute in the file META-INF/MANIFEST.MF :
In future versions this will be easier and won't require an implementation of RegistryProvider.
Define configurations and contributions
The definition of configurations and contributions is as straightforward as the service definition. A configuration point is defined by the Configuration annotation:
The method marked with the Configuration method creates empty configuration data in
but it could already provide initial data.
A contribution from a different module references the id of the configuration and gets
a reference to the configuration data handed in.
The module id of an annotated module
The @Module annotation is optional. The id attribute defines the id of the module if the annotation is present.
If not, then the id is built from package and class name.
The Adder service in the followind example can be referenced by "calculator.Adder":
Whereas in the next example it can be referenced by "org.apache.hivemind.Adder":
Obtaining services and configurations
In the examples above other services and configurations are obtained by calls to the service and configuration methods defined
in the ancestor AbstractAnnotatedModule. It is not required to inherit from this class (see #Prerequisites).
If one doesn't want to inherit from this ancestor it is possible to get a reference to the registry injected automatically:
HiveMind checks if a module class implementes a property named "registry" and calls the corresponding
setter after a module instance has been created.
Don't call methods directly
It is not possible to obtain valid configuration or service references by calling the corresponding methods directly.
The instance returned is not controlled by HiveMind. It is no singleton, not intercepted etc.
Prerequisites for a module class
A module class
- must be public
- must not be final
- must not be abstract
- must have a public constructor without parameters
- should not execute login in its constructor
A module class need not inherit from AbstractAnnotatedModule above.
It can be any POJO conforming to the rules above. AbstractAnnotatedModule just offers convenience
methods for looking up services and configurations.