Note prior to the 1.0 release, SPIs are subject to change
Fabric3 is architected as a small, modular kernel that can be extended to add additional functionality. Once the kernel is bootstrapped, the runtime is assembled from a series of extensions. As extensions are SCA components, it is more accurate to say that Fabric3 runtimes are SCA composites activated in a local domain.
This design allows the kernel to remain as concise as possible and avoids having the runtimes degenerate into a proverbial "ball of twine". The design also allows the kernel to be extended through a familiar (and powerful) programming model, namely the Java-based SCA programming model.
This guide provides a brief introduction to writing Fabric3 extensions, including coverage of key concepts common to all extension types. As this guide assumes knowledge of SCA, it is recommend you review the specifications before proceeding, particulary the Assembly Specification and Java Programming Model specifications found on the OSOA website.
Module Structure
Fabric3 is divided into a series of jars containing runtime APIs, SPIs, implementation classes, and extension classes. The relevant jars for extension developers are:
- fabric3-api - Annotation classes for Fabric3 extensions to the Java-based SCA programming model
- fabric3-host-api - The API for interacting with Fabric3 runtimes. This is typically used by hosts embedding Fabric3.
- fabric3-spi - The SPI for extensions developers
- fabric3-extensions - Helper classes for extension developers
Extensions should not reference Fabric3 classes in other jars as they are not part of the public SPI and are subject to change.
The System Implementation Type
Extending Fabric3 involves writing a component or set of SCA components, assembling them into a composite, and activating them in the local runtime domain. To assist with the specific requirements of writing infrastructure, as opposed to application, components, Fabric3 extends the standard Java SCA programming model by introducing a system component type. The system component type, implementation.system has the same semantics as implementation.java except for three important differences:
- System component types are composite scope, requiring them to be thread-safe. Other scopes such as stateless, request, and conversation are not supported.
- System component types are not proxied. Component references are set with the un-proxied target for performance reasons. This means interceptors and policy are not supported with system components.
- Callbacks are not supported.
Other than these exceptions, Fabric3 extensions follow the basic Java SCA programming model.
All extension components must be of type implementation.system as implementation.java will not necessarily be available when the extension is activated (the latter is an extension as well).
Monitoring
Fabric3 uses monitoring to report system events. A runtime may be configured to send monitor events to a logging subsystem or take some other action. To enable monitoring, define an interface and use the @Monitor tag to inject a monitor proxy:
@Monitor protected MyMonitor monitor; //.... public void doSomething() { //.... monitor.event("some event"); }
The default monitor implementation reports events using JDK logging. It suppots the use of the JDK logging @LogLevel annotation on interface methods.
Testing
Since the SCA programming and Fabric3 extension models are based on dependency injection, unit testing is straightforward: instantiate extension classes in a test case using mocks when appropriate. The Fabric3 runtime is not required (and should not be used) for unit testing. For automated mocking, we highly recommend EasyMock.
For integration testing, use the Fabric3 Maven Runtime, which provides the ability to launch an embedded Fabric3 runtime during the integration test phase of a Maven build.
Packaging
Extensions are packaged as jars with a composite and SCA deployable files in the META-INF directory. Third-party libraries (i.e. jars) may be bundled in an extension archive by placing them in the META-INF/lib directory. Fabric3 provides a Maven contribution plugin that automates the task of creating SCA archives. Non-Maven builds can create contribution archives by "manually" producing a jar file. For examples of how to use the contribution plugin, refer to the pom.xml file one of the existing extensions.
Installing
Installing an extension will vary by runtime distribution. For the standalone and development runtimes, extension archives are placed in the extensions directory. For the Maven integration test and web application runtimes, the appropriate plugin must be configured. Please refer to the individual runtime documentation for specifics of how to install extensions.