JBoss AS is a full Java application server and hence it requires a Virtual Machine for the Java Platform to run on.

So, let's move on the Oracle download page, which now hosts all JDK downloads: http://www.oracle.com/technetwork/java/javase/downloads/index.html

Choose to download the latest JDK/JRE which is, at the time of writing, the JDK 1.6 Update 26.

The download will take a few minutes depending how fast your network is. Once the download is complete, run the executable file to start the installation. (The actual name of the installer varies, also if you are on a 32-bit system or 64-bit. However, the steps will be the same, just the name will change).

jdk-6u26-windows-i586.exe       # Windows
sh jdk-6u26-linux-i586.bin      # Linux

If you are installing on a Linux/Unix box, you can safely accept all the defaults given to you by the setup wizard. The Windows users should stay away from the installation paths that include empty spaces, such as C:\Program Files, as this leads to some issues when you are referencing the core libraries. An installation path such as C:\Software\Java or simply C:\Java is a better alternative.

When the installation is complete, we need to update a couple of settings on the computer so it can interact with Java. The most important setting is JAVA_HOME, which is directly referenced by JBoss startup script.

If you are running Windows XP-2000, follow these steps:

Unix/Linux users can add the following commands in the user's profile scripts:

export JAVA_HOME=/installDir/jdk1.6.0_26
export PATH=$JAVA_HOME/bin:$PATH

JBoss application server can be freely downloaded from the community site: http://www.jboss.org/jbossas/downloads/.

Choose to download the full server distribution. You will be then warned that this download is part of a community release and, as such, it is not yet fully supported. As said before, RedHat maintains the Enterprise releases of JBoss middleware and, hopefully, the AS 7 will be soon part of it.

Windows users can simply use any uncompress utility, such as WinZip, or WinRAR taking care to choose a folder, which doesn't contain empty spaces. Unix /Linux should use the unzip shell command to explode the archive:

unzip jboss-as-7.0.2.Final.zip

After you have installed JBoss, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, move to the bin directory of your JBOSS_HOME directory and issue the following command:

standalone.bat    # Windows users
$ standalone.sh   # Linux/Unix users

Here's a sample JBoss AS 7 startup console:

The above command starts up a JBoss standalone instance that's equivalent of starting the application server with the run.bat/run.sh script used by earlier AS releases. You will notice how amazingly fast is starting the new release of the application server; this is due to the new modular architecture, which only starts up necessary parts of the application server container needed by loaded applications.

If you need to customize the startup properties of your application server, then you need to open the standalone.conf (or standalone.conf.bat for the Windows users) where the memory requirements of JBoss are declared. Here's the Linux core section of it:

if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 - Dsun.rmi.dgc.server.gcInterval=3600000"
fi

So, by default, the application server starts with a minimum memory requirement of 64MB of heap space and a maximum of 512MB. This will be just enough to get started, however, if you need to run a core Java EE application on it, you will likely require at least 1GB of heap space or 2GB or more depending on your application type. Generally speaking, 32-bit machines cannot execute a process whose space exceeds 2GB, however on 64 bit machines, there's essentially no limit to process size.

You can verify that the server is reachable from the network by simply pointing your browser to the application server's welcome page, which is reachable by default at the well-known address: http://localhost:8080.

Connecting to the server with the command line interface

If you have been using previous releases of the application server you might have heard about the twiddle command-line utility that queried the MBeans installed on the application server. This utility has been replaced by a more sophisticated interface named the Command Line Interface (CLI), which can be found in the JBOSS_HOME/bin folder.

Just launch the jboss-admin.bat script (or jboss-admin.sh for Linux users) and you will be able to manage the application server via a shell interface.

We have just started an interactive shell session which is also able to use the command-line completion (by pressing the Tab key) to match partly-typed command names. No more searches for finding the exact syntax of commands!

Note

In the previous screenshot, we have just connected to the server using the connect command, which by default uses the loopback server address and plugs into the port 9999.

The command-line interface is discussed in depth in Chapter 7, Managing the Application Server, which is all about the server-management interfaces; We will, however, have an initial taste of its basic functionalities in the following sections to get you accustomed to this powerful tool.

Probably the easiest way to stop JBoss is by sending an interrupt signal with Ctrl+C.

However, if your JBoss process was launched in the background or rather is running on another machine (see next), then you can use the CLI interface to issue an immediate shutdown command:

[disconnected /] connect
Connected to localhost:9999
[localhost:9999 /] :shutdown

jboss-admin.bat --connect command=:shutdown      # Windows

jboss-admin.sh --connect command=:shutdown       # Unix / Linux

[disconnected /] connect 192.168.1.10
Connected to 192.168.1.10:9999
[192.168.1.10:9999 /] :shutdown

The command-line Interface contains a lot of useful commands. One of the most interesting options is the ability to reload all or parts of the AS configuration using the reload command.

When issued on the root node path of the AS server, it is able to reload the services configuration:

[disconnected /] connect 
Connected to localhost:9999
[localhost:9999 /] :reload

Although the main focus of this book is the administration of the application server, we are also concerned with the application packaging and deploying. For this reason, we will sometimes add examples that require a development environment to be executed.

The development environment used in this book is Eclipse known by Java developers worldwide and contains a huge set of plugins to expand its functionalities. Besides this, Eclipse is the first IDE that is compatible with the new application server.

So, let's move to the downloading page of Eclipse which is located at: http://www.eclipse.org.

From there, download the latest Enterprise Edition (at the time of this writing, it's version 3.7 and is also known as Indigo). The compressed package contains all the Java EE plugins already installed and requires about 210MB of disk space:

Once you have unzipped the previously downloaded file, you will see a folder named eclipse. In that folder, you will find the eclipse application (a big blue dot). We recommend you create a shortcut on the desktop to simplify the launching of Eclipse. Note that just like JBoss AS, Eclipse does not have an installation process. Once you have unzipped the file, you are done!

Installing JBoss tools

The next step will be installing the JBoss AS plugin, which is a part of the suite of plugins named JBoss tools. Installing new plugins in Eclipse is pretty simple; just follow these steps:

1. From the menu, choose Help | Install New Software.

2. Then, click on the Add button where you will enter the JBoss tools' download URL (along with a description): http://download.jboss.org/jbosstools/updates/development/indigo/.

   

As you can see from the previous screenshot, you need to check the JBossAS Tools plugin and move forward to the next options where you will complete the installation process. Once done, restart when prompted.

Now, you should be able to see the JBoss AS 7 enlisted as a server by choosing New | Server from the upper menu and expanding the JBoss Community option:

Completing the server installation into the Eclipse is quite straightforward as it just requires pointing to the folder where your server distribution, hence we will leave this to the reader as a practical exercise.

This is where you start your application server instances. You can start a standalone server by launching the standalone.bat (standalone.sh for Linux users). In addition to the startup scripts, you can find the standalone.bat, which can be used to customize JBoss' bootstrap processIf you are going to use a domain of servers, you will use the domain.bat script (domain.sh for Linux users). This shell script starts up a set of application server instances as specified by the domain configuration file.

The bin folder also includes another useful script command, named jboss-admin.bat (jboss-admin.sh for Linux users), which starts the new interactive command-line interface.

In addition, this folder contains the web services utility scripts (wsconsume.sh and wsprovide.sh) used to generate the web services definition language and the corresponding Java interfaces.

In spite of its name, this folder does not contain the server documentation, but two subfolders: the first one named licenses barely contains the licenses information for the application server and its dependencies. You might use the licenses.xml file as quick reference for finding out which are the version shipped with the default application server modules or dependencies. For example, JBoss AS 7 ships with the release 4.0.0.CR2 of Hibernate core libraries.

<dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>4.0.0.CR2</version>
      <licenses>
        <license>
          <name>GNU Lesser General Public License</name>
          <url>http://www.gnu.org/licenses/lgpl-2.1.html</url>
          <distribution>repo</distribution>
          <comments>See discussion at http://hibernate.org/license for more details.</comments>
        </license>
      </licenses>
</dependency>

The other subfolder named schema contains the .xsd files which are used by the configuration as schema.

The next folder is the domain folder, which contains the domain structure, split across a set of folders:

The configuration folder contains as you might imagine the configuration files. The main configuration file is domain.xml which contains all services which are used by the nodes of the domain. It also configures the socket-binding interfaces for all services.

Along with it, the other key file is host.xml which is used to define the management aspects of the domain.

The last file contained in the configuration folder is logging.properties which are used to define the logging format of the bootstrap process.

The content folder is used as a repository to store deployed modules.

The lib folder hosts the sub-folder ext, which is there to support Java SE/EE style "extensions". Some of the application server deployers are able to scan this folder for additional libraries which are picked up by the local class loader; nevertheless this approach is not recommended and maintained only for compliance with the language specifications. The modules folder should be the one and only path for your libraries.

The log folder contains as you might imagine the logging output of the domain. The file, by default, is truncated every time the server is rebooted.

The servers folder holds a set of sub-folders for each server defined in the configuration file. The most useful directory contained beneath each server is the log folder which is the location where single instances emit their log. The data folder is used by the application server to store its runtime data, such as the transaction logging The tmp folder is a temporary location for some resource artifacts which is not a big issue for any of you.

If you are running the application server in standalone mode, this is the part of the AS file system you will be interested in. Its structure is quite similar to the domain folder with the notable exception of a deployment folder. Let's proceed with order. Just below the domain folder, you will find the following set of subdirectories.

The configuration folder contains also the application server configuration files. As a matter of fact the application server ships with a set of different configuration files, each one using a different set of functionalities. Launching the standalone start-up script, by default, the standalone.xml configuration file will be used.

Besides standalone.xml, this folder contains the logging.properties file, which is also about the logging of bootstrap process. The other file you will find within it, mgmt-users.properties, can be used to secure the management interfaces. The security is discussed in detail in Chapter 10, Securing JBoss AS, of this book.

The data folder is used by the application server to store its runtime data, such as the transaction logging.

The deployments folder is the location in which users can place their deployment content (for example, WAR, EAR, JAR, SAR files) to have it automatically deployed into the server runtime. Users, particularly those running production systems, are encouraged to use the JBoss AS management APIs to upload and deploy deployment content instead of relying on the deployment scanner subsystem that periodically scans this directory. See Chapter 6, Deploying Applications on JBoss AS 7, for more details.

The lib folder hosts the sub folder ext, which is used to define extensions of the application server. The same considerations for the domain's lib path apply here.

The log folder contains the logs emitted by the standalone instance of the application server. The default log file, named server.log, is truncated every time the server is rebooted.

The tmp folder holds is used by JBoss Virtual File System as a temporary location for resource artifacts.

This directory contains the default page which is loaded when you surf on the home of your application server (http://localhost:8080). In terms of web server configuration, this is the Web root context .

Beneath the modules folder, you will find the application server's set of libraries, which are a part of the server distribution.

Historically, JBoss AS releases used to manage their set of libraries in different ways. Lets recap to make some order. Earlier, Release 4.x was used to define the core server libraries into the JBOSS_HOME/server libraries. Thereafter, each server definition had its specific library into the server/<servername>/lib folder.

This approach was pretty simple this way; however, it led to a useless proliferation of libraries which were replicated in the default/all server distribution.

The release 5.x and 6.x had the concept of the common/lib folder which was the main repository for all modules that were common to all server definitions. Each server distribution still contained a server/<servername>/lib path for the libraries that were specific to that server definition. Unchanged from the earlier release was the repository for core server modules comprised by JBOSS_HOME/server.

JBoss AS 7 follows a real modular approach deprecating all earlier approaches. The server bootstrap libraries are now located at the root of the application server. There you can find the jboss-modules.jar archive, which is all you need to bootstrap the new application server kernel, based on the JBoss modules.

The application server modules are now defined beneath the modules folder, grouped in a set of subfolders each one dedicated to a set of resources. At first sight, this approach might seem less intuitive than previous releases; however, once accustomed to it, you will find it much easier to handle module installation/updates.

The following table resumes the diverse approaches used across different server releases:

Listing all the modules will take up too much space; however, the module repository layout is pretty much the same as the module name. For example, the org.jboss.as.ejb3 module will be found in org/jboss/as/ejb3 subfolder of the modules folder. In the last section of this chapter, we will see how modules are actually loaded by the application server.

Learning more about JBoss module is essential if you want to understand the next chapters that discuss about the server configuration. Basically, each module is a pluggable unit. As depicted by the following picture. JBoss modules can load libraries using two approaches:

Using a static file system approach is the simplest way to load a module, and it's used as a default when starting up the application server. It is based on the assumption that the filesystem reflects the name and version of modules used. All you need to provide to the environment is the location where modules are stored. So, for example, you could start a standalone instance of JBoss AS 7 using the following command:

java -jar jboss-modules.jar -mp "%JBOSS_HOME%\modules" org.jboss.as.standalone

The argument module path (-mp) actually points to the root directory (or directories), which will be searched by the default module loader for module definitions. A module is defined using a simple XML descriptor, like this:

<module xmlns="urn:jboss:module:1.0" name="org.jboss.msc">

    <main-class name="org.jboss.msc.Version"/>
    <resources>
        <resource-root path="jboss-msc-1.0.0.Beta8.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="org.jboss.logging"/>
        <module name="org.jboss.modules"/>
    </dependencies>
</module>

Basically, a module definition contains two main elements: the resources defined in the module (and their path) and the module dependencies . The previous example is the module definition for the JBoss MSC module which is contained in the jboss-msc-1.0.0.Beta8.jar file and bears a dependency on javax.api, org.jboss.logging and org.jboss.modules module.

The other way to approach the module repository is by using direct JAR execution . This means that the module information, such as its dependencies, is contained in the MANIFEST file.

When the module is executed as a JAR file you just need to provide the name of your application module, which is packed in JAR file, and it will be picked up by JBoss modules:

java -jar jboss-modules.jar -jar your-app.jar

Then, in your application.jar, you might specify a set of module definitions, much the same way you did for flat filesystem modules. These definitions are contained in the META-INF/MANIFEST.MF file:

Main-Class: mypackage/MyClass
Dependencies: org.jboss.logging