Debugging Discovery Framework / Oracle Endeca Studio in Eclipse

Most, if not all, implementations of Oracle’s Endeca Discovery platform have some kind of custom portlet or supported extension that assists your users in the Discovery process.  Maybe you have a custom security manager that integrates a user’s LDAP groups at query time to restrict access to certain records.  Or maybe a custom charting portlet to include a chart type that you don’t get from the base software.

When your system goes live, you (typically) get all the source code for your customizations and you can maintain, modify and improve your component going forward.

That’s great but a custom portlet can be an extremely complex piece of code that can be difficult for even the most seasoned Java developer to pick up, dust off and improve.  At Ranzal, we find it incredibly valuable to be able to “step through” the code and understand what exactly is going on before we go off and make changes or upgrades.  So, here’s a primer on how we set up our local Eclipse instance in debug mode to enable this process:

Note: We’re assuming that you’ve followed the Endeca Developer’s Guide documentation and have set up your development environment in Eclipse before beginning.

First, fire up your Eclipse workspace and create a new Server from the Servers dialog (Window->Show View->Servers).  Select Apache -> Tomcat v6.0 Server and click “Next”, you can leave everything else as default:


If this is the first Tomcat 6.0 server you’ve created in your Eclipse workspace, you’ll need to provide some additional information.  If not, this step will be skipped.  For the Tomcat Installation Directory, browse to the tomcat-6.0.29 folder underneath your Portal Installation and make sure your installed JDK is selected and click Finish:

The Server should now be showing in your Servers window, double-click on it to finish the configuration.  Once the Overview window loads, click the “Open Launch Configuration” link underneath General Information.  Switch to the Arguments tab and add the following text to VM Arguments:

-Xmx1024m -Xms128m -XX:MaxPermSize=256m

Then Click OK.

Back in the Overview Window, under Server Locations, select “Use Tomcat Installation” from the radio button list and change the Deploy Path to webapps.  Then, on the right side of the Overview Window, expand the “Timeouts” section and increase the Start and Stop intervals.  Typically, we set the Start to be 450 seconds (Studio can take a while to start up) and the Stop to be 30 seconds.

Finally, if desired, set your ports for running this Tomcat instance.  Since I typically am running anywhere from 2-4 Studio instances on a given box (different versions, different configurations), I’ve set mine to be based in the 7000 range.

Finally, make sure your “Deploy Path:” is set to webapps.

And that’s all for configuration.  Click Save and then right-click on the Server and Select “Debug” to get started.  Once the server starts up, you should be looking for a message in the console that says:

INFO: Server startup in ### ms (where ### is how many milliseconds it took to start)

Now, you can go into your code, add some breakpoints, open your application in a web browser and “trigger” your customization.  Assuming everything’s done right, you’re ready to step through your code as it’s running!

Once your code is triggered and the breakpoint gets hit, Eclipse will open (or Confirm that you want to open) the Debug Perspective and you will see a window with a button that says “Source not Found”:


Click Edit Source Lookup Path to tell Eclipse where the source code for your portlet/security manager/state manager (whatever it is you’re debugging) resides.  It’s likely that your project is not added to the list of projects,  If so, you’ll need to click Add and then Java Project to make it eligible to step through:

Click Add…

Select Java Project and Click Ok.

Choose your project and Click OK.  Then, click OK on all of the preceding dialog boxes to dismiss them and, voila!, your code should be available to step through:

Hopefully this will come as a help, if you have any questions or comments, please leave them below!



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s