In this chapter we will discuss how to install runtimes and servers
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 must start with creating 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 than be used for two primary purposes:
it provides classpath additions to WTP projects that require them.
For JBoss server at least, it provides information necessary for the starting and stopping of the server, it tells which jars to run and which configuration to use.
You can install runtimes into eclipse from the Window > Preferences... menu, and then select Server > Installed Runtimes from the categories available.
From this preference page you can see what runtimes are declared, and what type they are. In the image shown above, there are two declared runtimes, including a JBoss 4.2 instance.
To create a JBoss runtime, we begin by clicking the Add button. This will open another dialog that allows us to choose what type of runtime we want to create. Most of the runtime options are provided by WTP, but those provided by JBoss Tools are the ones we will focus on.
As seen above, there appear to be two JBoss categories. The first is contributed by WTP, and is a generic adapter that is not upkept very well. For this reason, JBoss Tools provides updated and supported adapters of our own. There is one for each of JBoss 3.2, 4.0, and 4.2. You'll also note a deploy-only runtime type. This type provides no 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 don't wish to make use of starting, stopping, or debugging their projects inside eclipse.
As shown above, all you need to do to create the runtime is to name it, browse to it's install directory, select a Java Runtime Environment, and select which configuration you want. As you browse to a valid installation folder, the list of configurations will update allowing you to select the configuration of your choice.
Once the runtime is created, the configuration is an unchanging property of that runtime. This is because many of the jars necessary to provide for classpaths, such as the ejb3 jar locations or the servlet jar locations, are located in deploy directories of each configurations (depending on which version of JBoss is being used). Because of this, to compile against a different configuration's jars, you will need to create a new runtime from that configuration.
Also, because of the open-source nature of JBoss, it is likely that a user may want to modify and repackage some of the configuration-specific jboss jars and create their own configuration using those modified jars. Rather than forcing the user to copy his entire JBoss installation, this structure allows them to create only a new configuration instead.
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. It will do no good to try to remember if "JBoss-runtime 5" is the 4.0 install with ejb3? Or the 4.2 install's custom configuration you decided to create.
After pressing finish, you'll see that your new runtime has been added to the list and can now be targeted by WTP type projects or servers, both of which we'll get to later.
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 what modules (jars, wars, etc) you deploy to the server and also allow you to undeploy those modules.
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... wizard, and type in Server. This should show the screen below, which does not look that different from the initial screen when creating a new runtime.
Because the server object is what keeps track of things like command line arguments when starting or stopping, and runtimes keep track of the location of the installation, each server instance must be backed by an appropriate runtime.
Because there may be many runtimes of each type declared, the wizard allows you to select which runtime you want your server to be backed by. The combo box below the view lets you select which declared runtime to use. For example, if there were already multiple JBoss 4.2 runtimes declared, the combo box would list all of the 4.2 runtimes available.
If none of the runtimes declared are one you want to use, for example if you declared a default and a minimal runtime before but now want your server to be backed by the ALL configuration, then you can click on the Installed Runtimes... button to bring up the preference page shown at the beginning of this chapter.
If the server you want to create doesn't have any installed runtime yet, the combo box and button will disappear, and the next page in the wizard will force you to create the associated runtime first.
Either way, after targeting your server to a runtime, the final screen in this wizard is largely confirmational, giving the user a chance to verify that he's selected the appropriate runtime. It also allows the user to name the server appropriately.