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

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

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 15 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 15 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 15 make their servers reference the main-server-group server group, and the HCs using older versions of WildFly 15 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 15.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.