In this chapter we will discuss how to install and configure JBoss runtimes and servers.
Runtimes in JBoss Tools provide key functionality for creating, running, and debugging J2EE applications. They provide classpath entries for projects, and are instrumental in starting, stopping, and publishing to the various server adapters. In their simplest form, though, a Runtime is nothing more than a representation of key information about a server configuration which can be used to provide classpath entries or other information important for the server lifecycles.
For AS7 / EAP6 related servers, the runtime consists of a server home, a JRE compatible with the server, and the configuration file used to describe the specific details about the server. For earlier versions of JBoss Application Server, the Runtime consists of the server home and JRE, as well as a configuration folder, and a configuration name.
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, as mentioned above:
Providing classpath additions to WTP projects that require them.
Acting as the backing data for a JBoss Server, which we'll look at later.
You can install runtimes into Eclipse by selecting → menu and then selecting → 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 button and choose the appropriate 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).
Note:
JBoss Tools provides server adapters for all versions of the JBoss Application Server and JBoss Enterprise Application Platform. We currently 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 simple deploy directory for users who do not wish to make use of starting, stopping, or debugging their projects inside Eclipse.
The following tables describe all the available options for JBoss runtimes.
Table 2.1. Runtime Options for AS 3.2 to AS 6.0, EAP 4.3 to EAP 5.2
Name | Description |
|---|---|
Name | The name of a new Runtime for a chosen server. We suggest that you do not leave the default value for this field. It is better to give descriptive names that will help to distinguish one runtime from another. |
Home directory | The path to a directory where the runtime is installed. |
JRE | A compatible Java Runtime Environment which can be used for launching or classpath resolution. |
Directory | The path to a directory where the configurations are installed. |
Configuration | The list of configurations (all, default, minimal), which is updated as soon as you browse to a valid runtime installation folder. |
Table 2.2. Runtime Options for JBoss AS 7.x / EAP 6.x
Name | Description |
|---|---|
Name | The name of a new Runtime for a chosen server. |
Home directory | The path to a directory where the runtime is installed. |
JRE | A compatible Java Runtime Environment. |
Configuration File | A path to the configuration file you are targeting. This path must be relative to the standalone folder. |
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. With this in mind, 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 button to see your new runtime in the list.
Note:
For the most part, changes to runtimes will be persisted, and all dependent servers will be updated according to those changes. However, you should be aware that if multiple servers depend on the same runtime, modifications to that runtime will change several servers, not just one.
As a word of warning, renaming your runtime will cause all servers targeting that runtime to lose their reference. This may manifest itself by the server being unable to start, or publish. The most visible way to verify that your server is in a consistent state is to double left-click on the server to open the Server Editor, and look in the → If the combo has no selected item, your server is in an inconsistant state. To fix this, simply select the newly renamed runtime from the combo box, and save the editor.
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 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 → → → .
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 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 button.
Note
If you are using a full JBoss Developer Studio installation, runtime detection now recognizes the ESB runtime distributed as part of the JBoss Service-Oriented Architecture Platform runtimes during a scan. If you are using the a-la-carte installation options provided by JBoss Tools, you may or may not benefit from this enhancement depending on what plugins you have installed.
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. This is convenient in that it allows you to quickly create a new workspace with your runtime settings much easier to replicate. If you wish for a path to be searched on each and every 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 button.
Important
No official support is available for community application servers (this includes enterprise customers using JBoss Developer Studio).
Clicking on the 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 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 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.
While installing a new runtime you can create a clone configuration from an existing one. To do this you should perform all the steps in Section 2.1.1, “Installing a new runtime”, but do not click the button in the New Server Runtime Environment dialog.
Make sure that you browse to a valid runtime folder and can see the list of configurations (all, default, minimal) in the Configuration section. Then choose an appropriate Configuration from the list and click the button. You will then see the following dialog.
First, give the new clone configuration a name. Then, click the button and select the new location for your configuration to live, or leave as it is if you want it to be located together with other runtime configurations.
Click the button and you should see the next wizard with the newly copied configuration.
Click the button and you will see your new runtime in the list.
You can also change the configuration of existing runtime to a copied one in the same way by selecting → → → and clicking the button.
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 also keep track of the modules (JARs, WARs, etc) you deploy to the server, and allow you to undeploy those modules (see Section 6.1.1, “Deploying with Run On Server Wizard”).
Servers can be started or stopped via the Servers view in your workbench. They are usually backed by a runtime object representing that server's configuration details.
There are many ways to get to the new server wizard. One way is to select → → → . This should show the wizard like below.
A server object keeps track of the command line arguments for starting or stopping a server process. The runtime keeps track of the location of the installation and is used to help generate these command line arguments.
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 one of the already-created runtimes 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 EAP 6.0 Runtime”). To make changes to an existing runtime, go to server preferences by pressing the Configure runtime environments... link. Be aware that any changes you make here may change other servers dependent on that runtime. We reccommend creating new runtimes for each different scenario.
If the server you want to create does not have any installed runtime yet, the combobox and the links are absent.
If there is no runtime when creating your server, the next page of the wizard will be identical to the runtime page mentioned in the previous section. This page guides you through creating a runtime for your server.
After either targeting your server to an existing runtime, or creating a new runtime, the final page of the wizard presents a summary of the selected options, giving you a chance to verify that you have selected the appropriate runtime.
You will also see several other options here. The first option reads Server is externally managed. Assume server is started. This option indicates that starting the server should actually take no action, launch no java command, and assume that the user is managing the server lifecycle on his own.
The second option reads Listen on all interfaces to allow remote connections. This option is most often required when using the tools to control a remote server. Effectively, this adds the -b 0.0.0.0 flags to the server's launch command, which allows your server to respond to requests on all hostnames.
The third option reads Expose your management port as the server's hostname. This option helps ensure that attempts to connect to your server over the management port actually succeed. If your server adapter does not have this option selected, requests to run management commands may be rejected. This should not be a problem for any server adapters representing a local server instance. Locally, JBoss passes around a filesystem token for management authorizations. However, if your server adapter is representing a remote server, failure to expose the management ports may lead to an inability to communicate with the remote instance.
Not all of these options will show for all servers. JBoss 7.0.0 and 7.0.1 for example do not support the -b binding flag, while versions < 7.0 do not have the same remote management options. Be aware that this list changes based on the context of what server types you are creating.
Click the 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.
Important
It is not recommended to run two servers on the same host, at the same time as you may experience a conflict in ports. If a server is already running on the same host a warning will appear indicating this and will ask if you wish to Set the server adapter to 'started', but do not launch or Launch a new instance anyway
You may also create a server adapter to control a remote server instance. These types of server adapters are slightly different to set up, but generally follow the same process. the primary difference here is that on the last page of the New Server Wizard, you will also need to select Remote System Deployment option in the combo box at the bottom of the page as shown below..
Once you've chosen the Remote Server Deployment behavior type, your next step is to choose a remote host. If you do not have a remote host defined, you'll want to click New Host..., which will walk you through the process of setting up a remote host. After that, you must fill in the remote details for your server configuration. This includes filling in your remote server's home directory and the appropriate configuration details depending on your chosen server version. As with local runtimes, earlier versions of JBoss require a configuration folder and a configuration name, while recent versions require only a configuration file.