JBoss.orgCommunity Documentation

JBoss Server Manager Reference Guide

Svetlana Mukhina

Version: 2.0.0.GA

April 2008


1. Quick Start with JBoss Server
1.1. Starting JBoss Server
1.2. Stopping JBoss Server
1.3. Project Archiving
1.4. Deploying an Application to a Server
1.5. Other relevant resources on the topic
2. Runtimes and Servers in the JBoss AS plugin
2.1. Runtimes
2.1.1. Installing a New Runtime
2.2. Servers
2.2.1. Creating a New Server
3. JBoss AS Perspective
3.1. The JBoss Server View
3.1.1. JBoss Server View Toolbar
3.1.2. JBoss Server View Structure
3.1.3. Drag-n-Drop to JBoss Server 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.1.2. Deploying single files
5.2. Deploying with JBoss Server View
5.2.1. Top part of JBoss Server View
5.2.2. Bottom part of JBoss Server 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. If you already have installed JBoss server and runtime you can quickly learn how to configure, start, stop the server, to know deployment and archiving processes. How to install runtimes and servers read in the Runtimes and Servers in the JBoss AS plugin chapter.

To start working with JBoss AS, select a JBoss AS Perspective via Window > Open Perspective > Other > JBoss AS.

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

First of all it's 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, and it can then be used for two primary purposes:

You can install runtimes into eclipse from the Window > Preferences menu, and then select Server > Runtime Environments from the categories available on the left.


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

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


Note:

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 with its own new feature, that is a safer incremental deployment, 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.

Note:

Currently we recommend you to use a fully supported JBoss 4.2 server adapter.

You'll also note a Deploy-Only Runtime type. This type provides no classpath for WTP projects. It is used solely by its server type for the purpose of setting up a deploy directory for users who don't wish to make use of starting, stopping, or debugging their projects inside eclipse.


The following table describes all the available options of the currant 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'll create several different runtimes to test each of your configurations. It becomes important to ensure your runtimes, and later your servers, are given descriptive names that help you remember which is which.

Press Finish to see your new runtime in the list.

WTP servers are eclipse-representations of a backing 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 Deploying with Run On Server Wizard section).

Servers can be started or stopped with different command-line arguments. 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 use the old standard File > New > Other... and then Server . This should show the wizard like below.


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

From the list of already declared runtimes in the combo box below the view it's possible to select which runtime you want your server to be backed by. If there is no runtime that matches your needs just press the Add... link nearby to bring up the wizard for creating a new runtime (see the previous section). To configure the already installed runtimes you should go to server preferences that you can easily do by pressing the Configure runtime environments... link.

If the server you want to create doesn't have any installed runtime yet, the combo box and the links are absent.


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

Either way, after targeting your server to a runtime, the final screen in this wizard is largely confirmational, giving you a chance to verify that you've selected the appropriate runtime. It also allows to name the server appropriately.


Press Finish to complete the process of the server creation.

Now that we've created our runtimes and servers, we can dwell on all services and tools that JBoss Server Manager provides.

We hope, this guide helped you to get started with the JBoss Tools server manager. Besides, for additional information you are welcome on JBoss forum.

This chapter tells how to manage installed JBoss Server via JBoss AS perspective.

The JBoss AS perspective is similar to the Java perspective, but it contains a few additional views. Two of the additional views are standard views, specifically the Console view and the Properties view. The other two views that are added are the Project archives view and the JBoss Server View.

The JBoss Server View is built on Common Navigator Framework allowing extensions and is using label decorators what makes the UI enough compact without loosing the vital information.

Let's have a look at the JBoss Server View and inspect in detail all parts it consists of.


The JBoss Server View displays all declared servers as well as their current states (that is whether they are started or stopped) and statuses in the square brackets next to a server name.


The following table lists possible server statuses.


You can control a server behavior as well as adjust some server preferences with the help of the context menu commands.


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


Under the server element in the JBoss Server View, you can see currently deployed to the server modules and some server extensions which provide the additional information on the server.

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


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 is filled with many of the most commonly used ports in the JBoss Server.


By right-clicking on XML Configuration, 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 JBoss Server View. Look for them in the Inactive Categories afterwards to re-enable.


By right-clicking on Ports 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 like on the next figure.


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

Tip:

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

Then, on the other hand, 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 Preview to see how many matches you have for that particular XPath.


By double-clicking on any server, an editor window will appear allowing you to edit parts of that server.


Tip:

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

It should be pointed out that our server adapter by default tries to automatically detect the ports it needs for integrating with a JBoss Server. Sometimes it can though be relevant to override this automatic detection if you are using some custom configuration. For this purposes the Server Ports section in the Server editor is provided where the port settings are configurable. Click the Configure... link to bring up the wizard for adjusting the settings for the ports.


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


The settings related to Publishing , Timeouts or Server Polling can be also adjusted in the Server editor.

Server editor makes it also possible to modify the server's launch configuration. It's just after clicking Open launch configuration link. In the open window there are the tabs for setting command line arguments, classpaths and other things that are relevant to launching the server.


Look up here to find parameters which can be specified for JBoss Server.

Note:

Please note, that the Launch Configurations for JBoss Servers are enough strict in enforcing the configured values in the server 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 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.

Until 3.0.0.GA release of JBoss Tools, the servers classpath was readonly, 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, Restore Default Entries should add it properly. Also, Restore Default Entries will also remove any extra entries you added yourself.

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 come with our own Archives tool with a bit easier and less-verbose XML and a handy user interface. The Project Archives plugin consists primarily of a view, that is Project Archives view, to set up each packaging configuration.

So far, 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 what 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.


Note:

If you see only JAR from the list of available archive types, you should verify whether AS Tools plugins/features are in place. EAR, EJB JAR and WAR options are contributed by the AS Tools independently from webtools and the virtual project model. Thus, without them only JAR 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 asks 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 some other archive, or inside a folder declared inside an archive. Select the necessary checkbox (either workspace or file system ) for marking the destination as related to either workspace or file system. 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 press the Workspace button. At the bottom of the list, you'll see 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 chechbox in the Archive type section.

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


Click in Details to see detailed information about what caused the error.

In the Package Explorer you can observe 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 Ant manual to find more on how to build your applications with help of Ant.

We also recommend you to watch the movie which demonstrates a powerful archiving functionality in JBoss Tools.

At this point, you are guessed to be familiar with JBoss AS perspective and your next step now is to explore how to work 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. Web projects of JBoss Tools are Struts, JSF and Seam projects. All of them are called faceted projects. Thus, in this chapter we are going to tell you about facets the main benefit of which to provide proper structuring and packaging for any type of project.

In this section we're going to consider the facets added by JBoss Tools and show how you can configure them in a project: add new ones or modify already existing configuration of the facets.

One way to configure the facets is doing it while organizing a new project. To demonstrate this let's create a new Dynamic Web Project by selecting File > New > Other... and then Web > Dynamic Web Project.


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

The first page of most WTP projects allows you to target a specific runtime, representing 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 facet you might want.

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


Click on the Modify button next to Configuration section in order to open the wizard which allows you to modify a chosen configuration. The wizard looks as follows.


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

  • JBoss ESB

  • JBoss Portlets

  • JBoss Web Services

  • Seam

On this wizard page you can enable or disable any facet as well as change it version. What you should note here is that some facets or facets versions may conflict with each other. In case of incompatibility you'll be prompted about this in the combo box underneath.


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


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

Clicking on OK will save the chosen configuration of the facets and return you to the Dynamic Web Project wizard. Further pages in the wizard are specific to either the project type or the facets selected.

If you need to configure the facets for the existing project, you should bring up the context menu for selected project and click Properties and then Project Facets. This will bring up the familiar 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.

First of all it is necessary to say that deploying to a server is mostly painless. There are several ways to do it provided by WTP, and some additional methods provided by JBoss Tools. These methods are described further in this chapter.

On the package explorer it is possible to publish either a project to a server or just a single file. Let's look at how to do this.

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 first download TPTP 4.5.0 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.

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 Profile As > Profile on Server option in 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: Window > Open Perspective > Other…


All additional information on TPTP(Test and Performance Tools Platform) you can find in eclipse documentation.

In summary, this reference should help you to start with JBoss AS and get to know with functionality for work with it.