Before we can start, make sure the following preconditions are fulfilled:
-
You have already installed the latest "Oxygen" release of Eclipse IDE for Java EE (if not, get it here)
-
You have a valid IBM Bluemix account (if not, create your test account here)
-
You have installed the Cloud Foundry CLI (if not, download from here)
For being able to connect with Bluemix from within Eclipse, we need to install a corresponding plugin at first. To search for plugins in Eclipse, go to Help in the menu bar and navigate to Eclipse Marketplace. You should then see a window where you can search for available plugins. Typing "bluemix" and start searching should offer you the IBM Eclipse Tools for Bluemix for Oxygen plugin.
Click Install, accept the license terms as well as the pre-selected packages and finally restart Eclipse after a successful installation process.
Now that we have Bluemix support enabled in Eclipse, the next step is to login into your Bluemix account. From the menu bar, go to File > New > Other and search for server in the window that shows up. Select the Server entry and hit Next. That should give you another window where you can choose the type of server you want to create. Open up the IBM folder that should be present and you should see an entry labeled with IBM Bluemix. Because this is what we want, select the entry and click Next.
Now you're prompted to provide your Bluemix credentials. Besides, make sure you select the correct Bluemix region before you continue. Otherwise your login might fail. As soon as you're done, press Finish.
Given that your login has been successful, a new "IBM Bluemix" entry should appear in the Servers tab of Eclipse. You can expand the entry and see all the services you have currently deployed in Bluemix.
Next, we need a demo application that we can ship to Bluemix in order to test remote debugging. If you haven't done this yet, move over to the dev4cloud/hangman-app repository and clone it to your local machine. You can either use the Git CLI or clone the repository directly from within Eclipse. Let's assume you directly used the Git CLI to get a copy of the hangman app. As the next step, the project must be imported into Eclipse. To do so, navigate to File > Import and select Existing Projects into Workspace.
Then, hit Next and browse to the root directory of your recently cloned hangman app repo. Keep the defaults of the remaining settings and press the Finish button. The hangman app should now appear in the Eclipse project explorer. In order to check if your Eclipse project setup is correct, right-click the "IBM Bluemix" entry in the Servers tab in Eclipse and select Add and Remove... from the context menu. This will give you a window showing which applications are currently deployed to Bluemix or rather which projects in your workspace are ready to get deployed. If your hangman app is listed under the Available section, then everything is fine and you can skip the next section.
In case the freshly imported hangman app project does not appear in the list, this is due to a misconfiguration of the project preferences in Eclipse. However, this can be fixed by slightly tweaking these settings. Make sure that the app is selected and navigate to Project > Properties from the menu bar. In the popup, search for the Project Facets entry and click it. You should see that the checkbox for Dynamic Web Module is deselected, which is the reason why the project is not considered "available" by the Bluemix plugin.
Activate the checkbox and make also sure that the Java facet is also selected and its version is 1.7 (this is also marked as "required" by the Dynamic Web Module facet). Otherwise, Eclipse will start throwing weird exceptions and error messages. As soon as you're finished, the hangman app should now be recognized correctly by the Bluemix plugin.
The hangman app relies on the Ant tool for build configuration. Since Eclipse for Java EE IDE comes with Ant support by default, setting up the Ant build is fairly simple. Just click on the arrow to the right of the External Tools button and move on to External Tool Configurations. This should give you a pre-configured Ant run configuration based on the hangman project's build.xml file. This configuration was created by Eclipse, which recognized the project as an Ant project due to the build.xml file in the root directory. Selecting the Targets tab shows a list of all Ant targets defined in the build.xml file.
The build target should already be checked, which is perfectly ok for us. This target compiles the code and packages up the application within a WAR archive, which can be deployed on an application server. Click Run and watch the output of the build process in the Console tab. The following screenshot shows the output messages of a successful build.
The final step before we can start a remote debugging session is transferring the hangman application to Bluemix and launch it there. It is assumed that at this point, the configured Bluemix server has recognized your hangman Eclipse project as ready for being deployed to Bluemix (if not, go back to this section). Right-click the Bluemix server in the Eclipse Servers tab and go to Add and Remove... as you did before. The hangman app, which is now listed on the left side as available for deployment to Bluemix, can easily be transferred to Bluemix by highlighting it and clicking on Add > afterwards. You can track the deployment process by watching the console output.
The current state of your deployment is also visible in your Bluemix console. You should see that a new application appears under Cloud Foundry Apps whose state should finally go to green and "Running" once the deployment has finished and the hangman app is ready.
We're now all set to finally give remote debugging with Eclipse and Bluemix a try. First of all, we need to switch over the already deployed application into debug mode. The debug mode is disabled by default. To get it activated, right-click the hangman app in the Eclipse Servers view, and hit Enable Application debug.
You will see that the application must be restarted by Bluemix to bring it into debug mode, which might take a few seconds. Once the deployment is back in "Running" state (or the Eclipse console says that the app "appears to be running"), the debugging can eventually begin. Select a place in the hangmann app's source code you want to inspect and set a breakpoint. For example, you can set your breakpoint in the doPost method of the LoadGame class, since this method will be passed everytime a new word category has been chosen in the dropdown menu. Make sure you've defined at least one breakpoint and then navigate to the hangmann app by following the URL from the Bluemix Dashboard. As soon as the execution path passes your breakpoint, you will see Eclipse switching into the debug perspective, which allows for inspecting variables, the current call stack and so on.
