In the first major section of this guide, we provided an example of how to implement an extension to the AS. The emphasis there was learning by doing. In this section, we'll focus a bit more on the major AS 7 interfaces and classes that most are relevant to extension developers. The best way to learn about these interfaces and classes in detail is to look at their javadoc. What we'll try to do here is provide a brief introduction of the key items and how they relate to each other.
Before digging into this section, readers are encouraged to read the "Core Management Concepts" section of the Admin Guide.
The org.jboss.as.controller.Extension interface is the hook by which your extension to the core AS is able to integrate with the AS. During boot of the AS, when the <extension> element in the AS's xml configuration file naming your extension is parsed, the JBoss Modules module named in the element's name attribute is loaded. The standard JDK java.lang.ServiceLoader mechanism is then used to load your module's implementation of this interface.
The function of an Extension implementation is to register with the core AS the management API, xml parsers and xml marshallers associated with the extension module's subsystems. An Extension can register multiple subsystems, although the usual practice is to register just one per extension.
Once the Extension is loaded, the core AS will make two invocations upon it:
void initializeParsers(ExtensionParsingContext context)
When this is invoked, it is the Extension implementation's responsibility to initialize the XML parsers for this extension's subsystems and register them with the given ExtensionParsingContext. The parser's job when it is later called is to create org.jboss.dmr.ModelNode objects representing AS 7 management API operations needed make the AS's running configuration match what is described in the xml. Those management operation {{ModelNode}}s are added to a list passed in to the parser.
A parser for each version of the xml schema used by a subsystem should be registered. A well behaved subsystem should be able to parse any version of its schema that it has ever published in a final release.
void initialize(ExtensionContext context)
When this is invoked, it is the Extension implementation's responsibility to register with the core AS the management API for its subsystems, and to register the object that is capable of marshalling the subsystem's in-memory configuration back to XML. Only one XML marshaller is registered per subsystem, even though multiple XML parsers can be registered. The subsystem should always write documents that conform to the latest version of its XML schema.
The registration of a subsystem's management API is done via the ManagementResourceRegistration interface. Before discussing that interface in detail, let's describe how it (and the related Resource interface) relate to the notion of managed resources in the AS.
Each subsystem is responsible for managing one or more management resources. The conceptual characteristics of a management resource are covered in some detail in the Admin Guide; here we'll just summarize the main points. A management resource has
An address consisting of a list of key/value pairs that uniquely identifies a resource
Zero or more attributes, the value of which is some sort of org.jboss.dmr.ModelNode
Zero or more supported operations. An operation has a string name and zero or more parameters, each of which is a key/value pair where the key is a string naming the parameter and the value is some sort of ModelNode
Zero or children, each of which in turn is a managed resource
The implementation of a managed resource is somewhat analogous to the implementation of a Java object. A managed resource will have a "type", which encapsulates API information about that resource and logic used to implement that API. And then there are actual instances of the resource, which primarily store data representing the current state of a particular resource. This is somewhat analogous to the "class" and "object" notions in Java.
A managed resource's type is encapsulated by the org.jboss.as.controller.registry.ManagementResourceRegistration the core AS creates when the type is registered. The data for a particular instance is encapsulated in an implementation of the org.jboss.as.controller.registry.Resource interface.
TODO
TODO
Most commonly used implementation: SimpleResourceDefinition
TODO
Most commonly used implementation: StandardResourceDescriptionResolver
TODO
Most commmonly used implementation: SimpleAttributeDefinition. Use SimpleAttributeDefinitionBuilder to build.
TODO
TODO
TODO
TODO
TODO