< Previous | Front page | Next >
Skip to end of metadata
Go to start of metadata

Target Audience

This document is intended for people who want to extend WildFly to introduce new capabilities.


You should know how to download, install and run WildFly. If not please consult the Getting Started Guide. You should also be familiar with the management concepts from the Admin Guide, particularly the Core management concepts section and you need Java development experience to follow the example in this guide.

Examples in this guide

Most of the examples in this guide are being expressed as excerpts of the XML configuration files or by using a representation of the de-typed management model.


In this document we provide an example of how to extend the kernel functionality of WildFly via an extension and the subsystem it installs. The WildFly kernel is very simple and lightweight; most of the capabilities people associate with an application server are provided via extensions and their subsystems. The WildFly distribution includes many extensions and subsystems; the webserver integration is via a subsystem; the transaction manager integration is via a subsystem, the EJB container integration is via a subsystem, etc.

This document is divided into two main sections. The first is focused on learning by doing. This section will walk you through the steps needed to create your own subsystem, and will touch on most of the concepts discussed elsewhere in this guide. The second focuses on a conceptual overview of the key interfaces and classes described in the example. Readers should feel free to start with the second section if that better fits their learning style. Jumping back and forth between the sections is also a good strategy.

Example subsystem

Our example subsystem will keep track of all deployments of certain types containing a special marker file, and expose operations to see how long these deployments have been deployed.

Create the skeleton project

To make your life easier we have provided a maven archetype which will create a skeleton project for implementing subsystems.

Maven will download the archetype and it's dependencies, and ask you some questions:

1 Enter the groupId you wish to use
2 Enter the artifactId you wish to use
3 Enter the version you wish to use, or just hit Enter if you wish to accept the default 1.0-SNAPSHOT
4 Enter the java package you wish to use, or just hit Enter if you wish to accept the default (which is copied from groupId).
5 Enter the module name you wish to use for your extension.
6 Finally, if you are happy with your choices, hit Enter and Maven will generate the project for you.

You can also do this in Eclipse, see Creating your own application for more details. We now have a skeleton project that you can use to implement a subsystem. Import the acme-subsystem project into your favourite IDE. A nice side-effect of running this in the IDE is that you can see the javadoc of WildFly classes and interfaces imported by the skeleton code. If you do a mvn install in the project it will work if we plug it into WildFly, but before doing that we will change it to do something more useful.

The rest of this section modifies the skeleton project created by the archetype to do something more useful, and the full code can be found in acme-subsystem.zip.

If you do a mvn install in the created project, you will see some tests being run

We will talk about these later in the Testing the parsers section.

Create the schema

First, let us define the schema for our subsystem. Rename src/main/resources/schema/mysubsystem.xsd to src/main/resources/schema/acme.xsd. Then open acme.xsd and modify it to the following

Note that we modified the xmlns and targetNamespace values to urn.com.acme.corp.tracker:1.0. Our new subsystem element has a child called deployment-types, which in turn can have zero or more children called deployment-type. Each deployment-type has a required suffix attribute, and a tick attribute which defaults to true.

Now modify the com.acme.corp.tracker.extension.SubsystemExtension class to contain the new namespace.

Design and define the model structure

The following example xml contains a valid subsystem configuration, we will see how to plug this in to WildFly later in this tutorial.

Now when designing our model, we can either do a one to one mapping between the schema and the model or come up with something slightly or very different. To keep things simple, let us stay pretty true to the schema so that when executing a :read-resource(recursive=true) against our subsystem we'll see something like:

Each deployment-type in the xml becomes in the model a child resource of the subsystem's root resource. The child resource's child-type is type, and it is indexed by its suffix. Each type resource then contains the tick attribute.

We also need a name for our subsystem, to do that change com.acme.corp.tracker.extension.SubsystemExtension:

Once we are finished our subsystem will be available under /subsystem=tracker.

The SubsystemExtension.initialize() method defines the model, currently it sets up the basics to add our subsystem to the model:

The registerSubsystem() call registers our subsystem with the extension context. At the end of the method we register our parser with the returned SubsystemRegistration to be able to marshal our subsystem's model back to the main configuration file when it is modified. We will add more functionality to this method later.

Registering the core subsystem model

Next we obtain a ManagementResourceRegistration by registering the subsystem model. This is a compulsory step for every new subsystem.

Its parameter is an implementation of the ResourceDefinition interface, which means that when you call /subsystem=tracker:read-resource-description the information you see comes from model that is defined by SubsystemDefinition.INSTANCE.

Since we need child resource type we need to add new ResourceDefinition,

The ManagementResourceRegistration obtained in SubsystemExtension.initialize() is then used to add additional operations or to register submodels to the /subsystem=tracker address. Every subsystem and resource must have an ADD method which can be achieved by the following line inside registerOperations in your ResourceDefinition or by providing it in constructor of your SimpleResourceDefinition just as we did in example above.

The parameters when registering an operation handler are:

  1. The name - i.e. ADD.
  2. The handler instance - we will talk more about this below
  3. The handler description provider - we will talk more about this below.
  4. Whether this operation handler is inherited - false means that this operation is not inherited, and will only apply to /subsystem=tracker. The content for this operation handler will be provided by 3.

Let us first look at the description provider which is quite simple since this operation takes no parameters. The addition of type children will be handled by another operation handler, as we will see later on.

There are two way to define DescriptionProvider, one is by defining it by hand using ModelNode, but as this has show to be very error prone there are lots of helper methods to help you automatically describe the model. Following example is done by manually defining Description provider for ADD operation handler

Or you can use API that helps you do that for you. For Add and Remove methods there are classes DefaultResourceAddDescriptionProvider and DefaultResourceRemoveDescriptionProvider that do work for you. In case you use SimpleResourceDefinition even that part is hidden from you.

For other operation handlers that are not add/remove you can use DefaultOperationDescriptionProvider that takes additional parameter of what is the name of operation and optional array of parameters/attributes operation takes. This is an example to register operation "add-mime" with two parameters:

When descriping an operation its description provider's OPERATION_NAME must match the name used when calling ManagementResourceRegistration.registerOperationHandler()

Next we have the actual operation handler instance, note that we have changed its populateModel() method to initialize the type child of the model.

SubsystemAdd also has a performBoottime() method which is used for initializing the deployer chain associated with this subsystem. We will talk about the deployers later on. However, the basic idea for all operation handlers is that we do any model updates before changing the actual runtime state.

The rule of thumb is that every thing that can be added, can also be removed so we have a remove handler for the subsystem registered
in SubsystemDefinition.registerOperations or just provide the operation handler in constructor.

SubsystemRemove extends AbstractRemoveStepHandler which takes care of removing the resource from the model so we don't need to override its performRemove() operation, also the add handler did not install any services (services will be discussed later) so we can delete the performRuntime() method generated by the archetype.

The description provider for the remove operation is simple and quite similar to that of the add handler where just name of the method changes.

Registering the subsystem child

The type child does not exist in our skeleton project so we need to implement the operations to add and remove them from the model.

First we need an add operation to add the type child, create a class called com.acme.corp.tracker.extension.TypeAddHandler. In this case we extend the org.jboss.as.controller.AbstractAddStepHandler class and implement the org.jboss.as.controller.descriptions.DescriptionProvider interface. org.jboss.as.controller.OperationStepHandler is the main interface for the operation handlers, and AbstractAddStepHandler is an implementation of that which does the plumbing work for adding a resource to the model.

Then we define subsystem model. Lets call it TypeDefinition and for ease of use let it extend SimpleResourceDefinition instead just implement ResourceDefinition.

Which will take care of describing the model for us. As you can see in example above we define SimpleAttributeDefinition named TICK, this is a mechanism to define Attributes in more type safe way and to add more common API to manipulate attributes. As you can see here we define default value of 1000 as also other constraints and capabilities. There could be other properties set such as validators, alternate names, xml name, flags for marking it attribute allows expressions and more.

Then we do the work of updating the model by implementing the populateModel() method from the AbstractAddStepHandler, which populates the model's attribute from the operation parameters. First we get hold of the model relative to the address of this operation (we will see later that we will register it against /subsystem=tracker/type=*), so we just specify an empty relative address, and we then populate our model with the parameters from the operation. There is operation validateAndSet on AttributeDefinition that helps us validate and set the model based on definition of the attribute.

We then override the performRuntime() method to perform our runtime changes, which in this case involves installing a service into the controller at the heart of WildFly. (AbstractAddStepHandler.performRuntime() is similar to AbstractBoottimeAddStepHandler.performBoottime() in that the model is updated before runtime changes are made.

Since the add methods will be of the format /subsystem=tracker/suffix=war:add(tick=1234), we look for the last element of the operation address, which is war in the example just given and use that as our suffix. We then create an instance of TrackerService and install that into the service target of the context and add the created service controller to the newControllers list.

The tracker service is quite simple. All services installed into WildFly must implement the org.jboss.msc.service.Service interface.

We then have some fields to keep the tick count and a thread which when run outputs all the deployments registered with our service.

Next we have three methods which come from the Service interface. getValue() returns this service, start() is called when the service is started by the controller, stop is called when the service is stopped by the controller, and they start and stop the thread outputting the deployments.

Next we have a utility method to create the ServiceName which is used to register the service in the controller.

Finally we have some methods to add and remove deployments, and to set and read the tick. The 'cool' deployments will be explained later.

Since we are able to add type children, we need a way to be able to remove them, so we create a com.acme.corp.tracker.extension.TypeRemoveHandler. In this case we extend AbstractRemoveStepHandler which takes care of removing the resource from the model so we don't need to override its performRemove() operationa. But we need to implement the DescriptionProvider method to provide the model description, and since the add handler installs the TrackerService, we need to remove that in the performRuntime() method.

We then need a description provider for the type part of the model itself, so we modify TypeDefinitnion to registerAttribute

Then finally we need to specify that our new type child and associated handlers go under /subsystem=tracker/type=* in the model by adding registering it with the model in SubsystemExtension.initialize(). So we add the following just before the end of the method.

The above first creates a child of our main subsystem registration for the relative address type=*, and gets the typeChild registration.
To this we add the TypeAddHandler and TypeRemoveHandler.
The add variety is added under the name add and the remove handler under the name remove, and for each registered operation handler we use the handler singleton instance as both the handler parameter and as the DescriptionProvider.

Finally, we register tick as a read/write attribute, the null parameter means we don't do anything special with regards to reading it, for the write handler we supply it with an operation handler called TrackerTickHandler.
Registering it as a read/write attribute means we can use the :write-attribute operation to modify the value of the parameter, and it will be handled by TrackerTickHandler.

Not registering a write attribute handler makes the attribute read only.

TrackerTickHandler extends AbstractWriteAttributeHandler
directly, and so must implement its applyUpdateToRuntime and revertUpdateToRuntime method.
This takes care of model manipulation (validation, setting) but leaves us to do just to deal with what we need to do.

The operation used to execute this will be of the form /subsystem=tracker/type=war:write-attribute(name=tick,value=12345) so we first get the suffix from the operation address, and the tick value from the operation parameter's resolvedValue parameter, and use that to update the model.

We then add a new step associated with the RUNTIME stage to update the tick of the TrackerService for our suffix. This is essential since the call to context.getServiceRegistry() will fail unless the step accessing it belongs to the RUNTIME stage.

When implementing execute(), you must call context.completeStep() when you are done.

Parsing and marshalling of the subsystem xml

WildFly uses the Stax API to parse the xml files. This is initialized in SubsystemExtension by mapping our parser onto our namespace:

We then need to write the parser. The contract is that we read our subsystem's xml and create the operations that will populate the model with the state contained in the xml. These operations will then be executed on our behalf as part of the parsing process. The entry point is the readElement() method.

So in the above we always create the add operation for our subsystem. Due to its address /subsystem=tracker defined by SUBSYSTEM_PATH this will trigger the SubsystemAddHandler we created earlier when we invoke /subsystem=tracker:add. We then parse the child elements and create an add operation for the child address for each type child. Since the address will for example be /subsystem=tracker/type=sar (defined by TYPE_PATH ) and TypeAddHandler is registered for all type subaddresses the TypeAddHandler will get invoked for those operations. Note that when we are parsing attribute tick we are using definition of attribute that we defined in TypeDefintion to parse attribute value and apply all rules that we specified for this attribute, this also enables us to property support expressions on attributes.

The parser is also used to marshal the model to xml whenever something modifies the model, for which the entry point is the writeContent() method:

Then we have to implement the SubsystemDescribeHandler which translates the current state of the model into operations similar to the ones created by the parser. The SubsystemDescribeHandler is only used when running in a managed domain, and is used when the host controller queries the domain controller for the configuration of the profile used to start up each server. In our case the SubsystemDescribeHandler adds the operation to add the subsystem and then adds the operation to add each type child. Since we are using ResourceDefinitinon for defining subsystem all that is generated for us, but if you want to customize that you can do it by implementing it like this.

Testing the parsers

Changes to tests between 7.0.0 and 7.0.1
The testing framework was moved from the archetype into the core JBoss AS 7 sources between JBoss AS 7.0.0 and JBoss AS 7.0.1, and has been improved upon and is used internally for testing JBoss AS 7's subsystems. The differences between the two versions is that in 7.0.0.Final the testing framework is bundled with the code generated by the archetype (in a sub-package of the package specified for your subsystem, e.g. com.acme.corp.tracker.support), and the test extends the AbstractParsingTest class.

From 7.0.1 the testing framework is now brought in via the org.jboss.as:jboss-as-subsystem-test maven artifact, and the test's superclass is org.jboss.as.subsystem.test.AbstractSubsystemTest. The concepts are the same but more and more functionality will be available as JBoss AS 7 is developed.

Now that we have modified our parsers we need to update our tests to reflect the new model. There are currently three tests testing the basic functionality, something which is a lot easier to debug from your IDE before you plug it into the application server. We will talk about these tests in turn and they all live in com.acme.corp.tracker.extension.SubsystemParsingTestCase. SubsystemParsingTestCase extends AbstractSubsystemTest which does a lot of the setup for you and contains utility methods for verifying things from your test. See the javadoc of that class for more information about the functionality available to you. And by all means feel free to add more tests for your subsystem, here we are only testing for the best case scenario while you will probably want to throw in a few tests for edge cases.

The first test we need to modify is testParseSubsystem(). It tests that the parsed xml becomes the expected operations that will be parsed into the server, so let us tweak this test to match our subsystem. First we tell the test to parse the xml into operations

There should be one operation for adding the subsystem itself and an operation for adding the deployment-type, so check we got two operations

Now check that the first operation is add for the address /subsystem=tracker:

Then check that the second operation is add for the address /subsystem=tracker, and that 12345 was picked up for the value of the tick parameter:

The second test we need to modify is testInstallIntoController() which tests that the xml installs properly into the controller. In other words we are making sure that the add operations we created earlier work properly. First we create the xml and install it into the controller. Behind the scenes this will parse the xml into operations as we saw in the last test, but it will also create a new controller and boot that up using the created operations

The returned KernelServices allow us to execute operations on the controller, and to read the whole model.

Now we make sure that the structure of the model within the controller has the expected format and values

The last test provided is called testParseAndMarshalModel(). It's main purpose is to make sure that our SubsystemParser.writeContent() works as expected. This is achieved by starting a controller in the same way as before

Now we read the model and the xml that was persisted from the first controller, and use that xml to start a second controller

Finally we read the model from the second controller, and make sure that the models are identical by calling compare() on the test superclass.

We then have a test that needs no changing from what the archetype provides us with. As we have seen before we start a controller

We then call /subsystem=tracker:describe which outputs the subsystem as operations needed to reach the current state (Done by our SubsystemDescribeHandler)

Then we create a new controller using those operations

And then we read the model from the second controller and make sure that the two subsystems are identical
ModelNode modelB = servicesB.readWholeModel();

To test the removal of the the subsystem and child resources we modify the testSubsystemRemoval() test provided by the archetype:

We provide xml for the subsystem installing a child, which in turn installs a TrackerService

Having installed the xml into the controller we make sure the TrackerService is there

This call from the subsystem test harness will call remove for each level in our subsystem, children first and validate
that the subsystem model is empty at the end.

Finally we check that all the services were removed by the remove handlers

For good measure let us throw in another test which adds a deployment-type and also changes its attribute at runtime. So first of all boot up the controller with the same xml we have been using so far

Now create an operation which does the same as the following CLI command /subsystem=tracker/type=foo:add(tick=1000)

Execute the operation and make sure it was successful

Read the whole model and make sure that the original data is still there (i.e. the same as what was done by testInstallIntoController()

Then make sure our new type has been added:

Then we call write-attribute to change the tick value of /subsystem=tracker/type=foo:

To give you exposure to other ways of doing things, now instead of reading the whole model to check the attribute, we call read-attribute instead, and make sure it has the value we set it to.

Since each type installs its own copy of TrackerService, we get the TrackerService for type=foo from the service container exposed by the kernel services and make sure it has the right value


Add the deployers

When discussing SubsystemAddHandler we did not mention the work done to install the deployers, which is done in the following method:

This adds an extra step which is responsible for installing deployment processors. You can add as many as you like, or avoid adding any all together depending on your needs. Each processor has a Phase and a priority. Phases are sequential, and a deployment passes through each phases deployment processors. The priority specifies where within a phase the processor appears. See org.jboss.as.server.deployment.Phase for more information about phases.

In our case we are keeping it simple and staying with one deployment processor with the phase and priority created for us by the maven archetype. The phases will be explained in the next section. The deployment processor is as follows:

The deploy() method is called when a deployment is being deployed. In this case we look for the TrackerService instance for the service name created from the deployment's suffix. If there is one it means that we are meant to be tracking deployments with this suffix (i.e. TypeAddHandler was called for this suffix), and if we find one we add the deployment's name to it. Similarly undeploy() is called when a deployment is being undeployed, and if there is a TrackerService instance for the deployment's suffix, we remove the deployment's name from it.

Deployment phases and attachments

The code in the SubsystemDeploymentProcessor uses an attachment, which is the means of communication between the individual deployment processors. A deployment processor belonging to a phase may create an attachment which is then read further along the chain of deployment unit processors. In the above example we look for the Attachments.DEPLOYMENT_ROOT attachment, which is a view of the file structure of the deployment unit put in place before the chain of deployment unit processors is invoked.

As mentioned above, the deployment unit processors are organized in phases, and have a relative order within each phase. A deployment unit passes through all the deployment unit processors in that order. A deployment unit processor may choose to take action or not depending on what attachments are available. Let's take a quick look at what the deployment unit processors for in the phases described in org.jboss.as.server.deployment.Phase.


The deployment unit processors in this phase determine the structure of a deployment, and looks for sub deployments and metadata files.


In this phase the deployment unit processors parse the deployment descriptors and build up the annotation index. Class-Path entries from the META-INF/MANIFEST.MF are added.


Extra class path dependencies are added. For example if deploying a war file, the commonly needed dependencies for a web application are added.


In this phase the modular class loader for the deployment is created. No attempt should be made loading classes from the deployment until after this phase.


Now that our class loader has been constructed we have access to the classes. In this stage deployment processors may use the Attachments.REFLECTION_INDEX attachment which is a deployment index used to obtain members of classes in the deployment, and to invoke upon them, bypassing the inefficiencies of using java.lang.reflect directly.


Install new services coming from the deployment.


Attachments put in place earlier in the deployment unit processor chain may be removed here.

Integrate with WildFly

Now that we have all the code needed for our subsystem, we can build our project by running mvn install

This will have built our project and assembled a module for us that can be used for installing it into WildFly. If you go to the target/module folder where you built the project you will see the module

The module.xml comes from src/main/resources/module/main/module.xml and is used to define your module. It says that it contains the acme-subsystem.jar:

And has a default set of dependencies needed by every subsystem created. If your subsystem requires additional module dependencies you can add them here before building and installing.

Note that the name of the module corresponds to the directory structure containing it. Now copy the target/module/com/acme/corp/tracker/main/ directory and its contents to $WFLY/modules/com/acme/corp/tracker/main/ (where $WFLY is the root of your WildFly install).

Next we need to modify $WFLY/standalone/configuration/standalone.xml. First we need to add our new module to the <extensions> section:

And then we have to add our subsystem to the <profile> section:

Adding this to a managed domain works exactly the same apart from in this case you need to modify $WFLY/domain/configuration/domain.xml.

Now start up WildFly by running $WFLY/bin/standalone.sh and you should see messages like these after the server has started, which means our subsystem has been added and our TrackerService is working:

If you run the command line interface you can execute some commands to see more about the subsystem. For example

will return a lot of information, including what we provided in the DescriptionProviders we created to document our subsystem.

To see the current subsystem state you can execute

We can remove both the deployment types which removes them from the model:

You should now see the output from the TrackerService instances having stopped.

Now, let's add the war tracker again:

and the WildFly console should show the messages coming from the war TrackerService again.

Now let us deploy something. You can find two maven projects for test wars already built at test1.zip and test2.zip. If you download them and extract them to /Downloads/test1 and /Downloads/test2, you can see that /Downloads/test1/target/test1.war contains a META-INF/cool.txt while /Downloads/test2/target/test2.war does not contain that file. From CLI deploy test1.war first:

And you should now see the output from the war TrackerService list the deployments:

So our test1.war got picked up as a 'cool' deployment. Now if we deploy test2.war

You will see that deployment get picked up as well but since there is no META-INF/cool.txt it is not marked as a 'cool' deployment:

An undeploy

is also reflected in the TrackerService output:

Finally, we registered a write attribute handler for the tick property of the type so we can change the frequency

You should now see the output from the TrackerService happen every second

If you open $WFLY/standalone/configuration/standalone.xml you can see that our subsystem entry reflects the current state of the subsystem:


Expressions are mechanism that enables you to support variables in your attributes, for instance when you want the value of attribute to be resolved using system / environment properties.

An example expression is

which means that the value should be taken from a system property named jboss.bind.address.management and if it is not defined use

What expression types are supported

  • System properties, which are resolved using java.lang.System.getProperty(String key)
  • Environment properties, which are resolved using java.lang.System.getEnv(String name).
  • Security vault expressions, resolved against the security vault configured for the server or Host Controller that needs to resolve the expression.

In all cases, the syntax for the expression is

For an expression meant to be resolved against environment properties, the expression_to_resolve must be prefixed with env.. The portion after env. will be the name passed to java.lang.System.getEnv(String name).

Security vault expressions do not support default values (i.e. the in the jboss.bind.address.management: example above.)

How to support expressions in subsystems

The easiest way is by using AttributeDefinition, which provides support for expressions just by using it correctly.

When we create an AttributeDefinition all we need to do is mark that is allows expressions. Here is an example how to define an attribute that allows expressions to be used.

Then later when you are parsing the xml configuration you should use the MY_ATTRIBUTE attribute definition to set the value to the management operation ModelNode you are creating.

Note that this just helps you to properly set the value to the model node you are working on, so no need to additionally set anything to the model for this attribute. Method parseAndSetParameter parses the value that was read from xml for possible expressions in it and if it finds any it creates special model node that defines that node is of type ModelType.EXPRESSION.

Later in your operation handlers where you implement populateModel and have to store the value from the operation to the configuration model you also use this MY_ATTRIBUTE attribute definition.

This will make sure that the attribute that is stored from the operation to the model is valid and nothing is lost. It also checks the value stored in the operation ModelNode, and if it isn't already ModelType.EXPRESSION, it checks if the value is a string that contains the expression syntax. If so, the value stored in the model will be of type ModelType.EXPRESSION. Doing this ensures that expressions are properly handled when they appear in operations that weren't created by the subsystem parser, but are instead passed in from CLI or admin console users.

As last step we need to use the value of the attribute. This is usually needed inside of the performRuntime method

As you can see resolving of attribute's value is not done until it is needed for use in the subsystem's runtime services. The resolved value is not stored in the configuration model, the unresolved expression is. That way we do not lose any information in the model and can assure that also marshalling is done properly, where we must marshall back the unresolved value.

Attribute definitinon also helps you with that:

Working with WildFly Capabilities

An extension to WildFly will likely want to make use of services provided by the WildFly kernel, may want to make use of services provided by other subsystems, and may wish to make functionality available to other extensions. Each of these cases involves integration between different parts of the system. In releases prior to WildFly 10, this kind of integration was done on an ad-hoc basis, resulting in overly tight coupling between different parts of the system and overly weak integration contracts. For example, a service installed by subsystem A might depend on a service installed by subsystem B, and to record that dependency A's authors copy a ServiceName from B's code, or even refer to a constant or static method from B's code. The result is B's code cannot evolve without risking breaking A. And the authors of B may not even intend for other subsystems to use its services. There is no proper integration contract between the two subsystems.

Beginning with WildFly Core 2 and WildFly 10 the WildFly kernel's management layer provides a mechanism for allowing different parts of the system to integrate with each other in a loosely coupled manner. This is done via WildFly Capabilities. Use of capabilities provides the following benefits:

  1. A standard way for system components to define integration contracts for their use by other system components.
  2. A standard way for system components to access integration contracts provided by other system components.
  3. A mechanism for configuration model referential integrity checking, such that if one component's configuration has an attribute that refers to an other component (e.g. a socket-binding attribute in a subsystem that opens a socket referring to that socket's configuration), the validity of that reference can be checked when validating the configuration model.


A capability is a piece of functionality used in a WildFly Core based process that is exposed via the WildFly Core management layer. Capabilities may depend on other capabilities, and this interaction between capabilities is mediated by the WildFly Core management layer.

Some capabilities are automatically part of a WildFly Core based process, but in most cases the configuration provided by the end user (i.e. in standalone.xml, domain.xml and host.xml) determines what capabilities are present at runtime. It is the responsibility of the handlers for management operations to register capabilities and to register any requirements those capabilities may have for the presence of other capabilities. This registration is done during the MODEL stage of operation execution

A capability has the following basic characteristics:

  1. It has a name.
  2. It may install an MSC service that can be depended upon by services installed by other capabilities. If it does, it provides a mechanism for discovering the name of that service.
  3. It may expose some other API not based on service dependencies allowing other capabilities to integrate with it at runtime.
  4. It may depend on, or require other capabilities.

During boot of the process, and thereafter whenever a management operation makes a change to the process' configuration, at the end of the MODEL stage of operation execution the kernel management layer will validate that all capabilities required by other capabilities are present, and will fail any management operation step that introduced an unresolvable requirement. This will be done before execution of the management operation proceeds to the RUNTIME stage, where interaction with the process' MSC Service Container is done. As a result, in the RUNTIME stage the handler for an operation can safely assume that the runtime services provided by a capability for which it has registered a requirement are available.

Comparison to other concepts

Capabilities vs modules

A JBoss Modules module is the means of making resources available to the classloading system of a WildFly Core based process. To make a capability available, you must package its resources in one or more modules and make them available to the classloading system. But a module is not a capability in and of itself, and simply copying a module to a WildFly installation does not mean a capability is available. Modules can include resources completely unrelated to management capabilities.

Capabilities vs Extensions

An extension is the means by which the WildFly Core management layer is made aware of manageable functionality that is not part of the WildFly Core kernel. The extension registers with the kernel new management resource types and handlers for operations on those resources. One of the things a handler can do is register or unregister a capability and its requirements. An extension may register a single capability, multiple capabilities, or possibly none at all. Further, not all capabilities are registered by extensions; the WildFly Core kernel itself may register a number of different capabilities.

Capability Names

Capability names are simple strings, with the dot character serving as a separator to allow namespacing.

The 'org.wildfly' namespace is reserved for projects associated with the WildFly organization on github (https://github.com/wildfly).

Statically vs Dynamically Named Capabilities

The full name of a capability is either statically known, or it may include a statically known base element and then a dynamic element. The dynamic part of the name is determined at runtime based on the address of the management resource that registers the capability. For example, the management resource at the address '/socket-binding-group=standard-sockets/socket-binding=web' will register a dynamically named capability named 'org.wildlfy.network.socket-binding.web'. The 'org.wildlfy.network.socket-binding' portion is the static part of the name.

All dynamically named capabilities that have the same static portion of their name should provide a consistent feature set and set of requirements.

Service provided by a capability

Typically a capability functions by registering a service with the WildFly process' MSC ServiceContainer, and then dependent capabilities depend on that service. The WildFly Core management layer orchestrates registration of those services and service dependencies by providing a means to discover service names.

Custom integration APIs provided by a capability

Instead of or in addition to providing MSC services, a capability may expose some other API to dependent capabilities. This API must be encapsulated in a single class (although that class can use other non-JRE classes as method parameters or return types).

Capability Requirements

A capability may rely on other capabilities in order to provide its functionality at runtime. The management operation handlers that register capabilities are also required to register their requirements.

There are three basic types of requirements a capability may have:

  • Hard requirements. The required capability must always be present for the dependent capability to function.
  • Optional requirements. Some aspect of the configuration of the dependent capability controls whether the depended on capability is actually necessary. So the requirement cannot be known until the running configuration is analyzed.
  • Runtime-only requirements. The dependent capability will check for the presence of the depended upon capability at runtime, and if present it will utilize it, but if it is not present it will function properly without the capability. There is nothing in the dependent capability's configuration that controls whether the depended on capability must be present. Only capabilities that declare themselves as being suitable for use as a runtime-only requirement should be depended upon in this manner.

Hard and optional requirements may be for either statically named or dynamically named capabilities. Runtime-only requirements can only be for statically named capabilities, as such a requirement cannot be specified via configuration, and without configuration the dynamic part of the required capability name is unknown.

Supporting runtime-only requirements

Not all capabilities are usable as a runtime-only requirement.

Any dynamically named capability is not usable as a runtime-only requirement.

For a capability to support use as a runtime-only requirement, it must guarantee that a configuration change to a running process that removes the capability will not impact currently running capabilities that have a runtime-only requirement for it. This means:

  • A capability that supports runtime-only usage must ensure that it never removes its runtime service except via a full process reload.
  • A capability that exposes a custom integration API generally is not usable as a runtime-only requirement. If such a capability does support use as a runtime-only requirement, it must ensure that any functionality provided via its integration API remains available as long as a full process reload has not occurred.

Capability Contract

A capability provides a stable contract to users of the capability. The contract includes the following:

  • The name of the capability (including whether it is dynamically named).
  • Whether it installs an MSC Service, and if it does, the value type of the service. That value type then becomes a stable API users of the capability can rely upon.
  • Whether it provides a custom integration API, and if it does, the type that represents that API. That type then becomes a stable API users of the capability can rely upon.
  • Whether the capability supports use as a runtime-only requirement.

Developers can learn about available capabilities and the contracts they provide by reading the WildFly capabilty registry.

Capability Registry

The WildFly organization on github maintains a git repo where information about available capabilities is published.


Developers can learn about available capabilities and the contracts they provide by reading the WildFly capabilty registry.

The README.md file at the root of that repo explains the how to find out information about the registry.

Developers of new capabilities are strongly encouraged to document and register their capability by submitting a pull request to the wildfly-capabilities github repo. This both allows others to learn about your capability and helps prevent capability name collisions. Capabilities that are used in the WildFly or WildFly Core code base itself must have a registry entry before the code referencing them will be merged.

External organizations that create capabilities should include an organization-specific namespace as part their capability names to avoid name collisions.

Using Capabilities

Now that all the background information is presented, here are some specifics about how to use WildFly capabilities in your code.

Basics of Using Your Own Capability

Creating your capability

A capability is an instance of the immutable org.jboss.as.controller.capability.RuntimeCapability class. A capability is usually registered by a resource, so the usual way to use one is to store it in constant in the resource's ResourceDefinition. Use a RuntimeCapability.Builder to create one.

That creates a statically named capability named com.example.foo.

If the capability is dynamically named, add the dynamic parameter to state this:

Most capabilities install a service that requiring capabilities can depend on. If your capability does this, you need to declare the service's value type (the type of the object returned by org.jboss.msc.Service.getValue()). For example, if FOO_CAPABILITY provides a Service<javax.sql.DataSource>:

For a dynamic capability:

If the capability provides a custom integration API, you need to instantiate an instance of that API:

and provide it to the builder:

For a dynamic capability:

A capability can provide both a custom integration API and install a service:

Registering and unregistering your capability

Once you have your capability, you need to ensure it gets registered with the WildFly Core kernel when your resource is added. This is easily done simply by providing a reference to the capability to the resource's ResourceDefinition. This assumes your resource definition is a subclass of the standard org.jboss.as.controller.SimpleResourceDefinition. SimpleResourceDefinition provides a Parameters class that provides a builder-style API for setting up all the data needed by your definition. This includes a setCapabilities method that can be used to declare the capabilities provided by resources of this type.

Your add handler needs to extend the standard org.jboss.as.controller.AbstractAddStepHandler class or one of its subclasses:

AbstractAddStepHandler's logic will register the capability when it executes.

Your remove handler must also extend of the standard org.jboss.as.controller.AbstractRemoveStepHandler or one of its subclasses.

AbstractRemoveStepHandler's logic will deregister the capability when it executes.

If for some reason you cannot base your ResourceDefinition on SimpleResourceDefinition or your handlers on AbstractAddStepHandler and AbstractRemoveStepHandler then you will need to take responsibility for registering the capability yourself. This is not expected to be a common situation. See the implementation of those classes to see how to do it.

Installing, accessing and removing the service provided by your capability

If your capability installs a service, you should use the RuntimeCapability when you need to determine the service's name. For example in the Stage.RUNTIME handling of your "add" step handler. Here's an example for a statically named capability:

If the capability is dynamically named, get the dynamic part of the name from the OperationContext and use that when getting the service name:

The same patterns should be used when accessing or removing the service in handlers for remove, write-attribute and custom operations.

If you use ServiceRemoveStepHandler for the remove operation, simply provide your RuntimeCapability to the ServiceRemoveStepHandler constructor and it will automatically remove your capability's service when it executes.

Basics of Using Other Capabilities

When a capability needs another capability, it only refers to it by its string name. A capability should not reference the RuntimeCapability object of another capability.

Before a capability can look up the service name for a required capability's service, or access its custom integration API, it must first register a requirement for the capability. This must be done in Stage.MODEL, while service name lookups and accessing the custom integration API is done in Stage.RUNTIME.

Registering a requirement for a capability is simple.

Registering a hard requirement for a static capability

If your capability has a hard requirement for a statically named capability, simply declare that to the builder for your RuntimeCapability. For example, WildFly's JTS capability requires both a basic transaction support capability and IIOP capabilities:

When your capability is registered with the system, the WildFly Core kernel will automatically register any static hard requirements declared this way.

Registering a requirement for a dynamically named capability

If the capability you require is dynamically named, usually your capability's resource will include an attribute whose value is the dynamic part of the required capability's name. You should declare this fact in the AttributeDefinition for the attribute using the SimpleAttributeDefinitionBuilder.setCapabilityReference method.

For example, the WildFly "remoting" subsystem's "org.wildfly.remoting.connector" capability has a requirement for a dynamically named socket-binding capability:

If the "add" operation handler for your resource extends AbstractAddStepHandler and the handler for write-attribute extends AbstractWriteAttributeHandler, the declaration above is sufficient to ensure that the appropriate capability requirement will be registered when the attribute is modified.

Depending upon a service provided by another capability

Once the requirement for the capability is registered, your OperationStepHandler can use the OperationContext to discover the name of the service provided by the required capability.

For example, the "add" handler for a remoting connector uses the OperationContext to find the name of the needed {{SocketBinding} service:

That service name is then used to add a dependency on the SocketBinding service to the remoting connector service.

If the required capability isn't dynamically named, OperationContext exposes an overloaded getCapabilityServiceName variant. For example, if a capability requires a remoting Endpoint:

Using a custom integration API provided by another capability

In your Stage.RUNTIME handler, use OperationContext.getCapabilityRuntimeAPI to get a reference to the required capability's custom integration API. Then use it as necessary.

Runtime-only requirements

If your capability has a runtime-only requirement for another capability, that means that if that capability is present in Stage.RUNTIME you'll use it, and if not you won't. There is nothing about the configuration of your capability that triggers the need for the other capability; you'll just use it if it's there.

In this case, use OperationContext.hasOptionalCapability in your Stage.RUNTIME handler to check if the capability is present:

The WildFly Core kernel will not register a requirement for the "com.example.bar" capability, so if a configuration change occurs that means that capability will no longer be present, that change will not be rolled back. Because of this, runtime-only requirements can only be used with capabilities that declare in their contract that they support such use.

Using a capability in a DeploymentUnitProcessor

A DeploymentUnitProcessor is likely to have a need to interact with capabilities, in order to create service dependencies from a deployment service to a capability provided service or to access some aspect of a capability's custom integration API that relates to deployments.

If a DeploymentUnitProcessor associated with a capability implementation needs to utilize its own capability object, the DeploymentUnitProcessor authors should simply provide it with a reference to the RuntimeCapability instance. Service name lookups or access to the capabilities custom integration API can then be performed by invoking the methods on the RuntimeCapability.

If you need to access service names or a custom integration API associated with a different capability, you will need to use the org.jboss.as.controller.capability.CapabilityServiceSupport object associated with the deployment unit. This can be found as an attachment to the DeploymentPhaseContext:

Once you have the CapabilityServiceSupport you can use it to look up service names:

It's important to note that when you request a service name associated with a capability, the CapabilityServiceSupport will give you one regardless of whether the capability is actually registered with the kernel. If the capability isn't present, any service dependency your DUP creates using that service name will eventually result in a service start failure, due to the missing dependency. This behavior of not failing immediately when the capability service name is requested is deliberate. It allows deployment operations that use the rollback-on-runtime-failure=false header to successfully install (but not start) all of the services related to a deployment. If a subsequent operation adds the missing capability, the missing service dependency problem will then be resolved and the MSC service container will automatically start the deployment services.

You can also use the CapabilityServiceSupport to obtain a reference to the capability's custom integration API:

Note that here, unlike the case with service name lookups, the CapabilityServiceSupport will throw a checked exception if the desired capability is not installed. This is because the kernel has no way to satisfy the request for a custom integration API if the capability is not installed. The DeploymentUnitProcessor will need to catch and handle the exception.

Detailed API

The WildFly Core kernel's API for using capabilities is covered in detail in the javadoc for the RuntimeCapability and RuntimeCapability.Builder classes and the OperationContext and CapabilityServiceSupport interfaces.

Many of the methods in OperationContext related to capabilities have to do with registering capabilities or registering requirements for capabilities. Typically non-kernel developers won't need to worry about these, as the abstract OperationStepHandler implementations provided by the kernel take care of this for you, as described in the preceding sections. If you do find yourself in a situation where you need to use these in an extension, please read the javadoc thoroughly.

Domain mode subsystem transformers


A WildFly domain may consist of a new Domain Controller (DC) controlling slave Host Controllers (HC) running older versions. Each slave HC maintains a copy of the centralized domain configuration, which they use for controlling their own servers. In order for the slave HCs to understand the configuration from the DC, transformation is needed, whereby the DC translates the configuration and operations into something the slave HCs can understand.


WildFly comes with a domain mode which allows you to have one Host Controller acting as the Domain Controller. The Domain Controller's job is to maintain the centralized domain configuration. Another term for the DC is 'Master Host Controller'. Before explaining why transformers are important and when they should be used, we will revisit how the domain configuration is used in domain mode.

The centralized domain configuration is stored in domain.xml. This is only ever parsed on the DC, and it has the following structure:

  • extensions - contains:
    • extension - a references to a module that bootstraps the org.jboss.as.controller.Extension implementation used to bootstrap your subsystem parsers and initialize the resource definitions for your subsystems.
  • profiles - contains:
    • profile - a named set of:
      • subsystem - contains the configuration for a subsystem, using the parser initialized by the subsystem's extension.
  • socket-binding-groups - contains:
    • socket-binding-group - a named set of:
      • socket-binding - A named port on an interface which can be referenced from the subsystem configurations for subsystems opening sockets.
  • server-groups - contains
    • server-group - this has a name and references a profile and a socket-binding-group. The HCs then reference the server-group name from their <servers> section in host.xml.

When the DC parses domain.xml, it is transformed into add (and in some cases write-attribute) operations just as explained in Parsing and marshalling of the subsystem xml. These operations build up the model on the DC.

A HC wishing to join the domain and use the DC's centralized configuration is known as a 'slave HC'. A slave HC maintains a copy of the DC's centralized domain configuration. This copy of the domain configuration is used to start its servers. This is done by asking the domain model to describe itself, which in turn asks the subsystems to describe themselves. The describe operation for a subsystem looks at the state of the subsystem model and produces the add operations necessary to create the subsystem on the server. The same mechanism also takes place on the DC (bear in mind that the DC is also a HC, which can have its own servers), although of course its copy of the domain configuration is the centralized one.

There are two steps involved in keeping the keeping the slave HC's domain configuration in sync with the centralized domain configuration.

  • getting the initial domain model
  • an operation changes something in the domain configuration

Let's look a bit closer at what happens in each of these steps.

Getting the initial domain model

When a slave HC connects to the DC it obtains a copy of the domain model from the DC. This is done in a simpler serialized format, different from the operations that built up the model on the DC, or the operations resulting from the describe step used to bootstrap the servers. They describe each address that exists in the DC's model, and contain the attributes set for the resource at that address. This serialized form looks like this:

The slave HC then applies these one at a time and builds up the initial domain model. It needs to do this before it can start any of its servers.

An operation changes something in the domain configuration

Once a domain is up and running we can still change things in the domain configuration. These changes must happen when connected to the DC, and are then propagated to the slave HCs, which then in turn propagate the changes to any servers running in a server group affected by the changes made. In this example:

the DC propagates the changes to itself host=master, which in turn propagates it to its two servers belonging to main-server-group which uses the full profile. More interestingly, it also propagates it to host=slave which updates its local copy of the domain model, and then propagates the change to its server-one which belongs to main-server-group which uses the full profile.

Versions and backward compatibility

A HC and its servers will always be the same version of WildFly (they use the same module path and jars). However, the DC and the slave HCs do not necessarily need to be the same version. One of the points in the original specification for WildFly is that

A Domain Controller should be able to manage slave Host Controllers older than itself.

This means that for example a WildFly 10.1 DC should be able to work with slave HCs running WildFly 10. The opposite is not true, the DC must be the same or the newest version in the domain.

Versioning of subsystems

To help with being able to know what is compatible we have versions within the subsystems, this is stored in the subsystem's extension. When registering the subsystem you will typically see something like:

Which sets the ModelVersion of the subsystem.

Whenever something changes in the subsystem, such as:
  • an attribute is added or removed from a resource
  • a attribute is renamed in a resource
  • an attribute has its type changed
  • an attribute or operation parameter's nillable or allows expressions is changed
  • an attribute or operation parameter's default value changes
  • a child resource type is added or removed
  • an operation is added or removed
  • an operation has its parameters changed

and the current version of the subsystem has been part of a Final release of WildFly, we must bump the version of the subsystem.

Once it has been increased you can of course make more changes until the next Final release without more version bumps. It is also worth noting that a new WildFly release does not automatically mean a new version for the subsystem, the new version is only needed if something was changed. For example the jaxrs subsystem has remained on 1.0.0 for all versions of WildFly and JBoss AS 7.

You can find the ModelVersion of a subsystem by querying its extension:

The role of transformers

Now that we have mentioned the slave HCs registration process with the DC, and know about ModelVersions, it is time to mention that when registering with the DC, the slave HC will send across a list of all its subsystem ModelVersions. The DC maintains this information in a registry for each slave HC, so that it knows which transformers (if any) to invoke for a legacy slave. We will see how to write and register transformers later on in How do I write a transformer. Slave HCs from version 7.2.0 onwards will also include a list of resources that they ignore (see Ignoring resources on legacy hosts), and the DC will maintain this information in its registry. The DC will not send across any resources that it knows a slave ignores during the initial domain model transfer. When forwarding operations onto the slave HCs, the DC will skip forwarding those to slave HCs ignoring those resources.

There are two kinds of transformers:

  • resource transformers
  • operation transformers

The main function of transformers is to transform a subsystem to something that the legacy slave HC can understand, or to aggressively reject things that the legacy slave HC will not understand. Rejection, in this context, essentially means, that the resource or operation cannot safely be transformed to something valid on the slave, so the transformation fails. We will see later how to reject attributes in Rejecting attributes, and child resources in Reject child resource.

Both resource and operation transformers are needed, but take effect at different times. Let us use the weld subsystem, which is relatively simple, as an example. In JBoss AS 7.2.0 and lower it had a ModelVersion of 1.0.0, and its resource description was as follows:

In WildFly 8, it has a ModelVersion of 2.0.0 and has added two attributes, require-bean-descriptor and non-portable mode:

In the rest of this section we will assume that we are running a DC running WildFly 8 so it will have ModelVersion 2.0.0 of the weld subsystem, and that we are running a slave using ModelVersion 1.0.0 of the weld subsystem.

Transformation always takes place on the Domain Controller, and is done when sending across the initial domain model AND forwarding on operations to legacy slave HCs.

Resource transformers

When copying over the centralized domain configuration as mentioned in Getting the initial domain model, we need to make sure that the copy of the domain model is something that the servers running on the legacy slave HC understand. So if the centralized domain configuration had any of the two new attributes set, we would need to reject the transformation in the transformers. One reason for this is to keep things consistent, it doesn't look good if you connect to the slave HC and find attributes and/or child resources when doing :read-resource which are not there when you do :read-resource-description. Also, to make life easier for subsystem writers, most instances of the describe operation use a standard implementation which would include these attributes when creating the add operation for the server, which could cause problems there.

Another, more concrete example from the logging subsystem is that it allows a '%K{...}' in the pattern formatter which makes the formatter use color:

This '%K{...}' however was introduced in JBoss AS < 7.1.3 (ModelVersion 1.2.0), so if that makes it across to a slave HC running an older version, the servers will fail to start up. So the logging extension registers transformers to strip out the '%K{...}' from the attribute value (leaving '%-5p [%c] (%t) %s%E%n"') so that the old slave HC's servers can understand it.

Rejection in resource transformers

Only slave HCs from JBoss AS 7.2.0 and newer inform the DC about their ignored resources (see Ignoring resources on legacy hosts). This means that if a transformer on the DC rejects transformation for a legacy slave HC, exactly what happens to the slave HC depends on the version of the slave HC. If the slave HC is:

  • older than 7.2.0 - the DC has no means of knowing if the slave HC has ignored the resource being rejected or not. So we log a warning on the DC, and send over the serialized part of that model anyway. If the slave HC has ignored the resource in question, it does not apply it. If the slave HC has not ignored the resource in question, it will apply it, but no failure will happen until it tries to start a server which references this bad configuration.
  • 7.2.0 or newer - If a resource is ignored on the slave HC, the DC knows about this, and will not attempt to transform or send the resource across to the slave HC. If the resource transformation is rejected, we know the resource was not ignored on the slave HC and so we can aggressively fail the transformation, which in turn will cause the slave HC to fail to start up.

Operation transformers

When An operation changes something in the domain configuration the operation gets sent across to the slave HCs to update their copies of the domain model. The slave HCs then forward this operation onto the affected servers. The same considerations as in Resource transformers are true, although operation transformers give you quicker 'feedback' if something is not valid. If you try to execute:

This will fail on the legacy slave HC since its version of the subsystem does not contain any such attribute. However, it is best to aggressively reject in such cases.

Rejection in operation transformers

For transformed operations we can always know if the operation is on an ignored resource in the legacy slave HC. In 7.2.0 onwards, we know this through the DC's registry of ignored resources on the slave. In older versions of slaves, we send the operation across to the slave, which tries to invoke the operation. If the operation is against an ignored resource we inform the DC about this fact. So as part of the transformation process, if something gets rejected we can (and do!) fail the transformation aggressively. If the operation invoked on the DC results in the operation being sent across to 10 slave HCs and one of them has a legacy version which ends up rejecting the transformation, we rollback the operation across the whole domain.

Different profiles for different versions

Now for the weld example we have been using there is a slight twist. We have the new require-bean-descriptor and non-portable-mode attributes. These have been added in WildFly 8 which supports Java EE 7, and thus CDI 1.1. JBoss AS 7.x supports Java EE 6, and thus CDI 1.0. In CDI 1.1 the values of these attributes are tweakable, so they can be set to either true or false. The default behaviour for these in CDI 1.1, if not set, is that they are false. However, for CDI 1.0 these were not tweakable, and with the way the subsystem in JBoss AS 7.x worked is similar to if they are set to true.

The above discussion implies that to use the weld subsystem on a legacy slave HC, the domain.xml configuration for it must look like:

We will see the exact mechanics for how this is actually done later but in short when pushing this to a legacy slave DC we register transformers which reject the transformation if these attributes are not set to true since that implies some behavior not supported on the legacy slave DC. If they are true, all is well, and the transformers discard, or remove, these attributes since they don't exist in the legacy model. This removal is fine since they have the values which would result in the behavior assumed on the legacy slave HC.

That way the older slave HCs will work fine. However, we might also have WildFly 8 slave HCs in our domain, and they are missing out on the new features introduced by the attributes introduced in ModelVersion 2.0.0. If we do

then it will fail when doing transformation for the legacy controller. The solution is to put these in two different profiles in domain.xml

Then have the HCs using WildFly 8 make their servers reference the main-server-group server group, and the HCs using older versions of WildFly 8 make their servers reference the main-server-group-legacy server group.

Ignoring resources on legacy hosts

Booting the above configuration will still cause problems on legacy slave HCs, especially if they are JBoss AS 7.2.0 or later. The reason for this is that when they register themselves with the DC it lets the DC know which ignored resources they have. If the DC comes to transform something it should reject for a slave HC and it is not part of its ignored resources it will aggressively fail the transformation. Versions of JBoss AS older than 7.2.0 still have this ignored resources mechanism, but don't let the DC know about what they have ignored so the DC cannot reject aggressively - instead it will log some warnings. However, it is still good practice to ignore resources you are not interested in regardless of which legacy version the slave HC is running.

To ignore the profile we cannot understand we do the following in the legacy slave HC's host.xml

Any top-level resource type can be ignored profile, extension, server-group etc. Ignoring a resource instance ignores that resource, and all its children.

How do I know what needs to be transformed?

There is a set of related classes in the org.wildfly.legacy.util package to help you determine this. These now live at https://github.com/wildfly/wildfly-legacy-test/tree/master/tools/src/main/java/org/wildfly/legacy/util.
They are all runnable in your IDE, just start the WildFly or JBoss AS 7 instances as described below.

Getting data for a previous version

https://github.com/wildfly/wildfly-legacy-test/tree/master/tools/src/main/resources/legacy-models contains the output for the previous WildFly/JBoss AS 7 versions, so check if the files for the version you want to check backwards compatibility are there yet. If not, then you need to do the following to get the subsystem definitions:

  1. Start the old version of WildFly/JBoss AS 7 using --server-config=standalone-full-ha.xml
  2. Run org.wildfly.legacy.util.GrabModelVersionsUtil, which will output the subsystem versions to target/standalone-model-versions-running.dmr
  3. Run org.wildfly.legacy.util.DumpStandaloneResourceDefinitionUtil which will output the full resource definition to target/standalone-resource-definition-running.dmr
  4. Stop the running version of WildFly/JBoss AS 7

See what changed

To do this follow the following steps

  1. Start the new version of WildFly using --server-config=standalone-full-ha.xml
  2. Run org.wildfly.legacy.util.CompareModelVersionsUtil and answer the following questions"
    1. Enter Legacy AS version:
      • If it is known version in the tools/src/test/resources/legacy-models folder, enter the version number.
      • If it is a not known version, and you got the data yourself in the last step, enter 'running'
    2. Enter type:
      • Answer 'S'
    3. Read from target directory or from the legacy-models directory:
      • If it is known version in the controller/src/test/resources/legacy-models folder, enter 'l'.
      • If it is a not known version, and you got the data yourself in the last step, enter 't'
    4. Report on differences in the model when the management versions are different?:
      • Answer 'y'

Here is some example output, as a subsystem developer you can ignore everything down to ====== Comparing subsystem models ======:

So we can see that for the remoting subsystem, we have added a child type called http-connector, and we have added an attribute called protocol (they are missing in legacy).
in the weld subsystem, we have added the require-bean-descriptor and non-portable-mode attributes in the current version. It will also point out other issues like changed attribute types, changed defaults etc.

Note that CompareModelVersionsUtil simply inspects the raw resource descriptions of the specified legacy and current models. Its results show the differences between the two. They do not take into account whether one or more transformers have already been written for those versions differences. You will need to check that transformers are not already in place for those versions.

One final point to consider are that some subsystems register runtime-only resources and operations. For example the modcluster subsystem has a stop method. These do not get registered on the DC, e.g. there is no /profile=full-ha/subsystem=modcluster:stop operation, it only exists on the servers, for example /host=xxx/server=server-one/subsystem=modcluster:stop. What this means is that you don't have to transform such operations and resources. The reason is they are not callable on the DC, and so do not need propagation to the servers in the domain, which in turn means no transformation is needed.

How do I write a transformer?

There are two APIs available to write transformers for a resource. There is the original low-level API where you register transformers directly, the general idea is that you get hold of a TransformersSubRegistration for each level and implement the ResourceTransformer, OperationTransformer and PathAddressTransformer interfaces directly. It is, however, a pretty complex thing to do, so we recommend the other approach. For completeness here is the entry point to handling transformation in this way.

Having implemented a number of transformers using the above approach, we decided to simplify things, so we introduced the org.jboss.as.controller.transform.description.ResourceTransformationDescriptionBuilder API. It is a lot simpler and avoids a lot of the duplication of functionality required by the low-level API approach. While it doesn't give you the full power that the low-level API does, we found that there are very few places in the WildFly codebase where this does not work, so we will focus on the ResourceTransformationDescriptionBuilder API here. (If you come across a problem where this does not work, get in touch with someone from the WildFly Domain Management Team and we should be able to help). The builder API makes all the nasty calls to TransformersSubRegistration for you under the hood. It also allows you to fall back to the low-level API in places, although that will not be covered in the current version of this guide. The entry point for using the builder API here is taken from the WeldExtension (in current WildFly this has ModelVersion 2.0.0).

Here we register a discard check and a reject check. As mentioned in Attribute transformation lifecycle all attributes are inspected for whether they should be discarded first. Then all attributes which were not discarded are checked for if they should be rejected. We will dig more into what this code means in the next few sections, but in short it means that we discard the require-bean-descriptor and non-portable attributes on the weld subsystem resource if they have the value true. If they have any other value, they will not get discarded and so reach the reject check, which will reject the transformation of the attributes if they have any other value.

Here we are saying that we should discard the require-bean-descriptor and non-portable-mode attributes on the weld subsystem resource if they are undefined, and reject them if they are defined. So that means that if the weld subsystem looks like


or any other combination (the default values for these attributes if undefined is false) we will reject the transformation for the slave legacy HC.

If the resource has true for these attributes:

they both get discarded (i.e. removed), so they will not get inspected for rejection, and an empty model not containing these attributes gets sent to the legacy HC.

Here we will discuss this API a bit more, to outline the most important features/most commonly needed tasks.


The ResourceTransformationDescriptionBuilder contains transformations for a resource type. The initial one is for the subsystem, obtained by the following call:

The ResourceTransformationDescriptionBuilder contains functionality for how to handle child resources, which we will look at in this section. It is also the entry point to how to handle transformation of attributes as we will see in AttributeTransformationDescriptionBuilder. Also, it allows you to further override operation transformation as discussed in OperationTransformationOverrideBuilder. When we have finished with our builder, we register it with the SubsystemRegistration against the target ModelVersion.

If you have several old ModelVersions you could be transforming to, you need a separate builder for each of those.

Silently discard child resources

To make the ResourceTransformationDescriptionBuilder do something, we need to call some of its methods. For example, if we want to silently discard a child resource, we can do

This means that any usage of /subsystem=my-subsystem/child=discarded never make it to the legacy slave HC running ModelVersion 1.0.0. During the initial domain model transfer, that part of the serialized domain model is stripped out, and any operations on this address are not forwarded on to the legacy slave HCs running that version of the subsystem. (For brevity this section will leave out the leading /profile=xxx part used in domain mode, and use /subsystem=my-subsystem as the 'top-level' address).

Note that discarding, although the simplest option in theory, is rarely the right thing to do.

The presence of the defined child normally implies some behaviour on the DC, and that behaviour is not available on the legacy slave HC, so normally rejection is a better policy for those cases. Remember we can have different profiles targeting different groups of versions of legacy slave HCs.

Reject child resource

If we want to reject transformation if a child resource exists, we can do

Now, if there are any legacy slaves running ModelVersion 1.0.0, any usage of /subsystem=my-subsystem/child=reject will get rejected for those slaves. Both during the initial domain model transfer, and if any operations are invoked on that address. For example the remoting subsystem did not have a http-connector=* child until ModelVersion 2.0.0, so it is set up to reject that child when transforming to legacy HCs for all previous ModelVersions (1.1.0, 1.2.0 and 1.3.0). (See Rejection in resource transformers and Rejection in operation transformers for exactly what happens when something is rejected).

Redirect address for child resource

Sometimes we rename the addresses for a child resource between model versions. To do that we use one of the addChildRedirection() methods, note that these also return a builder for the child resource (since we are not rejecting or discarding it), we can do this for all children of a given type:

Now, in the initial domain transfer /subsystem=my-subsystem/newChild=test becomes /subsystem=my-subsystem/oldChild=test. Similarly all operations against the former address get mapped to the latter when executing operations on the DC before sending them to the legacy slave HC running ModelVersion 1.1.0 of the subsystem.

We can also rename a specific named child:

Now, /subsystem=my-subsystem/newChild=newName becomes /subsystem=my-subsystem/oldChild=oldName both in the initial domain transfer, and when mapping operations to the legacy slave. For example, under the web subsystem ssl=configuration got renamed to configuration=ssl in later versions, meaning we need a redirect from configuration=ssl to ssl=configuration in its transformers.

Getting a child resource builder

Sometimes we don't want to transform the subsystem resource, but we want to transform something in one of its child resources. Again, since we are not discarding or rejecting, we get a reference to the builder for the child resource.


To transform attributes you call ResourceTransformationDescriptionBuilder.getAttributeBuilder() which returns you a AttributeTransformationDescriptionBuilder which is used to define transformation for the resource's attributes. For example this gets the attribute builder for the subsystem resource:

or we could get it for one of the child resources:

The attribute transformations defined by the AttributeTransformationDescriptionBuilder will also impact the parameters to all operations defined on the resource. This means that if you have defined the example attribute of /subsystem=my-subsystem/some-child=* to reject transformation if its value is true, the inital domain transfer will reject if it is true, also the transformation of the following operations will reject:

The following operations will pass in this example, since the example attribute is not getting set to true

For the rest of the examples in this section we assume that the attributeBuilder is for /subsystem=my-subsystem

Attribute transformation lifecycle

There is a well defined lifecycle used for attribute transformation that is worth explaining before jumping into specifics. Transformation is done in the following phases, in the following order:

  1. discard - All attributes in the domain model transfer or invoked operation that have been registered for a discard check, are checked to see if the attribute should be discarded. If an attribute should be discarded, it is removed from the resource's attributes/operation's parameters and it does not get passed to the next phases. Once discarded it does not get sent to the legacy slave HC.
  2. reject - All attributes that have been registered for a reject check (and which not have been discarded) are checked to see if the attribute should be rejected. As explained in Rejection in resource transformers and Rejection in operation transformers exactly what happens when something is rejected varies depending on whether we are transforming a resource or an operation, and the version of the legacy slave HC we are transforming for. If a transformer rejects an attribute, all other reject transformers still get invoked, and the next phases also get invoked. This is because we don't know in all cases what will happen if a reject happens. Although this might sound cumbersome, in practice it actually makes it easier to write transformers since you only need one kind regardless of if it is a resource, an operation, and legacy slave HC version. However, as we will see in Common transformation use-cases, it means some extra checks are needed when writing reject and convert transformers.
  3. convert - All attributes that have been registered for conversion are checked to see if the attribute should be converted. If the attribute does not exist in the original operation/resource it may be introduced. This is useful for setting default values for the target legacy slave HC.
  4. rename - All attributes registered for renaming are renamed.

Next, let us have a look at how to register attributes for each of these phases.

Discarding attributes

The general idea behind a discard is that we remove attributes which do not exist in the legacy slave HC's model. However, as hopefully described below, we normally can't simply discard everything, we need to check the values first.

To discard an attribute we need an instance of org.jboss.as.controller.transform.description.DiscardAttributeChecker, and call the following method on the AttributeTransformationDescriptionBuilder:

As shown, you can register the DiscardAttributeChecker for several attributes at once, in the above example both attr1 and attr2 get checked for if they should be discarded. You can also register different DiscardAttributeChecker instances for different attributes:

Note that you can only have one DiscardAttributeChecker per attribute, so the following would cause an error (if running with assertions enabled, otherwise discardCheckerB will overwrite discardCheckerA):

The DiscardAttributeChecker interface

org.jboss.as.controller.transform.description.DiscardAttributeChecker contains both the DiscardAttributeChecker and some helper implementations. The implementations of this interface get called for each attribute they are registered against. The interface itself is quite simple:

Return true here to discard the attribute if it is an expression. If it is an expression, and this method returns true, the isOperationParameterDiscardable and isResourceAttributeDiscardable methods will not get called.

Return true here to discard the attribute if it is undefined. If it is undefined, and this method returns true, the isDiscardExpressions, isOperationParameterDiscardable and isResourceAttributeDiscardable methods will not get called.

If we are transforming an operation, this method gets called for each operation parameter. We have access to the address of the operation, the name and value of the operation parameter, an unmodifiable copy of the original operation and the TransformationContext. The TransformationContext allows you access to the original resource the operation is working on before any transformation happened, which is useful if you want to check other values in the resource if this is, say a write-attribute operation. Return true to discard the operation.

If we are transforming a resource, this method gets called for each attribute in the resource. We have access to the address of the resource, the name and value of the attribute, and the TransformationContext. Return true to discard the operation.

DiscardAttributeChecker helper classes/implementations

DiscardAttributeChecker contains a few helper implementations for the most common cases to save you writing the same stuff again and again.


DiscardAttributeChecker.DefaultDiscardAttributeChecker is an abstract convenience class. In most cases you don't need a separate check for if an operation or a resource is being transformed, so it makes both the isResourceAttributeDiscardable() and isOperationParameterDiscardable() methods call the following method.

All you lose, in the case of an operation transformation, is the name of the transformed operation. The constructor of DiscardAttributeChecker.DefaultDiscardAttributeChecker also allows you to define values for isDiscardExpressions() and isDiscardUndefined().


This is another convenience class, which allows you to discard an attribute if it has one or more values. Here is a real-world example from the jpa subsystem:

We will come back to the reject checks in the Rejecting attributes section. We are saying that we should discard the JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE attribute if it has the value deep. The reasoning here is that this attribute did not exist in the old model, but the legacy slave HCs implied behaviour is that this was deep. In the current version we added the possibility to toggle this setting, but only deep is consistent with what is available in the legacy slave HC. In this case we are using the constructor for DiscardAttributeChecker.DiscardAttributeValueChecker which says don't discard if it uses expressions, and discard if it is undefined. If it is undefined in the current model, looking at the default value of JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE, it is deep, so a discard is in line with the implied legacy behaviour. If an expression is used, we cannot discard since we have no idea what the expression will resolve to on the slave HC.


DiscardAttributeChecker.ALWAYS will always discard an attribute. Use this sparingly, since normally the presence of an attribute in the current model implies some behaviour should be turned on, and if that does not exist in the legacy model it implies that that behaviour does not exist in the legacy slave HC and its servers. Normally the legacy slave HC's subsystem has some implied behaviour which is better checked for by using a DiscardAttributeChecker.DiscardAttributeValueChecker. One valid use for DiscardAttributeChecker.ALWAYS can be found in the ejb3 subsystem:

As the comment says, this attribute only makes sense with the security-manager susbsystem, which does not exist on legacy slaves running ModelVersion 1.1.0 of the ejb3 subsystem.


DiscardAttributeChecker.UNDEFINED will discard an attribute if it is undefined. This is normally safer than DiscardAttributeChecker.ALWAYS since the attribute is not set in the current model, we don't need to send it to the legacy model. However, you should check that this attribute not existing in the legacy slave HC, implies the same functionality as being undefined in the current DC.

Rejecting attributes

The next step is to check attributes and values which we know for sure will not work on the target legacy slave HC.

To reject an attribute we need an instance of org.jboss.as.controller.transform.description.RejectAttributeChecker, and call the following method on the AttributeTransformationDescriptionBuilder:

As shown you can register the RejectAttributeChecker for several attributes at once, in the above example both attr1 and attr2 get checked for if they should be discarded. You can also register different RejectAttributeChecker instances for different attributes:

You can also register several RejectAttributeChecker instances per attribute

In this case attr1 gets both rejectCheckerA and rejectCheckerB. For attributes with several RejectAttributeChecker registered, they get processed in the order that they have been added. So when checking attr1 for rejection, rejectCheckerA gets run before rejectCheckerB. As mentioned in Attribute transformation lifecycle, if an attribute is rejected, we still invoke the rest of the reject checkers.

The RejectAttributeChecker interface

org.jboss.as.controller.transform.description.RejectAttributeChecker contains both the RejectAttributeChecker and some helper implementations. The implementations of this interface get called for each attribute they are registered against. The interface itself is quite simple, and its main methods are similar to DiscardAttributeChecker:

If we are transforming an operation, this method gets called for each operation parameter. We have access to the address of the operation, the name and value of the operation parameter, an unmodifiable copy of the original operation and the TransformationContext. The TransformationContext allows you access to the original resource the operation is working on before any transformation happened, which is useful if you want to check other values in the resource if this is, say a write-attribute operation. Return true to reject the operation.

If we are transforming a resource, this method gets called for each attribute in the resource. We have access to the address of the resource, the name and value of the attribute, and the TransformationContext. Return true to discard the operation.

Here we need a unique id for the log message from the RejectAttributeChecker. It is used to group rejected attributes by their log message. A typical implementation will contain {{return getRejectionLogMessage(Collections.<String, ModelNode>emptyMap());}

Here we return a message saying why the attributes were rejected, with the possibility to format the message to include the names of all the rejected attributes and the values they had.

RejectAttributeChecker helper classes/implementations

RejectAttributeChecker contains a few helper classes for the most common scenarios to save you from writing the same stuff again and again.


RejectAttributeChecker.DefaultRejectAttributeChecker is an abstract convenience class. In most cases you don't need a separate check for if an operation or a resource is being transformed, so it makes both the rejectOperationParameter() and rejectResourceAttribute() methods call the following method.

Like DefaultDiscardAttributeChecker, all you loose is the name of the transformed operation, in the case of operation transformation.


RejectAttributeChecker.DEFINED is used to reject any attribute that has a defined value. Normally this is because the attribute does not exist on the target legacy slave HC. A typical use case for these is for the implied behavior example we looked at in the jpa subsystem in DiscardAttributeChecker.DiscardAttributeValueChecker

So we discard the JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE value if it is not an expression, and also has the value deep. Now if it was not discarded, it would will still be defined so we reject it.

Reject and discard often work in pairs.

RejectAttributeChecker.SIMPLE_EXPRESSIONS can be used to reject an attribute that contains expressions. This was used a lot for transformations to subsystems in JBoss AS 7.1.x, since we had not fully realized the importance of where to support expressions until JBoss AS 7.2.0 was released, so a lot of attributes in earlier versions were missing expressions support.


The RejectAttributeChecker}}s we have seen so far work on simple attributes, i.e. where the attribute has a ModelType which is one of the primitives. We also have a {{RejectAttributeChecker.ListRejectAttributeChecker which allows you to define a checker for the elements of a list, when the type of an attribute is ModelType.LIST.

For attr1 it will check each element of the list and run RejectAttributeChecker.EXPRESSIONS to check that each element is not an expression. You can of course pass in another kind of RejectAttributeChecker to check the elements as well.


For attributes where the type is ModelType.OBJECT we have RejectAttributeChecker.ObjectFieldsRejectAttributeChecker which allows you to register different reject checkers for the different fields of the registered object.

Now if attr1 is a complex type where attr1.get("time").getType() == ModelType.EXPRESSION or attr1.get("unit").asString().equals("Lunar Month") we reject the attribute.

Converting attributes

To convert an attribute you register an org.jboss.as.controller.transform.description.AttributeConverter instance against the attributes you want to convert:

Now if attr1 and attr2 get converted with converterA, while attr3 gets converted with converterB.

The AttributeConverter interface

The AttributeConverter interface gets called for each attribute for which the AttributeConverter has been registered

If we are transforming an operation, this method gets called for each operation parameter for which the con. We have access to the address of the operation, the name and value of the operation parameter, an unmodifiable copy of the original operation and the TransformationContext. The TransformationContext allows you access to the original resource the operation is working on before any transformation happened, which is useful if you want to check other values in the resource if this is, say a write-attribute operation. To change the attribute value, you modify the attributeValue.

If we are transforming a resource, this method gets called for each attribute in the resource. We have access to the address of the resource, the name and value of the attribute, and the TransformationContext. To change the attribute value, you modify the attributeValue.

A hypothetical example is if the current and legacy subsystems both contain an attribute called timeout. In the legacy model this was specified to be milliseconds, however in the current model it has been changed to be seconds, hence we need to convert the value when sending it to slave HCs using the legacy model:

We need to be a bit careful here. If the timeout attribute is an expression our nice conversion will not work, so we need to add a reject check to make sure it is not an expression as well:

Now it should be fine.

AttributeConverter.DefaultAttributeConverter is is an abstract convenience class. In most cases you don't need a separate check for if an operation or a resource is being transformed, so it makes both the convertOperationParameter() and convertResourceAttribute() methods call the following method.

Like DefaultDiscardAttributeChecker and DefaultRejectAttributeChecker, all you loose is the name of the transformed operation, in the case of operation transformation.

Introducing attributes during transformation

Say both the current and the legacy models have an attribute called port. In the legacy version this attribute had to be specified, and the default xml configuration had 1234 for its value. In the current version this attribute has been made optional with a default value of 1234 so that it does not need to be specified. When transforming to a slave HC using the old version we will need to introduce this attribute if the new model does not contain it:

So what this factory method does is to create an implementation of AttributeConverter.DefaultAttributeConverter where in convertAttribute() we set attributeValue to have the value 1234 if it is undefined. As long as attributeValue gets set in that method it will get set in the model, regardless of if it existed already or not.

Renaming attributes

To rename an attribute, you simply do

Now, in the initial domain transfer to the legacy slave HC, we rename /subsystem=my-subsystem's my-name attribute to legacy-name. Also, the operations involving this attribute are affected, so


All operations on a resource automatically get the same transformations on their parameters as set up by the AttributeTransformationDescriptionBuilder. In some cases you might want to change this, so you can use the OperationTransformationOverrideBuilder, which is got from:

In this case the operation will now no longer inherit the attribute/operation parameter transformations, so they are effectively turned off. In other cases you might want to include them by calling inheritResourceAttributeDefinitions(), and to include some more checks (the OperationTransformationBuilder interface has all the methods found in AttributeTransformationBuilder:

You can also rename operations, in this case the operation some-operation gets renamed to legacy-operation before getting sent to the legacy slave HC.

Evolving transformers with subsystem ModelVersions

Say you have a subsystem with ModelVersions 1.0.0 and 1.1.0. There will (hopefully!) already be transformers in place for 1.1.0 to 1.0.0 transformations. Let's say that the transformers registration looks like:

Now say we want to do a new version of the model. This new version contains a new attribute called 'new-attr' which cannot be defined when transforming to 1.1.0, we bump the model version to 2.0.0:

There are a few ways to evolve your transformers:

The old way

This is the way that has been used up to WildFly 8.x. However, in WildFly 9 and later, it is strongly recommended to migrate to what is mentioned in Chained transformers

Now we need some new transformers from the current ModelVersion to 1.1.0 where we reject any defined occurrances of our new attribute new-attr:

So that is all well and good, however we also need to take into account that new-attr does not exist in ModelVersion 1.0.0 either, so we need to extend our transformer for 1.0.0 to reject it there as well. As you can see 1.0.0 also rejects a defined 'attr1' in addition to the 'new-attr'(which is rejected in both versions).

Now new-attr will be rejected if defined for all previous model versions.

Chained transformers

Since 'The old way' had a lot of duplication of code, since WildFly 9 we now have chained transformers. You obtain a ChainedTransformationDescriptionBuilder which is a different entry point to the ResourceTransformationDescriptionBuilder we have seen earlier. Each ResourceTransformationDescriptionBuilder deals with transformation across one version delta.

The buildAndRegister(ModelVersion[]... chains) method registers a chain consisting of the built builder110 and builder100 for transformation to 1.0.0, and a chain consisting of the built builder110 for transformation to 1.1.0. It allows you to specify more than one chain.

Now when transforming from the current version to 1.0.0, the resource is first transformed from the current version to 1.1.0 (which rejects a defined new-attr) and then it is transformed from 1.1.0 to 1.0.0 (which rejects a defined attr1). So when evolving transformers you should normally only need to add things to the last version delta. The full current-to-1.1.0 transformation is run before the 1.1.0-to-1.0.0 transformation is run.

One thing worth pointing out that the value returned by TransformationContext.readResource(PathAddress address) and TransformationContext.readResourceFromRoot(PathAddress address) which you can use from your custom RejectAttributeChecker, DiscardAttributeChecker and AttributeConverter behaves slightly differently depending on if you are transforming an operation or a resource.

During resource transformation this will be the latest model, so in our above example, in the current-to-1.1.0 transformation it will be the original model. In the 1.1.0-to-1.0.0 transformation, it will be the result of the current-to-1.1.0 transformation.

During operation transformation these methods will always return the original model (we are transforming operations, not resources!).

In WildFly 9 we are now less aggressive about transforming to all previous versions of WildFly, however we still have a lot of good tests for running against 7.1.x, 8. Also, for Red Hat employees we have tests against EAP versions. These tests no longer get run by default, to run them you need to specify some system properties when invoking maven. They are:

  • -Djboss.test.transformers.subsystem.old - enables the non-default subsystem tests.
  • -Djboss.test.transformers.eap - (Red Hat developers only), enables the eap tests, but only the ones run by default. If run in conjunction with -Djboss.test.transformers.subsystem.old you get all the possible subsystem tests run.
  • -Djboss.test.transformers.core.old - enables the non-default core model tests.

Testing transformers

To test transformation you need to extend org.jboss.as.subsystem.test.AbstractSubsystemTest or org.jboss.as.subsystem.test.AbstractSubsystemBaseTest. Then, in order to have the best test coverage possible, you should test the fullest configuration that will work, and you should also test configurations that don't work if you have rejecting transformers registered. The following example is from the threads subsystem, and I have only included the tests against 7.1.2 - there are more! First we need to set up our test:

So we say that this test is for the threads subsystem, and that it is implemented by ThreadsExtension. This is the same test framework as we use in Example subsystem#Testing the parsers, but we will only talk about the parts relevant to transformers here.

Testing a configuration that works

To test a configuration xxx

What this test does is get the builder to configure the test controller using threads-transform-1_0.xml. This main builder works with the current subsystem version, and the jars in the WildFly checkout.

Next we configure a 'legacy' controller. This will run the version of the core libraries (e.g the controller module) as found in the targeted legacy version of JBoss AS/Wildfly), and the subsystem. We need to pass in that it is using the core AS version 7.1.2.Final (i.e. the ModelTestControllerVersion.V7_1_2_FINAL part) and that that version is ModelVersion 1.0.0. Next we have some addMavenResourceURL() calls passing in the Maven GAVs of the old version of the subsystem and any dependencies it has needed to boot up. Normally, specifying just the Maven GAV of the old version of the subsystem is enough, but that depends on your subsystem. In this case the old subsystem GAV is enough. When booting up the legacy controller the framework uses the parsed operations from the main controller and transforms them using the 1.0.0 transformer in the threads subsystem. The addOperationValidationResolve() and excludeFromParent() calls are not normally necessary, see the javadoc for more examples.

The call to KernelServicesBuilder.build() will build both the main controller and the legacy controller. As part of that it also boots up a second copy of the main controller using the transformed operations to make sure that the 'old' ops to boot our subsystem will still work on the current controller, which is important for backwards compatibility of CLI scripts. To tweak how that is done if you see failures there, see LegacyKernelServicesInitializer.skipReverseControllerCheck() and LegacyKernelServicesInitializer.configureReverseControllerCheck(). The LegacyKernelServicesInitializer is what gets returned by KernelServicesBuilder.createLegacyKernelServicesBuilder().

Finally we call checkSubsystemModelTransformation() which reads the full legacy subsystem model. The legacy subsystem model will have been built up from the transformed boot operations from the parsed xml. The operations get transformed by the operation transformers. Then it takes the model of the current subsystem and transforms that using the resource transformers. Then it compares the two models, which should be the same. In some rare cases it is not possible to get those two models exactly the same, so there is a version of this method that takes a ModelFixer to make adjustments. The checkSubsystemModelTransformation() method also makes sure that the legacy model is valid according to the legacy subsystem's resource definition.

The legacy subsystem resource definitions are read on demand from the legacy controller when the tests run. In some older versions of subsystems (before we converted everything to use ResourceDefinition, and DescriptionProvider implementations were coded by hand) there were occasional problems with the resource definitions and they needed to be touched up. In this case you can generate a new one, touch it up and store the result in a file in the test resources under /same/package/as/the/test/class/{{subsystem-name-model-version. This will then prefer the file read from the file system to the one read at runtime. To generate the .dmr file, you need to generate it by adding a temporary test (make sure that you adjust controllerVersion and modelVersion to what you want to generate):

Now run the test and delete it. The legacy .dmr file should be in target/test-classes/org/jboss/as/subsystem/test/<your-subsystem-name>-<your-version>.dmr. Copy this .dmr file to the correct location in your project's test resources.

Testing a configuration that does not work

The threads subsystem (like several others) did not support the use of expression values in the version that came with JBoss AS 7.1.2.Final. So we have a test that attempts to use expressions, and then fixes each resource and attribute where expressions were not allowed.

Again we boot up a current and a legacy controller. However, note in this case that they are both empty, no xml was parsed on boot so there are no operations to boot up the model. Instead once the controllers have been booted, we call KernelServicesBuilder.parseXmlResource() which gets the operations from expressions.xml. expressions.xml uses expressions in all the places they were not allowed in 7.1.2.Final. For each resource ModelTestUtils.checkFailedTransformedBootOperations() will check that the add operation gets rejected, and then correct one attribute at a time until the resource has been totally corrected. Once the add operation is totally correct, it will check that the add operation no longer is rejected. The configuration for this is the FailedOperationTransformationConfig returned by the getConfig() method:

So what this means is that we expect the allow-core-timeout and keepalive-time attributes for the blocking-bounded-queue-thread-pool=* and bounded-queue-thread-pool=* add operations to use expressions in the parsed xml. We then expect them to fail since there should be transformers in place to reject expressions, and correct them one at a time until the add operation should pass. As well as doing the add operations the ModelTestUtils.checkFailedTransformedBootOperations() method will also try calling write-attribute for each attribute, correcting as it goes along. As well as allowing you to test rejection of expressions FailedOperationTransformationConfig also has some helper classes to help testing rejection of other scenarios.

Common transformation use-cases

Most transformations are quite similar, so this section covers some of the actual transformation patterns found in the WildFly codebase. We will look at the output of CompareModelVersionsUtil, and see what can be done to transform for the older slave HCs. The examples come from the WildFly codebase but are stripped down to focus solely on the use-case being explained in an attempt to keep things as clear/simple as possible.

Child resource type does not exist in legacy model

Looking at the model comparison between WildFly and JBoss AS 7.2.0, there is a change to the remoting subsystem. The relevant part of the output is:

So our current model has added a child type called http-connector which was not there in 7.2.0. This is configurable, and adds new behavior, so it can not be part of a configuration sent across to a legacy slave running version 1.2.0. So we add the following to RemotingExtension to reject all instances of that child type against ModelVersion 1.2.0.

Since this child resource type also does not exist in ModelVersion 1.1.0 we need to reject it there as well using a similar mechanism.

Attribute does not exist in the legacy subsystem

Default value of the attribute is the same as legacy implied behavior

This example also comes from the remoting subsystem, and is probably the most common type of transformation. The comparison tells us that there is now an attribute under /subsystem=remoting/remote-outbound-connection=* called protocol which did not exist in the older version:

This difference also affects the add operation. Looking at the current model the valid values for the protocol attribute are remote, http-remoting and https-remoting. The last two are new protocols introduced in WildFly 8, meaning that the implied behaviour in JBoss 7.2.0 and earlier is the remote protocol. Since this attribute does not exist in the legacy model we want to discard this attribute if it is undefined or if it has the value remote, both of which are in line with what the legacy slave HC is hardwired to use. Also we want to reject it if it has a value different from remote. So what we need to do when registering transformers against ModelVersion 1.2.0 to handle this attribute:

So the first thing to happens is that we register a DiscardAttributeChecker.DiscardAttributeValueChecker which discards the attribute if it is either undefined (the default value in the current model is remote), or defined and has the value remote. Remembering that the discard phase always happens before the reject phase, the reject checker checks that the protocol attribute is defined, and rejects it if it is. The only reason it would be defined in the reject check, is if it was not discarded by the discard check. Hopefully this example shows that the discard and reject checkers often work in pairs.

An alternative way to write the protocolTransform() method would be:

The reject check remains the same, but we have implemented the discard check by using DiscardAttributeChecker.DefaultDiscardAttributeChecker instead. However, the effect of the discard check is exactly the same as when we used DiscardAttributeChecker.DiscardAttributeValueChecker.

Default value of the attribute is different from legacy implied behaviour

We touched on this in the weld subsystem example we used earlier in this guide, but let's take a more thorough look. Our comparison tells us that we have two new attributes require-bean-descriptor and non-portable-mode:

Now when we look at this we see that the default value for both of the attributes in the current model is false, which allows us more flexible behavior introduced in CDI 1.1 (which was introduced with this version of the subsystem). The old model does not have these attributes, and implements CDI 1.0, which under the hood (using our weld subsystem expertise knowledge) implies the values true for both of these. So our transformer must reject anything that is not true for these attributes. Let us look at the transformer registered by the WeldExtension:

This looks a bit more scary than the previous transformer we have seen, but isn't actually too bad. The first thing we do is register a DiscardAttributeChecker.DiscardAttributeValueChecker which will discard the attribute if it has the value true. It will not discard if it is undefined since that defaults to false. This is registered for both attributes.

If the attributes had the value true they will get discarded we will not hit the reject checker since discarded attributes never get checked for rejection. If on the other hand they were an expression (since we are interested in the actual value, but cannot evaluate what value an expression will resolve to on the target from the DC running the transformers), false, or undefined (which will then default to false) they will not get discarded and will need to be rejected. So our RejectAttributeChecker.DefaultRejectAttributeChecker.rejectAttribute() method will return true (i.e. reject) if the attribute value is undefined (since that defaults to false) or if it is defined and 'not equal to true'. It is better to check for 'not equal to true' than to check for 'equal to false' since if an expression was used we still want to reject, and only the 'not equal to true' check would actually kick in in that case.

The other thing we need in our DiscardAttributeChecker.DiscardAttributeValueChecker is to override the getRejectionLogMessage() method to get the message to be displayed when rejecting the transformation. In this case it says something along the lines "These attributes must be 'true' for use with CDI 1.0 '%s'", with the names of the attributes having been rejected substituting the %s.

Attribute has a different default value


(The gist of this is to use a value converter, such that if the attribute is undefined, and hence the default value will take effect, then the value gets converted to the current version's default value. This ensures that the legacy HC will use the same effective setting as current version HCs.

Note however that a change in default values is a form of incompatible API change, since CLI scripts written assuming the old defaults will now produce a configuration that behaves differently. Transformers make it possible to have a consistently configured domain even in the presence of this kind of incompatible change, but that doesn't mean such changes are good practice. They are generally unacceptable in WildFly's own subsystems.

One trick to ameliorate the impact of a default value change is to modify the xml parser for the old schema version such that if the xml attribute is not configured, the parser sets the old default value for the attribute, instead of undefined. This approach allows the parsing of old config documents to produce results consistent with what happened when they were created. It does not help with CLI scripts though.)

Attribute has a different type

Here the example comes from the capacity parameter some way into the modcluster subsystem, and the legacy version is AS 7.1.2.Final. There are quite a few differences, so I am only showing the ones relevant for this example:

So as we can see expressions are not allowed for the capacity attribute, and the current type is double while the legacy subsystem is int. So this means that if the value is for example 2.0 we can convert this to 2, but 2.5 cannot be converted. The way this is solved in the ModClusterExtension is to register the following some other attributes are registered here, but hopefully it is clear anyway:

So we register that we should reject expressions, and we also register the CapacityCheckerAndConverter for capacity. CapacityCheckerAndConverter extends the convenience class DefaultCheckersAndConverter which implements the DiscardAttributeChecker, RejectAttributeChecker, and AttributeConverter interfaces. We have seen DiscardAttributeChecker and RejectAttributeChecker in previous examples. Since we now need to convert a value we need an instance of AttributeConverter.

We should not discard so isValueDiscardable() from DiscardAttributeChecker always returns false:

Now we check to see if we can convert the attribute to an int and reject if not. Note that if it is an expression, we have no idea what its value will resolve to on the target host, so we need to reject it. Then we try to change it into an int, and reject if that was not possible:

And then finally we do the conversion:

Key Interfaces and Classes Relevant to Extension Developers

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 WildFly 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.

Extension Interface

The org.jboss.as.controller.Extension interface is the hook by which your extension to the AS kernel 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 WildFly 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.

WildFly Managed Resources

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 more 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.

ManagementResourceRegistration Interface

In the Java analogy used above, the ManagementResourceRegistration is analogous to the "class", while the Resource discussed below is analogous to an instance of that class.

A ManagementResourceRegistration represents the specification for a particular managed resource type. All resources whose address matches the same pattern will be of the same type, specified by the type's ManagementResourceRegistration. The MRR encapsulates:

  • A PathAddress showing the address pattern that matches resources of that type. This PathAddress can and typically does involve wildcards in the value of one or more elements of the address. In this case there can be more than one instance of the type, i.e. different Resource instances.
  • Definition of the various attributes exposed by resources of this type, including the OperationStepHandler implementations used for reading and writing the attribute values.
  • Definition of the various operations exposed by resources of this type, including the OperationStepHandler implementations used for handling user invocations of those operations.
  • Definition of child resource types. ManagementResourceRegistration instances form a tree.
  • Definition of management notifications emitted by resources of this type.
  • Definition of capabilities provided by resources of this type.
  • Definition of RBAC access constraints that should be applied by the management kernel when authorizing operations against resources of this type.
  • Whether the resource type is an alias to another resource type, and if so information about that relationship. Aliases are primarily used to preserve backwards compatibility of the management API when the location of a given type of resources is moved in a newer release.

The ManagementResourceRegistration interface is a subinterface of ImmutableManagementResourceRegistration, which provides a read-only view of the information encapsulated by the MRR. The MRR subinterface adds the methods needed for registering the attributes, operations, children, etc.

Extension developers do not directly instantiate an MRR. Instead they create a ResourceDefinition for the root resource type for each subsystem, and register it with the ExtensionContext passed in to their Extension implementation's initialize method:

The kernel uses the provided ResourceDefinition to construct a ManagementResourceRegistration and then passes that MRR to the various registerXXX methods implemented by the ResourceDefinition, giving it the change to record the resource type's attributes, operations and children.

ResourceDefinition Interface

An implementation of ResourceDefinition is the primary class used by an extension developer when defining a managed resource type. It provides basic information about the type, exposes a DescriptionProvider used to generate a DMR description of the type, and implements callbacks the kernel can invoke when building up the ManagementResourceRegistration to ask for registration of definitions of attributes, operations, children, notifications and capabilities.

Almost always an extension author will create their ResourceDefinition by creating a subclass of the org.jboss.as.controller.SimpleResourceDefinition class or of its PersistentResourceDefinition subclass. Both of these classes have constructors that take a Parameters object, which is a simple builder class to use to provide most of the key information about the resource type. The extension-specific subclass would then take responsibility for any additional behavior needed by overriding the registerAttributes, registerOperations, registerNotifications and registerChildren callbacks to do whatever is needed beyond what is provided by the superclasses.

For example, to add a writable attribute:

To register a custom operation:

To register a child resource type:


One of the things a ResourceDefinition must be able to do is provide a DescriptionProvider that provides a proper DMR description of the resource to use as the output for the standard read-resource-description management operation. Since you are almost certainly going to be using one of the standard ResourceDefinition implementations like SimpleResourceDefinition, the creation of this DescriptionProvider is largely handled for you. The one thing that is not handled for you is providing the localized free form text descriptions of the various attributes, operations, operation parameters, child types, etc used in creating the resource description.

For this you must provide an implementation of the ResourceDescriptionResolver interface, typically passed to the Parameters object provided to the SimpleResourceDefinition constructor. This interface has various methods that are invoked when a piece of localized text description is needed.

Almost certainly you'll satisfy this requirement by providing an instance of the StandardResourceDescriptionResolver class.

StandardResourceDescriptionResolver uses a ResourceBundle to load text from a properties file available on the classpath. The keys in the properties file must follow patterns expected by StandardResourceDescriptionResolver. See the StandardResourceDescriptionResolver javadoc for further details.

The biggest task here is to create the properties file and add the text descriptions. A text description must be provided for everything. The typical thing to do is to store this properties file in the same package as your Extension implementation, in a file named LocalDescriptions.properties.

AttributeDefinition Class

The AttributeDefinition class is used to create the static definition of one of a managed resource's attributes. It's a bit poorly named though, because the same interface is used to define the details of parameters to operations, and to define fields in the result of of operations.

The definition includes all the static information about the attribute/operation parameter/result field, e.g. the DMR ModelType of its value, whether its presence is required, whether it supports expressions, etc. See Description of the Management Model for a description of the metadata available. Almost all of this comes from the AttributeDefinition.

Besides basic metadata, the AttributeDefinition can also hold custom logic the kernel should use when dealing with the attribute/operation parameter/result field. For example, a ParameterValidator to use to perform special validation of values (beyond basic things like DMR type checks and defined/undefined checks), or an AttributeParser or AttributeMarshaller to use to perform customized parsing from and marshaling to XML.

WildFly Core's controller module provides a number of subclasses of AttributeDefinition used for the usual kinds of attributes. For each there is an associated builder class which you should use to build the AttributeDefinition. Most commonly used are SimpleAttributeDefinition, built by the associated SimpleAttributeDefinitionBuilder. This is used for attributes whose values are analogous to java primitives, String or byte[]. For collections, there are various subclasses of ListAttributeDefinition and MapAttributeDefinition. All have a Builder inner class. For complex attributes, i.e. those with a fixed set of fully defined fields, use ObjectTypeAttributeDefinition. (Each field in the complex type is itself specified by an AttributeDefinition.) Finally there's ObjectListAttributeDefinition and ObjectMapAttributeDefinition for lists whose elements are complex types and maps whose values are complex types respectively.

Here's an example of creating a simple attribute definition with extra validation of the range of allowed values:

Via a bit of dark magic, the kernel knows that the IntRangeValidator defined here is a reliable source of information on min and max values for the attribute, so when creating the read-resource-description output for the attribute it will use it and output min and max metadata. For STRING attributes, StringLengthValidator can also be used, and the kernel will see this and provide min-length and max-length metadata. In both cases the kernel is checking for the presence of a MinMaxValidator and if found it provides the appropriate metadata based on the type of the attribute.

Use EnumValidator to restrict a STRING attribute's values to a set of legal values:

EnumValidator is an implementation of AllowedValuesValidator that works with Java enums. You can use other implementations or write your own to do other types of restriction to certain values.

Via a bit of dark magic similar to what is done with MinMaxValidator, the kernel recognizes the presence of an AllowedValuesValidator and uses it to seed the allowed-values metadata in read-resource-description output.

Key Uses of AttributeDefinition

Your AttributeDefinition instances will be some of the most commonly used objects in your extension code. Following are the most typical uses. In each of these examples assume there is a SimpleAttributeDefinition stored in a constant FOO_AD that is available to the code. Typically FOO_AD would be a constant in the relevant ResourceDefinition implementation class. Assume FOO_AD represents an INT attribute.

Note that for all of these cases except for "Use in Extracting Data from the Configuration Model for Use in Runtime Services" there may be utility code that handles this for you. For example PersistentResourceXMLParser can handle the XML cases, and AbstractAddStepHandler can handle the "Use in Storing Data Provided by the User to the Configuration Model" case.

Use in XML Parsing

Here we have your extension's implementation of XMLElementReader<List<ModelNode>> that is being used to parse the xml for your subsystem and add ModelNode operations to the list that will be used to boot the server.

Note that the parsing code has deliberately been abbreviated. The key point is the parseAndSetParameter call. FOO_AD will validate the value read from XML, throwing an XMLStreamException with a useful message if invalid, including a reference to the current location of the reader. If valid, value will be converted to a DMR ModelNode of the appropriate type and stored as a parameter field of addOp. The name of the parameter will be what FOO_AD.getName() returns.

If you use PersistentResourceXMLParser this parsing logic is handled for you and you don't need to write it yourself.

Use in Storing Data Provided by the User to the Configuration Model

Here we illustrate code in an OperationStepHandler that extracts a value from a user-provided operation and stores it in the internal model:

As the name implies validateAndSet will validate the value in operation before setting it. A validation failure will result in an OperationFailedException with an appropriate message, which the kernel will use to provide a failure response to the user.

Note that validateAndSet will not perform expression resolution. Expression resolution is not appropriate at this stage, when we are just trying to store data to the persistent configuration model. However, it will check for expressions and fail validation if found and FOO_AD wasn't built with setAllowExpressions(true).

This work of storing data to the configuration model is usually done in handlers for the add and write-attribute operations. If you base your handler implementations on the standard classes provided by WildFly Core, this part of the work will be handled for you.

Use in Extracting Data from the Configuration Model for Use in Runtime Services

This is the example you are most likely to use in your code, as this is where data needs to be extracted from the configuration model and passed to your runtime services. What your services need is custom, so there's no utility code we provide.

Assume as part of ... do other stuff in the last example that your handler adds a step to do further work once operation execution proceeds to RUNTIME state (see Operation Execution and the OperationContext for more on what this means):

Use resolveModelAttribute to extract data from the model. It does a number of things:

  • reads the value from the model
  • if it's an expression and expressions are supported, resolves it
  • if it's undefined and undefined is allowed but FOO_AD was configured with a default value, uses the default value
  • validates the result of that (which is how we check that expressions resolve to legal values), throwing OperationFailedException with a useful message if invalid
  • returns that as a ModelNode

If when you built FOO_AD you configured it such that the user must provide a value, or if you configured it with a default value, then you know the return value of resolveModelAttribute will be a defined ModelNode. Hence you can safely perform type conversions with it, as we do in the example above with the call to asInt(). If FOO_AD was configured such that it's possible that the attribute won't have a defined value, you need to guard against that, e.g.:

Use in Marshaling Configuration Model Data to XML

Your Extension must register an XMLElementWriter<SubsystemMarshallingContext> for each subsystem. This is used to marshal the subsystem's configuration to XML. If you don't use PersistentResourceXMLParser for this you'll need to write your own marshaling code, and AttributeDefinition will be used.

The SubsystemMarshallingContext provides a ModelNode that represents the entire resource tree for the subsystem (including child resources). Your XMLElementWriter should walk through that model, using marshalAsAttribute or marshalAsElement to write the attributes in each resource. If the model includes child node trees that represent child resources, create child xml elements for those and continue down the tree.

OperationDefinition and OperationStepHandler Interfaces

OperationDefinition defines an operation, particularly its name, its parameters and the details of any result value, with AttributeDefinition instances used to define the parameters and result details. The OperationDefinition is used to generate the read-operation-description output for the operation, and in some cases is also used by the kernel to decide details as to how to execute the operation.

Typically SimpleOperationDefinitionBuilder is used to create an OperationDefinition. Usually you only need to create an OperationDefinition for custom operations. For the common add and remove operations, if you provide minimal information about your handlers to your SimpleResourceDefinition implementation via the Parameters object passed to its constructor, then SimpleResourceDefinition can generate a correct OperationDefinition for those operations.

The OperationStepHandler is what contains the actual logic for doing what the user requests when they invoke an operation. As its name implies, each OSH is responsible for doing one step in the overall sequence of things necessary to give effect to what the user requested. One of the things an OSH can do is add other steps, with the result that an overall operation can involve a great number of OSHs executing. (See Operation Execution and the OperationContext for more on this.)

Each OSH is provided in its execute method with a reference to the OperationContext that is controlling the overall operation, plus an operation ModelNode that represents the operation that particular OSH is being asked to deal with. The operation node will be of ModelType.OBJECT with the following key/value pairs:

  • a key named operation with a value of ModelType.STRING that represents the name of the operation. Typically an OSH doesn't care about this information as it is written for an operation with a particular name and will only be invoked for that operation.
  • a key named address with a value of ModelType.LIST with list elements of ModelType.PROPERTY. This value represents the address of the resource the operation targets. If this key is not present or the value is undefined or an empty list, the target is the root resource. Typically an OSH doesn't care about this information as it can more efficiently get the address from the OperationContext via its getCurrentAddress() method.
  • other key/value pairs that represent parameters to the operation, with the key the name of the parameter. This is the main information an OSH would want from the operation node.

There are a variety of situations where extension code will instantiate an OperationStepHandler

  • When registering a writable attribute with a ManagementResourceRegistration (typically in an implementation of ResourceDefinition.registerAttributes), an OSH must be provided to handle the write-attribute operation.
  • When registering a read-only or read-write attribute that needs special handling of the read-attribute operation, an OSH must be provided.
  • When registering a metric attribute, an OSH must be provided to handle the read-attribute operation.
  • Most resources need OSHs created for the add and remove operations. These are passed to the Parameters object given to the SimpleResourceDefinition constructor, for use by the SimpleResourceDefinition in its implementation of the registerOperations method.
  • If your resource has custom operations, you will instantiate them to register with a ManagementResourceRegistration, typically in an implementation of ResourceDefinition.registerOperations
  • If an OSH needs to tell the OperationContext to add additional steps to do further handling, the OSH will create another OSH to execute that step. This second OSH is typically an inner class of the first OSH.

Operation Execution and the OperationContext

When the ModelController at the heart of the WildFly Core management layer handles a request to execute an operation, it instantiates an implementation of the OperationContext interface to do the work. The OperationContext is configured with an initial list of operation steps it must execute. This is done in one of two ways:

  • During boot, multiple steps are configured, one for each operation in the list generated by the parser of the xml configuration file. For each operation, the ModelController finds the ManagementResourceRegistration that matches the address of the operation and finds the OperationStepHandler registered with that MRR for the operation's name. A step is added to the OperationContext for each operation by providing the operation ModelNode itself, plus the OperationStepHandler.
  • After boot, any management request involves only a single operation, so only a single step is added. (Note that a composite operation is still a single operation; it's just one that internally executes via multiple steps.)

The ModelController then asks the OperationContext to execute the operation.

The OperationContext acts as both the engine for operation execution, and as the interface provided to OperationStepHandler implementations to let them interact with the rest of the system.

Execution Process

Operation execution proceeds via execution by the OperationContext of a series of "steps" with an OperationStepHandler doing the key work for each step. As mentioned above, during boot the OC is initially configured with a number of steps, but post boot operations involve only a single step initially. But even a post-boot operation can end up involving numerous steps before completion. In the case of a /:read-resource(recursive=true) operation, thousands of steps might execute. This is possible because one of the key things an OperationStepHandler can do is ask the OperationContext to add additional steps to execute later.

Execution proceeds via a series of "stages", with a queue of steps maintained for each stage. An OperationStepHandler can tell the OperationContext to add a step for any stage equal to or later than the currently executing stage. The instruction can either be to add the step to the head of the queue for the stage or to place it at the end of the stage's queue.

Execution of a stage continues until there are no longer any steps in the stage's queue. Then an internal transition task can execute, and the processing of the next stage's steps begins.

Here is some brief information about each stage:


This stage is concerned with interacting with the persistent configuration model, either making changes to it or reading information from it. Handlers for this stage should not make changes to the runtime, and handlers running after this stage should not make changes to the persistent configuration model.

If any step fails during this stage, the operation will automatically roll back. Rollback of MODEL stage failures cannot be turned off. Rollback during boot results in abort of the process start.

The initial step or steps added to the OperationContext by the ModelController all execute in Stage.MODEL. This means that all OperationStepHandler instances your extension registers with a ManagementResourceRegistration must be designed for execution in Stage.MODEL. If you need work done in later stages your Stage.MODEL handler must add a step for that work.

When this stage completes, the OperationContext internally performs model validation work before proceeding on to the next stage. Validation failures will result in rollback.


This stage is concerned with interacting with the server runtime, either reading from it or modifying it (e.g. installing or removing services or updating their configuration.) By the time this stage begins, all model changes are complete and model validity has been checked. So typically handlers in this stage read their inputs from the model, not from the original operation ModelNode provided by the user.

Most OperationStepHandler logic written by extension authors will be for Stage.RUNTIME. The vast majority of Stage.MODEL handling can best be performed by the base handler classes WildFly Core provides in its controller module. (See below for more on those.)

During boot failures in Stage.RUNTIME will not trigger rollback and abort of the server boot. After boot, by default failures here will trigger rollback, but users can prevent that by using the rollback-on-runtime-failure header. However, a RuntimeException thrown by a handler will trigger rollback.

At the end of Stage.RUNTIME, the OperationContext blocks waiting for the MSC service container to stabilize (i.e. for all services to have reached a rest state) before moving on to the next stage.


Service container verification work is performed in this stage, checking that any MSC changes made in Stage.RUNTIME had the expected effect. Typically extension authors do not add any steps in this stage, as the steps automatically added by the OperationContext itself are all that are needed. You can add a step here though if you have an unusual use case where you need to verify something after MSC has stabilized.

Handlers in this stage should not make any further runtime changes; their purpose is simply to do verification work and fail the operation if verification is unsuccessful.

During boot failures in Stage.VERIFY will not trigger rollback and abort of the server boot. After boot, by default failures here will trigger rollback, but users can prevent that by using the rollback-on-runtime-failure header. However, a RuntimeException thrown by a handler will trigger rollback.

There is no special transition work at the end of this stage.


Extension authors should not add steps in this stage; it is only for use by the kernel.

Steps needed to execute rollout across the domain of an operation that affects multiple processes in a managed domain run here. This stage is only run on Host Contoller processes, never on servers.

Stage.DONE and ResultHandler / RollbackHandler Execution

This stage doesn't maintain a queue of steps; no OperationStepHandler executes here. What does happen here is persistence of any configuration changes to the xml file and commit or rollback of changes affecting multiple processes in a managed domain.

While no OperationStepHandler executes in this stage, following persistence and transaction commit all ResultHandler or RollbackHandler callbacks registered with the OperationContext by the steps that executed are invoked. This is done in the reverse order of step execution, so the callback for the last step to run is the first to be executed. The most common thing for a callback to do is to respond to a rollback by doing whatever is necessary to reverse changes made in Stage.RUNTIME. (No reversal of Stage.MODEL changes is needed, because if an operation rolls back the updated model produced by the operation is simply never published and is discarded.)

Tips About Adding Steps

Here are some useful tips about how to add steps:

  • Add a step to the head of the current stage's queue if you want it to execute next, prior to any other steps. Typically you would use this technique if you are trying to decompose some complex work into pieces, with reusable logic handling each piece. There would be an OperationStepHandler for each part of the work, added to the head of the queue in the correct sequence. This would be a pretty advanced use case for an extension author but is quite common in the handlers provided by the kernel.
  • Add a step to the end of the queue if either you don't care when it executes or if you do care and want to be sure it executes after any already registered steps.
    • A very common example of this is a Stage.MODEL handler adding a step for its associated Stage.RUNTIME work. If there are multiple model steps that will execute (e.g. at boot or as part of handling a composite), each will want to add a runtime step, and likely the best order for those runtime steps is the same as the order of the model steps. So if each adds its runtime step at the end, the desired result will be achieved.
    • A more sophisticated but important scenario is when a step may or may not be executing as part of a larger set of steps, i.e. it may be one step in a composite or it may not. There is no way for the handler to know. But it can assume that if it is part of a composite, the steps for the other operations in the composite are already registered in the queue. (The handler for the composite op guarantees this.) So, if it wants to do some work (say validation of the relationship between different attributes or resources) the input to which may be affected by possible other already registered steps, instead of doing that work itself, it should register a different step at the end of the queue and have that step do the work. This will ensure that when the validation step runs, the other steps in the composite will have had a chance to do their work. Rule of thumb: always doing any extra validation work in an added step.
Passing Data to an Added Step

Often a handler author will want to share state between the handler for a step it adds and the handler that added it. There are a number of ways this can be done:

  • Very often the OperationStepHandler for the added class is an inner class of the handler that adds it. So here sharing state is easily done using final variables in the outer class.
  • The handler for the added step can accept values passed to its constructor which can serve as shared state.
  • The OperationContext includes an Attachment API which allows arbitary data to be attached to the context and retrieved by any handler that has access to the attachment key.
  • The OperationContext.addStep methods include overloaded variants where the caller can pass in an operation ModelNode that will in turn be passed to the execute method of the handler for the added step. So, state can be passed via this ModelNode. It's important to remember though that the address field of the operation will govern what the OperationContext sees as the target of operation when that added step's handler executes.
Controlling Output from an Added Step

When an OperationStepHandler wants to report an operation result, it calls the OperationContext.getResult() method and manipulates the returned ModelNode. Similarly for failure messages it can call OperationContext.getFailureDescription(). The usual assumption when such a call is made is that the result or failure description being modified is the one at the root of the response to the end user. But this is not necessarily the case.

When an OperationStepHandler adds a step it can use one of the overloaded OperationContext.addStep variants that takes a response ModelNode parameter. If it does, whatever ModelNode it passes in will be what is updated as a result of OperationContext.getResult() and OperationContext.getFailureDescription() calls by the step's handler. This node does not need to be one that is directly associated with the response to the user.

How then does the handler that adds a step in this manner make use of whatever results the added step produces, since the added step will not run until the adding step completes execution? There are a couple of ways this can be done.

The first is to add yet another step, and provide it a reference to the response node used by the second step. It will execute after the second step and can read its response and use it in formulating its own response.

The second way involves using a ResultHandler. The ResultHandler for a step will execute after any step that it adds executes. And, it is legal for a ResultHandler to manipulate the "result" value for an operation, or its "failure-description" in case of failure. So, the handler that adds a step can provide to its ResultHandler a reference to the response node it passed to addStep, and the ResultHandler can in turn and use its contents to manipulate its own response.

This kind of handling wouldn't commonly be done by extension authors and great care needs to be taken if it is done. It is often done in some of the kernel handlers.

OperationStepHandler use of the OperationContext

All useful work an OperationStepHandler performs is done by invoking methods on the OperationContext. The OperationContext interface is extensively javadoced, so this section will just provide a brief partial overview. The OSH can use the OperationContext to:

  • Learn about the environment in which it is executing (getProcessType, getRunningMode, isBooting, getCurrentStage, getCallEnvironment, getSecurityIdentity, isDefaultRequiresRuntime, isNormalServer)
  • Learn about the operation (getCurrentAddress, getCurrentAddressValue, getAttachmentStream, getAttachmentStreamCount)
  • Read the Resource tree (readResource, readResourceFromRoot, getOriginalRootResource)
  • Manipulate the Resource tree (createResource, addResource, readResourceForUpdate, removeResource)
  • Read the resource type information (getResourceRegistration, getRootResourceRegistration)
  • Manipulate the resource type information (getResourceRegistrationForUpdate)
  • Read the MSC service container (getServiceRegistry(false))
  • Manipulate the MSC service container (getServiceTarget, getServiceRegistry(true), removeService)
  • Manipulate the process state (reloadRequired, revertReloadRequired, restartRequired, revertRestartRequired
  • Resolve expressions (resolveExpressions)
  • Manipulate the operation response (getResult, getFailureDescription, attachResultStream, runtimeUpdateSkipped)
  • Force operation rollback (setRollbackOnly)
  • Add other steps (addStep)
  • Share data with other steps (attach, attachIfAbsent, getAttachment, detach)
  • Work with capabilities (numerous methods)
  • Emit notifications (emit)
  • Request a callback to a ResultHandler or RollbackHandler (completeStep)

Locking and Change Visibility

The ModelController and OperationContext work together to ensure that only one operation at a time is modifying the state of the system. This is done via an exclusive lock maintained by the ModelController. Any operation that does not need to write never requests the lock and is able to proceed without being blocked by an operation that holds the lock (i.e. writes do not block reads.) If two operations wish to concurrently write, one or the other will get the lock and the loser will block waiting for the winner to complete and release the lock.

The OperationContext requests the exclusive lock the first time any of the following occur:

  • A step calls one of its methods that indicates a wish to modify the resource tree (createResource, addResource, readResourceForUpdate, removeResource)
  • A step calls one of its methods that indicates a wish to modify the ManagementResourceRegistration tree (getResourceRegistrationForUpdate)
  • A step calls one of its methods that indicates a desire to change MSC services (getServiceTarget, removeService or getServiceRegistry with the modify param set to true)
  • A step calls one of its methods that manipulates the capability registry (various)
  • A step explicitly requests the lock by calling the acquireControllerLock method (doing this is discouraged)

The step that acquired the lock is tracked, and the lock is released when the ResultHandler added by that step has executed. (If the step doesn't add a result handler, a default no-op one is automatically added).

When an operation first expresses a desire to manipulate the Resource tree or the capability registry, a private copy of the tree or registry is created and thereafter the OperationContext works with that copy. The copy is published back to the ModelController in Stage.DONE if the operation commits. Until that happens any changes to the tree or capability registry made by the operation are invisible to other threads. If the operation does not commit, the private copies are simply discarded.

However, the OperationContext does not make a private copy of the ManagementResourceRegistration tree before manipulating it, nor is there a private copy of the MSC service container. So, any changes made by an operation to either of those are immediately visible to other threads.

Resource Interface

An instance of the Resource interface holds the state for a particular instance of a type defined by a ManagementResourceRegistration. Referring back to the analogy mentioned earlier the ManagementResourceRegistration is analogous to a Java class while the Resource is analogous to an instance of that class.

The Resource makes available state information, primarily

  • Some descriptive metadata, such as its address, whether it is runtime-only and whether it represents a proxy to a another primary resource that resides on another process in a managed domain
  • A ModelNode of ModelType.OBJECT whose keys are the resource's attributes and whose values are the attribute values
  • Links to child resources such that the resources form a tree

Creating Resources

Typically extensions create resources via OperationStepHandler calls to the OperationContext.createResource method. However it is allowed for handlers to use their own Resource implementations by instantiating the resource and invoking OperationContext.addResource. The AbstractModelResource class can be used as a base class.

Runtime-Only and Synthetic Resources and the PlaceholderResourceEntry Class

A runtime-only resource is one whose state is not persisted to the xml configuration file. Many runtime-only resources are also "synthetic" meaning they are not added or removed as a result of user initiated management operations. Rather these resources are "synthesized" in order to allow users to use the management API to examine some aspect of the internal state of the process. A good example of synthetic resources are the resources in the /core-service=platform-mbeans branch of the resource tree. There are resources there that represent various aspects of the JVM (classloaders, memory pools, etc) but which resources are present entirely depends on what the JVM is doing, not on any management action. Another example are resources representing "core queues" in the WildFly messaging and messaging-artemismq subsystems. Queues are created as a result of activity in the message broker which may not involve calls to the management API. But for each such queue a management resource is available to allow management users to perform management operations against the queue.

It is a requirement of execution of a management operation that the OperationContext can navigate through the resource tree to a Resource object located at the address specified. This requirement holds true even for synthetic resources. How can this be handled, given the fact these resources are not created in response to management operations?

The trick involves using special implementations of Resource. Let's imagine a simple case where we have a parent resource which is fairly normal (i.e. it holds persistent configuration and is added via a user's add operation) except for the fact that one of its child types represents synthetic resources (e.g. message queues). How would this be handled?

First, the parent resource would require a custom implementation of the Resource interface. The OperationStepHandler for the add operation would instantiate it, providing it with access to whatever API is needed for it to work out what items exist for which a synthetic resource should be made available (e.g. an API provided by the message broker that provides access to its queues). The add handler would use the OperationContext.addResource method to tie this custom resource into the overall resource tree.

The custom Resource implementation would use special implementations of the various methods that relate to accessing children. For all calls that relate to the synthetic child type (e.g. core-queue) the custom implementation would use whatever API call is needed to provide the correct data for that child type (e.g. ask the message broker for the names of queues).

A nice strategy for creating such a custom resource is to use delegation. Use Resource.Factory.create}() to create a standard resource. Then pass it to the constructor of your custom resource type for use as a delegate. The custom resource type's logic is focused on the synthetic children; all other work it passes on to the delegate.

What about the synthetic resources themselves, i.e. the leaf nodes in this part of the tree? These are created on the fly by the parent resource in response to getChild, requireChild, getChildren and navigate calls that target the synthetic resource type. These created-on-the-fly resources can be very lightweight, since they store no configuration model and have no children. The PlaceholderResourceEntry class is perfect for this. It's a very lightweight Resource implementation with minimal logic that only stores the final element of the resource's address as state.

See LoggingResource in the WildFly Core logging subsystem for an example of this kind of thing. Searching for other uses of PlaceholderResourceEntry will show other examples.

DeploymentUnitProcessor Interface


Useful classes for implementing OperationStepHandler

The WildFly Core controller module includes a number of OperationStepHandler implementations that in some cases you can use directly, and that in other cases can serve as the base class for your own handler implementation. In all of these a general goal is to eliminate the need for your code to do anything in Stage.MODEL while providing support for whatever is appropriate for Stage.RUNTIME.

Add Handlers

AbstractAddStepHandler is a base class for handlers for add operations. There are a number of ways you can configure its behavior, the most commonly used of which are to:

  • Configure its behavior in Stage.MODEL by passing to its constructor AttributeDefinition and RuntimeCapability instances for the attributes and capabilities provided by the resource. The handler will automatically validate the operation parameters whose names match the provided attributes and store their values in the model of the newly added Resource. It will also record the presence of the given capabilities.
  • Control whether a Stage.RUNTIME step for the operation needs to be added, by overriding the protected boolean requiresRuntime(OperationContext context) method. Doing this is atypical; the standard behavior in the base class is appropriate for most cases.
  • Implement the primary logic of the Stage.RUNTIME step by overriding the protected void performRuntime(final OperationContext context, final ModelNode operation, final Resource resource) method. This is typically the bulk of the code in an AbstractAddStepHandler subclass. This is where you read data from the Resource model and use it to do things like configure and install MSC services.
  • Handle any unusual needs of any rollback of the Stage.RUNTIME step by overriding protected void rollbackRuntime(OperationContext context, final ModelNode operation, final Resource resource). Doing this is not typically needed, since if the rollback behavior needed is simply to remove any MSC services installed in performRuntime, the OperationContext will do this for you automatically.

AbstractBoottimeAddStepHandler is a subclass of AbstractAddStepHandler meant for use by add operations that should only do their normal Stage.RUNTIME work in server, boot, with the server being put in reload-required if executed later. Primarily this is used for add operations that register DeploymentUnitProcessor implementations, as this can only be done at boot.

Usage of AbstractBoottimeAddStepHandler is the same as for AbstractAddStepHandler except that instead of overriding performRuntime you override protected void performBoottime(OperationContext context, ModelNode operation, Resource resource).

A typical thing to do in performBoottime is to add a special step that registers one or more DeploymentUnitProcessor s.

Remove Handlers

TODO AbstractRemoveStepHandler ServiceRemoveStepHandler

Write attribute handlers

TODO AbstractWriteAttributeHandler

Reload-required handlers

ReloadRequiredAddStepHandler ReloadRequiredRemoveStepHandler ReloadRequiredWriteAttributeHandler

Use these for cases where, post-boot, the change to the configuration model made by the operation cannot be reflected in the runtime until the process is reloaded. These handle the mechanics of recording the need for reload and reverting it if the operation rolls back.

Restart Parent Resource Handlers

RestartParentResourceAddHandler RestartParentResourceRemoveHandler RestartParentWriteAttributeHandler

Use these in cases where a management resource doesn't directly control any runtime services, but instead simply represents a chunk of configuration that a parent resource uses to configure services it installs. (Really, this kind of situation is now considered to be a poor management API design and is discouraged. Instead of using child resources for configuration chunks, complex attributes on the parent resource should be used.)

These handlers help you deal with the mechanics of the fact that, post-boot, any change to the child resource likely requires a restart of the service provided by the parent.

Model Only Handlers

ModelOnlyAddStepHandler ModelOnlyRemoveStepHandler ModelOnlyWriteAttributeHandler

Use these for cases where the operation never affects the runtime, even at boot. All it does is update the configuration model. In most cases such a thing would be odd. These are primarily useful for legacy subsystems that are no longer usable on current version servers and thus will never do anything in the runtime. However, current version Domain Controllers must be able to understand the subsystem's configuration model to allow them to manage older Host Controllers running previous versions where the subsystem is still usable by servers. So these handlers allow the DC to maintain the configuration model for the subsystem.


AbstractRuntimeOnlyHandler is used for custom operations that don't involve the configuration model. Create a subclass and implement the protected abstract void executeRuntimeStep(OperationContext context, ModelNode operation) method. The superclass takes care of adding a Stage.RUNTIME step that calls your method.

ReadResourceNameOperationStepHandler is for cases where a resource type includes a 'name' attribute whose value is simply the value of the last element in the resource's address. There is no need to store the value of such an attribute in the resource's model, since it can always be determined from the resource address. But, if the value is not stored in the resource model, when the attribute is registered with ManagementResourceRegistration.registerReadAttribute an OperationStepHandler to handle the read-attribute operation must be provided. Use ReadResourceNameOperationStepHandler for this. (Note that including such an attribute in your management API is considered to be poor practice as it's just redundant data.)

 CLI Extensibility for Layered Products

In addition to supporting the ServiceLoader extension mechanism to load command handlers coming from outside of the CLI codebase, starting from the wildfly-core-1.0.0.Beta1 release the CLI running in a modular classloading environment can be extended with commands exposed in server extension modules. The CLI will look for and register extension commands when it (re-)connects to the controller by iterating through the registered by that time extensions and using the ServiceLoader mechanism on the extension modules. (Note, that this mechanism will work only for extensions available in the server installation the CLI is launched from.)

Here is an example of a simple command handler and its integration.

The command will simply print a message to the terminal. The next step is to implement the CLI CommandHandlerProvider interface.

The final step is to include META-INF/services/org.jboss.as.cli.CommandHandlerProvider entry into the JAR file containing the classes above with value org.jboss.as.test.cli.extensions.ExtCommandHandlerProvider.

All WildFly documentation

There are several guides in the WildFly documentation series. This list gives an overview of each of the guides:

*Getting Started Guide - Explains how to download and start WildFly.
*Getting Started Developing Applications Guide - Talks you through developing your first applications on WildFly, and introduces you to JBoss Tools and how to deploy your applications.
*JavaEE 6 Tutorial - A Java EE 6 Tutorial.
*Admin Guide - Tells you how to configure and manage your WildFly instances.
*Developer Guide - Contains concepts that you need to be aware of when developing applications for WildFly. Classloading is explained in depth.
*High Availability Guide - Reference guide for how to set up clustered WildFly instances.
*Extending WildFly - A guide to adding new functionality to WildFly.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 09, 2013

    There has apparently been some refactoring since the article was written? I noticed that nowadays the subsystem registration has the class

    public class TrackerSubsystemDefinition extends SimpleResourceDefinition {

    and it has been simplified a bit.
    public class TrackerSubsystemDefinition extends SimpleResourceDefinition {public class TrackerSubsystemDefinition extends SimpleResourceDefinition {