How To:

Debug an OpenShift Online Java App

OpenShift Tools enables you to debug your deployed OpenShift applications within the IDE, enabling you to take advantage of the IDE debugging tools. This article specifically details the steps needed to set up an OpenShift Online Java application for debugging. A number of configuration tasks are required both locally and remotely to enable the IDE debugger to connect to the OpenShift server and OpenShift Tools for achieving this. Some tasks only need to be completed once for each OpenShift Online application but others must be completed every time you reconnect to OpenShift Online from the IDE.

Instructions are provided for the following tasks:

Configure the OpenShift Application for Debugging
Enable Port Forwarding for the Local and Remote Debug Ports
Configure and Connect the IDE Debugger

This article guides you through each of these configuration requirements and must be completed in the given order.

Your application must be deployed on OpenShift before attempting to configure the OpenShift application for debugging and enabling port forwarding.

1. Configure the OpenShift Application for Debugging

You must first configure your OpenShift application for debugging, which requires setting the Enable JPDA (Java Platform Debugger Architecture) marker in your application source code and republishing the application. Marker information is retained with the application so you only need to complete this task once for each OpenShift Online application:

To configure the OpenShift application for debugging, complete the following steps:

In the Project Explorer view, right-click {project name} and click OpenShift Configure Markers.
In the Configure OpenShift Markers window, select the Enable JPDA check box and click OK.

Figure 1. OpenShift Enable JPDA Marker Selected
In the Servers view, right-click {application name} at OpenShift and click Publish.
In the Publish Changes window, in the Commit message field type a message for the commit.
From the Files list, ensure the .openshift/markers/enable_jpda check box is selected and click Commit and Publish.

The project changes are pushed to the remote Git repository and the application is automatically updated on the OpenShift server.

When debugging is enabled on the OpenShift application a debug port is assigned; for default Java applications the debug port is 8787. To perform the remaining tasks, it is important to know which port is the debug port. To identify the debug port for other applications, see the cartridge documentation.

2. Enable Port Forwarding for the Local and Remote Debug Ports

After the OpenShift application is configured for debugging, you must enable port forwarding for the local (IDE) and remote (OpenShift server) debug ports. You can achieve this with the OpenShift Tools Application port forwarding wizard, which connects all local ports to their remote counterpart ports, including the local and remote debug ports.

Port forwarding is automatically stopped when your OpenShift Online connection closes; this includes closing the IDE or changing workspaces. You must enable port forwarding every time you reconnect to OpenShift Online from the IDE.

To enable port forwarding, complete the following steps:

In the OpenShift Explorer view, right-click {application name} and click Port Forwarding.
In the Application port forwarding window, click Start All. Ensure the Status value shows Started for the debug ports and click OK to close the Application port forwarding window.

Figure 2. Port Forwarding Started for All Ports

3. Configure and Connect the IDE Debugger

With port forwarding configured for the debug ports, you must create a debug configuration for the OpenShift server and connect the IDE debugger. You can then review debug output in the Debug and Console views. The debug configuration is retained with the workspace so you only need to create a new debug configuration once for each OpenShift Online application. But you must restart each debug configuration every time you reconnect to OpenShift Online from the IDE.

To configure and connect the IDE Debugger, complete the following steps:

In the global toolbar of the JBoss perspective, click the drop-down list for the Debug icon and select Debug Configurations.
From the debug configurations list, select Remote Java Application and click the New launch configuration icon
In the Connect tab, complete the following fields:
- In the Project field, type the name of the workspace project associated with the OpenShift application or click Browse to locate the project.
- In the Port field, type the value of the debug port.
- Click Apply and then click Debug.
  
  Figure 3. Debug Configuration Ready for Your OpenShift Application

Connecting to the OpenShift server may take some time to complete and you can monitor the progress in the Progress bar or Progress view.

Did You Know?

Setting the Enable JPDA marker adds an .openshift/markers/enable_jpda file to your project. To locate the hidden .openshift directory and access the file, open the Navigator view.
You can also access the Port Forwarding wizard by right-clicking {application name} at OpenShift in the Servers view, and clicking OpenShift Port forwarding.
The Debug perspective automatically arranges useful views for debugging. To open the Debug perspective, click Window Open Perspective Debug.
You can set the debugger to look up source code for classes it encounters that are not contained in your project, for example classes used by application servers defined in the IDE. When inputing values for the launch configuration, in the Source tab click Add. From the list of source containers, select JBoss Maven Source Container and click OK. The JBoss Maven Source Container uses indexes available from Maven repositories to locate the source code. From the list, select a runtime server, the libraries of which will be indexed in the JBoss Maven Source Container, and click OK.