JBoss

This topic describes how to set up and use a JBoss server with the BEA Workshop Studio family of products. The topics discussed here are:

• Defining the Server inside the IDE
• Updating the Server Definition
• Running and Debugging Applications
• Deploying Applications Manually
• Using Remote Debugging

This topic assumes that you already have a server installed locally on your development machine, or on a server available for development. For information on installing, setting up and managing the server, consult the JBoss documentation.

If you are using JBoss 3.2.3, we recommend that you upgrade to a newer version. The Workshop Studio products do not support versions of JBoss prior to 3.2.8. For JBoss 3.2.3, consult the Installation Instructions for a possible workaround.

Defining the Server Inside the IDE

To define a server:

1. Before you run an application for the first time, the Run > Debug command allows you to define your server.



2. To define a new server, right click on J2EE Server and choose New.



3. On the next screen, first specify a name for the server in the Name field. This name is for internal use in the IDE only.

   

4. Next, click New to specify the server type.



Choose the server by expanding JBoss and choosing the appropriate server. Click Next to continue.

5. In the next dialog, you must specify the JBoss settings.

   

   Note that you must specify the full JDK (not just the JRE that is the default).

   Click Next to continue.

6. The next screen specifies additional JBoss settings.

   

   Fill in the appropriate values and click Finish to continue.

7. You will be returned to the Debug dialog. Click (beside the Deployed Projects box) to specify which projects will be deployed to this server.

   

8. After you click Finish, the projects will be listed in the Deployed Projects box.

   Note that the first project is automatically selected in the Select Project to Debug field. You can use the pull-down to specify which project will be debugged.

   Only one project at a time can be debugged on the server. The project that is currently allowed to run in debug mode is the project displayed in the Select Project to Debug field. You are not required to run this project in debug mode, but if you wish to debug another project on the server, you must change this setting before debugging the application.

   

9. Note the Connection Type default setting is for local servers that are managed within the IDE. Click Apply and the server definition is complete. A new server entry appears in Servers view.
10. If you wish to debug your application at this point, click Debug to run the selected application in debug mode. Otherwise, click Close.
11. You may also also update the server definition to specify deployment and runtime options.

Updating the Server Definition

To update the definition for a server:

1. Double click on the server name in the Servers view to see the Server Overview.

   

   From Server Overview you can view and set deployment and runtime properties.

   Note the Run module directly from the workspace option. This is a WTP feature that allows you to run your application in "exploded" mode where the application runs directly from your workspace. If you wish your application compiled into a WAR file and deployed, you must uncheck this option.

   Click here for information on manual deployment.

2. You can also click on the Properties tab to alter the properties that were set when the server was configured.

   

Running and Debugging Applications

Running and debugging applications is the same for all servers.

Hot Deployment

Workshop Studio supports hot deployment of JSPs and other artifacts like Struts actions.

If you update a JSP, changes are automatically published to the server and you can simply click the Refresh button to see them running live on the server. Other changes are automatically deployed and the application is restarted as necessary.

Accessing Artifacts Outside the Project

For JBoss servers, Workshop Studio integrates Workshop DevLoader (similar to Sysdeo DevLoader for Tomcat) which allows web project to use libraries/classes either from dependent projects or from external location (i.e. outside of project's WEB-INF/classes or WEB-INF/lib folder). Workshop detects the external references and resolves them by doing the following:

• Installs jboss\server\default\deploy\jbossweb-tomcatxx.sar\0-nitrox-loader.jar file
• Creates the .#jbossclasspath file within the project's\WebAppRoot containing list of all external references

In addition the user must manually enable the UseJBossWebLoader flag in the jboss- \server\default\deploy\jbossweb-tomcatxx.sar\META-INF\jboss-service.xml file ( <attribute name="UseJBossWebLoader">true</attribute> ) and restart the server.

Note that Workshop DevLoader works only in exploded mode (the Run modules directly from the workspace option on the Server Overview).

Deploying Applications Manually

To deploy an application manually requires that you create an alternate configuration. For information on how to create an alternate configuration, consult your server documentation.

To deploy the alternate configuration:

1. Double click the server name in the Servers view. The Server Overview will be displayed.

   Manual deployment is only allowed when the Run module directly from the workspace option is selected.

   You will see this screen that allows you to specify a custom configuration XML file.

   

    

Using Remote Debugging

To debug on a remote server (or on a local server which is started and managed OUTSIDE of the IDE), you must configure the server for remote debugging and then define the remote server's address.

Step 1: Configuring the Server to Allow Remote Debugging

To debug on a remote server (or on a local server which is started and managed OUTSIDE of the IDE), you must configure the server for remote debugging, deploy the application manually and then define the remote server's address.

JBoss 4.0

Workshop uses standard JPDA and self-generated line maps. The JSR-45 debug information has to be disabled by placing the following servlet in the application web.xml file:

  <servlet>
      <servlet-name>nitrox-debugger-jboss4</servlet-name>    <description>Added to compile JSPs without JSR-045 debug info</description>    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>    <init-param>        <param-name>suppressSmap</param-name>        <param-value>true</param-value>    </init-param>    <load-on-startup>3</load-on-startup></servlet>
  <servlet-mapping>    <servlet-name>nitrox-debugger-jboss4</servlet-name>    <url-pattern>*.jsp</url-pattern></servlet-mapping> 
  

JBoss 3.2.4+

Workshop uses standard JPDA and self-generated line maps. The JSR-45 debug information has to be disabled by placing the following servlet in the application web.xml file.

<servlet>
    <servlet-name>nitrox-debugger-jboss32</servlet-name>    <description>Added to compile JSPs without JSR-045 debug info</description>    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>    <init-param>        <param-name>suppressSmap</param-name>        <param-value>true</param-value>    </init-param>    <load-on-startup>3</load-on-startup></servlet>
<servlet-mapping>    <servlet-name>nitrox-debugger-jboss32</servlet-name>    <url-pattern>*.jsp</url-pattern></servlet-mapping>

All versions of JBoss

Open run.bat in the <JBoss Install Directory>\bin folder and define the following environment variable at the start of the BAT file:

    set JAVA_OPTS=-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8453,server=y,suspend=n 

Start JBoss using run.bat. The JBoss Server console should display message:

   Listening for transport dt_socket at address: 8453

Step 2: Preparing the Application for Remote Debugging

Before attempting to debug an application on a remote server, you must:

1. Build the application (not required if Build Automatically is set).
2. Deploy the application manually. You can deploy as an exploded application or use a WAR or EAR file to deploy.
3. Clear, the work/temp directory to remove files without debug information.
4. Make sure the deployed application version matches with the one in IDE.

Step 3: (Optional) Enabling JSP Servlet Source Debugging on Separate Server

When remote debugging an application on a physically separate machine, the debugger will hit JSP breakpoints but the IDE will not show the correct source line in JSP, becasue Workshop Studio is trying to locate JSP servlet source for line mapping but the files are not available to the IDE.

To enable source debugging of servlets on a separate server, map the following directory (on the remote server) to a local directory, and use the Source Lookup Path dialog, or the Source tab in the Launch Configuration dialog (the Run > Run command), to add the mapped directory to Source Lookup Path.

For JBoss 4.0.x and 3.2.x
$JBOSS_ROOT\server\default\work\jboss.web\localhost\[CONTEXT_ROOT]
e.g.:
C:\jboss-4.0.3SP1\server\default\work\jboss.web\localhost\_

Step 4: Defining the Remote Server and Debugging the Application

To define a remote server:

1. Define the server.
2. Click Run > Debug to modify the server definition for remote operation. Click on the name of your server under J2EE Server.

   Change the Connection Type to Standard (Socket Attach) and specify the Host and Port.



3. The Allow termination of remote VM checkbox is not recommended because it allows the IDE to do a hard stop of the server, even if the server is in mid-transaction.
4. Click Apply to save your changes.
5. Click Debug to run the application in debug mode.

Note that when debugging an application on a remote server, you must not disable the Run module directly from the workspace option when you update server settings.

Related Topics

Running and Debugging