Addressing resources

Operation requests might not always have the address part or the parameters. E.g.

:read-resource

which will list all the node types for the current node.

To syntactically disambiguate between the commands and operations, operations require one of the following prefixes:

To execute an operation against the current node, e.g.

cd subsystem=web
:read-resource(recursive="true")

To execute an operation against a child node of the current node, e.g.

cd subsystem=web
./connector=http:read-resource

To execute an operation against the root node, e.g.

/subsystem=threads:read-resource

Available Operation Types and Descriptions

The operation types can be distinguished between common operations that exist on any node and specific operations that belong to a particular configuration resource (i.e. subsystem). The common operations are:

• add

• read-attribute

• read-children-names

• read-children-resources

• read-children-types

• read-operation-description

• read-operation-names

• read-resource

• read-resource-description

• remove

• validate-address

• write-attribute

For a list of specific operations (e.g. operations that relate to the logging subsystem) you can always query the model itself. For example, to read the operations supported by the logging subsystem resource on a standalone server:

[[standalone@localhost:9999 /] /subsystem=logging:read-operation-names
{
   "outcome" => "success",
   "result" => [
       "add",
       "change-root-log-level",
       "read-attribute",
       "read-children-names",
       "read-children-resources",
       "read-children-types",
       "read-operation-description",
       "read-operation-names",
       "read-resource",
       "read-resource-description",
       "remove-root-logger",
       "root-logger-assign-handler",
       "root-logger-unassign-handler",
       "set-root-logger",
       "validate-address",
       "write-attribute"
   ]
}

As you can see, the logging resource offers four additional operations, namely root-logger-assign-handler, root-logger-unassign-handler , set-root-logger and remove-root-logger.

Further documentation about a resource or operation can be retrieved through the description:

[standalone@localhost:9999 /] /subsystem=logging:read-operation-description(name=change-root-log-level)
{
   "outcome" => "success",
   "result" => {
       "operation-name" => "change-root-log-level",
       "description" => "Change the root logger level.",
       "request-properties" => {"level" => {
           "type" => STRING,
           "description" => "The log level specifying which message levels will be logged by this logger.
                            Message levels lower than this value will be discarded.",
           "required" => true
       }}
   }
}

Host

Each "Host" box in the above diagram represents a physical or virtual host. A physical host can contain zero, one or more server instances.

Host Controller

When the domain.sh or domain.bat script is run on a host, a process known as a Host Controller is launched. The Host Controller is solely concerned with server management; it does not itself handle application server workloads. The Host Controller is responsible for starting and stopping the individual application server processes that run on its host, and interacts with the Domain Controller to help manage them.

Each Host Controller by default reads its configuration from the domain/configuration/host.xml file located in the unzipped JBoss Application Server 7 installation on its host's filesystem. The host.xml file contains configuration information that is specific to the particular host. Primarily:

• the listing of the names of the actual JBoss Application Server 7 instances that are meant to run off of this installation.

• configuration of how the Host Controller is to contact the Domain Controller to register itself and access the domain configuration. This may either be a configuration of how to find and contact a remote Domain Controller, or a configuration telling the Host Controller to itself act as the Domain Controller.

• configuration of items that are specific to the local physical installation. For example, named interface definitions declared in domain.xml (see below) can be mapped to an actual machine-specific IP address in host.xml. Abstract path names in domain.xml can be mapped to actual filesystem paths in host.xml.

Domain Controller

One Host Controller instance is configured to act as the central management point for the entire domain, i.e. to be the Domain Controller. The primary responsibility of the Domain Controller is to maintain the domain's central management policy, to ensure all Host Controllers are aware of its current contents, and to assist the Host Controllers in ensuring any running application server instances are configured in accordance with this policy. This central management policy is stored by default in the domain/configuration/domain.xml file in the unzipped JBoss Application Server 7 installation on Domain Controller's host's filesystem.

A domain.xml file must be located in the domain/configuration directory of an installation that's meant to run the Domain Controller. It does not need to be present in installations that are not meant to run a Domain Controller; i.e. those whose Host Controller is configured to contact a remote Domain Controller. The presence of a domain.xml file on such a server does no harm.

The domain.xml file includes, among other things, the configuration of the various "profiles" that JBoss Application Server 7 instances in the domain can be configured to run. A profile configuration includes the detailed configuration of the various subsystems that comprise that profile (e.g. an embedded JBoss Web instance is a subsystem; a JBoss TS transaction manager is a subsystem, etc). The domain configuration also includes the definition of groups of sockets that those subsystems may open. The domain configuration also includes the definition of "server groups":

Server Group

A server group is set of server instances that will be managed and configured as one. In a managed domain each application server instance is a member of a server group. (Even if the group only has a single server, the server is still a member of a group.) It is the responsibility of the Domain Controller and the Host Controllers to ensure that all servers in a server group have a consistent configuration. They should all be configured with the same profile and they should have the same deployment content deployed.

The domain can have multiple server groups. The above diagram shows two server groups, "ServerGroupA" and "ServerGroupB". Different server groups can be configured with different profiles and deployments; for example in a domain with different tiers of servers providing different services. Different server groups can also run the same profile and have the same deployments; for example to support rolling application upgrade scenarios where a complete service outage is avoided by first upgrading the application on one server group and then upgrading a second server group.

An example server group definition is as follows:

<server-group name="main-server-group" profile="default">
    <socket-binding-group ref="standard-sockets"/>
    <deployments>
        <deployment name="foo.war_v1" runtime-name="foo.war" />
        <deployment name="bar.ear" runtime-name="bar.ear" />
    </deployments>
</server-group>

A server-group configuration includes the following required attributes:

• name -- the name of the server group

• profile -- the name of the profile the servers in the group should run

In addition, the following optional elements are available:

• socket-binding-group -- specifies the name of the default socket binding group to use on servers in the group. Can be overridden on a per-server basis in host.xml. If not provided in the server-group element, it must be provided for each server in host.xml.

• deployments -- the deployment content that should be deployed on the servers in the group.

• system-properties -- system properties that should be set on all servers in the group

• jvm -- default jvm settings for all servers in the group. The Host Controller will merge these settings with any provided in host.xml to derive the settings to use to launch the server's JVM. See JVM settings for further details.

Server

Each "Server" in the above diagram represents an actual application server instance. The server runs in a separate JVM process from the Host Controller. The Host Controller is responsible for launching that process. (In a managed domain the end user cannot directly launch a server process from the command line.)

The Host Controller synthesizes the server's configuration by combining elements from the domain wide configuration (from domain.xml ) and the host-specific configuration (from host.xml ).

Standalone server

The structure of the managed resource tree is quite close to the structure of the standalone.xml configuration file.

• The root resource

  • extension – extensions installed in the server

  • path – paths available on the server

  • system-property – system properties set as part of the configuration (i.e. not on the command line)

  • core-service=management – the server's core management services

  • core-service=service-container – resource for the JBoss MSC ServiceContainer that's at the heart of the AS

  • subsystem – the subsystems installed on the server. The bulk of the management model will be children of type subsystem

  • interface – interface configurations

  • socket-binding-group – the central resource for the server's socket bindings

    • socket-binding – individual socket binding configurations

  • deployment – available deployments on the server

Managed domain

In a managed domain, the structure of the managed resource tree spans the entire domain, covering both the domain wide configuration (e.g. what's in domain.xml, the host specific configuration for each host (e.g. what's in host.xml, and the resources exposed by each running application server. The Host Controller processes in a managed domain provide access to all or part of the overall resource tree. How much is available depends on whether the management client is interacting with the Host Controller that is acting as the master Domain Controller. If the Host Controller is the master Domain Controller, then the section of the tree for each host is available. If the Host Controller is a slave to a remote Domain Controller, then only the portion of the tree associated with that host is available.

• The root resource for the entire domain. The persistent configuration associated with this resource and its children, except for those of type host, is persisted in the domain.xml file on the Domain Controller.

  • extension – extensions available in the domain

  • path – paths available on across the domain

  • system-property – system properties set as part of the configuration (i.e. not on the command line) and available across the domain

  • profile – sets of subsystem configurations that can be assigned to server groups

    • subsystem – configuration of subsystems that are part of the profile

  • interface – interface configurations

  • socket-binding-group – sets of socket bindings configurations that can be applied to server groups

    • socket-binding – individual socket binding configurations

  • deployment – deployments available for assignment to server groups

  • server-group – server group configurations

  • host – the individual Host Controllers. Each child of this type represents the root resource for a particular host. The persistent configuration associated with one of these resources or its children is persisted in the host's host.xml file.

    • path – paths available on each server on the host

    • system-property – system properties to set on each server on the host

    • core-service=management – the Host Controller's core management services

    • interface – interface configurations that apply to the Host Controller or servers on the host

    • jvm – JVM configurations that can be applied when launching servers

    • server-config – configuration describing how the Host Controller should launch a server; what server group configuration to use, and any server-specific overrides of items specified in other resources

    • server – the root resource for a running server. Resources from here and below are not directly persisted; the domain-wide and host level resources contain the persistent configuration that drives a server

      • extension – extensions installed in the server

      • path – paths available on the server

      • system-property – system properties set as part of the configuration (i.e. not on the command line)

      • core-service=management – the server's core management services

      • core-service=service-container – resource for the JBoss MSC ServiceContainer that's at the heart of the AS

      • subsystem – the subsystems installed on the server. The bulk of the management model will be children of type subsystem

      • interface – interface configurations

      • socket-binding-group – the central resource for the server's socket bindings

        • socket-binding – individual socket binding configurations

      • deployment – available deployments on the server

Stack and address preference

The system properties java.net.preferIPv4Stack and java.net.preferIPv6Addresses are used to configure the JVM for use with IPv4 or IPv6 addresses. With AS7, in order to run using IPv4 addresses, we need to specify java.net.preferIPv4Stack=true; in order to run the AS7 with IPv6 addresses, we need to specify java.net.preferIPv4Stack=false (the JVM default) and java.net.preferIPv6Addresses=true. The latter ensures that any hostname to IP address conversions always return IPv6 address variants.

These system properties are conveniently set by the JAVA_OPTS environment variable, defined in the standalone.conf (or domain.conf) file. For example, to change the IP stack preference from its default of IPv4 to IPv6, edit the standalone.conf (or domain.conf) file and change its default IPv4 setting:

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=true ..."
...

to an IPv6 suitable setting:

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true ..."
...

IP address literals

To change the IP address literals referenced in standalone.xml (or domain.xml), first visit the interface declarations and ensure that valid IPv6 addresses are being used as interface values. For example, to change the default configuration in which the loopback interface is used as the primary interface, change from the IPv4 loopback address:

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
</interfaces>

to the IPv6 loopback address:

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:[::1]}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:[::1]}"/>
  </interface>
</interfaces>

Note that when embedding IPv6 address literals in the substitution expression, square brackets surrounding the IP address literal are used to avoid ambiguity. This follows the convention for the use of IPv6 literals in URLs.

Over and above making such changes for the interface definitions, you should also check the rest of your configuration file and adjust IP address literals from IPv4 to IPv6 as required.

Inbound Connections

<native-interface security-realm="ManagementRealm">...</native-interface>
<http-interface security-realm="ManagementRealm">...</http-interface>

<subsystem xmlns="urn:jboss:domain:remoting:1.1">
  <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"/>
</subsystem>

Outbound Connections

<remote-outbound-connection name="remote-ejb-connection"
                            outbound-socket-binding-ref="binding-remote-ejb-connection"
                            username="user1"
                            security-realm="PasswordRealm">

<domain-controller>
  <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/>
</domain-controller>

Authentication

The authentication configuration is very similar to the ManagementRealm in that it enabled both the local mechanism and a username/password based Digest mechanism.

• local

The local configuration is similar to the ManagementRealm in that where the remote user does not supply a username it will be assumed that the username is $local, however in addition to this there is now an allowed-users attribute with a value of '*' - this means that the remote user can specify any username and it will be accepted over the local mechanism provided that the local verification is a success.

• properties

The properties definition works in exactly the same way as the definition for ManagementRealm except now the properties file is called application-users.properties.

Authorization

The contents of the Authorization element are specific to the ApplicationRealm, in this case a properties file is used to load a users roles.

The properties file is called application-roles.properties and is located in {jboss.home}/standalone/configuration or {jboss.home}/domain/configuration depending on the running mode of the server. The format of this file is username=ROLES where ROLES is a comma separated list of the users roles.

other security domain

<security-domain name="other" cache-type="default">
  <authentication>
    <login-module code="Remoting" flag="optional">
      <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>
    <login-module code="RealmDirect" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>
  </authentication>
</security-domain>

When applications are deployed to the application server they are associated with a security domain within the security subsystem, the other security domain is provided to work with the ApplicationRealm, this domain is defined with a pair of login modules Remoting and RealmDirect.

• Remoting

The Remoting login module is used to check if the request currently being authenticated is a request received over a Remoting connection, if so the identity that was created during the authentication process is used and associated with the current request.

If the request did not arrive over a Remoting connection this module does nothing and allows the JAAS based login to continue to the next module.

• RealmDirect

The RealmDirect login module makes use of a security realm to authenticate the current request if that did not occur in the Remoting login module and then use the realm to load the users roles, by default this login module assumes the realm to use is called ApplicationRealm although other names can be overridden.

The advantage of this approach is that all of the backing store configuration can be left within the realm with the security domain just delegating to the realm.

Adding a User

Adding users to the properties files is the primary purpose of this utility.

Updating a User

Within the add-user utility it is also possible to update existing users, in interactive mode you will be prompted to confirm if this is your intention.

Community Contributions

There are still a few features to add to the add-user utility such as removing users or adding application users with roles in non-interactive mode, if you are interested in contributing to JBoss AS development the add-user utility is a good place to start as it is a stand alone utility, however it is a part of the AS build so you can become familiar with the AS development processes without needing to delve straight into the internals of the application server.

<ssl />

<server-identities>
  <ssl protocol="...">
    <keystore path="..." relative-to="..." keystore-password="..." alias="..." key-password="..." />
  </ssl>
</server-identities>

• protocol - By default this is set to TLS and in general does not need to be set.

The SSL element then contains the nested <keystore /> element, this is used to define how to load the key from the file based (JKS) keystore.

• path (mandatory) - This is the path to the keystore, this can be an absolute path or relative to the next attribute.

• relative-to (optional) - The name of a service representing a path the keystore is relative to.

• keystore-password (mandatory) - The password required to open the keystore.

• alias (optional) - The alias of the entry to use from the keystore - for a keystore with multiple entries in practice the first usable entry is used but this should not be relied on and the alias should be set to guarantee which entry is used.

• key-password (optional) - The password to load the key entry, if omitted the keystore-password will be used instead.

<secret />

<server-identities>
  <secret value="..." />
</server-identities>

• value (mandatory) - The password to use for outbound connections encoded as Base64, this field also supports a vault expression should stronger protection be required.

<truststore />

<authentication>
  <truststore path="..." relative-to="..." keystore-password="..."/>
</authentication>

This element is used to define how to load a key store file that can be used as the trust store within the SSLContext we create internally, the store is then used to verify the certificates of the remote side of the connection be that inbound or outbound.

• path (mandatory) - This is the path to the keystore, this can be an absolute path or relative to the next attribute.

• relative-to (optional) - The name of a service representing a path the keystore is relative to.

• keystore-password (mandatory) - The password required to open the keystore.

<local />

<authentication>
  <local default-user="..." allowed-users="..." />
</authentication>

This element switches on the local authentication mechanism that allows clients to the server to verify that they are local to the server, at the protocol level it is optional for the remote client to send a user name in the authentication response.

• default-user (optional) - If the client does not pass in a username this is the assumed username, this value is also automatically added to the list of allowed-users.

• allowed-users (optional) - This attribute is used to specify a comma separated list of users allowed to authenticate using the local mechanism, alternatively '*' can be specified to allow any username to be specified.

<jaas />

<authentication>
  <jaas name="..." />
</authentication>

The jaas element is used to enable username and password based authentication where the supplied username and password are verified by making use of a configured jaas domain.

• name (mandatory) - The name of the jaas domain to use to verify the supplied username and password.

<ldap />

<authentication>
  <ldap connection="..." base-dn="..." recursive="..." user-dn="...">
    <username-filter attribute="..." />
    <advanced-filter filter="..." />
  </ldap>
</authentication>

The ldap element is used to define how LDAP searches will be used to authenticate a user, this works by first connecting to LDAP and performing a search using the supplied user name to identity the distinguished name of the user and then a subsequent connection is made to the server using the password supplied by the user - if this second connection is a success then authentication succeeds.

• connection (mandatory) - The name of the connection to use to connect to LDAP.

• base-dn (mandatory) - The distinguished name of the context to use to begin the search from.

• recursive (optional) - Should the filter be executed recursively? Defaults to false.

• user-dn (optional) - After the user has been found specifies which attribute to read for the users distinguished name, defaults to 'dn'.

Within the ldap element only one of <username-filter /> or <advanced-filter /> can be specified.

<properties />

<authentication>
  <properties path="..." relative-to="..." plain-text="..." />
</authentication>

The properties element is used to reference a properties file to load to read a users password or pre-prepared digest for the authentication process.

• path (mandatory) - The path to the properties file, either absolute or relative to the path referenced by the relative-to attribute.

• relative-to (optional) - The name of a path service that the defined path will be relative to.

• plain-text (optional) - Setting to specify if the passwords are stored as plain text within the properties file, defaults to false.

<users />

<authentication>
  <users>
    <user username="...">
      <password>...</password>
    </user>
  </users>
</authentication>

This is a very simple store of a username and password that stores both of these within the domain model, this is only really provided for the provision of simple examples.

• username (mandatory) - A users username.

The <password/> element is then used to define the password for the user.

<properties />

<authorization>
  <properties path="..." relative-to="..." />
</authorization>

The format of the properties file is username={ROLES} where {ROLES} is a comma separated list of the users roles.

• path (mandatory) - The path to the properties file, either absolute or relative to the path referenced by the relative-to attribute.

• relative-to (optional) - The name of a path service that the defined path will be relative to.

<ldap />

At the moment we only support outbound connections to ldap servers for the authentication process - this will later be expanded when we add support for database based authentication.

<outbound-connections>
  <ldap name="..." url="..." search-dn="..." search-credential="..." initial-context-factory="..." />
</outbound-connections>

The outbound connections are defined in this section and then referenced by name from the configuration that makes use of them.

• name (mandatory) - The unique name used to reference this connection.

• url (mandatory) - The URL use to establish the LDAP connection.

• search-dn (mandatory) - The distinguished name of the user to authenticate as to perform the searches.

• search-credential (mandatory) - The password required to connect to LDAP as the search-dn.

• initial-context-factory (optional) - Allows overriding the initial context factory, defaults to 'com.sun.jndi.ldap.LdapCtxFactory'

PasswordCredential

public final class PasswordCredential implements Credential { 
    public PasswordCredential(final char[] password);
    public char[] getPassword();
    void clear();
}

The PasswordCredential is already implemented so use this class if you have the plain text password of the remote user, by using this the secured interfaces will be able to continue using the Digest mechanism for authentication.

DigestCredential

public final class DigestCredential implements Credential {
    public DigestCredential(final String hash);
    public String getHash();
}

This class is also already implemented and should be returned if instead of the plain text password you already have a pre-prepared hash of the username, realm and password.

ValidatePasswordCredential

public interface ValidatePasswordCredential extends Credential {
    boolean validatePassword(final char[] password);
}

This is a special Credential type to use when it is not possible to obtain either a plain text representation of the password or a pre-prepared hash - this is an interface as you will need to provide an implementation to verify a supplied password. The down side of using this type of Credential is that the authentication mechanism used at the transport level will need to drop down from Digest to either HTTP Basic or SASL Plain which will now mean that the remote client is sending their credential across the network in the clear.

If you use this type of credential be sure to force the mechanism choice to Plain as described in the configuration section below.

PlugInProvider

public interface PlugInProvider {
    AuthenticationPlugIn<Credential> loadAuthenticationPlugIn(final String name);
    AuthorizationPlugIn loadAuthorizationPlugIn(final String name);
}

These methods are called with the name that is supplied in the plug-in elements that are contained within the authentication and authorization elements of the configuration, based on the sample configuration above the loadAuthenticationPlugIn method will be called with a parameter of 'Sample' and the loadAuthorizationPlugIn method will be called with a parameter of 'Delegate'.

Multiple plug-in providers may be available to the application server so if a PlugInProvider implementation does not recognise a name then it should just return null and the server will continue searching the other providers. If a PlugInProvider does recognise a name but fails to instantiate the PlugIn then a RuntimeException can be thrown to indicate the failure.

As a server could have many providers registered it is recommended that a naming convention including some form of hierarchy is used e.g. use package style names to avoid conflicts.

For the example the implementation is as follows: -

public class SamplePluginProvider implements PlugInProvider {
 
    public AuthenticationPlugIn<Credential> loadAuthenticationPlugIn(String name) {
        if ("Sample".equals(name)) {
            return new SampleAuthenticationPlugIn();
        }
        return null;
    }
 
    public AuthorizationPlugIn loadAuthorizationPlugIn(String name) {
        if ("Sample".equals(name)) {
            return new SampleAuthenticationPlugIn();
        } else if ("Delegate".equals(name)) {
            return new DelegateAuthorizationPlugIn();
        }
        return null;
    }
}

The load methods are called for each authentication attempt but it will be an implementation detail of the provider if it decides to return a new instance of the provider each time - in this scenario as we also use configuration and shared state then new instances of the implementations make sense.

To load the provider use a ServiceLoader so within the META-INF/services folder of the jar this project adds a file called 'org.jboss.as.domain.management.plugin.PlugInProvider' - this contains a single entry which is the fully qualified class name of the PlugInProvider implementation class.

org.jboss.as.sample.SamplePluginProvider

Package as a Module

To make the PlugInProvider available to the application it is bundled as a module and added to the modules already shipped with AS7.

To add as a module we first need a module.xml: -

<?xml version="1.0" encoding="UTF-8"?>

<module xmlns="urn:jboss:module:1.1" name="org.jboss.as.sample.plugin">
    <properties>
    </properties>

    <resources>
        <resource-root path="SamplePlugIn.jar"/>
    </resources>

    <dependencies>
        <module name="org.jboss.as.domain-management" />
    </dependencies>
</module>

The interfaces being implemented are in the 'org.jboss.as.domain-management' module so a dependency on that module is defined, this module.xml is then placed in the '{jboss.home}/modules/org/jboss/as/sample/plugin/main'.

The compiled classed and META-INF/services as described above are assmbled into a jar called SamplePlugIn.jar and also placed into this folder.

Looking back at the sample configuration at the top of the realm definition the following element was added: -

   <plug-ins>
      <plug-in module="org.jboss.as.sample.plugin"/>
   </plug-ins>

This element is used to list the modules that should be searched for plug-ins. As plug-ins are loaded during the server start up this search is a lazy search so don't expect a definition to a non existant module or to a module that does not contain a plug-in to report an error.

The AuthenticationPlugIn

The example AuthenticationPlugIn is implemented as: -

public class SampleAuthenticationPlugIn extends AbstractPlugIn {
 
    private static final String PASSWORD_SUFFIX = ".password";
    private static final String ROLES_SUFFIX = ".roles"; 
    private Map<String, String> configuration;
 
    public void init(Map<String, String> configuration, Map<String, Object> sharedState) throws IOException {
        this.configuration = configuration;
        // This will allow an AuthorizationPlugIn to delegate back to this instance.
        sharedState.put(AuthorizationPlugIn.class.getName(), this);
    }
 
    public Identity loadIdentity(String userName, String realm) throws IOException {
        String passwordKey = userName + PASSWORD_SUFFIX;
        if (configuration.containsKey(passwordKey)) {
            return new SampleIdentity(userName, configuration.get(passwordKey));
        }
        throw new IOException("Identity not found.");
    }
 
    public String[] loadRoles(String userName, String realm) throws IOException {
        String rolesKey = userName + ROLES_SUFFIX;
        if (configuration.containsKey(rolesKey)) {
            String roles = configuration.get(rolesKey);
            return roles.split(",");
        } else {
            return new String[0];
        }
    }
 
    private static class SampleIdentity implements Identity {
        private final String userName;
        private final Credential credential;
 
        private SampleIdentity(final String userName, final String password) {
            this.userName = userName;
            this.credential = new PasswordCredential(password.toCharArray());
        }
 
        public String getUserName() {
            return userName;
        }
 
        public Credential getCredential() {
            return credential;
        }
    }
}

As you can see from this implementation there is also an additional class being extended AbstractPlugIn - that is simply an abstract class that implements the AuthenticationPlugIn, AuthorizationPlugIn, and PlugInConfigurationSupport interfaces already. The properties that were defined in the configuration are passed in as a Map and importantly for this sample the plug-in adds itself to the shared state map.

The AuthorizationPlugIn

The example implementation of the authentication plug in is as follows: -

public class DelegateAuthorizationPlugIn extends AbstractPlugIn {
 
    private AuthorizationPlugIn authorizationPlugIn;
 
    public void init(Map<String, String> configuration, Map<String, Object> sharedState) throws IOException {
        authorizationPlugIn = (AuthorizationPlugIn) sharedState.get(AuthorizationPlugIn.class.getName());
    }
 
    public String[] loadRoles(String userName, String realm) throws IOException {
        return authorizationPlugIn.loadRoles(userName, realm);
    } 
 
}

This plug-in illustrates how two plug-ins can work together, by the AuthenticationPlugIn placing itself in the shared state map it is possible for the authorization plug-in to make use of it for the loadRoles implementation.

Another option to consider to achieve similar behaviour could be to provide an Identity implementation that also contains the roles and place this in the shared state map - the AuthorizationPlugIn can retrieve this and return the roles.

Forcing Plain Text Authentication

As mentioned earlier in this article if the ValidatePasswordCredential is going to be used then the authentication used at the transport level needs to be forced from Digest authentication to plain text authentication, this can be achieved by adding a mechanism attribute to the plug-in definition within the authentication element i.e.

  <authentication>
    <plug-in name="Sample" mechanism="PLAIN">

Standalone

Managed Domain

Standalone

Managed Domain

The following parameters take no value and are only usable on slave host controllers (i.e. hosts configured to connect to a remote domain controller.)

Common parameters

These parameters apply in both standalone or managed domain mode:

JDBC Driver Installation

jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver

Datasource Definitions

The datasource itself is defined within the subsystem datasources:

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS">
            <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
            <driver>h2</driver>
            <pool>
                <min-pool-size>10</min-pool-size>
                <max-pool-size>20</max-pool-size>
                <prefill>true</prefill>
            </pool>
            <security>
                <user-name>sa</user-name>
                <password>sa</password>
            </security>
        </datasource>
        <xa-datasource jndi-name="java:jboss/datasources/ExampleXADS" pool-name="ExampleXADS">
           <driver>h2</driver>
           <xa-datasource-property name="URL">jdbc:h2:mem:test</xa-datasource-property>
           <xa-pool>
                <min-pool-size>10</min-pool-size>
                <max-pool-size>20</max-pool-size>
                <prefill>true</prefill>
           </xa-pool>
           <security>
                <user-name>sa</user-name>
                <password>sa</password>
           </security>
        </xa-datasource>
        <drivers>
            <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
            </driver>
        </drivers>
  </datasources>

</subsystem>

_(See standalone/configuration/standalone.xml₎

As you can see the datasource references a driver by it's logical name.

You can easily query the same information through the CLI:

[standalone@localhost:9999 /] /subsystem=datasources:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "data-source" => {"java:/H2DS" => {
            "connection-url" => "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1",
            "jndi-name" => "java:/H2DS",
            "driver-name" => "h2",
            "pool-name" => "H2DS",
            "use-java-context" => true,
            "enabled" => true,
            "jta" => true,
            "pool-prefill" => true,
            "pool-use-strict-min" => false,
            "user-name" => "sa",
            "password" => "sa",
            "flush-strategy" => "FailingConnectionOnly",
            "background-validation" => false,
            "use-fast-fail" => false,
            "validate-on-match" => false,
            "use-ccm" => true
        }},
        "xa-data-source" => undefined,
        "jdbc-driver" => {"h2" => {
            "driver-name" => "h2",
            "driver-module-name" => "com.h2database.h2",
            "driver-xa-datasource-class-name" => "org.h2.jdbcx.JdbcDataSource"
        }}
    }
}


[standalone@localhost:9999 /] /subsystem=datasources:installed-drivers-list
{
    "outcome" => "success",
    "result" => [{
        "driver-name" => "h2",
        "deployment-name" => undefined,
        "driver-module-name" => "com.h2database.h2",
        "module-slot" => "main",
        "driver-xa-datasource-class-name" => "org.h2.jdbcx.JdbcDataSource",
        "driver-class-name" => "org.h2.Driver",
        "driver-major-version" => 1,
        "driver-minor-version" => 2,
        "jdbc-compliant" => true
    }]
}

The CLI offers a set of commands to create and modify datasources:

[standalone@localhost:9999 /] help
Supported commands:

 [...]

 data-source             - allows to add new, modify and remove existing data sources
 xa-data-source          - allows add new, modify and remove existing XA data sources

For a more detailed description of a specific command,
execute the command with '--help' as the argument.

Using security domains

Information can be found at https://community.jboss.org/wiki/JBossAS7SecurityDomainModel

Deployment of -ds.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -ds.xml file following the schema:

http://docs.jboss.org/ironjacamar/schema/datasources_1_1.xsd

It is mandatory to use a reference to an already deployed / defined <driver> entry.

Component Reference

The datasource subsystem is provided by the IronJacamar project. For a detailed description of the available configuration properties, please consult the project documentation.

Connection Factories

There are two kinds of basic JMS connection-factory:

• In-VM connection factories can be used by a local client (i.e. one running in the same JVM as the server)

• Netty connections factories can be used by a remote client. 

There is also a pooled-connection-factory which is special in that it leverages the outbound adapter of the HornetQ JCA Resource Adapter.  It is also special because:

• It is only available to local clients, although it can be configured to point to a remote server.

• As the name suggests, it is pooled and therefore provides superior performance to the clients which are able to use it.  The pool size can be configured via the max-pool-size and min-pool-size attributes.

• It should only be used to send (i.e. produce) messages.

• It can be configured to use specific security credentials via the user and password attributes.  This is useful if the remote server to which it is pointing is secured.

To be clear, the inbound adapter of the HornetQ JCA RA (which is for consuming messages) is only used by MDBs and is not available to other kinds of clients.

Both a connection-factory a pooled-connection-factory reference a connector declaration.  

A netty-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.

• A connection-factory referencing a netty-connector is suitable to be used by a remote client to send messages to or receive messages from the server (assuming the connection-factory has an appropriately exported entry).  

• A pooled-connection-factory referencing a netty-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.

An in-vm-connector is associated with a server-id which tells the client using the connection-factory where to connect (since multiple HornetQ servers can run in a single JVM).

• A connection-factory referencing an in-vm-connector is suitable to be used by a local client to either send messages to or receive messages from a local server.  

• A pooled-connection-factory referencing an in-vm-connector is suitable to be used by a local client only to send messages to a local server.

The entry declaration of a connection-factory or a pooled-connection-factory specifies the JNDI name under which the factory will be exposed.  Only JNDI names bound in the "java:jboss/exported" namespace are available to remote clients.  If a connection-factory has an entry bound in the "java:jboss/exported" namespace a remote client would look-up the connection-factory using the text after "java:jboss/exported".  For example, the "RemoteConnectionFactory" is bound by default to "java:jboss/exported/jms/RemoteConnectionFactory" which means a remote client would look-up this connection-factory using "jms/RemoteConnectionFactory".  A pooled-connection-factory should not have any entry bound in the "java:jboss/exported" namespace because a pooled-connection-factory is not suitable for remote clients.

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <connectors>
      <netty-connector name="netty" socket-binding="messaging"/>
      <netty-connector name="netty-throughput" socket-binding="messaging-throughput">
          <param key="batch-delay" value="50"/>
      </netty-connector>
      <in-vm-connector name="in-vm" server-id="0"/>
   </connectors>
   [...]
   <jms-connection-factories>
      <connection-factory name="InVmConnectionFactory">
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/ConnectionFactory"/>
          </entries>
      </connection-factory>
      <connection-factory name="RemoteConnectionFactory">
          <connectors>
              <connector-ref connector-name="netty"/>
          </connectors>
          <entries>
              <entry name="RemoteConnectionFactory"/>
              <entry name="java:jboss/exported/jms/RemoteConnectionFactory"/>
          </entries>
      </connection-factory>
      <pooled-connection-factory name="hornetq-ra">
          <transaction mode="xa"/>
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/JmsXA"/>
          </entries>
      </pooled-connection-factory>
   </jms-connection-factories>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

JMS Queues and Topics

JMS queues and topics are sub resources of the messaging subsystem.  They are defined in the jms-destinations section.  One can define either a jms-queue or jms-topic.  Each destination must be given a name and contain at least one entry element.

Each entry refers to a JNDI name of the queue or topic.  Keep in mind that any jms-queue or jms-topic which needs to be accessed by a remote client needs to have an entry in the "java:jboss/exported" namespace.  As with connection factories, if a jms-queue or jms-topic has an entry bound in the "java:jboss/exported" namespace a remote client would look it up using the text after "java:jboss/exported".  For example, the following jms-queue "testQueue" is bound to "java:jboss/exported/jms/queue/test" which means a remote client would look-up this jms-queue using "jms/queue/test".  A local client could look it up using "java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more simply "jms/queue/test":

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <jms-destinations>
       <jms-queue name="testQueue">
           <entry name="jms/queue/test"/>
           <entry name="java:jboss/exported/jms/queue/test"/>
       </jms-queue>
       <jms-topic name="testTopic">
           <entry name="jms/topic/test"/>
           <entry name="java:jboss/exported/jms/topic/test"/>
       </jms-topic>
   </jms-destinations>
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

JMS endpoints can easily be created through the CLI:

[standalone@localhost:9999 /] jms-queue add --name=myQueue --entries=queues/myQueue

[standalone@localhost:9999 /] /subsystem=messaging/jms-queue=myQueue:read-resource
{
   "outcome" => "success",
   "result" => {"entries" => ["queues/myQueue"]},
   "compensating-operation" => undefined
}

A number of additional commands to maintain the JMS subsystem are available as well:

[standalone@localhost:9999 /] jms-queue --help --commands
add...removeTo read the description of a specific command execute'jms-queue command_name --help'.

Dead Letter & Redelivery

Some of the settings are applied against an address wild card instead of a specific messaging destination. The dead letter queue and redelivery settings belong into this group:

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <address-settings>
      <address-setting match="#">
         <dead-letter-address>jms.queue.DLQ</dead-letter-address>
         <expiry-address>jms.queue.ExpiryQueue</expiry-address>
         <redelivery-delay>0</redelivery-delay>
         [...]
      </address-setting>
   </address-settings>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

Security Settings for HornetQ addresses and JMS destinations

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.  Note: Multiple roles are separated by spaces.

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-settings>
      <security-setting match="#">
         <permission type="send" roles="guest"/>
         <permission type="consume" roles="guest"/>
         <permission type="createNonDurableQueue" roles="role1"/>
         <permission type="deleteNonDurableQueue" roles="role1 role2"/>
      </security-setting>
   </security-settings>
   [...]
</subsystem>

_{(See standalone/configuration/standalone-full.xml)}

Security Domain for Users

By default, HornetQ will use the "other" JAAS security domain.  This domain is used to authenticate users making connections to HornetQ and then they are authorized to perform specific functions based on their role(s) and the security-settings described above.  This domain can be changed by using security-domain, e.g.:

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-domain>mySecurityDomain</security-domain>
   [...]
</subsystem>

Deployment of -jms.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -jms.xml file defining JMS destinations, e.g.:

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
   <hornetq-server>
      <jms-destinations>
         <jms-queue name="sample">
            <entry name="jms/queue/sample"/>
            <entry name="java:jboss/exported/jms/queue/sample"/>
         </jms-queue>
      </jms-destinations>
   </hornetq-server>
</messaging-deployment>

Component Reference

The messaging subsystem is provided by the HornetQ project. Fo a detailed description of the available configuration properties, please consult the project documentation.

Container configuration

[standalone@localhost:9999 /] /subsystem=web:read-resource               
{
    "outcome" => "success",
    "result" => {
        "configuration" => {
            "static-resources" => {
                "sendfile" => 49152,
                "max-depth" => 3,
                "read-only" => true,
                "webdav" => false,
                "listings" => false,
                "disabled" => false
            },
            "jsp-configuration" => {
                "development" => false,
                "keep-generated" => true,
                "recompile-on-fail" => false,
                "check-interval" => 0,
                "modification-test-interval" => 4,
                "display-source-fragment" => true,
                "error-on-use-bean-invalid-class-attribute" => false,
                "java-encoding" => "UTF8",
                "tag-pooling" => true,
                "generate-strings-as-char-arrays" => false,
                "target-vm" => "1.5",
                "dump-smap" => false,
                "mapped-file" => true,
                "disabled" => false,
                "source-vm" => "1.5",
                "trim-spaces" => false,
                "smap" => true
            }
        },
        "connector" => {"http" => undefined},
        "virtual-server" => {"localhost" => undefined}
    }
}

Connector configuration

The connectors are child resources of the subsystem web. Each connector does reference a particular socket binding:

[standalone@localhost:9999 /] /subsystem=web:read-children-names(child-type=connector)
{
    "outcome" => "success",
    "result" => ["http"]
}

[standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "protocol" => "HTTP/1.1",
        "scheme" => "http",
        "socket-binding" => "http",
        "ssl" => undefined,
        "virtual-server" => undefined
    }
}

Creating a new connector requires you to declare a new socket binding first:

[standalone@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=custom:add(port=8181)

The newly created, unused socket binding can then be used to create a new connector configuration:

[standalone@localhost:9999 /] /subsystem=web/connector=test-connector:add(
               socket-binding=custom, scheme=http, protocol="HTTP/1.1", enabled=true
               )

Statistic information can be displayed from the connectors:

The following attributes can be queried:

For example:

[standalone@localhost:9999 /] /subsystem=web/connector=http:read-attribute(name=bytesSent, name=requestCount)
{
    "outcome" => "success",
    "result" => "3"
}

There are 3 different connectors available:

HTTP Connectors

This one is the default connector, it runs usually on port 8080. See above how to configure it.

HTTPS Connectors

The HTTPS connectors are child resources of the subsystem web. By default they use JSSE. Each connector does reference a particular socket binding:

[standalone@localhost:9999 /] /subsystem=web:read-children-names(child-type=connector)
{
    "outcome" => "success",
    "result" => [
        "ajp",
        "http",
        "https"
    ]
}
[standalone@localhost:9999 /] /subsystem=web/connector=https:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "protocol" => "HTTP/1.1",
        "scheme" => "https",
        "secure" => true,
        "socket-binding" => "https",
        "ssl" => {},
        "virtual-server" => undefined
    }
}

Creating a new connector may require you to declare a new socket binding first:

[standalone@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=https:add(port=8443)

The newly created, unused socket binding can then be used to create a new connector configuration:

[standalone@localhost:9999 /] /subsystem=web/connector=test-connector:add(socket-binding=https, scheme=https, protocol="HTTP/1.1", enabled=true, ssl = {})

The default for SSL is to use Alias "tomcat" and password "changeit". It is possible to create the corresponding keystore using keytool:

keytool -genkey -alias tomcat -keyalg RSA

Of course specify a password value of "changeit".

AJP Connectors

The AJP connectors are child resources of the subsystem web. They are used with mod_jk, mod_proxy and mod_cluster of the Apache httpd front-end. Each connector does reference a particular socket binding:

[standalone@localhost:9999 /] /subsystem=web:read-children-names(child-type=connector)
{
    "outcome" => "success",
    "result" => [
        "ajp",
        "http"
    ]
}

[standalone@localhost:9999 /] /subsystem=web/connector=ajp:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "protocol" => "AJP/1.3",
        "scheme" => "http",
        "socket-binding" => "ajp",
        "ssl" => undefined,
        "virtual-server" => undefined
    }
}

Creating a new connector requires you to declare a new socket binding first:

[standalone@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)

The newly created, unused socket binding can then be used to create a new connector configuration:

[standalone@localhost:9999 /] /subsystem=web/connector=ajp:add(
               socket-binding=ajp, protocol="AJP/1.3", enabled=true, scheme="http"
               )

Native Connectors

Native connectors are high performance connectors based on Tomcat native. They are used if the native modules are installed, a lot of distributions have it included, in case you don't have it try JBoss Web Native.

At a configuration level only the SSL part needs to be configured differently because it use OpenSSL.

[standalone@localhost:9999 /] /subsystem=web/connector=https:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "protocol" => "HTTP/1.1",
        "scheme" => "https",
        "secure" => true,
        "socket-binding" => "https",
        "ssl" => {
            "certificate-file" => "/home/jfclere/CERTS/SERVER/newcert.pem",
            "certificate-key-file" => "/home/jfclere/CERTS/SERVER/newkey.pem",
            "password" => "xxxxxxx"
        },
        "virtual-server" => undefined
    }
}

Virtual-Server configuration

Similar to the connectors, the virtual server declarations are child resources of the web subsystem. They will be referenced by alias names and can optionally refer to a default web application that acts serves the root web context.

[standalone@localhost:9999 /] /subsystem=web:read-children-names(child-type=virtual-server)
{
    "outcome" => "success",
    "result" => ["localhost"]
}

[standalone@localhost:9999 /] /subsystem=web/virtual-server=default-host:read-resource
{
    "outcome" => "success",
    "result" => {
        "access-log" => undefined,
        "alias" => ["example.com"],
        "default-web-module" => undefined,
        "enable-welcome-root" => true,
        "rewrite" => undefined
    }
}

Adding a virtual server declaration is can be done through the default :add() operation

[standalone@localhost:9999 /] /subsystem=web/virtual-server=example.com:add

[standalone@localhost:9999 /] /subsystem=web/virtual-server=example.com:remove

Component Reference

The web subsystem is provided by the JBossWeb project. Fo a detailed description of the available configuration properties, please consult the JBossWeb documentation.

Published endpoint address

JBossWS supports rewriting the of the <soap:address> element in endpoint published WSDL contracts. That's useful for controlling the server address that is advertised to clients for each endpoint.

The following elements are available and can be modified (all are optional and require server restart upon modification):

Predefined endpoint configurations

JBossWS allows for defining endpoint configurations to be referenced by endpoint implementations. This allows for instance for adding a given handler to any WS endpoint that is marked with a given endpoint configuration (through @org.jboss.ws.api.annotation.EndpointConfig).

JBoss Application Server comes with a default Standard-Endpoint-Config as well as with an example of custom endpoint configuration (Recording-Endpoint-Config) including a recording handler (please reference the JBossWS documentation for details on that).

[standalone@localhost:9999 /] /subsystem=webservices:read-resource
{
    "outcome" => "success",
    "result" => {
        "endpoint" => {},
        "modify-wsdl-address" => true,
        "wsdl-host" => expression "${jboss.bind.address:127.0.0.1}",
        "endpoint-config" => {
            "Standard-Endpoint-Config" => undefined,
            "Recording-Endpoint-Config" => undefined
        }
    }
}

[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config:read-resource
{
    "outcome" => "success",
    "result" => {
        "post-handler-chain" => undefined,
        "property" => undefined,
        "pre-handler-chain" => {"recording-handlers" => undefined}
    }
}

[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config:add
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-restart" => true,
        "process-state" => "restart-required"
    }
}

* Server inbound messages
Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint

* Server outbound messages
Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> ... --> Client

[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config/pre-handler-chain=recording-handlers:read-resource
{
    "outcome" => "success",
    "result" => {
        "protocol-bindings" => "##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM",
        "handler" => {"RecordingHandler" => undefined}
    },
    "response-headers" => {"process-state" => "restart-required"}
}

[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers:add(protocol-bindings="##SOAP11_HTTP")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-restart" => true,
        "process-state" => "restart-required"
    }
}
[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers:read-resource
{
    "outcome" => "success",
    "result" => {
        "handler" => undefined,
        "protocol-bindings" => "##SOAP11_HTTP"
    },
    "response-headers" => {"process-state" => "restart-required"}
}

[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config/pre-handler-chain=recording-handlers/handler=RecordingHandler:read-resource
{
    "outcome" => "success",
    "result" => {"class" => "org.jboss.ws.common.invocation.RecordingServerHandler"},
    "response-headers" => {"process-state" => "restart-required"}
}
[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers/handler=foo-handler:add(class="org.jboss.ws.common.invocation.RecordingServerHandler")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-restart" => true,
        "process-state" => "restart-required"
    }
}

Why is there a logging.properties file?

You may have noticed that there is a logging.properties file in the configuration directory. This logging configuration is used when the server boots up until the logging subsystem kicks in. If the logging subsystem is not included in your configuration, then this would act as the logging configuration for the entire server.

In the future this file may go away or be automatically generated from the logging subsystem. For most users this file should not be modified.

Note: If the logging.properties is not available during start there will be no logging until the logging subsystems kicks in, this is also the case if the configuration is damaged, the server might exit without any further message.

Managed Domain

In a managed domain two types of log files do exist: Controller and server logs. The controller components govern the domain as whole. It's their responsibility to start/stop server instances and execute managed operations throughout the domain. Server logs contain the logging information for a particular server instance. They are co-located with the host the server is running on.

For the sake of simplicity we look at the default setup for managed domain. In this case, both the domain controller components and the servers are located on the same host:

Standalone Server 

The default log files for a standalone server can be found in the log subdirectory of the distribution:

root-logger

Defines the root logger for this log context.

logger

Defines a logger category.

async-handler

Defines a handler which writes to the sub-handlers in an asynchronous thread. Used for handlers which introduce a substantial amount of lag.

console-handler

Defines a handler which writes to the console.

file-handler

Defines a handler which writes to a file.

periodic-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a time period derived from the given suffix string, which should be in a format understood by java.text.SimpleDateFormat.

size-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a the size of the file grows beyond a certain point and keeping a fixed number of backups.

custom-handler

Defines a custom logging handler. The custom handler must extend java.util.logging.Handler.

What is the %s and %E in the pattern-formatter's pattern?

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

%s is the message

%E is the exception if one exists

Deployment Commands

The process of distributing deployment binaries involves two steps: You need to upload the deployment to the repository from which the domain controller can distribute it's contents. In a second step you need to assign the deployment to one or more server groups:

Using the CLI you can do it one sweep:

[domain@localhost:9999 /] deploy ~/Desktop/test-application.war
Either --all-server-groups or --server-groups must be specified.

[domain@localhost:9999 /] deploy ~/Desktop/test-application.war --all-server-groups
'test-application.war' deployed successfully.

[domain@localhost:9999 /] deploy --help
[...]

After you've uploaded the binary using the "deploy" command, it will be available to the domain controller
and assigned to a server group:

[domain@localhost:9999 /] :read-children-names(child-type=deployment)
{
   "outcome" => "success",
   "result" => [
       "mysql-connector-java-5.1.15.jar",
       "test-application.war"
   ]
}

[domain@localhost:9999 /] /server-group=main-server-group/deployment=test-application.war:read-resource
{
   "outcome" => "success",
   "result" => {
       "enabled" => true,
       "name" => "test-application.war",
       "runtime-name" => "test-application.war"
   }
}

In a similar way it can be removed from the server group:

[domain@localhost:9999 /] undeploy test-application.war --all-relevant-server-groups
Successfully undeployed test-application.war.

[domain@localhost:9999 /] /server-group=main-server-group:read-children-names(child-type=deployment)
{
   "outcome" => "success",
   "result" => []
}

Content Repository

Any deployment is referenced from the domain configuration file and stored co-located with the domain controller:

[...]
<deployments>
   <deployment name="test-application.war"
               runtime-name="test-application.war">
       <content sha1="dda9881fa7811b22f1424b4c5acccb13c71202bd"/>
   </deployment>
</deployments>
[...]
<server-groups>
   <server-group name="main-server-group" profile="default">
       [...]
       <deployments>
           <deployment name="test-application.war" runtime-name="test-application.war"/>
       </deployments>
   </server-group>
</server-groups>
[...]

_{(See domain/configuration/domain.xml)}

The actual binaries are stored in the content subdirectory:

ls domain/content/
  |---/47
  |-----95cc29338b5049e238941231b36b3946952991
  |---/dd
  |-----a9881fa7811b22f1424b4c5acccb13c71202bd

Deployment Commands

You can rely on the same CLI command as for a managed domain to deploy an application:

[standalone@localhost:9999 /] deploy ~/Desktop/test-application.war
'test-application.war' deployed successfully.

[standalone@localhost:9999 /] undeploy test-application.war
Successfully undeployed test-application.war.

File System Deployments

The standalone/deployments directory in the JBoss Application Server 7 distribution is the location end users can place their deployment content (e.g. war, ear, jar, sar files) to have it automically deployed into the server runtime.

<deployment-scanner scan-interval="5000" relative-to="jboss.server.base.dir"
   path="deployments" auto-deploy-zipped="true" auto-deploy-exploded="false"/>

The add operation

The operation that creates a new resource must be named add. The operation may take zero or more parameters; what those parameters are depends on the resource being created.

The remove operation

The operation that removes an existing resource must be named remove. The operation should take no parameters.

Basic ModelNode manipulation

To illustrate how to work with ModelNode s, we'll use the Beanshell scripting library. We won't get into many details of beanshell here; it's a simple and intuitive tool and hopefully the following examples are as well.

We'll start by launching a beanshell interpreter, with the jboss-dmr library available on the classpath. Then we'll tell beanshell to import all the jboss-dmr classes so they are available for use:

$ java -cp bsh-2.0b4.jar:jboss-dmr-1.0.0.Final.jar bsh.Interpreter
BeanShell 2.0b4 - by Pat Niemeyer (pat@pat.net)
bsh % import org.jboss.dmr.*;
bsh % 

Next, create a ModelNode and use the beanshell print function to output what type it is:

bsh % ModelNode node = new ModelNode();
bsh % print(node.getType());
UNDEFINED

A new ModelNode has no value stored, so its type is ModelType.UNDEFINED.

Use one of the overloaded set method variants to assign a node's value:

bsh % node.set(1);
bsh % print(node.getType());
INT
bsh % node.set(true);
bsh % print(node.getType());
BOOLEAN
bsh % node.set("Hello, world");
bsh % print(node.getType());
STRING

Use one of the asXXX() methods to retrieve the value:

bsh % node.set(2);
bsh % print(node.asInt());
2
bsh % node.set("A string");
bsh % print(node.asString());
A string

ModelNode will attempt to perform type conversions when you invoke the asXXX methods:

bsh % node.set(1);
bsh % print(node.asString());
1
bsh % print(node.asBoolean());
true
bsh % node.set(0);
bsh % print(node.asBoolean());
false
bsh % node.set("true");
bsh % print(node.asBoolean());
true

Not all type conversions are possible:

bsh % node.set("A string");
bsh % print(node.asInt());
// Error: // Uncaught Exception: Method Invocation node.asInt : at Line: 20 : in file: <unknown file> : node .asInt ( ) 

Target exception: java.lang.NumberFormatException: For input string: "A string"

java.lang.NumberFormatException: For input string: "A string"
	at java.lang.NumberFormatException.forInputString(NumberFormatException.java:48)
	at java.lang.Integer.parseInt(Integer.java:449)
	at java.lang.Integer.parseInt(Integer.java:499)
	at org.jboss.dmr.StringModelValue.asInt(StringModelValue.java:61)
	at org.jboss.dmr.ModelNode.asInt(ModelNode.java:117)
        ....

The ModelNode.getType() method can be used to ensure a node has an expected value type before attempting a type conversion.

One set variant takes another ModelNode as its argument. The value of the passed in node is copied, so there is no shared state between the two model nodes:

bsh % node.set("A string");
bsh % ModelNode another = new ModelNode();
bsh % another.set(node);
bsh % print(another.asString());
A string
bsh % node.set("changed");
bsh % print(node.asString());
changed
bsh % print(another.asString());
A string

A ModelNode can be cloned. Again, there is no shared state between the original node and its clone:

bsh % ModelNode clone = another.clone();
bsh % print(clone.asString());
A string
bsh % another.set(42);
bsh % print(another.asString());
42
bsh % print(clone.asString());
A string

Use the protect() method to make a ModelNode immutable:

bsh % clone.protect();
bsh % clone.set("A different string");
// Error: // Uncaught Exception: Method Invocation clone.set : at Line: 15 : in file: <unknown file> : clone .set ( "A different string" ) 

Target exception: java.lang.UnsupportedOperationException

java.lang.UnsupportedOperationException
	at org.jboss.dmr.ModelNode.checkProtect(ModelNode.java:1441)
	at org.jboss.dmr.ModelNode.set(ModelNode.java:351)
        ....

Lists

The above examples aren't particularly interesting; if all we can do with a ModelNode is wrap a simple Java primitive, what use is that? However, a ModelNode's value can be more complex than a simple primitive, and using these more complex types we can build complex data structures. The first more complex type is ModelType.LIST.

Use the add methods to initialize a node's value as a list and add to the list:

bsh % ModelNode list = new ModelNode();
bsh % list.add(5);
bsh % list.add(10);
bsh % print(list.getType());
LIST

Use asInt() to find the size of the list:

bsh % print(list.asInt());
2

Use the overloaded get method variant that takes an int param to retrieve an item. The item is returned as a ModelNode:

bsh % ModelNode child = list.get(1);
bsh % print(child.asInt());
10

Elements in a list need not all be of the same type:

bsh % list.add("A string");
bsh % print(list.get(1).getType());
INT
bsh % print(list.get(2).getType());
STRING

Here's one of the trickiest things about jboss-dmr: The get methods actually mutate state; they are not "read-only". For example, calling get with an index that does not exist yet in the list will actually create a child of type ModelType.UNDEFINED at that index (and will create UNDEFINED children for any intervening indices.)

bsh % ModelNode four = list.get(4);
bsh % print(four.getType());
UNDEFINED
bsh % print(list.asInt());
6

Since the get call always returns a ModelNode and never null it is safe to manipulate the return value:

bsh % list.get(5).set(30);
bsh % print(list.get(5).asInt());
30

That's not so interesting in the above example, but later on with node of type ModelType.OBJECT we'll see how that kind of method chaining can let you build up fairly complex data structures with a minimum of code.

Use the asList() method to get a List<ModelNode> of the children:

bsh % bsh % for (ModelNode element : list.asList()) {
print(element.getType());
}
INT
INT
STRING
UNDEFINED
UNDEFINED
INT

The asString() and toString() methods provide slightly differently formatted text representations of a ModelType.LIST node:

bsh % print(list.asString());
[5,10,"A string",undefined,undefined,30]
bsh % print(list.toString());
[
    5,
    10,
    "A string",
    undefined,
    undefined,
    30
]

Finally, if you've previously used set to assign a node's value to some non-list type, you cannot use the add method:

bsh % node.add(5);
// Error: // Uncaught Exception: Method Invocation node.add : at Line: 18 : in file: <unknown file> : node .add ( 5 ) 

Target exception: java.lang.IllegalArgumentException

java.lang.IllegalArgumentException
	at org.jboss.dmr.ModelValue.addChild(ModelValue.java:120)
	at org.jboss.dmr.ModelNode.add(ModelNode.java:1007)
	at org.jboss.dmr.ModelNode.add(ModelNode.java:761)
        ...

You can, however, use the setEmptyList() method to change the node's type, and then use add:

bsh % node.setEmptyList();
bsh % node.add(5);
bsh % print(node.toString());
[5]

Properties

The third public class in the jboss-dmr library is org.jboss.dmr.Property. A Property is a String => ModelNode tuple.

bsh % Property prop = new Property("stuff", list);
bsh % print(prop.toString());
org.jboss.dmr.Property@79a5f739
bsh % print(prop.getName());
stuff
bsh % print(prop.getValue());
[
    5,
    10,
    "A string",
    undefined,
    undefined,
    30
]

The property can be passed to ModelNode.set:

bsh % node.set(prop);
bsh % print(node.getType());
PROPERTY

The text format for a node of ModelType.PROPERTY is:

bsh % print(node.toString());
("stuff" => [
    5,
    10,
    "A string",
    undefined,
    undefined,
    30
])

Directly instantiating a Property via its constructor is not common. More typically one of the two argument ModelNode.add or ModelNode.set variants is used. The first argument is the property name:

bsh % ModelNode simpleProp = new ModelNode();
bsh % simpleProp.set("enabled", true);
bsh % print(simpleProp.toString());
("enabled" => true)
bsh % print(simpleProp.getType());
PROPERTY
bsh % ModelNode propList = new ModelNode();
bsh % propList.add("min", 1);
bsh % propList.add("max", 10);
bsh % print(propList.toString());
[
    ("min" => 1),
    ("max" => 10)
]
bsh % print(propList.getType());
LIST
bsh % print(propList.get(0).getType());
PROPERTY

The asPropertyList() method provides easy access to a List<Property>:

bsh % for (Property prop : propList.asPropertyList()) {
print(prop.getName() + " = " + prop.getValue());
}
min = 1
max = 10

ModelType.OBJECT

The most powerful and most commonly used complex value type in jboss-dmr is ModelType.OBJECT. A ModelNode whose value is ModelType.OBJECT internally maintains a Map<String, ModelNode.

Use the get method variant that takes a string argument to add an entry to the map. If no entry exists under the given name, a new entry is added with a the value being a ModelType.UNDEFINED node. The node is returned:

bsh % ModelNode range = new ModelNode();
bsh % ModelNode min = range.get("min");
bsh % print(range.toString());
{"min" => undefined}
bsh % min.set(2);
bsh % print(range.toString());
{"min" => 2}

Again it is important to remember that the get operation may mutate the state of a model node by adding a new entry. It is not a read-only operation.

Since get will never return null, a common pattern is to use method chaining to create the key/value pair:

bsh % range.get("max").set(10);
bsh % print(range.toString());
{
    "min" => 2,
    "max" => 10
}

A call to get passing an already existing key will of course return the same model node as was returned the first time get was called with that key:

bsh % print(min == range.get("min"));
true

Multiple parameters can be passed to get. This is a simple way to traverse a tree made up of ModelType.OBJECT nodes. Again, get may mutate the node on which it is invoked; e.g. it will actually create the tree if nodes do not exist. This next example uses a workaround to get beanshell to handle the overloaded get method that takes a variable number of arguments:

bsh % String[] varargs = { "US", "Missouri", "St. Louis" };
bsh % salesTerritories.get(varargs).set("Brian");
bsh % print(salesTerritories.toString());
{"US" => {"Missouri" => {"St. Louis" => "Brian"}}}

The normal syntax would be:

salesTerritories.get("US", "Missouri", "St. Louis").set("Brian");

The key/value pairs in the map can be accessed as a List<Property:

bsh % for (Property prop : range.asPropertyList()) {
print(prop.getName() + " = " + prop.getValue());
}
min = 2

The semantics of the backing map in a node of ModelType.OBJECT are those of a LinkedHashMap. The map remembers the order in which key/value pairs are added. This is relevant when iterating over the pairs after calling asPropertyList() and for controlling the order in which key/value pairs appear in the output from toString().

Since the get method will actually mutate the state of a node if the given key does not exist, ModelNode provides a couple methods to let you check whether the entry is there. The has method simply does that:

bsh % print(range.has("unit"));
false
bsh % print(range.has("min"));
true

Very often, the need is to not only know whether the key/value pair exists, but whether the value is defined (i.e. not ModelType.UNDEFINED. This kind of check is analogous to checking whether a field in a Java class has a null value. The hasDefined lets you do this:

bsh % print(range.hasDefined("unit"));
false
bsh % // Establish an undefined child 'unit';
bsh % range.get("unit");
bsh % print(range.toString());
{
    "min" => 2,
    "max" => 10,
    "unit" => undefined
}
bsh % print(range.hasDefined("unit"));
false
bsh % range.get("unit").set("meters");
bsh % print(range.hasDefined("unit"));
true

ModelType.EXPRESSION

A value of type ModelType.EXPRESSION is stored as a string, but can later be resolved to different value. The string has a special syntax that should be familiar to those who have used the system property substitution feature in previous JBoss AS releases.

[<prefix>][${<system-property-name>[:<default-value>]}][<suffix>]*

For example:

${queue.length}
http://${host}
http://${host:localhost}:${port:8080}/index.html

Use the setExpression method to set a node's value to type expression:

bsh % ModelNode expression = new ModelNode();
bsh % expression.setExpression("${queue.length}");
bsh % print(expression.getType());
EXPRESSION

Calling asString() returns the same string that was input:

bsh % print(expression.asString());
${queue.length}

However, calling toString() tells you that this node's value is not of ModelType.STRING:

bsh % print(expression.toString());
expression "${queue.length}"

When the resolve operation is called, the string is parsed and any embedded system properties are resolved against the JVM's current system property values. A new ModelNode is returned whose value is the resolved string:

bsh % System.setProperty("queue.length", "10");
bsh % ModelNode resolved = expression.resolve();
bsh % print(resolved.asInt());
10

Note that the type of the ModelNode returned by resolve() is ModelType.STRING:

bsh % print(resolved.getType());
STRING

The resolved.asInt() call in the previous example only worked because the string "10" happens to be convertible into the int 10.

Calling resolve() has no effect on the value of the node on which the method is invoked:

bsh % resolved = expression.resolve();
bsh % print(resolved.toString());
"10"
bsh % print(expression.toString());
expression "${queue.length}"

If an expression cannot be resolved, resolve just uses the original string. The string can include more than one system property substitution:

bsh % expression.setExpression("http://${host}:${port}/index.html");
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
http://${host}:${port}/index.html

The expression can optionally include a default value, separated from the name of the system property by a colon:

bsh % expression.setExpression("http://${host:localhost}:${port:8080}/index.html");
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
http://localhost:8080/index.html

Actually including a system property substitution in the expression is not required:

bsh % expression.setExpression("no system property");
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
no system property
bsh % print(expression.toString());
expression "no system property"

The resolve method works on nodes of other types as well; it returns a copy without attempting any real resolution:

bsh % ModelNode basic = new ModelNode();
bsh % basic.set(10);
bsh % resolved = basic.resolve();
bsh % print(resolved.getType());
INT
bsh % resolved.set(5);
bsh % print(resolved.asInt());
5
bsh % print(basic.asInt());
10

ModelType.TYPE

You can also pass one of the values of the ModelType enum to set:

bsh % ModelNode type = new ModelNode();
bsh % type.set(ModelType.LIST);
bsh % print(type.getType());
TYPE
bsh % print(type.toString());
LIST

This is useful when using a ModelNode data structure to describe another ModelNode data structure.

Full list of ModelNode types

BIG_DECIMAL
BIG_INTEGER
BOOLEAN
BYTES
DOUBLE
EXPRESSION
INT
LIST
LONG
OBJECT
PROPERTY
STRING
TYPE
UNDEFINED

Text representation of a ModelNode

JSON representation of a ModelNode

Description of an Attribute

An attribute is a portion of the management model that is not directly addressable. Instead, it is conceptually a property of an addressable management resource. For each attribute in the model, the following descriptive information will be available:

• description – String – text description of the attribute

• type – org.jboss.dmr.ModelType – the type of the attribute value. One of the enum values BIG_DECIMAL, BIG_INTEGER, BOOLEAN, BYTES, DOUBLE, INT, LIST, LONG, OBJECT, PROPERTY, STRING. Most of these are self-explanatory. An OBJECT will be represented in the detyped model as a map of string keys to values of some other legal type, conceptually similar to a javax.management.openmbean.CompositeData. A PROPERTY is a single key/value pair, where the key is a string, and the value is of some other legal type.

• value-type – ModelType or complex structure – Only present if type is LIST or OBJECT. If all elements in the LIST or all the values of the OBJECT type are of the same type, this will be one of the ModelType enums BIG_DECIMAL, BIG_INTEGER, BOOLEAN, BYTES, DOUBLE, INT, LONG, STRING. Otherwise, value-type will detail the structure of the attribute value, enumerating the value's fields and the type of their value.

• expressions-allowed – boolean – indicates whether the value of the attribute may be of type ModelType.EXPRESSION, instead of its standard type (see type and value-type above for discussion of an attribute's standard type.) A value of ModelType.EXPRESSION contains a system-property substitution expression that the server will resolve against the server-side system property map before using the value. For example, an attribute named max-threads may have an expression value of ${example.pool.max-threads:10} instead of just 10. Default value if not present is false.

• required – boolean – true if the attribute will always exist in a representation of its portion of the model; false if it may not (implying a null value.) If not present, true is the default.

• storage – String – Either "configuration" or "runtime". If "configuration", the attribute's value is stored as part of the persistent configuration (e.g. in domain.xml, host.xml or standalone.xml.) If "runtime" the attribute's value is not stored in the persistent configuration; the value only exists as long as the resource is running.

• access-type – String – One of "read-only", "read-write" or "metric". Whether an attribute value can be written, or can only read. A "metric" is a read-only attribute whose value is not stored in the persistent configuration, and whose value may change due to activity on the server. If an attribute is "read-write", the resource will expose an operation named "write-attribute" whose "name" parameter will accept this attribute's name and whose "value" parameter will accept a valid value for this attribute. That operation will be the standard means of updating this attribute's value.

• restart-required – String – One of "no-services", "all-services", "resource-services" or "jvm". Only relevant to attributes whose access-type is read-write. Indicates whether execution of a write-attribute operation whose name parameter specifies this attribute requires a restart of services (or an entire JVM) in order for the change to take effect in the runtime . See discussion of "Applying Updates to Runtime Services" below. Default value is "no-services".

• alternatives – List of string – Indicates an exclusive relationship between attributes. If this attribute is defined, the other attributes listed in this descriptor's value should be undefined (even if their required descriptor says true; i.e. the presence of this attribute satisfies the requirement.) Default is undefined; i.e. this does not apply to most attributes.

• requires – List of string – Indicates that if this attribute has a value (other than undefined), the other attributes listed in this descriptor's value must also have a value, even if their required descriptor says false. This would typically be used in conjunction with alternatives. For example, attributes "a" and "b" are required, but are alternatives to each other; "c" and "d" are optional. But "b" requires "c" and "d", so if "b" is used, "c" and "d" must also be defined. Default is undefined; i.e. this does not apply to most attributes.

• head-comment-allowed – boolean – indicates whether the model can store an XML comment that would be written in the persistent form of the model (e.g. domain.xml) before the start of the XML element that represents this attribute. This item is optional, and if not present defaults to false. (This is a different default from what is used for an entire management resource, since model attributes often map to XML attributes, which don't allow comments.) (Note: storing XML comments in the in-memory model is not currently supported. This description key is for future use.)

• tail-comment-allowed – boolean – similar to head-comment-allowed, but indicates whether a comment just before the close of the XML element is supported. A tail comment can only be supported if the element has child elements, in which case a comment can be inserted between the final child element and the element's closing tag. This item is optional, and if not present defaults to false. (This is a different default from what is used for an entire management resource, since model attributes often map to XML attributes, which don't allow comments.) (Note: storing XML comments in the in-memory model is not currently supported. This description key is for future use.)

• arbitrary key/value pairs that further describe the attribute value, e.g. "max" => 2. See "Arbitrary Descriptors" below.

Some examples:

"foo" => {
     "description" => "The foo",
     "type" => INT,
     "max" => 2
}

"bar" => {
     "description" => "The bar",
     "type" => OBJECT,
     "value-type" => {
          "size" => INT,
          "color" => STRING
     }
}

Description of an Operation

A management resource may have operations associated with it. The description of an operation will include the following information:

• operation-name – String – the name of the operation

• description – String – text description of the operation

• request-properties – Map of String to complex structure – description of the parameters of the operation. Keys are the names of the parameters, values are descriptions of the parameter value types. See below for details on the description of parameter value types.

• reply-properties – complex structure, or empty – description of the return value of the operation, with an empty node meaning void. See below for details on the description of operation return value types.

• restart-required – String – One of "no-services", "all-services", "resource-services" or "jvm". Indicates whether the operation makes a configuration change that requires a restart of services (or an entire JVM) in order for the change to take effect in the runtime. See discussion of "Applying Updates to Runtime Services" below. Default value is "no-services".

Arbitrary Descriptors

The description of an attribute, operation parameter or operation return value type can include arbitrary key/value pairs that provide extra information. Whether a particular key/value pair is present depends on the context, e.g. a pair with key "max" would probably only occur as part of the description of some numeric type.

Following are standard keys and their expected value type. If descriptor authors want to add an arbitrary key/value pair to some descriptor and the semantic matches the meaning of one of the following items, the standard key/value type must be used.

• min – int – the minimum value of some numeric type. The absence of this item implies there is no minimum value.

• max – int – the maximum value of some numeric type. The absence of this item implies there is no maximum value.

• min-length – int – the minimum length of some string, list or byte[] type. The absence of this item implies a minimum length of zero.

• max-length – int – the maximum length of some string, list or byte[]. The absence of this item implies there is no maximum value.

• nillable – boolean – whether null or a ModelNode of type ModelType.UNDEFINED is a legal value. The absence of this item implies false; i.e. null/undefined is not a legal value.

• allowed – List – a list of legal values. The type of the elements in the list should match the type of the attribute.

• default – the default value for the attribute if not present in the model

• unit - The unit of the value, if one is applicable - e.g. ns, ms, s, m, h, KB, MB, TB. See the org.jboss.as.controller.client.helpers.MeasurementUnit in the org.jboss.as:jboss-as-controller-client artifact for a listing of legal measurement units..

Some examples:

{
     "operation-name" => "incrementFoo",
     "description" => "Increase the value of the 'foo' attribute by the given amount",
     "request-properties" => {
          "increment" => {
               "type" => INT,
               "description" => "The amount to increment",
               "required" => true
     }},
     "reply-properties" => { 
               "type" => INT,
               "description" => "The new value",
     }
}

{
     "operation-name" => "start",
     "description" => "Starts the thing",
     "request-properties" => {},
     "reply-properties" => {}
}

Description of Parent/Child Relationships

The address used to target an addressable portion of the model must be an ordered list of key value pairs. The effect of this requirement is the addressable portions of the model naturally form a tree structure, with parent nodes in the tree defining what the valid keys are and the children defining what the valid values are. The parent node also defines the cardinality of the relationship. The description of the parent node includes a children element that describes these relationships:

{
     .... 
     "children" => {
          "connector" => {
               .... description of the relationship with children of type "connector"
          },
          "virtual-host" => {
               .... description of the relationship with children of type "virtual-host"
          }
}

The description of each relationship will include the following elements:

• description – String – text description of the relationship

• min-occurs – int, either 0 or 1 – Minimum number of children of this type that must exist in a valid model. If not present, the default value is 0.

• max-occurs – int – Maximum number of children of this type that may exist in a valid model. If not present, the default value is Integer.MAX_VALUE, i.e. there is no limit.

• allowed – List of strings – legal values for children names. If not present, there is no restriction on children names.

• model-description – either "undefined" or a complex structure – This is the full description of the child resource (its text description, attributes, operations, children) as detailed above. This may also be "undefined", i.e. a null value, if the query that asked for the parent node's description did not include the "recursive" param set to true.

Example with if the recursive flag was set to true:

{
     "description" => "The connectors used to handle client connections",
     "min-occurs" > 1,
     "model-description" => {
          "description" => "Handles client connections",
          "attributes => {
               ... details of children as documented above
          },
          "operations" => {
               .... details of operations as documented above
          },
          "children" => {
               .... details of the children's children
          }
     }
}

If the recursive flag was false:

 
{
     "description" => "The connectors used to handle client connections",
     "min-occurs" > 1,
     "model-description" => undefined
}

Applying Updates to Runtime Services

An attribute or operation description may include a "restart-required" descriptor; this section is an explanation of the meaning of that descriptor.

An operation that changes a management resource's persistent configuration usually can also also affect a runtime service associated with the resource. For example, there is a runtime service associated with any host.xml or standalone.xml <interface> element; other services in the runtime depend on that service to provide the InetAddress associated with the interface. In many cases, an update to a resource's persistent configuration can be immediately applied to the associated runtime service. The runtime service's state is updated to reflect the new value(s).

However, in many cases the runtime service's state cannot be updated without restarting the service. Restarting a service can have broad effects. A restart of a service A will trigger a restart of other services B, C and D that depend A, triggering a restart of services that depend on B, C and D, etc. Those service restarts may very well disrupt handling of end-user requests.

Because restarting a service can be disruptive to end-user request handling, the handlers for management operations will not restart any service without some form of explicit instruction from the end user indicating a service restart is desired. In a few cases, simply executing the operation is an indication the user wants services to restart (e.g. a /host=master/server-config=server-one:restart operation in a managed domain, or a /:reload operation on a standalone server.) For all other cases, if an operation (or attribute write) cannot be performed without restarting a service, the metadata describing the operation or attribute will include a "restart-required" descriptor whose value indicates what is necessary for the operation to affect the runtime:

• no-services – Applying the operation to the runtime does not require the restart of any services. This value is the default if the restart-required descriptor is not present.

• all-services – The operation can only immediately update the persistent configuration; applying the operation to the runtime will require a subsequent restart of all services in the affected VM. Executing the operation will put the server into a "reload-required" state. Until a restart of all services is performed the response to this operation and to any subsequent operation will include a response header "process-state" => "reload-required". For a standalone server, a restart of all services can be accomplished by executing the /:reload CLI command. For a server in a managed domain, restarting all services currently requires a full restart of the affected server VM (e.g. /host=master/server-config=server-one:restart).

• jvm --The operation can only immediately update the persistent configuration; applying the operation to the runtime will require a full process restart (i.e. stop the JVM and launch a new JVM). Executing the operation will put the server into a "restart-required" state. Until a restart is performed the response to this operation and to any subsequent operation will include a response header "process-state" => "restart-required". For a standalone server, a full process restart requires first stopping the server via OS-level operations (Ctrl-C, kill) or via the /:shutdown CLI command, and then starting the server again from the command line. For a server in a managed domain, restarting a server requires executing the /host=<host>/server-config=<server>:restart operation.

• resource-services – The operation can only immediately update the persistent configuration; applying the operation to the runtime will require a subsequent restart of some services associated with the resource. If the operation includes the request header "allow-resource-service-restart" => true, the handler for the operation will go ahead and restart the runtime service. Otherwise executing the operation will put the server into a "reload-required" state. (See the discussion of "all-services" above for more on the "reload-required" state.)

Creating the ModelControllerClient

To create a management client that can connect to your target process's native management socket, simply:

ModelControllerClient client = ModelControllerClient.Factory.create(InetAddress.getByName("localhost"), 9999);

The address and port are what is configured in the target process' <management><management-interfaces><native-interface.../> element.

Typically, however, the native management interface will be secured, requiring clients to authenticate. On the client side, the custom client will need to provide the user's authentication credentials, obtained in whatever manner is appropriate for the client (e.g. from a dialog box in a GUI-based client.) Access to these credentials is provided by passing in an implementation of the javax.security.auth.callback.CallbackHandler interface. For example:

static ModelControllerClient createClient(final InetAddress host, final int port,
                  final String username, final char[] password, final String securityRealmName) {

    final CallbackHandler callbackHandler = new CallbackHandler() {

        public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (Callback current : callbacks) {
                if (current instanceof NameCallback) {
                    NameCallback ncb = (NameCallback) current;
                    ncb.setName(username);
                } else if (current instanceof PasswordCallback) {
                    PasswordCallback pcb = (PasswordCallback) current;
                    pcb.setPassword(password.toCharArray());
                } else if (current instanceof RealmCallback) {
                    RealmCallback rcb = (RealmCallback) current;
                    rcb.setText(rcb.getDefaultText());
                } else {
                    throw new UnsupportedCallbackException(current);
                }
            }
        }
    };

    return ModelControllerClient.Factory.create(host, port, callbackHandler);
}

One thing to note on this, is that creating the ModelController client does not tell you whether you need to authenticate or not, only when you execute an operation, like what is described below, will tell you if you need to authenticate.  So, if you want your native client to be able to work in either an unauthenticated case and an authenticated case, then you need execute an operation, and catch an exception and then prompt for the credentials, and create a new ModelController client with the call back handler above.  For example:

 ModelControllerClient client = null;
        
 // Try connecting to the server without authentication first
        
 ModelControllerClient unauthenticatedClient = ModelControllerClient.Factory.create(serverHost, port);
        
 try {
     ModelNode testConnection = new ModelNode();
     testConnection.get("operation").set("read-resource");  // Execute an operation to see if we need to authenticate
     unauthenticatedClient.execute(testConnection);
     client = unauthenticatedClient;
 } catch(Exception e) {
     // Failed to connect, must authenticate and get the credentials in your application specific manner
            
     ...

     client = NativeClient.getInstance(serverHost, port, username, password);  // NativeClient.getInstance(...) is a class that contains the above CallBackHandler
 }

Creating an operation request object

Management requests are formulated using the org.jboss.dmr.ModelNode class from the jboss-dmr library. The jboss-dmr library allows the complete JBoss AS management model to be expressed using a very small number of Java types. See Detyped management and the jboss-dmr library for full details on using this library.

Let's show an example of creating an operation request object that can be used to read the resource description for the web subsystem's HTTP connector:

ModelNode op = new ModelNode();
op.get("operation").set("read-resource-description");

ModelNode address = op.get("address");
address.add("subsystem", "web");
address.add("connector", "http");

op.get("recursive").set(true);
op.get("operations").set(true);

What we've done here is created a ModelNode of type ModelType.OBJECT with the following fields:

• operation – the name of the operation to invoke. All operation requests must include this field and its value must be a String.

• address – the address of the resource to invoke the operation against. This field's must be of ModelType.LIST with each element in the list being a ModelType.PROPERTY. If this field is omitted the operation will target the root resource. The operation can be targeted at any address in the management model; here we are targeting it at the resource for the web subsystem's http connector.

In this case, the request includes two optional parameters:

• recursive – true means you want the description of child resources under this resource. Default is false

• operations – true means you want the description of operations exposed by the resource to be included. Default is false.

Different operations take different parameters, and some take no parameters at all.

See Format of a Detyped Operation Request for full details on the structure of a ModelNode that will represent an operation request.

The example above produces an operation request ModelNode equivalent to what the CLI produces internally when it parses and executes the following low-level CLI command:

[localhost:9999 /] /subsystem=web/connector=http:read-resource-description(recursive=true,operations=true)

Execute the operation and manipulate the result:

The execute method sends the operation request ModelNode to the process being managed and returns a ModelNode the contains the process' response:

ModelNode returnVal = client.execute(op);
System.out.println(returnVal.get("result").toString());

See Format of a Detyped Operation Response for general details on the structure of the "returnVal" ModelNode.

The execute operation shown above will block the calling thread until the response is received from the process being managed. ModelControllerClient also exposes and API allowing asynchronous invocation:

Future<ModelNode> future = client.executeAsync(op);
. . .  // do other stuff
ModelNode returnVal = future.get();
System.out.println(returnVal.get("result").toString());

Close the ModelControllerClient

A ModelControllerClient can be reused for multiple requests. Creating a new ModelControllerClient for each request is an anti-pattern. However, when the ModelControllerClient is no longer needed, it should always be explicitly closed, allowing it to close down any connections to the process it was managing and release other resources:

client.close();

Simple Operations

A text representation of simple operation would look like this:

{
    "operation" => "write-attribute",
    "address" => [
        ("profile" => "production"),
        ("subsystem" => "threads"),
        ("bounded-queue-thread-pool" => "pool1")
    ],
    "name" => "count",
    "value" => 20
}

Java code to produce that output would be:

ModelNode op = new ModelNode();
op.get("operation").set("write-attribute");
ModelNode addr = op.get("address");
addr.add("profile", "production");
addr.add("subsystem", "threads");
addr.add("bounded-queue-thread-pool", "pool1");
op.get("name").set("count");
op.get("value").set(20);
System.out.println(op);

The order in which the outermost elements appear in the request is not relevant. The required elements are:

• operation – String – The name of the operation being invoked.

• address – the address of the managed resource against which the request should be executed. If not set, the address is the root resource. The address is an ordered list of key-value pairs describing where the resource resides in the overall management resource tree. Management resources are organized in a tree, so the order in which elements in the address occur is important.

The other key/value pairs are parameter names and their values. The names and values should match what is specified in the operation's description.

Parameters may have any name, except for the reserved words operation, address and operation-headers.

Operation Headers

Besides the special operation and address values discussed above, operation requests can also include special "header" values that help control how the operation executes. These headers are created under the special reserved word operation-headers:

ModelNode op = new ModelNode();
op.get("operation").set("write-attribute");
ModelNode addr = op.get("address");
addr.add("base", "domain");
addr.add("profile", "production");
addr.add("subsystem", "threads");
addr.add("bounded-queue-thread-pool", "pool1");
op.get("name").set("count");
op.get("value").set(20);
op.get("operation-headers", "rollback-on-runtime-failure").set(false);
System.out.println(op);

This produces:

{
    "operation" => "write-attribute",
    "address" => [
        ("profile" => "production"),
        ("subsystem" => "threads"),
        ("bounded-queue-thread-pool" => "pool1")
    ],
    "name" => "count",
    "value" => 20,
    "operation-headers" => {
        "rollback-on-runtime-failure => false
    }
}

The following operation headers are supported:

• rollback-on-runtime-failure – boolean, optional, defaults to true. Whether an operation that successfully updates the persistent configuration model should be reverted if it fails to apply to the runtime. Operations that affect the persistent configuration are applied in two stages – first to the configuration model and then to the actual running services. If there is an error applying to the configuration model the operation will be aborted with no configuration change and no change to running services will be attempted. However, operations are allowed to change the configuration model even if there is a failure to apply the change to the running services – if and only if this rollback-on-runtime-failure header is set to false. So, this header only deals with what happens if there is a problem applying an operation to the running state of a server (e.g. actually increasing the size of a runtime thread pool.)

• rollout-plan – only relevant to requests made to a Domain Controller or Host Controller. See "Operations with a Rollout Plan" for details.

• allow-resource-service-restart – boolean, optional, defaults to false. Whether an operation that requires restarting some runtime services in order to take effect should do so. See discussion of resource-services in the "Applying Updates to Runtime Services" section of the Description of the Management Model section for further details.

Composite Operations

The root resource for a Domain or Host Controller or an individual server will expose an operation named "composite". This operation executes a list of other operations as an atomic unit (although the atomicity requirement can be relaxed. The structure of the request for the "composite" operation has the same fundamental structure as a simple operation (i.e. operation name, address, params as key value pairs).

{
    "operation" => "composite",
    "address" => [],
    "steps" => [
         {
              "operation" => "write-attribute",
              "address" => [
                   ("profile" => "production"),
                   ("subsystem" => "threads"),
                   ("bounded-queue-thread-pool" => "pool1")
              ],
              "count" => "count",
              "value" => 20
         },
         {
              "operation" => "write-attribute",
              "address" => [
                   ("profile" => "production"),
                   ("subsystem" => "threads"),
                   ("bounded-queue-thread-pool" => "pool2")
              ],
              "name" => "count",
              "value" => 10
         }
    ],
    "operation-headers" => {
        "rollback-on-runtime-failure => false
    }
}

The "composite" operation takes a single parameter:

• steps – a list, where each item in the list has the same structure as a simple operation request. In the example above each of the two steps is modifying the thread pool configuration for a different pool. There need not be any particular relationship between the steps. Note that the rollback-on-runtime-failure and rollout-plan operation headers are not supported for the individual steps in a composite operation.

The rollback-on-runtime-failure operation header discussed above has a particular meaning when applied to a composite operation, controlling whether steps that successfully execute should be reverted if other steps fail at runtime. Note that if any steps modify the persistent configuration, and any of those steps fail, all steps will be reverted. Partial/incomplete changes to the persistent configuration are not allowed.

Operations with a Rollout Plan

Operations targeted at domain or host level resources can potentially impact multiple servers. Such operations can include a "rollout plan" detailing the sequence in which the operation should be applied to servers as well as policies for detailing whether the operation should be reverted if it fails to execute successfully on some servers.

If the operation includes a rollout plan, the structure is as follows:

{
    "operation" => "write-attribute",
    "address" => [
        ("profile" => "production"),
        ("subsystem" => "threads"),
        ("bounded-queue-thread-pool" => "pool1")
    ],
    "name" => "count",
    "value" => 20,
    "operation-headers" => {
        "rollout-plan" => {
            "in-series" => [
                {
                    "concurrent-groups" => {
                        "groupA" => {
                            "rolling-to-servers" => true,
                            "max-failure-percentage" => 20
                        },
                        "groupB" => undefined
                    }
                },
                {
                   "server-group" => {
                        "groupC" => {
                            "rolling-to-servers" => false,
                            "max-failed-servers" => 1
                        }
                    }
                },
                {
                    "concurrent-groups" => {
                        "groupD" => {
                            "rolling-to-servers" => true,
                            "max-failure-percentage" => 20
                        },
                        "groupE" => undefined
                    }
                }
            ],
            "rollback-across-groups" => true
        }
    }
}

As you can see, the rollout plan is another structure in the operation-headers section. The root node of the structure allows two children:

• in-series – a list – A list of activities that are to be performed in series, with each activity reaching completion before the next step is executed. Each activity involves the application of the operation to the servers in one or more server groups. See below for details on each element in the list.

• rollback-across-groups – boolean – indicates whether the need to rollback the operation on all the servers in one server group should trigger a rollback across all the server groups. This is an optional setting, and defaults to false.

Each element in the list under the in-series node must have one or the other of the following structures:

• concurrent-groups – a map of server group names to policies controlling how the operation should be applied to that server group. For each server group in the map, the operation may be applied concurrently. See below for details on the per-server-group policy configuration.

• server-group – a single key/value mapping of a server group name to a policy controlling how the operation should be applied to that server group. See below for details on the policy configuration. (Note: there is no difference in plan execution between this and a "concurrent-groups" map with a single entry.)

The policy controlling how the operation is applied to the servers within a server group has the following elements, each of which is optional:

• rolling-to-servers – boolean – If true, the operation will be applied to each server in the group in series. If false or not specified, the operation will be applied to the servers in the group concurrently.

• max-failed-servers – int – Maximum number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.

• max-failure-percentage – int between 0 and 100 – Maximum percentage of the total number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.

If both max-failed-servers and max-failure-percentage are set, max-failure-percentage takes precedence.

Looking at the (contrived) example above, application of the operation to the servers in the domain would be done in 3 phases. If the policy for any server group triggers a rollback of the operation across the server group, all other server groups will be rolled back as well. The 3 phases are:

1. Server groups groupA and groupB will have the operation applied concurrently. The operation will be applied to the servers in groupA in series, while all servers in groupB will handle the operation concurrently. If more than 20% of the servers in groupA fail to apply the operation, it will be rolled back across that group. If any servers in groupB fail to apply the operation it will be rolled back across that group.

2. Once all servers in groupA and groupB are complete, the operation will be applied to the servers in groupC. Those servers will handle the operation concurrently. If more than one server in groupC fails to apply the operation it will be rolled back across that group.

3. Once all servers in groupC are complete, server groups groupD and groupE will have the operation applied concurrently. The operation will be applied to the servers in groupD in series, while all servers in groupE will handle the operation concurrently. If more than 20% of the servers in groupD fail to apply the operation, it will be rolled back across that group. If any servers in groupE fail to apply the operation it will be rolled back across that group.

Simple Responses

Simple responses are provided by the following types of operations:

• Non-composite operations that target a single server. (See below for more on composite operations).

• Non-composite operations that target a Domain Controller or slave Host Controller and don't require the responder to apply the operation on multiple servers and aggregate their results (e.g. a simple read of a domain configuration property.)

The response will always include a simple boolean outcome field, with one of three possible values:

• success – the operation executed successfully

• failed – the operation failed

• cancelled – the execution of the operation was cancelled. (This would be an unusual outcome for a simple operation which would generally very rapidly reach a point in its execution where it couldn't be cancelled.)

The other fields in the response will depend on whether the operation was sucessful.

The response for a failed operation:

{
    "outcome" => "failed",
    "failure-description" => "[JBAS-12345] Some failure message"
}

A response for a successful operation will include an additional field:

• result – the return value, or undefined for void operations or those that return null

A non-void result:

{
    "outcome" => "success",
    "result" => {
        "name" => "Brian",
        "age" => 22
    }
}

A void result:

{
    "outcome" => "success",
    "result" => undefined
}

The response for a cancelled operation has no other fields:

{
    "outcome" => "cancelled"
}

Response Headers

Besides the standard outcome, result and failure-description fields described above, the response may also include various headers that provide more information about the affect of the operation or about the overall state of the server. The headers will be child element under a field named response-headers. For example:

{
    "outcome" => "success",
    "result" => undefined,
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

A response header is typically related to whether an operation could be applied to the targeted runtime without requiring a restart of some or all services, or even of the target process itself. Please see the "Applying Updates to Runtime Services" section of the Description of the Management Model section for a discussion of the basic concepts related to what happens if an operation requires a service restart to be applied.

The current possible response headers are:

• operation-requires-reload – boolean – indicates that the specific operation that has generated this response requires a restart of all services in the process in order to take effect in the runtime. This would typically only have a value of 'true'; the absence of the header is the same as a value of 'false.'

• operation-requires-restart – boolean – indicates that the specific operation that has generated this response requires a full process restart in order to take effect in the runtime. This would typically only have a value of 'true'; the absence of the header is the same as a value of 'false.'

• process-state – enumeration – Provides information about the overall state of the target process. One of the following values:

  • starting – the process is starting

  • running – the process is in a normal running state. The process-state header would typically not be seen with this value; the absence of the header is the same as a value of 'running'.

  • reload-required – some operation (not necessarily this one) has executed that requires a restart of all services in order for a configuration change to take effect in the runtime.

  • restart-required – some operation (not necessarily this one) has executed that requires a full process restart in order for a configuration change to take effect in the runtime.

  • stopping – the process is stopping

Basic Composite Operation Responses

A composite operation is one that incorporates more than one simple operation in a list and executes them atomically. See the "Composite Operations" section for more information.

Basic composite responses are provided by the following types of operations:

• Composite operations that target a single server.

• Composite operations that target a Domain Controller or a slave Host Controller and don't require the responder to apply the operation on multiple servers and aggregate their results (e.g. a list of simple reads of domain configuration properties.)

The high level format of a basic composite operation response is largely the same as that of a simple operation response, although there is an important semantic difference. For a composite operation, the meaning of the outcome flag is controlled by the value of the operation request's rollback-on-runtime-failure header field. If that field was false (default is true), the outcome flag will be success if all steps were successfully applied to the persistent configuration even if none of the composite operation's steps was successfully applied to the runtime.

What's distinctive about a composite operation response is the result field. First, even if the operation was not successful, the result field will usually be present. (It won't be present if there was some sort of immediate failure that prevented the responder from even attempting to execute the individual operations.) Second, the content of the result field will be a map. Each entry in the map will record the result of an element in the steps parameter of the composite operation request. The key for each item in the map will be the string "step-X" where "X" is the 1-based index of the step's position in the request's steps list. So each individual operation in the composite operation will have its result recorded.

The individual operation results will have the same basic format as the simple operation results described above. However, there are some differences from the simple operation case when the individual operation's outcome flag is failed. These relate to the fact that in a composite operation, individual operations can be rolled back or not even attempted.

If an individual operation was not even attempted (because the overall operation was cancelled or, more likely, a prior operation failed):

{
    "outcome" => "cancelled"
}

An individual operation that failed and was rolled back:

{
    "outcome" => "failed",
    "failure-description" => "[JBAS-12345] Some failure message",
    "rolled-back" => true
}

An individual operation that itself succeeded but was rolled back due to failure of another operation:

{
    "outcome" => "failed",
    "result" => {
        "name" => "Brian",
        "age" => 22
    },
    "rolled-back" => true
}

An operation that failed and was rolled back:

{
    "outcome" => "failed",
    "failure-description" => "[JBAS-12345] Some failure message",
    "rolled-back" => true
}

Here's an example of the response for a successful 2 step composite operation:

{
    "outcome" => "success",
    "result" => [
        {
            "outcome" => "success",
            "result" => {
                "name" => "Brian",
                "age" => 22
            }
        },
        {
            "outcome" => "success",
            "result" => undefined
        }
    ]
}

And for a failed 3 step composite operation, where the first step succeeded and the second failed, triggering cancellation of the 3rd and rollback of the others:

{
    "outcome" => "failed",
    "failure-description" => "[JBAS-99999] Composite operation failed; see individual operation results for details",
    "result" => [
        {
            "outcome" => "failed",
            "result" => {
                "name" => "Brian",
                "age" => 22
            },
            "rolled-back" => true
        },
        {
            "outcome" => "failed",
            "failure-description" => "[JBAS-12345] Some failure message",
            "rolled-back" => true
        },
        {
            "outcome" => "cancelled"
        }
    ]
}

Multi-Server Responses

Multi-server responses are provided by operations that target a Domain Controller or slave Host Controller and require the responder to apply the operation on multiple servers and aggregate their results (e.g. nearly all domain or host configuration updates.)

Multi-server operations are executed in several stages.

First, the operation may need to be applied against the authoritative configuration model maintained by the Domain Controller (for domain.xml confgurations) or a Host Controller (for a host.xml configuration). If there is a failure at this stage, the operation is automatically rolled back, with a response like this:

{
    "outcome" => "failed",
    "domain-failure-description" => "[JBAS-33333] Failed to apply X to the domain model"
}

If the operation was addressed to the domain model, in the next stage the Domain Controller will ask each slave Host Controller to apply it to its local copy of the domain model. If any Host Controller fails to do so, the Domain Controller will tell all Host Controllers to revert the change, and it will revert the change locally as well. The response to the client will look like this:

{
    "outcome" => "failed",
    "host-failure-descriptions" => {
        "hostA" => "[DOM-3333] Failed to apply to the domain model",
        "hostB" => "[DOM-3333] Failed to apply to the domain model"
    }
}

If the preceding stages succeed, the operation will be pushed to all affected servers. If the operation is successful on all servers, the response will look like this (this example operation has a void response, hence the result for each server is undefined):

{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {
        "groupA" => {
            "serverA-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverA-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        },
        "groupB" => {
            "serverB-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverB-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        }
    }
}

The operation need not succeed on all servers in order to get an "outcome" => "success" result. All that is required is that it succeed on at least one server without the rollback policies in the rollout plan triggering a rollback on that server. An example response in such a situation would look like this:

{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {
        "groupA" => {
            "serverA-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverA-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        },
        "groupB" => {
            "serverB-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-3" => {
                "host" => "host3",
                "response" => {
                    "outcome" => "failed",
                    "failure-description" => "[DOM-4556] Something didn't work right",
                    "rolled-back" => true
                }
            }
        }
    }
}

Finally, if the operation fails or is rolled back on all servers, an example response would look like this:

{
    "outcome" => "failed",
    "server-groups" => {
        "groupA" => {
            "serverA-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            },
            "serverA-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "success",
                    "result" => undefined
                }
            }
        },
        "groupB" => {
            "serverB-1" => {
                "host" => "host1",
                "response" => {
                    "outcome" => "failed",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-2" => {
                "host" => "host2",
                "response" => {
                    "outcome" => "failed",
                    "result" => undefined,
                    "rolled-back" => true
                }
            },
            "serverB-3" => {
                "host" => "host3",
                "response" => {
                    "outcome" => "failed",
                    "failure-description" => "[DOM-4556] Something didn't work right",
                    "rolled-back" => true
                }
            }
        }
    }
}