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:
– Applying the operation to the runtime does not require the restart of any services. no-services
This value is the default if the restart-required descriptor is not present.
– The operation can only immediately update the persistent configuration; applying all-services
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
--The operation can only immediately update the persistent configuration; applying the operation jvm
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 "
". For a standalone server, a full process restart process-state" => "restart-required
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
operation. /host=<host>/server-config=<server>:restart
– The operation can only immediately update the persistent configuration; resource-services
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
, the handler for the operation will go ahead "allow-resource-service-restart" => true
and restart the runtime service. Otherwise executing the operation will put the server into a " " state. (See the discussion of " " above for more on the "
reload-required all-services
" state.) reload-required
6.4 The native management API
A standalone JBoss Application Server process, or a managed domain Domain Controller or slave Host Controller process can be configured to listen for remote management requests using its "native
JBoss Community Documentation Page 185 of 660 <native-interface interface="management" port="9999" security-realm="ManagementRealm"/>
(See standalone/configuration/standalone.xml or domain/configuration/host.xml)
The CLI tool that comes with the application server uses this interface, and user can develop custom clients that use it as well. In this section we'll cover the basics on how to develop such a client. We'll also cover details on the format of low-level management operation requests and responses – information that should prove useful for users of the CLI tool as well.
6.4.1 Native Management Client Dependencies
The native management interface uses an open protocol based on the JBoss Remoting library. JBoss Remoting is used to establish a communication channel from the client to the process being managed. Once the communication channel is established the primary traffic over the channel is management requests initiated by the client and asynchronous responses from the target process.
A custom Java-based client should have the maven artifact
and its dependencies on the classpath. The other org.jboss.as:jboss-as-controller-client
dependencies are:
Maven Artifact Purpose
org.jboss.remoting:jboss-remoting Remote communication
org.jboss:jboss-dmr Detyped representation of the management model org.jboss.as:jboss-as-protocol Wire protocol for remote JBoss AS management org.jboss.sasl:jboss-sasl SASL authentication
org.jboss.xnio:xnio-api Non-blocking IO
org.jboss.xnio:xnio-nio Non-blocking IO
org.jboss.logging:jboss-logging Logging
org.jboss.threads:jboss-threads Thread management
org.jboss.marshalling:jboss-marshalling Marshalling and unmarshalling data to/from streams The client API is entirely within the org.jboss.as:jboss-as-controller-client artifact; the other dependencies are part of the internal implementation of
and are not compile-time dependencies of any custom org.jboss.as:jboss-as-controller-client
client based on it.
The management protocol is an open protocol, so a completely custom client could be developed without using these libraries (e.g. using Python or some other language.)
6.4.2 Working with a ModelControllerClient
The org.jboss.as.controller.client.ModelControllerClient class is the main class a custom client would use to manage a JBoss Application Server server instance or a Domain Controller or slave Host Controller.
The custom client must have maven artifact org.jboss.as:jboss-as-controller-client and its dependencies on the classpath.
JBoss Community Documentation Page 187 of 660