JBoss.orgCommunity Documentation

JBoss Server Manager Reference Guide

Svetlana Mukhina

Version: 3.3.0.M5

1. Quick Start with JBoss Server
1.1. Key Features of JBoss Server
1.2. Starting JBoss Server
1.3. Stopping JBoss Server
1.4. Project Archiving
1.5. Deploying an Application to a Server
1.6. Publishing to JBoss Server
2. Runtimes and Servers in the JBoss AS plugin
2.1. Runtimes
2.1.1. Installing a new runtime
2.1.2. Detecting an existing runtime
2.1.3. Duplicating a runtime configuration
2.2. Servers
2.2.1. Creating a New Server
3. JBoss Perspective
3.1. The Servers view
3.1.1. Servers view Toolbar
3.1.2. Servers view Structure
3.1.3. Drag-n-Drop to Servers view
3.1.4. Server Log View
3.1.5. Server Editor
3.1.6. Relevant Resources Links
3.2. Project Archives View
3.2.1. Overview
3.2.2. Creating an Archive
3.2.3. Archive Actions
3.2.4. Publishing to Server
3.2.5. Relevant Resources Links
4. Projects
4.1. Faceted Projects Overview
4.2. Adding Facets to a Project
4.3. Relevant Resources Links
5. Deploying Modules
5.1. Deploying on the Package Explorer
5.1.1. Deploying with Run On Server Wizard
5.2. Deploying with Servers View
5.2.1. Top part of Servers view
5.2.2. Bottom part of Servers view
5.3. Deploying with Project Archives View
6. TPTP Support
6.1. TPTP Profiling
6.2. Relevant Resources Links

This chapter covers the basics of working with the JBoss Server.

The publishing of all the modules added to a Server is performed automatically when starting a Server.

Automatically publishing changes made to the workspace is enabled by default, allowing the workspace to remain in sync with the publish folder. If you need to control when to publish the changes, just disable the automatic publish in the Server Editor (see Section 3.1.5, “Server Editor”) and use the Publish to Server () button which will incrementally publish the workspace.

This section has provided some basic information that will allow you to use the common features provided by the JBoss server. However, JBoss server includes a great deal more functionality, which will be discussed in subsequent chapters.

In this chapter we will discuss how to install runtimes and servers.

First of all it is necessary to mention that the JBoss AS plugin makes use of WTP. This includes starting and stopping servers in run or debug mode. It also includes targeting WTP projects, such as Dynamic Web Projects, to certain server runtimes in order to ensure that the proper JARs from a specific server are added to the project's classpath properly.

In order to get started creating, running and debugging J2EE applications, we should create our runtime and server instances.

In JBoss Tools, the main purpose of Server Runtimes is to point to a server installation somewhere on disk. In our case, this will be a JBoss installation. It can then be used for two primary purposes:

You can install runtimes into Eclipse by selecting WindowPreferences menu and then selecting ServerRuntime Environments from the categories available on the left.

From this preference page you can see all declared runtimes along with their types. Here, it is possible to edit or remove existing runtimes, as well as add a new one.

To create a JBoss runtime click the Add button and choose the appropriate type of runtime from the JBoss Community category.


Now there is a separation between .org servers (the JBoss Community category) and product server that comes with JBoss EAP in JBDS ( the JBoss Enterprise Middleware category).

As you can see, JBoss Tools™ provide its own adapters such as JBoss 3.2, 4.0, 4.2 and 5.0 as well. The last one comes a new safer incremental deployment feature, which prevents partial deployments to be picked up by the server. It means that scanning for auto-deployment is suspended while files are being copied to the deployment location and resumed when the copy is completed.


We recommend you use a fully supported JBoss Enterprise 6.0 server adapter.

You will also note a Deploy-Only Runtime type. This type does not provide a classpath for WTP projects. It is used solely by it's server type for the purpose of setting up a deploy directory for users who do not wish to make use of starting, stopping, or debugging their projects inside Eclipse.

The following table describes all the available options of the current wizard page.

As a result of having each runtime represent a specific configuration rather than the server installation as a whole, it is very likely you will create several different runtimes to test each of your configurations. So it becomes important to ensure your runtimes and later your servers, are given descriptive names that help you to remember which is which.

Click the Finish button to see your new runtime in the list.


If you edit the configuration of a runtime, the changes don't affect the settings of the servers that currently use the runtime. To apply the changes to them also, you should double left click on the server, select OverviewRuntime Environment, make sure that necessary configuration is chosen, click the Finish button and then Save button.

JBoss Tools features the ability to search, detect and add existing JBoss server runtimes installed on your system. If you don't have an existing runtime you can download one through the Download option or Section 2.1.1, “Installing a new runtime” will guide you through the creation process. To begin searching for your existing JBoss runtime select WindowPreferencesJBoss ToolsJBoss Runtimes.

The JBoss Tools Runtimes preference page is split into two different sections. One section defines Paths to be searched for installed server runtimes, the other section defines the runtime detectors available when the paths in the previous section are checked.

The Add button in the Paths section opens a file system browser window. Select the directory you wish to have recursively searched for JBoss runtimes. The directory will be searched and all found servers will be displayed as a list in the Searching for runtimes dialog. From the returned list, choose the runtimes you wish to make available by clicking the box beside each runtime and clicking the OK button.


Server runtime detection now recognizes the ESB runtime distributed as part of the JBoss Service-Oriented Architecture Platform.

The path you searched is now added to a list in the JBoss Tools Runtime Detection dialog Paths section. All the paths in this section will be automatically searched when a new workspace is created. If you wish for a path to be searched on startup then check the checkbox in the Every start column associated with it.

If you don't have a runtime already downloaded, you can download a free community application server through the Download button.


No official support is available for community application servers (this includes enterprise customers using JBoss Developer Studio).

Clicking on the Download button will display a new screen of available runtimes that can be downloaded. Highlight the server you wish to download and install, and click the OK button.

A new dialog will appear asking you to specify an Install folder and Download folder; the option to Delete archive after installing is checked by default. Once you have specified the two paths above, click the OK button and the server will begin downloading.

Once the server has been downloaded and installed, you will notice that the path to the new server now appears in the Paths section of the JBoss Tools Runtime Detection dialog.

WTP servers are Eclipse-representations of a back end server installation. They are used to start or stop servers, deploy to servers, or debug code that will run on the server. They keep track of the modules (JARs, WARs, etc) you deploy to the server and also allow you to undeploy those modules (see Section 5.1.1, “Deploying with Run On Server Wizard”).

Servers can be started or stopped via the Servers view in your workbench. They are often backed by a runtime object representing that server's location.

There are many ways to get to the new server wizard. One way is to select FileNewOther...Server. This should show the wizard like below.

A server object keeps track of the command line arguments when starting or stopping and the runtimes keep track of the location of the installation. This means that each server instance must be backed by an appropriate runtime.

The New server wizard allows you to name the server via the Server name field, or you can use a generated default name.

You can select the appropriate runtime from the Server runtime environment combo box. If there is no runtime that matches your needs, press the Add... link nearby to bring up the wizard for creating a new runtime (see Figure 2.3, “Adding a JBoss 5.0 Runtime”). To configure an existing runtime, go to server preferences by pressing the Configure runtime environments... link.

If the server you want to create does not have any installed runtime yet, the combobox and the links are absent.

In this case the next page of the wizard which has the same form as in the previous section and will ask you to create the associated runtime.

After targeting your server to a runtime, the final screen in this wizard presents a summary of the selected options, giving you a chance to verify that you have selected the appropriate runtime.

Click the Finish button to complete the process of the server creation.

Now that we have created our runtimes and servers, we can explore the services and tools provided by the JBoss Server Manager.

This chapter describes how to manage installed JBoss Servers™ via the JBoss Perspective. The Servers view will primarily be discussed.

The view

The Servers view is built on the Common Navigator Framework allowing extensions and is using label decorators that make the UI compact enough without loosing the vital information.

Let's have a detailed look at the Servers view and its constituent components.

The Servers view displays all defined servers as well as their current status (that is whether they are started or stopped) in square brackets next to the server name.

The following table lists possible server statuses.

You can control a server behavior as well as adjust a number of server preferences through the context menu.

All available context menu commands are described in the following table.

Under the server element in the Servers view, you can see modules that are currently deployed to the server and some server extensions that provide additional information on the server.

The context menu for any module allows you to remove it from the server and force a full or incremental republish upon it.

The Filesets category in the Servers view provides a way to filter files.

To add a new file filter, right-click the Filesets category and select the Create File Filter option.

The New File Filter wizard should appear.

The wizard asks you to enter the filter name and add includes and excludes patterns. The preview box underneath provides a list of files matched to the defined patterns (see the figures bellow).

In order to set up a default fileset relative to the fixed configuration of the server runtime, use the following variable: ${jboss_config}, i. e. you should enter server/${jboss_config}/ in the Root Directory option. This allows you to modify the runtime's configuration and not have to manually update paths.

Notice, that the Browse button still returns an absolute path:

After the filter is created, you can explore it by expanding the Filesets category in the Servers view.

It is now possible to edit files directly from the Filesets category. Double clicking on a file from Filesets opens up the editor automatically, or you can use the Edit File context menu command.

To delete a file filter (or just a file) from the Filesets, right-click a file filter or file and select the Delete File Filter or Delete File command.

If you want to set filesets for some server types, select WindowPreferences and then select ServerDefault from the categories available on the left.

On this preference page you can add a fileset to any server type or to all servers at once. To do this you should select the server type in the combo box and click the Add fileset... button. In the opened New File Filter wizard follow the steps described in Section, “Filesets” and finally click the Apply button on the preference page.

The defined file filter will be automatically added to new servers during their creation.

The XML Configuration category allows you to quickly browse to descriptor files in your server's deploy directory and check or change the values. Basically, XML Configuration includes XML XPaths, where an XPath is a path used to access some specific part of an XML document.

The XML Configuration category itself contains only a list of categories. Ports are provided by default and display many of the most commonly used ports in the JBoss Server™.

By right-clicking on the XML Configuration node you can create a new category. Besides, context menu for XML Configuration category makes possible to disable it. You can disable any category in the bottom part of the Servers view. Look for them in the Inactive Categories afterwards to re-enable.

By right-clicking on the Ports category, or any other category in XML Configuration, you can create a new XPath.

After that, the dialog shown below will appear.

The goal here is to get an end result where the XPath matches up with a necessary property. With that in mind, let's look how it works. If the property you want to reach is the value of the name attribute in the element <mbean>, then your XPath Patten should end with mbean and your Attribute Name should be name, as demonstrated in the next figure.

    <mbean code="org.jboss.ejb.EJBDeployer" 
                   name="jboss.ejb:service=EJBDeployer" xmbean-dd="">
     <!-- Inline XMBean Descriptor BEGIN -->
                    The EJBDeployer responsible for ejb jar deployment</description> 


Notice when you type the fields autocomplete to help you locate exactly what XPath you're looking for.

If your desired field is the text of an element <description>, your XPath Patten should end with description and Attribute Name field should be left blank. When finished, click the Preview button to see how many matches are found for that particular XPath.

By double-clicking on any server, an window will appear allowing you to edit the servers settings.


On the figure you can see that the username and password fields are available. If you get a SecurityException when trying to launch the server, it is most likely because your server is protected, which requires that you need to fill the username and password fields with appropriate values.

The Server Behaviour settings tab allows you to set how tool interaction with the server should be undertaken.

When you created the server, if you selected that it was a local server then you will notice that the option Server is externally managed. Assume server is started is unchecked and the combo-box displays Local.

If you created a remote server then you will see that the combo-box displays Remote System Deployment. Also populated will be the Host and Remote Server Home settings.

You are also able to change a servers behaviour from Local to Remote System Deployment through this settings tab. In doing so you will see that the Host is not set by default, but the other fields contain default values.

You can select the Listen on all interfaces to allow remote web connections when using JBoss Application Server 3 to 7 or JBoss Enterprise Application Platform 4 to 6. This option will force the server to launch with the option -b This option will change the host address to, useful for testing web applications on your local machine. JMX commands and web browser activities will still use the host set in the General Information section.

Under the Publishing section it is possible to disable or enable the automatic publishing of the changes in the workspace.

In the Server editor you are able to edit the timeouts, reload behaviour and the server pollers.


The Timeouts section allows you to specify a time limit for the server to complete operations within. If an operation does not start or fails to finish before the times you specify, that operation will be cancelled to avoid server failure.

Application Reload Behavior

This section of the Server settings allows you to customize the reload behavior of your application, depending on server and module changes.

Server Pollers

Server pollers are set under the Server State Detectors section. Both Startup and Shutdown pollers can be set individually.


By default, the Startup poller is set to Web Port. If you change the Startup poller to Timeout Poller (which may be required if you are using the minimal configuration for your server), this will do no polling at all and will only set the server state to "Started" after your startup timeout is reached.

It should be pointed out that the server adapter tries to automatically detect the ports it needs for integrating with a JBoss Server by default. Sometimes it is necessary to override this automatic detection if you are using a custom configuration. The Server Ports section in the Server editor provides fields to customize port settings. Click the Configure... link to bring up the wizard for adjusting the settings for the ports.

Click the Edit XPath button for the chosen port to configure its XPath's values.

The Server editor window also allows you to modify the server's launch configuration. The settings is available by clicking the the Open launch configuration link. The resulting window provides tabs for setting command line arguments, main, classpaths and other things that are relevant to launching the server.

The first tab shows the JBoss server arguments


Please note that the values in the Launch Configurations for JBoss Servers are strictly enforced in order to avoid inconsistencies between server's and their configured runtime.

For example, if you change the launch configuration program arguments to "-c myConfig" but do not change the targeted runtime configuration, then your program arguments will be ignored. The configuration of the server runtime "wins" so to speak. This ensures consistency and if you change the location of the runtime, your launch configurations will automatically pick that up.

Values are not controlled by the server and its runtime setup will be passed on unaltered.

On the second tab you find the main class used for launching JBoss AS (the default is org.jboss.Main). This value can be changed if necessary.

Until JBoss Tools 3.0.0.GA the servers classpath was read only, but that caused problems for users wanting to add their own JARs in the startup classpath. That is relevant if you need to patch the server, add a custom charset or other tweaks that require early access to the classpath.

Now all servers have a custom 'server runtime classpath container', which is there by default and point to the default JARs in JBoss. You can now adjust the classpath. Then just make sure this container is there if you want the classpath to be picked up.

If for some reason you have a launch configuration without this container, the Restore Default Entries button should add it properly. Also, the Restore Default Entries button will remove any extra entries you added yourself.

Using Deployment tab you configure local deployment settings.

Using the group of radio buttons in the Default Settings section a user can set where the application will be deployed to. By default it is deployed to the user's workspace folder, [workspaceDirecotry]\.metadata\.plugins. If you would like the application to be deployed to your JBoss server deploy folder select the Use the JBoss deploy folder option. The option to specify a custom deploy folder is also available.

Every application, whether Plain Old Java, J2EE, or some other language altogether, needs to be packaged in some way. In Java-related projects, many people use ANT.

But JBoss Tools™ comes with our own Archives tool with simpler and less-verbose XML and a handy user interface. The Project Archives plugin consists primarily of the Project Archives view to set up each packaging configuration.

Let's look through all functionality that the Project Archives view provides.

When you open the Project archives view for the first time, it asks you to select the project for which you want to create an archive.

When creating a new archive for selected project, you have some different options at your disposal. You need right-click inside the view and select New Archive to see your archive type options.


If you see only JAR from the list of available archive types, you should verify whether AS Tools plugins are installed. EAR, EJB JAR and WAR options are contributed by the AS Tools independently from webtools and the virtual project model. So without them only the JAR option will show up.

JAR is the standard archive type and does very little configuration, leaving most of the work up to you. You can customize the name, add folders, filesets and inner JARs to it.

The other types, for the most part, simply start off with a default setting, usually the JAR with some specific children based on an expected structure of the project. For example, if the project is a Dynamic Web Project and you create a WAR archive, the archive will be created with a few filesets relevant to the known structure of the project.

Here is the first page of all New archive wizards. It is the same for any archive type and the only page in the New JAR wizard.

The page is pretty simple. First it prompts you to set the name of your new archive and a destination.

The destination of an archive can be anywhere on the file system, anywhere in the workspace, inside another archive, or inside a folder declared inside an archive. Select the appropriate checkbox (either workspace or file system) to specify that the destination is related to either the workspace or filesystem. You can browse to workspace or filesystem destinations by clicking on their respective buttons. To select a destination inside some other archive, you'll need to click the Workspace button. At the bottom of the list, you will see the archives that have been declared in the workspace.

Also in the wizard for creating a new archive you can choose whether an archive to be compressed or exploded into a folder (without compression). You need just select proper checkbox in the Archive type section.

If a build or incremental update fails Project Archives will show an error dialog:

Click the Details button to view detailed information about the cause of the error.

In the Package Explorer you can view the created archive.

If you use the exploded type of archiving, instead of a single file archive the result put into a folder is displayed in the Package Explorer.

Refer to the Ant manual to find more on how to build your applications using Ant.

We also recommend that you watch this movie which demonstrates the powerful archiving functionality in JBoss Tools™.

This chapter has covered the functionality provided by the JBoss AS perspective. The next chapter will explore working with different kinds of projects.

The most popular of the projects we deal with are the J2EE ones, such as Dynamic Web Project, EJB Project, or EAR project. JBoss Tools™ web projects include Struts, JSF and Seam projects. These are referred to as faceted projects. This chapter will cover facets, which are used to provide a consistent structure and packaging features to any type of project.

This section will cover the facets added by JBoss Tools and show how you can configure them in a project by adding new ones or modifying existing facet configurations.

One way to configure the facets is doing it while organizing a new project. To demonstrate this create a new Dynamic Web Project by clicking on the Dynamic Web Project option in the Create Projects section of JBoss Central.

Click the Next button and you will see a Dynamic Web Project page like on the figure below.

The first page of most WTP projects allows you to target a specific runtime, which represents a server's library location. It will also provide you the ability to add this project to an EAR project and select a preselected default set of facets, called a configuration, rather than manually select each required facet.

Selecting the runtime allows the project to install the proper classpaths to the project so it knows what code to compile against.

Click the Modify button next to the Configuration section to open a wizard which allows you to modify the chosen configuration. The wizard is shown in the image below.

Here part of the listed facets are those which are provided by WTP. Some of them are added by JBoss Tools. They are:

  • BIRT Charting Runtime Component

  • BIRT Reporting Runtime Component

  • CDI (Contexts and Dependency Injection)

  • CXF 2.x Web Services

  • JAX-RS (REST Web Services)

  • JAXB

  • JBoss Portlets

  • JBoss Web Services Core

  • JPA

  • Seam 2

On this wizard page you can enable or disable any facet as well as change its version. What you should note here is that some facets or facets versions may conflict with each other. In case of incompatibility you will be notified in the combobox underneath.

When switching on the Runtimes tab on the right you will see the current server Runtime.

On this tab you can also create a new Server Runtime and make it primary by enabling it and then clicking the Make Primary button.

Clicking on the OK button will save the chosen configuration of the facets and return you to the Dynamic Web Project wizard (see Figure 4.2, “New Dynamic Web Project”). Additional pages in the wizard are specific to either the project type or the facets selected.

If you need to configure the facets for an existing project, right click on the project, select Properties and then select Project Facets. This will bring up the Project Facets wizard (see Figure 4.3, “Project Facets Wizard”), where you can create your own custom facets configuration.

In this chapter it will be described how to deploy modules onto the server.

There are several ways to deploy to a server, provided by the Web Tools Platform (WTP) and some additional methods provided by JBoss Tools. These methods are described further in this chapter.

This chapter provides an overview on how to enable TPTP Profiling for JBoss AS™ adapters in JBoss Tools™.

To get TPTP profiling work on JBoss Application Server™ you should do the following:

  • Download TPTP Runtime and install it, i. e. just add the content of plugins/features folders from downloaded directory to the same folders in your eclipse installation directory or use the HelpInstall New Software command.

  • Install JBoss TPTP Tools which provide TPTP support for JBoss AS servers (find the latest stable version of the JBoss TPTP profile feature at http://www.jboss.org/tools/download/stable).

And now all profile actions should work for you. To start JBoss AS™ in profiling mode use Start the server in profiling mode button or select Profile AsProfile on Server from the context menu of the project.

To enable TPTP features in your workbench use Profiling and Logging Perspective that you can find in the list of proposed perspectives: WindowOpen PerspectiveOther...