Getting the initial domain model

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

[{
    "domain-resource-address" => [],
    "domain-resource-model" => {
        "management-major-version" => 2,
        "management-minor-version" => 0,
        "management-micro-version" => 0,
        "release-version" => "8.0.0.Beta1-SNAPSHOT",
        "release-codename" => "WildFly"
    }
},
{
    "domain-resource-address" => [("extension" => "org.jboss.as.clustering.infinispan")],
    "domain-resource-model" => {"module" => "org.jboss.as.clustering.infinispan"}
},
--SNIP - the rest of the extensions --
{
    "domain-resource-address" => [("extension" => "org.jboss.as.weld")],
    "domain-resource-model" => {"module" => "org.jboss.as.weld"}
},
{
    "domain-resource-address" => [("system-property" => "java.net.preferIPv4Stack")],
    "domain-resource-model" => {
        "value" => "true",
        "boot-time" => undefined
    }
},
{
    "domain-resource-address" => [("profile" => "full-ha")],
    "domain-resource-model" => undefined
},
{
    "domain-resource-address" => [
        ("profile" => "full-ha"),
        ("subsystem" => "logging")
    ],
    "domain-resource-model" => {}
},
{
    "domain-resource-address" => [sss|WFLY8:Example subsystem],
    "domain-resource-model" => {
        "level" => "INFO",
        "enabled" => undefined,
        "encoding" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "filter-spec" => undefined,
        "autoflush" => undefined,
        "target" => undefined,
        "named-formatter" => undefined
    }
},
--SNIP---

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

An operation changes something in the domain configuration

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

[disconnected /] connect
[domain@localhost:9990 /] /profile=full/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {
        "slave" => {"server-one" => {"response" => {
            "outcome" => "success",
            "result" => undefined,
            "response-headers" => {
                "operation-requires-restart" => true,
                "process-state" => "restart-required"
            }
        }}},
        "master" => {
            "server-one" => {"response" => {
                "outcome" => "success",
                "response-headers" => {
                    "operation-requires-restart" => true,
                    "process-state" => "restart-required"
                }
            }},
            "server-two" => {"response" => {
                "outcome" => "success",
                "response-headers" => {
                    "operation-requires-restart" => true,
                    "process-state" => "restart-required"
                }
            }}
        }
    }}}
}

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.

Versioning of subsystems

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

public class SomeExtension implements Extension {

    private static final String SUBSYSTEM_NAME = "my-subsystem"'

    private static final int MANAGEMENT_API_MAJOR_VERSION = 2;
    private static final int MANAGEMENT_API_MINOR_VERSION = 0;
    private static final int MANAGEMENT_API_MICRO_VERSION = 0;

    /**
     * {@inheritDoc}
     * @see org.jboss.as.controller.Extension#initialize(org.jboss.as.controller.ExtensionContext)
     */
    @Override
    public void initialize(ExtensionContext context) {

        // IMPORTANT: Management API version != xsd version! Not all Management API changes result in XSD changes
        SubsystemRegistration registration = context.registerSubsystem(SUBSYSTEM_NAME, MANAGEMENT_API_MAJOR_VERSION,
                MANAGEMENT_API_MINOR_VERSION, MANAGEMENT_API_MICRO_VERSION);

        //Register the resource definitions
        ....
    }
    ....
}

Which sets the ModelVersion 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:

domain@localhost:9990 /] /extension=org.jboss.as.clustering.infinispan:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "module" => "org.jboss.as.clustering.infinispan",
        "subsystem" => {"infinispan" => {
            "management-major-version" => 2,
            "management-micro-version" => 0,
            "management-minor-version" => 0,
            "xml-namespaces" => [jboss:domain:infinispan:1.0",
                "urn:jboss:domain:infinispan:1.1",
                "urn:jboss:domain:infinispan:1.2",
                "urn:jboss:domain:infinispan:1.3",
                "urn:jboss:domain:infinispan:1.4",
                "urn:jboss:domain:infinispan:2.0"]
        }}
    }
}

Resource transformers

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

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

            <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>

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.

Operation transformers

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

/profile=full/subsystem=weld:write-attribute(name=require-bean-descriptor, value=false)

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.

Different profiles for different versions

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

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

<subsystem xmlns="urn:jboss:domain:weld:2.0"
      require-bean-descriptor="true"
      non-portable-mode="true"/>

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

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

<subsystem xmlns="urn:jboss:domain:weld:2.0"
      require-bean-descriptor="false"
      non-portable-mode="false"/>

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

<domain>
....
  <profiles>
    <profile name="full">
      <subsystem xmlns="urn:jboss:domain:weld:2.0"
        require-bean-descriptor="false"
        non-portable-mode="false"/>
      ...
    </profile>
    <profile name="full-legacy">
      <subsystem xmlns="urn:jboss:domain:weld:2.0"
        require-bean-descriptor="true"
        non-portable-mode="true"/>
      ...
    </profile>
  </profiles>
  ...
  <server-groups>
    <server-group name="main-server-group" profile="full">
      ....
    <server-group>
    <server-group name="main-server-group-legacy" profile="full-legacy">
      ....
    <server-group>
  </server-groups>
</domain>

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

<host xmlns="urn:jboss:domain:1.3" name="slave">
...
    <domain-controller>
       <remote host="${jboss.test.host.master.address}" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm">
            <ignored-resources type="profile">
                <instance name="full-legacy"/>
            </ignored-resources>
       </remote>
    </domain-controller>
....
</host>

Getting data for a previous version

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

1. Start the old version of WildFly/JBoss AS 7 using --server-config=standalone-full-ha.xml

2. Run org.wildfly.legacy.util.GrabModelVersionsUtil, which will output the subsystem versions to target/standalone-model-versions-running.dmr

3. Run org.wildfly.legacy.util.DumpStandaloneResourceDefinitionUtil which will output the full resource definition to target/standalone-resource-definition-running.dmr

4. Stop the running version of WildFly/JBoss AS 7

See what changed

To do this follow the following steps

1. Start the new version of WildFly using --server-config=standalone-full-ha.xml

2. Run org.wildfly.legacy.util.CompareModelVersionsUtil and answer the following questions"

   1. Enter Legacy AS version:

      • If it is known version in the tools/src/test/resources/legacy-models folder, enter the version number.

      • If it is a not known version, and you got the data yourself in the last step, enter 'running'

   2. Enter type:

      • Answer 'S'

   3. Read from target directory or from the legacy-models directory:

      • If it is known version in the controller/src/test/resources/legacy-models folder, enter 'l'.

      • If it is a not known version, and you got the data yourself in the last step, enter 't'

   4. Report on differences in the model when the management versions are different?:

      • Answer 'y'

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

Enter legacy AS version: 7.2.0.Final
Using target model: 7.2.0.Final
Enter type [S](standalone)/H(host)/D(domain)/F(domain + host):S
Read from target directory or from the legacy-models directory - t/[l]:
Report on differences in the model when the management versions are different? y/[n]: y
Reporting on differences in the model when the management versions are different
Loading legacy model versions for 7.2.0.Final....
Loaded legacy model versions
Loading model versions for currently running server...
Oct 01, 2013 6:26:03 PM org.xnio.Xnio <clinit>
INFO: XNIO version 3.1.0.CR7
Oct 01, 2013 6:26:03 PM org.xnio.nio.NioXnio <clinit>
INFO: XNIO NIO Implementation Version 3.1.0.CR7
Oct 01, 2013 6:26:03 PM org.jboss.remoting3.EndpointImpl <clinit>
INFO: JBoss Remoting version 4.0.0.Beta1
Loaded current model versions
Loading legacy resource descriptions for 7.2.0.Final....
Loaded legacy resource descriptions
Loading resource descriptions for currently running STANDALONE...
Loaded current resource descriptions
Starting comparison of the current....

====== Comparing core models ======
-- SNIP --

====== Comparing subsystem models ======
-- SNIP --
====== Resource root address: ["subsystem" => "remoting"] - Current version: 2.0.0; legacy version: 1.2.0 =======
--- Problems for relative address to root []:
Missing child types in current: []; missing in legacy [http-connector]
--- Problems for relative address to root ["remote-outbound-connection" => "*"]:
Missing attributes in current: []; missing in legacy [protocol]
Missing parameters for operation 'add' in current: []; missing in legacy [protocol]
-- SNIP --
====== Resource root address: ["subsystem" => "weld"] - Current version: 2.0.0; legacy version: 1.0.0 =======
--- Problems for relative address to root []:
Missing attributes in current: []; missing in legacy [require-bean-descriptor, non-portable-mode]
Missing parameters for operation 'add' in current: []; missing in legacy [require-bean-descriptor, non-portable-mode]

Done comparison of STANDALONE!

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.

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.

ResourceTransformationDescriptionBuilder

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

        ResourceTransformationDescriptionBuilder subsystemBuilder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();

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.

        TransformationDescription.Tools.register(subsystemBuilder.build(), subsystem, ModelVersion.create(1, 0, 0));

    subsystemBuilder.discardChildResource(PathElement.pathElement("child", "discarded"));

    subsystemBuilder.rejectChildResource(PathElement.pathElement("child", "reject"));

    ResourceTransformationDescriptionBuilder childBuilder =
       subsystemBuilder.addChildRedirection(PathElement.pathElement("newChild"), PathElement.pathElement("oldChild");

    ResourceTransformationDescriptionBuilder childBuilder =
       subsystemBuilder.addChildRedirection(PathElement.pathElement("newChild", "newName"), PathElement.pathElement("oldChild", "oldName");

    ResourceTransformationDescriptionBuilder childBuilder =
       subsystemBuilder.addChildResource(PathElement.pathElement("some-child"));
    //We don't actually want to transform anything in /subsystem-my-subsystem/some-child=* either :-)
    //We are interested in /subsystem-my-subsystem/some-child=*/another-level
    ResourceTransformationDescriptionBuilder anotherBuilder =
       childBuilder.addChildResource(PathElement.pathElement("another-level"));

    //Use anotherBuilder to add child-resource and/or attribute transformation
    ....

AttributeTransformationDescriptionBuilder

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:

    AttributeTransformationDescriptionBuilder attributeBuilder = subSystemBuilder.getAttributeBuilder();

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

    ResourceTransformationDescriptionBuilder childBuilder =
       subsystemBuilder.addChildResource(PathElement.pathElement("some-child"));
    AttributeTransformationDescriptionBuilder attributeBuilder = childBuilder.getAttributeBuilder();

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:

    /subsystem=my-subsystem/some-child=test:add(example=true)
    /subsystem=my-subsystem:write-attribute(name=example, value=true)
    /subsystem=my-subsystem:custom-operation(example=true)

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

    /subsystem=my-subsystem/some-child=test:add(example=false)
    /subsystem=my-subsystem/some-child=test:add()             //Here it 'example' is simply left undefined
    /subsystem=my-subsystem:write-attribute(name=example, value=false)
    /subsystem=my-subsystem:undefine-attribute(name=example)  //Again this makes 'example' undefined
    /subsystem=my-subsystem:custom-operation(example=false)

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

     DiscardAttributeChecker discardCheckerA = ....;
     attributeBuilder.setDiscard(discardCheckerA, "attr1", "attr2");

     DiscardAttributeChecker discardCheckerA = ....;
     DiscardAttributeChecker discardCheckerB = ....;
     attributeBuilder.setDiscard(discardCheckerA, "attr1");
     attributeBuilder.setDiscard(discardCheckerA, "attr2");

     DiscardAttributeChecker discardCheckerA = ....;
     DiscardAttributeChecker discardCheckerB = ....;
     attributeBuilder.setDiscard(discardCheckerA, "attr1");
     attributeBuilder.setDiscard(discardCheckerB, "attr1");

public interface DiscardAttributeChecker {

    /**
     * Returns {@code true} if the attribute should be discarded if expressions are used
     *
     * @return whether to discard if expressions are used
     */
    boolean isDiscardExpressions();

    /**
     * Returns {@code true} if the attribute should be discarded if it is undefined
     *
     * @return whether to discard if the attribute is undefined
     */
    boolean isDiscardUndefined();

    /**
     * Gets whether the given operation parameter can be discarded
     *
     * @param address the address of the operation
     * @param attributeName the name of the operation parameter.
     * @param attributeValue the value of the operation parameter.
     * @param operation the operation executed. This is unmodifiable.
     * @param context the context of the transformation
     *
     * @return {@code true} if the operation parameter value should be discarded, {@code false} otherwise.
     */
    boolean isOperationParameterDiscardable(PathAddress address, String attributeName, ModelNode attributeValue, ModelNode operation, TransformationContext context);

    /**
     * Gets whether the given attribute can be discarded
     *
     * @param address the address of the resource
     * @param attributeName the name of the attribute
     * @param attributeValue the value of the attribute
     * @param context the context of the transformation
     *
     * @return {@code true} if the attribute value should be discarded, {@code false} otherwise.
     */
    boolean isResourceAttributeDiscardable(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

}

protected abstract boolean isValueDiscardable(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

    private void initializeTransformers_1_1_0(SubsystemRegistration subsystemRegistration) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();
        builder.getAttributeBuilder()
            .setDiscard(
                   new DiscardAttributeChecker.DiscardAttributeValueChecker(new ModelNode(ExtendedPersistenceInheritance.DEEP.toString())),
                   JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE)
            .addRejectCheck(RejectAttributeChecker.DEFINED, JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE)
            .end();
        TransformationDescription.Tools.register(builder.build(), subsystemRegistration, ModelVersion.create(1, 1, 0));
    }

    private static void registerTransformers_1_1_0(SubsystemRegistration subsystemRegistration) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance()
                .getAttributeBuilder()
                 ...
                // We can always discard this attribute, because it's meaningless without the security-manager subsystem, and
                // a legacy slave can't have that subsystem in its profile.
                .setDiscard(DiscardAttributeChecker.ALWAYS, EJB3SubsystemRootResourceDefinition.DISABLE_DEFAULT_EJB_PERMISSIONS)
   ...

     RejectAttributeChecker rejectCheckerA = ....;
     attributeBuilder.addRejectCheck(rejectCheckerA, "attr1", "attr2");

     RejectAttributeChecker rejectCheckerA = ....;
     RejectAttributeChecker rejectCheckerB = ....;
     attributeBuilder.addRejectCheck(rejectCheckerA, "attr1");
     attributeBuilder.addRejectCheck(rejectCheckerB, "attr2");

     RejectAttributeChecker rejectCheckerA = ....;
     RejectAttributeChecker rejectCheckerB = ....;
     attributeBuilder.addRejectCheck(rejectCheckerA, "attr1");
     attributeBuilder.addRejectCheck(rejectCheckerB, "attr1, "attr2");

public interface RejectAttributeChecker {
    /**
     * Determines whether the given operation parameter value is not understandable by the target process and needs
     * to be rejected.
     *
     * @param address        the address of the operation
     * @param attributeName  the name of the attribute
     * @param attributeValue the value of the attribute
     * @param operation      the operation executed. This is unmodifiable.
     * @param context        the context of the transformation
     * @return {@code true} if the parameter value is not understandable by the target process and so needs to be rejected, {@code false} otherwise.
     */
    boolean rejectOperationParameter(PathAddress address, String attributeName, ModelNode attributeValue, ModelNode operation, TransformationContext context);

    /**
     * Gets whether the given resource attribute value is not understandable by the target process and needs
     * to be rejected.
     *
     * @param address        the address of the resource
     * @param attributeName  the name of the attribute
     * @param attributeValue the value of the attribute
     * @param context        the context of the transformation
     * @return {@code true} if the attribute value is not understandable by the target process and so needs to be rejected, {@code false} otherwise.
     */
    boolean rejectResourceAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

    /**
     * Returns the log message id used by this checker. This is used to group it so that all attributes failing a type of rejection
     * end up in the same error message
     *
     * @return the log message id
     */
    String getRejectionLogMessageId();

    /**
     * Gets the log message if the attribute failed rejection
     *
     * @param attributes a map of all attributes failed in this checker and their values
     * @return the formatted log message
     */
    String getRejectionLogMessage(Map<String, ModelNode> attributes);

}

protected abstract boolean rejectAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

    private void initializeTransformers_1_1_0(SubsystemRegistration subsystemRegistration) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();
        builder.getAttributeBuilder()
            .setDiscard(
                   new DiscardAttributeChecker.DiscardAttributeValueChecker(new ModelNode(ExtendedPersistenceInheritance.DEEP.toString())),
                   JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE)
            .addRejectCheck(RejectAttributeChecker.DEFINED, JPADefinition.DEFAULT_EXTENDEDPERSISTENCE_INHERITANCE)
            .end();
        TransformationDescription.Tools.register(builder.build(), subsystemRegistration, ModelVersion.create(1, 1, 0));
    }

    attributeBuilder
            .addRejectCheck(new ListRejectAttributeChecker(RejectAttributeChecker.EXPRESSIONS), "attr1");

    Map<String, RejectAttributeChecker> fieldRejectCheckers = new HashMap<String, RejectAttributeChecker>();
    fieldRejectCheckers.put("time", RejectAttributeChecker.SIMPLE_EXPRESSIONS);
    fieldRejectCheckers.put("unit", "Lunar Month");
    attributeBuilder
            .addRejectCheck(new ObjectFieldsRejectAttributeChecker(fieldRejectCheckers), "attr1");

    AttributeConverter converterA = ...;
    AttributeConverter converterB = ...;
    attributeBuilder
            .setValueConverter(converterA, "attr1", "attr2");
    attributeBuilder
            .setValueConverter(converterB, "attr3");

public interface AttributeConverter {

    /**
     * Converts an operation parameter
     *
     * @param address the address of the operation
     * @param attributeName the name of the operation parameter
     * @param attributeValue the value of the operation parameter to be converted
     * @param operation the operation executed. This is unmodifiable.
     * @param context the context of the transformation
     */
    void convertOperationParameter(PathAddress address, String attributeName, ModelNode attributeValue, ModelNode operation, TransformationContext context);

    /**
     * Converts a resource attribute
     *
     * @param address the address of the operation
     * @param attributeName the name of the attribute
     * @param attributeValue the value of the attribute to be converted
     * @param context the context of the transformation
     */
    void convertResourceAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

}

     AttributeConverter secondsToMs = new AttributeConverter.DefaultAttributeConverter() {
                  @Override
                  protected void convertAttribute(PathAddress address, String attributeName, ModelNode attributeValue,
                           TransformationContext context) {
                      if (attributeValue.isDefined()) {
                           int seconds = attributeValue.asInt();
                           int milliseconds = seconds * 1000;
                           attributeValue.set(milliseconds);
                      }
                  }
          };

     attributeBuilder.
          .setValueConverter(secondsToMs , "timeout")

     attributeBuilder.
          .addRejectCheck(SIMPLE_EXPRESSIONS, "timeout")
          .setValueConverter(secondsToMs , "timeout")

protected abstract void convertAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context);

     attributeBuilder.
         setValueConverter(AttributeConverter.Factory.createHardCoded(new ModelNode(1234) true), "port");

    attributeBuilder.addRename("my-name", "legacy-name");

    /subsystem=my-subsystem/:add(my-name=true)  ->
         /subsystem=my-subsystem/:add(legacy-name=true)
    /subsystem=my-subsystem:write-attribute(name=my-name, value=true) ->
         /subsystem=my-subsystem:write-attribute(name=legacy-name, value=true)
    /subsystem=my-subsystem:undefine-attribute(name=my-name) ->
         /subsystem=my-subsystem:undefine-attribute(name=legacy-name)

OperationTransformationOverrideBuilder

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:

OperationTransformationOverrideBuilder operationBuilder = subSystemBuilder.addOperationTransformationOverride("some-operation");

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:

    OperationTransformationOverrideBuilder operationBuilder = subSystemBuilder.addOperationTransformationOverride("some-operation");
    operationBuilder.inheritResourceAttributeDefinitions();
    operationBuilder.setValueConverter(AttributeConverter.Factory.createHardCoded(new ModelNode(1234) true), "port");

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.

    OperationTransformationOverrideBuilder operationBuilder = subSystemBuilder.addOperationTransformationOverride("some-operation");
    operationBuilder.rename("legacy-operation");

The old way

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

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

    private void registerTransformers(final SubsystemRegistration subsystem) {
        registerTransformers_1_0_0(subsystem);
        registerTransformers_1_1_0(subsystem);
    }

    /**
     * Registers transformers from the current version to ModelVersion 1.1.0
     */
    private void registerTransformers_1_1_0(SubsystemRegistration subsystem) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();
        builder.getAttributeBuilder()
            .addRejectCheck(RejectAttributeChecker.DEFINED, "new-attr")
            .end();
        TransformationDescription.Tools.register(builder.build(), subsystem, ModelVersion.create(1, 1, 0));
    }

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

    /**
     * Registers transformers from the current version to ModelVersion 1.0.0
     */
    private void registerTransformers_1_0_0(SubsystemRegistration subsystem) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();
        builder.getAttributeBuilder()
            .addRejectCheck(RejectAttributeChecker.DEFINED, "attr1", "new-attr")
            .end();
        TransformationDescription.Tools.register(builder.build(), subsystem, ModelVersion.create(1, 0, 0));
    }
}

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

Chained transformers

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

    private void registerTransformers(SubsystemRegistration subsystem) {
        ModelVersion version1_1_0 = ModelVersion.create(1, 1, 0);
        ModelVersion version1_0_0 = ModelVersion.create(1, 0, 0);

        ChainedTransformationDescriptionBuilder chainedBuilder =
              TransformationDescriptionBuilder.Factory.createChainedSubystemInstance(subsystem.getSubsystemVersion());

        //Differences between the current version and 1.1.0
        ResourceTransformationDescriptionBuilder builder110 =
            chainedBuilder.create(subsystem.getSubsystemVersion(), version1_1_0);
        builder110.getAttributeBuilder()
            .addRejectCheck(RejectAttributeChecker.DEFINED, "new-attr")
            .end();

        //Differences between the 1.1.0 and 1.0.0
        ResourceTransformationDescriptionBuilder builder100 =
            chainedBuilder.create(subsystem.getSubsystemVersion(), version1_0_0);
        builder110.getAttributeBuilder()
            .addRejectCheck(RejectAttributeChecker.DEFINED, "attr1")
            .end();

        chainedBuilder.buildAndRegister(subsystem, new ModelVersion[]{version1_0_0, version1_1_0});

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

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

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

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

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

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

• -Djboss.test.transformers.subsystem.old - enables the non-default subsystem tests.

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

• -Djboss.test.transformers.core.old - enables the non-default core model tests.

Testing a configuration that works

To test a configuration xxx

    @Test
    public void testTransformerAS712() throws Exception {
        testTransformer_1_0(ModelTestControllerVersion.V7_1_2_FINAL);
    }
    /**
     * Tests transformation of model from 1.1.0 version into 1.0.0 version.
     *
     * @throws Exception
     */
    private void testTransformer_1_0(ModelTestControllerVersion controllerVersion) throws Exception {
        String subsystemXml = "threads-transform-1_0.xml";   //This has no expressions not understood by 1.0
        ModelVersion modelVersion = ModelVersion.create(1, 0, 0); //The old model version
        //Use the non-runtime version of the extension which will happen on the HC
        KernelServicesBuilder builder = createKernelServicesBuilder(AdditionalInitialization.MANAGEMENT)
                .setSubsystemXmlResource(subsystemXml);

        final PathAddress subsystemAddress = PathAddress.pathAddress(PathElement.pathElement(SUBSYSTEM, mainSubsystemName));

        // Add legacy subsystems
        builder.createLegacyKernelServicesBuilder(null, controllerVersion, modelVersion)
                .addOperationValidationResolve("add", subsystemAddress.append(PathElement.pathElement("thread-factory")))
                .addMavenResourceURL("org.jboss.as:jboss-as-threads:" + controllerVersion.getMavenGavVersion())
                .excludeFromParent(SingleClassFilter.createFilter(ThreadsLogger.class));

        KernelServices mainServices = builder.build();
        KernelServices legacyServices = mainServices.getLegacyServices(modelVersion);
        Assert.assertNotNull(legacyServices);
        checkSubsystemModelTransformation(mainServices, modelVersion);
    }

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

    @Test
    public void deleteMeWhenDone() throws Exception {
        ModelTestControllerVersion controllerVersion = ModelTestControllerVersion.V7_1_2_FINAL;
        ModelVersion modelVersion = ModelVersion.create(1, 0, 0);
        KernelServicesBuilder builder = createKernelServicesBuilder(null);

        builder.createLegacyKernelServicesBuilder(null, controllerVersion, modelVersion)
            .addMavenResourceURL("org.jboss.as:jboss-as-threads:" + controllerVersion.getMavenGavVersion());
        KernelServices services = builder.build();

        generateLegacySubsystemResourceRegistrationDmr(services, modelVersion);
    }

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

Testing a configuration that does not work

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

    @Test
    public void testRejectExpressionsAS712() throws Exception {
        testRejectExpressions_1_0_0(ModelTestControllerVersion.V7_1_2_FINAL);
    }

    private void testRejectExpressions_1_0_0(ModelTestControllerVersion controllerVersion) throws Exception {
        // create builder for current subsystem version
        KernelServicesBuilder builder = createKernelServicesBuilder(createAdditionalInitialization());

        // create builder for legacy subsystem version
        ModelVersion version_1_0_0 = ModelVersion.create(1, 0, 0);
        builder.createLegacyKernelServicesBuilder(null, controllerVersion, version_1_0_0)
                .addMavenResourceURL("org.jboss.as:jboss-as-threads:" + controllerVersion.getMavenGavVersion())
                .excludeFromParent(SingleClassFilter.createFilter(ThreadsLogger.class));

        KernelServices mainServices = builder.build();
        KernelServices legacyServices = mainServices.getLegacyServices(version_1_0_0);

        Assert.assertNotNull(legacyServices);
        Assert.assertTrue("main services did not boot", mainServices.isSuccessfulBoot());
        Assert.assertTrue(legacyServices.isSuccessfulBoot());

        List<ModelNode> xmlOps = builder.parseXmlResource("expressions.xml");

        ModelTestUtils.checkFailedTransformedBootOperations(mainServices, version_1_0_0, xmlOps, getConfig());
    }

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:

    private FailedOperationTransformationConfig getConfig() {
        PathAddress subsystemAddress = PathAddress.pathAddress(ThreadsExtension.SUBSYSTEM_PATH);
        FailedOperationTransformationConfig.RejectExpressionsConfig allowedAndKeepalive =
                new FailedOperationTransformationConfig.RejectExpressionsConfig(PoolAttributeDefinitions.ALLOW_CORE_TIMEOUT, PoolAttributeDefinitions.KEEPALIVE_TIME);
...
        return new FailedOperationTransformationConfig()
                .addFailedAttribute(subsystemAddress.append(PathElement.pathElement(CommonAttributes.BLOCKING_BOUNDED_QUEUE_THREAD_POOL)),
                        allowedAndKeepalive)
                .addFailedAttribute(subsystemAddress.append(PathElement.pathElement(CommonAttributes.BOUNDED_QUEUE_THREAD_POOL)),
                        allowedAndKeepalive)
    }

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.

Child resource type does not exist in legacy model

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

====== Resource root address: ["subsystem" => "remoting"] - Current version: 2.0.0; legacy version: 1.2.0 =======
--- Problems for relative address to root []:
Missing child types in current: []; missing in legacy [http-connector]

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.

    @Override
    public void initialize(ExtensionContext context) {
        ....
        if (context.isRegisterTransformers()) {
            registerTransformers_1_1(registration);
            registerTransformers_1_2(registration);
        }
    }

    private void registerTransformers_1_2(SubsystemRegistration registration) {
        TransformationDescription.Tools.register(get1_2_0_1_3_0Description(), registration, VERSION_1_2);
    }

    private static TransformationDescription get1_2_0_1_3_0Description() {
        ResourceTransformationDescriptionBuilder builder = ResourceTransformationDescriptionBuilder.Factory.createSubsystemInstance();
        builder.rejectChildResource(HttpConnectorResource.PATH);

        return builder.build();
    }

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

Attribute does not exist in the legacy subsystem

====== Resource root address: ["subsystem" => "remoting"] - Current version: 2.0.0; legacy version: 1.2.0 =======
--- Problems for relative address to root []:
....
--- Problems for relative address to root ["remote-outbound-connection" => "*"]:
Missing attributes in current: []; missing in legacy [protocol]
Missing parameters for operation 'add' in current: []; missing in legacy [protocol]

    private void registerTransformers_1_2(SubsystemRegistration registration) {
        TransformationDescription.Tools.register(get1_2_0_1_3_0Description(), registration, VERSION_1_2);
    }

    private static TransformationDescription get1_2_0_1_3_0Description() {
        ResourceTransformationDescriptionBuilder builder = ResourceTransformationDescriptionBuilder.Factory.createSubsystemInstance();
        protocolTransform(builder.addChildResource(RemoteOutboundConnectionResourceDefinition.ADDRESS)
                .getAttributeBuilder());
        return builder.build();
    }

    private static AttributeTransformationDescriptionBuilder protocolTransform(AttributeTransformationDescriptionBuilder builder) {
        builder.setDiscard(new DiscardAttributeChecker.DiscardAttributeValueChecker(new ModelNode(Protocol.REMOTE.toString())), RemoteOutboundConnectionResourceDefinition.PROTOCOL)
                .addRejectCheck(RejectAttributeChecker.DEFINED, RemoteOutboundConnectionResourceDefinition.PROTOCOL);
        return builder;
    }

     private static AttributeTransformationDescriptionBuilder protocolTransform(AttributeTransformationDescriptionBuilder builder) {
        builder.setDiscard(new DiscardAttributeChecker.DefaultDiscardAttributeChecker() {
                    @Override
                    protected boolean isValueDiscardable(final PathAddress address, final String attributeName, final ModelNode attributeValue, final TransformationCon
                        return !attributeValue.isDefined() || attributeValue.asString().equals(Protocol.REMOTE.toString());
                    }
                }, RemoteOutboundConnectionResourceDefinition.PROTOCOL)
         .addRejectCheck(RejectAttributeChecker.DEFINED, RemoteOutboundConnectionResourceDefinition.PROTOCOL);
         return builder;

====== Resource root address: ["subsystem" => "weld"] - Current version: 2.0.0; legacy version: 1.0.0 =======
--- Problems for relative address to root []:
Missing attributes in current: []; missing in legacy [require-bean-descriptor, non-portable-mode]
Missing parameters for operation 'add' in current: []; missing in legacy [require-bean-descriptor, non-portable-mode]

    private void registerTransformers(SubsystemRegistration subsystem) {
        ResourceTransformationDescriptionBuilder builder = TransformationDescriptionBuilder.Factory.createSubsystemInstance();
        //These new attributes are assumed to be 'true' in the old version but default to false in the current version. So discard if 'true' and reject if 'undefined'.
        builder.getAttributeBuilder()
                .setDiscard(new DiscardAttributeChecker.DiscardAttributeValueChecker(false, false, new ModelNode(true)),
                        WeldResourceDefinition.NON_PORTABLE_MODE_ATTRIBUTE, WeldResourceDefinition.REQUIRE_BEAN_DESCRIPTOR_ATTRIBUTE)
                .addRejectCheck(new RejectAttributeChecker.DefaultRejectAttributeChecker() {

                    @Override
                    public String getRejectionLogMessage(Map<String, ModelNode> attributes) {
                        return WeldMessages.MESSAGES.rejectAttributesMustBeTrue(attributes.keySet());
                    }

                    @Override
                    protected boolean rejectAttribute(PathAddress address, String attributeName, ModelNode attributeValue,
                            TransformationContext context) {
                        //This will not get called if it was discarded, so reject if it is undefined (default==false) or if defined and != 'true'
                        return !attributeValue.isDefined() || !attributeValue.asString().equals("true");
                    }
                }, WeldResourceDefinition.NON_PORTABLE_MODE_ATTRIBUTE, WeldResourceDefinition.REQUIRE_BEAN_DESCRIPTOR_ATTRIBUTE)
                .end();
        TransformationDescription.Tools.register(builder.build(), subsystem, ModelVersion.create(1, 0, 0));
    }

Attribute has a different default value

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

Attribute has a different type

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

====== Resource root address: ["subsystem" => "modcluster"] - Current version: 2.0.0; legacy version: 1.2.0 =======
...
--- Problems for relative address to root ["mod-cluster-config" => "configuration","dynamic-load-provider" => "configuration","custom-load-m
etric" => "*"]:
Different 'type' for attribute 'capacity'. Current: DOUBLE; legacy: INT
Different 'expressions-allowed' for attribute 'capacity'. Current: true; legacy: false
...
Different 'type' for parameter 'capacity' of operation 'add'. Current: DOUBLE; legacy: INT
Different 'expressions-allowed' for parameter 'capacity' of operation 'add'. Current: true; legacy: false

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:

        dynamicLoadProvider.addChildResource(LOAD_METRIC_PATH)
                    .getAttributeBuilder()
                        .addRejectCheck(RejectAttributeChecker.SIMPLE_EXPRESSIONS, TYPE, WEIGHT, CAPACITY, PROPERTY)
                        .addRejectCheck(CapacityCheckerAndConverter.INSTANCE, CAPACITY)
                        .setValueConverter(CapacityCheckerAndConverter.INSTANCE, CAPACITY)
                        ...
                        .end();

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.

    static class CapacityCheckerAndConverter extends DefaultCheckersAndConverter {

        static final CapacityCheckerAndConverter INSTANCE = new CapacityCheckerAndConverter();

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

        @Override
        protected boolean isValueDiscardable(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context) {
            //Not used for discard
            return false;
        }

        @Override
        public String getRejectionLogMessage(Map<String, ModelNode> attributes) {
            return ModClusterMessages.MESSAGES.capacityIsExpressionOrGreaterThanIntegerMaxValue(attributes.get(CAPACITY.getName()));
        }

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:

        @Override
        protected boolean rejectAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context) {
            if (checkForExpression(attributeValue)
                    || (attributeValue.isDefined() && !isIntegerValue(attributeValue.asDouble()))) {
                return true;
            }
            Long converted = convert(attributeValue);
            return (converted != null && (converted > Integer.MAX_VALUE || converted < Integer.MIN_VALUE));
        }

And then finally we do the conversion:

        @Override
        protected void convertAttribute(PathAddress address, String attributeName, ModelNode attributeValue, TransformationContext context) {
            Long converted = convert(attributeValue);
            if (converted != null && converted <= Integer.MAX_VALUE && converted >= Integer.MIN_VALUE) {
                attributeValue.set((int)converted.longValue());
            }
        }


        private Long convert(ModelNode attributeValue) {
            if (attributeValue.isDefined() && !checkForExpression(attributeValue)) {
                double raw = attributeValue.asDouble();
                if (isIntegerValue(raw)) {
                    return Math.round(raw);
                }
            }
            return null;
        }

        private boolean isIntegerValue(double raw) {
            return raw == Double.valueOf(Math.round(raw)).doubleValue();
        }

    }