<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
JBoss AS7 User Guide
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/stan.silvert%40jboss.com">Stan Silvert</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-16068">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>This is a brief guide intended to help users who wish to experiment with JBoss AS 7 as it undergoes development. Feedback on its content is most appreciated, either via comments on this page, via forum posts in this "JBoss AS7 Development" section of the wiki, or by posts to the <a class="jive-link-external-small" href="https://lists.jboss.org/mailman/listinfo/jboss-development">jboss-development mailing list</a>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>AS 7 is currently in "Alpha" status, so users should not expect all (or even most) of the capabilities of more stable AS 5 and 6 releases to be present. Users should also be aware that significant changes may be made from one alpha release to another.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>Getting JBoss AS 7</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>AS 7 is available from the <a class="jive-link-external-small" href="http://www.jboss.org/jbossas/downloads.html">jboss.org download page</a>. As in earlier JBoss AS releases, installation consists of unzipping the release distribution.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Users are encouraged to check out the AS 7 source and build it themselves. This is quite quick and painless once git is installed on your system, and getting git set up is also quite easy to do.  See the <a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-15596">Hacking On JBoss AS 7 wiki page</a> for more details on working with the AS 7 source.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>Quick Start</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Once you have the distribution unzipped, you need to decide whether you want to work in "domain mode" or "standalone mode". See "Domain Mode vs. Standalone Mode" below for more on what those choices mean.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If you want to work in domain mode, open a terminal and cd into the distribution's bin directory, and run the "domain" launch script:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">$ cd bin
$ ./domain.sh
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>On Windows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">> cd bin
> domain.bat
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>This will launch a total of 5 processes on your system: three JBoss AS server instances; a Domain Controller process that acts as a central management point for all servers that belong to the same "domain"; and a lightweight Process Controller process that is responsible for spawning the other 4 processes and monitoring their lifecycle.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If you want to work in standalone mode, open a terminal and cd into the distribution's bin directory, and run the "standalone" launch script:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive_text_macro jive_macro_code"><p>$ cd bin</p><p>$ ./standalone.sh</p></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>On Windows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive_text_macro jive_macro_code"><p>> cd bin</p><p>> standalone.bat</p></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>This will launch a single process on your system, a standalone JBoss AS server instance.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If you have the AS 7 source checked out, there are a number of demos that can be run from the source checkout's <span style="font-family: courier new,courier;">demos</span> module. See below for details.</p><h2>Domain Mode vs. Standalone Mode</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>One of the primary new features of AS 7 is the ability to manage multiple AS instances from a single control point. A collection of such servers are referred to as members of a "domain", with a single Domain Controller process acting as the management control point. Domains can span multiple physical (or virtual) machines, with all AS instances on a given host under the control of a Host Controller process. The Host Controllers interact with the Domain Controller to control the lifecycle of the AS instances running on that host and to assist the Domain Controller in managing them.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>When you launch JBoss AS in "domain mode" (via the domain.sh or domain.bat launch scripts) your intent is to launch a Domain Controller, a Host Controller and usually at least one AS instance.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>For more on running servers in domain mode, a roughly 20 minute video is available online (divided in two pieces):</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><a class="jive-link-external-small" href="http://www.youtube.com/watch?v=phV3QiKQf2E">http://www.youtube.com/watch?v=phV3QiKQf2E</a> <br/><a class="jive-link-external-small" href="http://www.youtube.com/watch?v=gCeQ2KIO0qc">http://www.youtube.com/watch?v=gCeQ2KIO0qc</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>For many use cases, the centralized managment capability available via domain mode is not necessary. For these use cases, the AS can also be run in "standalone mode". In standalone mode each AS instance is an independent process, much like an AS 3, 4, 5, or 6 instance is. Standalone instances can be launched via the standalone.sh or standalone.bat launch scripts.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If more than one standalone instance is launched and multi-server management is desired, it is the user's responsibility to coordinate management across the servers.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The current AS 7 alpha release does not support HA functionality. However, it's important to understand that once HA functionality is added, it will be orthogonal to "domain mode" vs. "standalone mode". That is, a group of servers running in standalone mode will be able to be configured to form an HA cluster. The domain and standalone modes determine how the servers are managed, not what capabilities they provide.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A given server instance cannot be switched between domain mode and standalone mode; i.e. you cannot launch domain.sh, stop the processes, and then launch standalone.sh and expect any relationship between what was running. The configurations are separate. We may in future releases include some tooling to ease the task of translating a given server configuration from domain mode to standalone mode.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>Contents of the AS 7 Distribution</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The AS 7 distribution includes the following directories:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>bin</strong></span> -- location of the launch scripts</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>docs</strong></span> -- license files, documentation, schemas, examples, etc. The amount of content in this directory will increase as development continues.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>modules</strong></span> -- AS 7 is based on a modular classloading architecture. The various modules used in the server are stored here. Generally speaking, this is not an area that would be modified by end users.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>domain</strong></span> -- only relevant when domain mode is used. Configuration files, deployment content, and writeable areas used by the domain mode processes that run off of this installation. See below for further details.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>standalone</strong></span> -- only relevant when standalone mode is used. Configuration files, deployment content, and writeable areas used by the single standalone server that runs off this installation. See below for further details.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Contents of the "domain" Directory</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Only relevant when domain mode is used.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>configuration</strong></span> -- configuration files for the domain and for the Host Controller and any servers running off of this installation. If we've done our jobs well, these configuration files are the only configuration files end users should need to touch (outside of deployment descriptors in their own application deployments). See below for more on these files.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>content </strong></span>-- an internal working area for the Host Controller that controls this installation. This is where it internally stores deployment content. This directory is not meant to be manipulated by end users.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>log</strong> -- location where the Process Controller and Host Controller write their log files.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>servers</strong></span> -- writeable area used by each AS instance. Each AS instance will have its own subdirectory, created when the server is first started. In each server's subdirectory there will be the following subdirectories:</p><p><span style="font-family: courier new,courier;">data</span> -- information written by the server that needs to survive a restart of the server</p><p><span style="font-family: courier new,courier;">log</span> -- the server's log files</p><p><span style="font-family: courier new,courier;">tmp</span> -- location for temporary files written by the server</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>system-content</strong></span> -- an internal working area. Storage for non-end-user deployments; i.e. deployments that the subsystems that comprise a running AS themselves deploy into the runtime as part of the service they provide.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Contents of the "standalone" Directory</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Only relevant when standalone mode is used.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>configuration</strong> -- configuration files for the standalone server that runs off of this installation. If we've done our jobs  well, these configuration files are the only configuration files end  users should need to touch (outside of deployment descriptors in their  own application deployments). See below for more on these files.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>data</strong></span> -- information written by the server that needs to survive a restart of the server</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>deployments</strong></span> -- an area where end user deployment content can be placed if automatic detection and deployment of that content into the server's runtime is desired. The server's management API exposes other means for installing deployment content, and use of that API in preference to the <span style="font-family: courier new,courier;">deployments</span> directory is preferred. We realize however, that at this early stage in AS 7's development the tooling around the deployment API is in its infancy, so many users will utilize the deployments directory to deploy content. Note that "domain mode" does not support deploying content based on scanning a filesystem.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>log</strong></span> -- the server's log files</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>tmp</strong></span> -- location for temporary files written by the server</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>system-content</strong> -- an internal working area. Storage for non-end-user deployments; i.e.  deployments that the subsystems that comprise a running AS themselves  deploy into the runtime as part of the service they provide.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>"Domain Mode" Configuration Files</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Located in the <span style="font-family: courier new,courier;"><strong>domain/configuration</strong></span> directory.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>domain.xml</strong></span> -- primary configuration file for the domain. Among other things, includes the configuration of the various "profiles" that AS instances 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). Includes the definition of groups of sockets that those subsystems may open. And includes definition of "server groups", to which a profile, a group of socket definitions and zero or more deployments are mapped. Each individual server will be mapped (in <span style="font-family: courier new,courier;">host.xml</span>, see below) to a server group; the configuration of that server group largely defines the configuration of the individual server.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>A <span style="font-family: courier new,courier;">domain.xml</span> 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 <span style="font-family: courier new,courier;">domain.xml</span> file on such a server does no harm; it will be ignored.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Users are encouraged to have a look at the <a class="jive-link-external-small" href="https://github.com/jbossas/jboss-as/blob/master/domain/src/main/resources/schema/jboss_7_0.xsd">AS 7 configuration schema</a>, starting with the <span style="font-family: courier new,courier;"><domain></span> element, to learn more about configuration of a Domain Controller.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>host.xml</strong></span> -- configuration file for the Host Controller that runs off of this particular installation. Each installation must have a <span style="font-family: courier new,courier;">host.xml</span> file. Contains configuration information that is specific to the particular installation. Primarily:</p><ul><li>the listing of the names of the actual AS server instances that are meant to run off of this installation, along with the server group they belong to.</li><li>configuration of how the Host Controller is to contact the Domain Controller to register itself and access the domain configuration. This may either be 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.</li><li>configuration of items that are specific to the local physical installation. For example, named interface definitions declared in <span style="font-family: courier new,courier;">domain.xml</span> can be mapped to an actual machine-specific IP address in <span style="font-family: courier new,courier;">host.xml</span>. Abstract path names in <span style="font-family: courier new,courier;">domain.xml</span> can be mapped to actual filesystem paths in <span style="font-family: courier new,courier;">host.xml</span>.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Users are encouraged to have a look at the <a class="jive-link-external-small" href="https://github.com/jbossas/jboss-as/blob/master/domain/src/main/resources/schema/jboss_7_0.xsd">AS 7 configuration schema</a>, starting with the <host> element, to learn more about configuration of a Host Controller.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><strong>logging.properties</strong></span> -- Contains the logging configuration for the Host Controller and Process Controller that run off of this installation. Also defines the initial bootstrap logging configuration for each individual AS instance. This boostrap logging configuration is replaced with the logging configuration specified in the domain.xml file once the server boot has reached the point where that configuration is available.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>"Standalone Mode" Configuration Files</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Located in the <strong>standalone/configuration</strong> directory.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>standalone.xml</strong> -- primary configuration file for the AS instance. Among other things, includes the configuration of the "profile" that the AS instance is 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). Also includes the definition of the sockets that those subsystems may open.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Users are encouraged to have a look at the <a class="jive-link-external-small" href="https://github.com/jbossas/jboss-as/blob/master/domain/src/main/resources/schema/jboss_7_0.xsd">AS 7 configuration schema</a>, starting with the <span style="font-family: courier new,courier;"><server></span> element, to learn more about configuration of a standalone AS instance.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>logging.properties</strong> -- Contains the initial bootstrap logging configuration for the AS instance.  This boostrap logging configuration is replaced with the logging configuration specified in the standalone.xml file once the server boot has reached the point where that configuration is available.</p><h2><br/>Available Subsystems</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>AS 7 is under active development. Not all capabilities present in more mature releases of the AS 5 and 6 series are available in AS 7 yet. Following is a brief listing of the subsystems available in the various AS 7 releases. Items listed below may not be entirely feature complete.</p><h4>7.0.0.Alpha1</h4><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ul><li>logging -- configuration of logging appenders, categories, etc</li><li>threads -- thread pool management</li><li>sockets -- socket binding management</li><li>naming -- local JNDI. Note that direct remote access to JNDI is not supported in Alpha1 (see the client.jms demo for an example of a clever hack to get remote access to JNDI via an MBeanServerConnection)</li><li>transactions -- JTA</li><li>jmx -- MBeanServer with remote access capability</li><li>web -- basic servlet and JSP support</li><li>messaging -- HornetQ server</li><li>JMS -- JMS queues, topics and connection factories</li><li>JCA connectors</li><li>Datasources</li><li>JCA resource adapter deployments</li><li>osgi -- OSGI bundle deployment</li><li>remoting -- JBoss Remoting 3 connectors</li><li>managed beans -- EE 6 managed bean deployments</li><li>SAR deployments -- both legacy mbean deployments and those based on the JDK 6 ServiceLoader concept. Note that not all legacy sar capabilities are supported</li><li>Filesystem based hot deployment scanning (standalone mode only) -- note that exploded deployments are not currently supported</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2>Demos in the Source Checkout</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The source checkout includes a "demos" module that includes a number of demos that can be run from maven. Building the module from the /demos directory will output a usage note that explains how to run the demos:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">usage:
     [echo] To run an example:
     [echo] 1) In a separate console window,start either a standalone JBoss AS instance or a JBoss AS domain
     [echo] 2) Run mvn package -Dexample=<example.name> where "exammple.name is the name of the example
     [echo]
     [echo] Valid example names to run against a standalone JBoss AS instance are
     [echo]   sar              - deploys mbeans packaged in a sar
     [echo]   managedbean      - deploys a managed bean
     [echo]   serviceloader    - deploys a serviceloader style service
     [echo]   messaging        - deploys HornetQ native sender and receiver
     [echo]   jms              - deploys HornetQ JMS sender and receiver
     [echo]   jms.client       - Uses HornetQ JMS API from the client
     [echo]   rar              - deploys a resource adapter
     [echo]   ds               - deploys a test bean for data sources
     [echo]   war              - deploys a simple servlet and connects to it
     [echo]   client.messaging - creates a HornetQ core queue using the management API
     [echo]   client.jms       - creates a JMS queue using the management API
     [echo]   web.connector    - creates and removes a jboss web connector
     [echo]
     [echo] Valid example names to run against a JBoss AS domain are
     [echo]   domain.configs     - reads the domain config and any available host controller configs
     [echo]   domain.ds          - deploys deploys a test bean for data sources
     [echo]   domain.messaging   - deploys HornetQ native sender and receiver
     [echo]   domain.rar         - deploys deploys a resource adapter
     [echo]   domain.servers     - shows domain, host controller and server configs, starts/stops servers</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The primary point of the demos is to look at the source code and see how they use the AS's management API to deploy content and/or alter the configuration of the running server(s). To see how an example works, look at the relevant <span style="font-family: courier new,courier;">demos/src/main/java/org/jboss/as/demos/<example.name>/runner.ExampleRunner.java</span> file.</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-16068">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS7 Development at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>