Extending WildFly

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:

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:

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.

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.

Changes to tests between 7.0.0 and 7.0.1

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

TypeDefinition.TICK.

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.

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 127.0.0.1 in the jboss.bind.address.management:127.0.0.1 example above.)

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:

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

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.wildfly.network.socket-binding.web'. The 'org.wildfly.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.

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.

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

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

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.

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.

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.

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.

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.

Important

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 remained on 1.0.0 for all versions of WildFly and JBoss AS 7 through Wildfly 18.

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

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.

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.

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 20 which supports Jakarta EE, and thus CDI. 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 20 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 20 make their servers reference the main-server-group server group, and the HCs using older versions of WildFly 20 make their servers reference the main-server-group-legacy server group.

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:

To do this follow the following steps

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.

Warning

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.

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.

Important

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

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.

This is the way that has been used up to WildFly 20.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.

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:

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.

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.

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.

– TODO

(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.)

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:

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.

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.

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:

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:

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:

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.

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.

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.

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:

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.

TODO AbstractRemoveStepHandler ServiceRemoveStepHandler

TODO AbstractWriteAttributeHandler

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.

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.

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

At the lowest level a JNDI entry is bound by installing a BinderService to a ServiceTarget:

But the example above is the simplest usage possible, it may become quite complicated if the entry’s value is not immediately available, for instance it is a value in another MSC service, or is a value in another JNDI entry. It’s also quite easy to introduce bugs when working with the service names, or incorrectly assume that other MSC functionality, such as alias names, may be used.

Using the new high level API, it’s as simple as:

If there is the need to access the binder’s service builder, perhaps to add a service verification handler or simply not install the binder service right away:

With respect to EE deployments, the subsystem API should not be used, since bindings may need to be discarded/overridden, thus a EE deployment processor should add a new binding in the form of a BindingConfiguration, to the EeModuleDescription or ComponentDescription, depending if the bind is specific to a component or not. An example of a deployment processor adding a binding:

A deployment processor may now also add a binding configuration to all components in a module:

Most cases for adding bindings to EE deployments are in the context of a processor deploying a XML descriptor, or scanning deployment classes for annotations, and there abstract types, such as the AbstractDeploymentDescriptorBindingsProcessor, which simplifies greatly the processor code for such use cases.

One particular use case is the parsing of EE Resource Definitions, and the reworked implementation provides high level abstract deployment processors for both XML descriptor and annotations, an example for each:

and