How to build a JBOSS 3.2.5 Server Definition for Eclipse Web Tools Platform

Summary

The Web Tools Platform (WTP) comes with a number of Server Defintions representing J2EE application servers. The server defintion for JBoss is only for version 3.2.3 which is not supported by Adobe as a platform for LiveCycle products. LiveCycle is certified and supported on JBoss version 3.2.5. This document describes how to create a new server definition for JBoss 3.2.5 which WTP can use as an application server.

Information

The Server Defintion files for WTP are stored in the plugins folder.
For WTP 0.7.0 they are found here :org.eclipse.jst.server.generic.serverdefinitions_0.7.0
For WTP 1.0.0 they are here: org.eclipse.jst.server.generic.serverdefinitions_1.0.0.v20060131b

This sub-folder contains all server definitions and associated files to allow WTP/Eclipse to include a specific Java application server during J2EE development.

Creating a new server definition for JBoss 3.2.5 will require the following new files:

• servers/jboss325.serverdef
• buildfiles/jboss325.xml

Additional, the following files must be modified

• plugin.properties
• plugin.xml

Make sure your Eclipse Environment is closed before changing the server definitions!

Download Sample Source Definition:

WTP 0.7.0 --> jboss325_serverDef.zip
WTP 1.0.0 --> jboss325_WTP1.0ServerDefinitions.zip

UPDATED - WTP1.5 --> http://www.markszulc.com/blog/articles/using-eclipse-32-web-tools-platform-wtp-15-jboss-325/

Open SUSE Linux version available thanks to Daniel Bornkessel

Instructions (Current for WTP 0.7.0, some changes required for WTP 1.0. See Sample Source above)

1. Modify "plugin.properties"

The plugin.properties file provides a location to store static string values for labels, etc. Add the following lines after the jboss323 section:

    # ============ jboss325 ====================
    jboss325runtimeTypeName=Generic JBoss 3.2.5
    jboss325runtimeTypeDescription= Generic JBoss 3.2.5 runtime

    jboss325serverTypeName=Generic JBoss 3.2.5
    jboss325serverTypeDescription=Generic JBoss 3.2.5 server

In the same file, add two new properties in the serverdef translations section with the following

    jboss325serverConfig=Server Co&nfiguration (minimal/default/all)
    javaHome=Java Home:

2. Modify "plugin.xml"

The plugin.xml file provides the link between the actual server definition (stored in the servers folder) and Eclipse/WTP. There are a number of sections which need to be extended in order to have Eclipse/WTP recognise the new server definition.

runtimeTypes
Under the first <extension> node, you will see a list of runtimeType nodes. Each node represents the runtime properties of each server. You will need to add the following runtimeType for JBoss 3.2.5

    <runtimeType
       id="org.eclipse.jst.server.generic.runtime.jboss325"
       name="%jboss325runtimeTypeName"
       description="%jboss325runtimeTypeDescription"
       vendor="%genericCategory"
       version="0"
       class="org.eclipse.jst.server.generic.core.internal.GenericServerRuntime"
       >
        <moduleType
            types="j2ee.web"
            versions="1.2, 1.3"/>
        <moduleType
            types="j2ee.ejb"
            versions="1.2, 1.3"/>
        <moduleType
            types="j2ee.ear"
            versions="1.2, 1.3"/>
    </runtimeType>

serverTypes
Under the second <extension> node, you find the server properties. Add the following <serverType> to the list

     <serverType
         runtime="true"
         class="org.eclipse.jst.server.generic.core.internal.GenericServer"
         id="org.eclipse.jst.server.generic.jboss325"
         initialState="stopped"
         supportsRemoteHosts="false"
         runtimeTypeId="org.eclipse.jst.server.generic.runtime.jboss325"
         description="%jboss325serverTypeDescription"
         launchConfigId="org.eclipse.jst.server.generic.core.launchConfigurationType"
         behaviourClass="org.eclipse.jst.server.generic.core.internal.GenericServerBehaviour"
         name="%jboss325serverTypeName"
         startTimeout="50000"
    stopTimeout="15000"
         hasConfiguration="false"
         launchModes="run,debug">
     </serverType>

wizardFragments
Under the third <extension> node, you find the wizard fragment properties representing the wizards for Runtime and Server Types. The new Server definition will make use of the default generic wizards which come with Eclipse/WTP. Add the following 2 <fragment> nodes to the this list of UI components

     <fragment
         id="org.eclipse.jst.server.generic.runtime"
         typeIds="org.eclipse.jst.server.generic.runtime.jboss325"
         class="org.eclipse.jst.server.generic.ui.internal.GenericServerRuntimeWizardFragment"/>           

     <fragment
         id="org.eclipse.jst.server.generic.server"
         typeIds="org.eclipse.jst.server.generic.jboss325"
         class="org.eclipse.jst.server.generic.ui.internal.GenericServerWizardFragment"/>   

serverImages
Under the fourth <extension> node, you find the icon images which the Eclipse/WTP UI will make use of. You can add new icons to represent the servers within the Eclipse UI here. For now, we will make use of the existing JBoss 3.2.3 icons. However, you still need to make a new entry to map the icons to the server definition using the following

     <image
         id="org.eclipse.jst.server.generic.image"
         icon="icons/obj16/jboss.gif"
         typeIds="org.eclipse.jst.server.generic.runtime.jboss325"/>

     <image
         id="org.eclipse.jst.server.generic.image"
         icon="icons/obj16/jboss.gif"
         typeIds="org.eclipse.jst.server.generic.jboss325"/>

serverDefinition
Under the last <extension> node, you find the link to the server definition file which the Eclipse/WTP UI will use to define the properties of the application server itself (i.e. How to start, stop, include libraries, etc.) It is important that you link the serverDef file in the servers folder to the servers types defined in the previous steps. The id is used to create the mapping between this file and the rest of the properties in this xml file. Add the following server definition to the end of this list

     <serverdefinition id="org.eclipse.jst.server.generic.runtime.jboss325"
          definitionfile="/servers/jboss325.serverdef">
     </serverdefinition>

3. Add "jboss325.serverdef" to servers sub-folder

The serverDef file contains the server runtime environment definition for the specific application server. It contains information on how to start the application server alongside any startup parameters to the java virtual machine. Also, determines the libraries to use during the startup bootstrap of the application server.
The serverDef file for JBoss 3.2.5 should contain the following XML:

<?xml version="1.0" encoding="UTF-8"?>
    <tns:ServerRuntime
   xmlns:tns="http://eclipse.org/jst/server/generic/ServerTypeDefinition"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://eclipse.org/jst/server/generic/ServerTypeDefinition/
        ServerTypeDefinitionSchema.xsd"
   name="JBOSS 3.2.5" version="v3.2.5">

   <property id="serverRootDirectory"
       label="%ApplicationServerDirectory"
       type="directory"
       context="runtime"
       default="/your_server_root/appservers/jboss-3.2.5" />

   <property id="serverAddress"
      label="%serverAddress"
      type="string"
      context="server"
      default="127.0.0.1" />

   <property id="port"
      label="%serverPort"
      type="string"
      context="server"
      default="8080" />

   <property id="serverConfig"
      label="%jboss325serverConfig"
      type="string"
      context="server"
      default="all" />

   <property id="classPath"
      label="%serverclassPath"
      type="directory"
      context="runtime"
      default="/your_server_root/appservers/jboss-3.2.5" />

   <property id="javaHome"
      label="%javaHome"
      type="directory"
      context="runtime"
      default="/jdk1.5" />

   <port>
       <no>${port}</no>
       <name>Http</name>
       <protocol>http</protocol>
   </port>

   <module>
       <type>j2ee.web</type>
       <publishDir>${serverRootDirectory}/server/${serverConfig}/deploy</publishDir>
       <publisherReference>org.eclipse.jst.server.generic.antpublisher</publisherReference>
   </module>
   <module>
       <type>j2ee.ejb</type>
       <publishDir>${serverRootDirectory}/server/${serverConfig}/deploy</publishDir>
       <publisherReference>org.eclipse.jst.server.generic.antpublisher</publisherReference>
   </module>
   <module>
       <type>j2ee.ear</type>
       <publishDir>${serverRootDirectory}/server/${serverConfig}/deploy</publishDir>
       <publisherReference>org.eclipse.jst.server.generic.antpublisher</publisherReference>
   </module>

   <project>
       <classpathReference>jboss.project</classpathReference>
   </project>
   
   <start>
       <mainClass>org.jboss.Main</mainClass>
       <workingDirectory>${serverRootDirectory}/bin</workingDirectory>
       <programArguments>-c ${serverConfig}</programArguments>
       <vmParameters>-Xms128m -Xmx512m -Dfile.encoding=UTF8 
                -Djava.endorsed.dirs=${serverRootDirectory}/server/${serverConfig}/lib/endorsed
            </vmParameters>
       <classpathReference>jboss.start</classpathReference>
   </start>

   <stop>
       <mainClass>org.jboss.Shutdown</mainClass>
       <workingDirectory>${serverRootDirectory}/bin</workingDirectory>
       <programArguments>-S</programArguments>
       <vmParameters></vmParameters>
       <classpathReference>jboss.stop</classpathReference>
   </stop>

   <publisher id="org.eclipse.jst.server.generic.antpublisher">
       <publisherdata>
      <dataname>build.file</dataname>
      <datavalue>/buildfiles/jboss325.xml</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.publish.j2ee.web</dataname>
      <datavalue>deploy.j2ee.web</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.publish.j2ee.ejb</dataname>
      <datavalue>deploy.j2ee.ejb</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.unpublish.j2ee.web</dataname>
      <datavalue>undeploy.j2ee.web</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.unpublish.j2ee.ejb</dataname>
      <datavalue>undeploy.j2ee.ejb</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.publish.j2ee.ear</dataname>
      <datavalue>deploy.j2ee.ear</datavalue>
       </publisherdata>
       <publisherdata>
      <dataname>target.unpublish.j2ee.ear</dataname>
      <datavalue>undeploy.j2ee.ear</datavalue>
       </publisherdata>            
   </publisher>

   <classpath id="jboss.start" >
       <archive path="${javaHome}/lib/tools.jar"/>
            <archive path="${javaHome}/jre/lib"/>
            <archive path="${classPath}/server/${serverConfig}/conf"/>
            <archive path="${classPath}/bin/run.jar" />
       <archive path="${classPath}/server/${serverConfig}/lib/log4j.jar"/>
   </classpath>

   <classpath id="jboss.stop" >
        <archive path="${classPath}/bin/shutdown.jar" />
        </classpath>

   <classpath id="jboss.project" >
       <archive path="${classPath}/client/jboss-j2ee.jar" />
       <archive path="${classPath}/server/${serverConfig}/deploy/
             jbossweb-tomcat50.sar/servlet-api.jar" />
       <archive path="${classPath}/server/default/lib/activation.jar" />
       <archive path="${classPath}/server/default/lib/mail.jar" />
   </classpath>

   <jndiConnection>
       <providerUrl>jnp://${serverAddress}:1099</providerUrl>
       <initialContextFactory>org.jnp.interfaces.NamingContextFactory</initialContextFactory>
       <jndiProperty>
      <name></name>
      <value></value>
       </jndiProperty>
   </jndiConnection>
    </tns:ServerRuntime>

4. Add "jboss325.xml" to buildfiles sub-folder

This file represents the build file which Eclipse will use to build and deploy your J2EE application to your application server.

The best way to create this file is to use the jboss323.xml as a template. Make a copy of jboss323.xml and rename it to jboss325.xml. No further modifications are required to the contents of this file as the structure and deployment is the same as version 3.2.3 of JBoss.

5. Execute clean Eclipse

If you have executed Eclipse previously, Eclipse will have cached the existing server definition files. Executing Eclipse normally after changing any of the files mentions in steps 1 through 4, will not have any effect. You must run Eclipse in clean mode by using the following on the command line:

    C:\eclipse> eclipse -clean

6. Verify Server Runtime

Once you have run eclipse using the clean parameter, eclipse should reload the plugins.xml and refresh the server definitions. To check that the server definition for JBoss 3.2.5 was successful, go to Window | Preferences and in the Server | Installed Runtimes, click "Add". Examine the Generic Example category and you should see a new entry called Generic JBoss 3.2.5

If you are not able to see this new server runtime, then you need to make sure you have everything correct in Steps 1 through 4. Any mistake in the descriptors will cause Eclipse to ignore the Server Definition. An example set of files have been attached and you can download this here!

Special thanks to Adobe's David O'Hanlon for the information above.