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.
In the right top corner of the Servers view there is a special toolbar which provides a quick access for starting a server (in the debug mode, run mode, or profile mode), restarting a server, stopping a server and a publishing to a server.
In order to debug your applications or EJB's that are deployed to the server, the server must be started in debug mode. By starting the server in debug mode, Eclipse will allow you to set breakpoints on code in your workspace and step through the code.
The button will republish any modules where it has determined that the workspace is out of synchronization with the server. It will attempt to do an incremental publish if the module in question is capable of doing one.
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.
Table 3.1. Server Publish Status
| Status | Description |
|---|---|
|
Republish |
The status which allows you to see if changes are awaiting |
|
Publishing... |
The status which shows if changes are being updated |
|
Synchronized |
The status which allows you to see if changes are synchronized |
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.
Table 3.2. Server Properties through the Context Menu
|
Name |
Description |
|---|---|
|
New Server |
The option allows you to define a new server |
|
Open |
The option opens the Server editor |
|
Show In |
This option provides easy access to the Console, Debug, Server Log or MBean Explorer views |
|
Show In -> File Browser |
This action uses the native OS file explorer to browse the deploy destination of a local server. |
|
Delete |
Standard option that allows you to delete the chosen server |
|
Start |
This will start the server in a run mode |
|
Debug |
This will start the server in a debug mode |
|
Stop |
This will stop the server |
|
Publish |
This will synchronize the publish information between the server and workspace |
|
Add and Remove Projects |
This option will publish a new project to the server (if it's type is supported) |
|
Monitoring |
Allows you to add ports to be monitored on the current server |
|
Properties |
Opens a window that allows you to adjust the current server preferences |
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 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 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 or command.
If you want to set filesets for some server types, select → and then select → 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 button. In the opened New File Filter wizard follow the steps described in Section 3.1.2.1, “Filesets” and finally click the 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.
Note:
This document assumes that you are familiar with XPath. If not, we highly suggested that you look through an appropriate manual or tutorial on the topic.
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.
...
<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.
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 button to see how many matches are found for that particular XPath.
The Servers view supports drag-n-drop of deployable and runnable projects and resources.
With drag-n-drop the following actions can be performed:
Dragging a project to a server will deploy it to the server and run it by showing the main page in a browser.
Dragging an
.xhtmlfile from theWebContentfolder will do the same and show the corresponding page in a browser.Dragging a deployable resource (i.e. a datasource
-ds.xmlfile that has been made deployable) will simply deploy that resource directly to the server.
In short, the feature does the same thing as if you used the or option in the context menu of the server.
You can monitor the current server behavior with the help of the Server Log. To open a server in the Server Log view you should right-click on the server and follow to → .
The Server Log view shows relevant information to your server's startup, shutdown and publish processes. This allows you to keep an eye on what's going on (such as automatic incremental deployment if you have it enabled).
The Server Log view toolbar contains several icons that perform the following actions:
Table 3.3. Server Log Toolbar Icons
|
Name |
Description |
|---|---|
|
Export Log |
Allows you to export the log into a text file |
|
Clear Log Viewer |
This option clears the current server log |
|
Delete Log |
Click to delete the server log |
|
Open Log |
Click to open the server log text file |
|
Restore Log |
Click to restore the server log |
By double-clicking on any server, an window will appear allowing you to edit the servers settings.
Tip:
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 .
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 0.0.0.0. This option will change the host address to 0.0.0.0, 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.
Timeouts
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.
Note
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
Note:
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 button should add it properly. Also, the 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.
Find more about XPath in the XPath Documentation.
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.
Note:
Those who use ANT will appreciate how the Project Archives Ant task is now improved: it supports variables and gives more informative error/logging messages when something goes wrong.
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.
The packaging configuration for each project is stored in the project's root folder in a file named .packages, which has a fairly simple XML structure. Modifying the file by hand is neither required nor recommended, as the UI is the only supported way to modify your packaging structure.
A project's configuration contains archives. As you can see on the image above a project can contain more than one archive. Internal archives and filesets can be directly inside of an archive, or in a sub-folder of that archive.
In the upper right corner of the view you can see an icon which, when clicked, will build the selected top-level archive. Additionally, you can select → when a project is selected in the Packages View to build all declared packages in that project's .packages file. This will execute a full build on all declared archives.
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 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 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 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 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.
To create a folder right-click on an archive or folder you want your new folder to be a child of. The only piece of required information the folder name.
To create a new fileset, right click on an available target location such as an archive, a nested archive, or a folder within an archive and select the option.
The New Fileset wizard requires a destination (where the files will be located) and a root directory (or where the files are coming from). The source can be anywhere in the workspace or from the filesystem at large.
Below that, the fileset requires only an Includes and excludes pattern. As you type in either of these fields, the preview viewer will list those files that are matched.
You can create a Fileset with flattening or without it. Look at the difference on the figure below.
If you make use of user libraries in your projects you can also refer to these from project archives and have all the JAR and ZIP files they refer included into the archive.
To add a new user libraries file set, right-click on the necessary archive and select the option.
You can edit the existing user libraries as well using User Libraries Fileset Wizard. Right-click on the library fileset and select the option.
There are a number of variable options in the context menu, but there are also several that come standard.
Table 3.4. Context Menu on the Item
|
Name |
Description |
|---|---|
|
Build Archive (Full) |
This action is enabled only on top-level archives and initiates a full build on that archive |
|
Edit Archive |
Standard action that brings up the wizard associated with that particular node type and allows the details to be changed |
|
Delete Archive |
This option deletes the selected node |
|
Publish To Server |
This action will publish to a declared server |
|
Edit publish settings |
This option edits the archives publish settings |
Note:
When editing an archive, it is also updated in all folders and other archives where it is nested.
Finally, you will need to publish your application to a server. This section describes how to do it with the help of the Archives View.
The dialog shown above appears after selecting the Publish To Server option. To publish once, select the server(s) that you want and click the button. If you want the Publish to Server action on that particular Archive to always publish to that set of servers, then check the appropriate checkbox. To enable automatic publishing upon build events, check the last checkbox.
The automatic publishing feature is nice if, for example, your package's destination (where it is built) is a temporary folder and you want the archive published to several servers. If you only need your archive published to one server, it might be easier to have the archive's destination folder be the deploy folder of the server.
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.