Remote debugging with Eclipse can be useful in many cases, especially if the server you'd like to debug isn't running through Eclipse, either locally or remotely. The following steps will configure remote debugging for JBoss. You'll need to adjust them a bit for other servers.

Changes to Server

1. Locate the bin folder of the server you are running
2. Add the following JAVA_OPTS setting to run.bat
   • set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%
3. Relaunch your server

In Eclipse

1. Launch the Debug Configurations window (Run -> Debug Configurations)
2. In the Debug Configurations window, create a new Remote Java Application
   • Name: Enter name for the new configuration
   • Connection Type: Standard (Socket Attach)
   • Host: Enter IP address server is at
   • Port: Port number specified in JAVA_OPTS above (This example uses 8787)
     
3. Attach the source code that's running on the remote server:
   
   • In the Source tab, click Add...
   • Select Java Project and click OK
   • Add the following projects: 
     • com.elasticpath.connect
     • com.elasticpath.cm
     • com.elasticpath.search
     • com.elasticpath.sf
     (Note that com.elasticpath.core will be added automatically)
   • Click Apply
4. Click Debug
   • At this point, if you are in the Java Perspective in Eclipse, you won't see anything different
5. Change perspectives by going to Windows -> Open Perspective -> Others...
6. Select Debug and click OK

Now you're ready to debug JBoss!

To debug, simply set breakpoints in parts of the code you're interested in and debugging is exactly the same as if the server was running within Eclipse!

For more information, you can refer to the following links:

• http://www.eclipsezone.com/eclipse/forums/t53459.html
• http://java.sys-con.com/node/44918

When developing your ecommerce site using Elastic Path, using the Eclipse WTP functionality to run your web applications from within Eclipse allows easy debugging. However, there are a few common problems that can occur which can disrupt your development and have you cursing Eclipse. Here are the top 5:

1. Not having enough memory allocated

By default, Java allocates only 128 Mb of memory for the heap and 64 Mb for the perm size. This isn't nearly enough for large applications. If you haven't told you server to allocate sufficient memory, it may start up without error, but once you try to do anything significant it will crash with an error like the following:

Exception in thread "RMI TCP Connection(idle)" java.lang.OutOfMemoryError: PermGen space

or

java.lang.OutOfMemoryError: Java heap space

As per the developer documentation, ensure you have enough heap and perm space by double-clicking your server in the Servers view, clicking Open launch configuration and adding the following to the VM arguments:

-Xmx1024m -Xms256m -XX:MaxPermSize=512m

If you are using Java 6 you should also ensure you have the following:

-Dsun.lang.ClassLoader.allowArraySyntax=true

2. Classes not enhanced

If you make changes to core persistence classes in Eclipse, it may compile the class without running the OpenJPA enhancement. When you start your application in WTP, it will try to do runtime enhancement and fail with an error like the following:

java.lang.ClassNotFoundException: org.apache.renamed.openjpa.enhance.InstrumentationFactory
Exception in thread "Attach Listener"      at java.net.URLClassLoader$1.run(URLClassLoader.java:200)
     at java.security.AccessController.doPrivileged(Native Method)
     at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
     at java.lang.ClassLoader.loadClass(ClassLoader.java:315)
     at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:330)
     at java.lang.ClassLoader.loadClass(ClassLoader.java:250)
     at sun.instrument.InstrumentationImpl.loadClassAndStartAgent(InstrumentationImpl.java:280)
     at sun.instrument.InstrumentationImpl.loadClassAndCallAgentmain(InstrumentationImpl.java:348)
Agent failed to start!

You may also see an error like the following:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'messageSource' defined in ServletContext resource
[/WEB-INF/conf/spring/views/velocity/velocity.xml]: Cannot resolve reference to bean 'storeMessageSourceDelegate' while setting bean property 'storeMessageSource';
nested exception is org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'storeMessageSourceDelegate' defined in ServletContext resource [/WEB-INF/conf/spring/views/velocity/velocity.xml]:
Cannot resolve reference to bean 'messageSourceCache' while setting bean property 'messageSourceCache'; 
nested exception is org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'messageSourceCache' defined in ServletContext resource [/WEB-INF/conf/spring/views/velocity/velocity.xml]: 
Invocation of init method failed; 
nested exception is <openjpa-1.2.1-r62037:76497M nonfatal user error> org.apache.renamed.openjpa.persistence.ArgumentException:
[Error while processing persistent field com.elasticpath.domain.order.impl.AbstractOrderShipmentImpl.status, declared in null. Error details:
The accessor for field getStatus in type com.elasticpath.domain.order.impl.AbstractOrderShipmentImpl is private or package-visible. 
OpenJPA requires accessors in unenhanced instances to be public or protected. 
If you do not want to add such an accessor, you must run the OpenJPA enhancer after compilation, or deploy to an environment that supports deploy-time enhancement,
such as a Java EE 5 application server.]

To avoid these, ensure the classes are enhanced by doing one of the following whenever you change a core persistence class:

• Run ant enhance from the command line if you are working directly on com.elasticpath.core. If you do this be sure to refresh the project in Eclipse.
• Launch an ant-based enhance from within Eclipse by running coreAntJpaEnhance.launch in core
• If using binary based development, ensure you are using the Maven OpenJPA plugin for enhancement and you have Eclipse configured to call the maven build

3. Missing datasource context

The datasource used by the Elastic Path applications to connect to the database is configured through JNDI. When using WTP with Tomcat, for example, you need to make sure you have the JNDI datasource defined in the container. If it can't be found, you will end up with an error something like the below (note that this will be preceded by several pages of  various "Error creating bean..." messages:

Caused by: org.apache.tomcat.dbcp.dbcp.SQLNestedException: Cannot create JDBC driver of class '' for connect URL 'null'
     at org.apache.tomcat.dbcp.dbcp.BasicDataSource.createDataSource(BasicDataSource.java:1150)
     at org.apache.tomcat.dbcp.dbcp.BasicDataSource.getConnection(BasicDataSource.java:880)
     at org.apache.renamed.openjpa.lib.jdbc.DelegatingDataSource.getConnection(DelegatingDataSource.java:106)
     at org.apache.renamed.openjpa.lib.jdbc.DecoratingDataSource.getConnection(DecoratingDataSource.java:87)
     at org.apache.renamed.openjpa.jdbc.sql.DBDictionaryFactory.newDBDictionary(DBDictionaryFactory.java:91)
     ... 115 more
Caused by: java.sql.SQLException: No suitable driver
     at java.sql.DriverManager.getDriver(DriverManager.java:264)
     at org.apache.tomcat.dbcp.dbcp.BasicDataSource.createDataSource(BasicDataSource.java:1143)
     ... 119 more

When using Tomcat with the Elastic Path web applications, the ant eclipse-setup task will create a META-INF/context.xml file which defines the datasource using values from your env.config. Ensure this file is present and has the database details you are expecting.

Alternatively (or when using binary based development), you may add a <Resource> definition to the Context for your web app directly in the server.xml file. In either case it will look as follows:

    <Resource name="jdbc/epjndi"
        auth="Container"
        scope="Shareable"
        type="javax.sql.DataSource"
        maxActive="100"
        maxIdle="30"
        maxWait="10000"
        removeAbandoned="true"
        username="root"
        password="password"
        driverClassName="com.mysql.jdbc.Driver"
        url="jdbc:mysql://localhost:3306/COMMERCE_DB?AutoReconnect=true&useUnicode=true&characterEncoding=utf-8"
    />

4. Changes not published

Another common problem is making changes in Eclipse and (mysteriously) not having these changes present when you start your web applications. One cause of is related to the fact that our ant build copies spring configuration to the web applications at build time. All the files from WEB-INF/conf/spring are copied, namely:

• commons/serviceChangeset.xml
• commons/util-config.xml
• dataaccess/openjpa/openjpa.xml
• dataaccess/dao.xml
• models/domainModel.xml
• service/service.xml
• service/serviceRemote.xml

If you change any of these files in core within Eclipse, they won't get automatically copied across to your web applications; you will need to re-run ant build for those projects from the command line. Conversely, if you change the copies in your web applications directory, then next time you run ant build your changes will get overwritten.

You may also encounter issues where code changes you make do not seem to be present when running your web applications. If this occurs, you may want to check the following:

• Did you already have your server running when you made changes? Don't rely on Eclipse's ability to "hot swap" code into place.
• Do you have maven Workspace Resolution disabled? If so, WTP won't be looking at the eclipse-compiled version of your code, but rather using the last version that was installed in your local maven repository. If you do feel the need to have workspace resolution disabled, you will need to run the appropriate ant or maven target on the command line to build and install the changed code into the repository.
• Did you make any changes outside of Eclipse (including updating from your source code repository if working in a team environment) or run a command line build? If so, make sure you refresh the project in Eclipse so it knows there are changes to publish to WTP

5. Unable to publish due to file locks

This one happens less frequently than the others but is one of the more frustrating problems. Sometimes when you have been stopping and starting your web applications through WTP enough, Eclipse may have held onto a file lock for a little to long, and you get a message popup during publishing/startup that it is unable to publish a particular file. It is quite tempting to treat the OK button of this popup message as a "yeah, whatever" button and just continue. Sometimes when this occurs everything does still work, but other times Eclipse will, from that point on, fail to start your web applications properly.

There is no specific error message, but rather one or more of the apps will fail to start up and you may see pages of meaningless tomcat DEBUG lines or blank lines. The only good solution to this is to shut down Eclipse completely and relaunch it, which forces it to release the file locks and thus allow a republish. You may also need to right-click your server in the Servers view and select the Clean options to force a full republish.

Short screencast illustrating how to enable and use the Step Filtering feature of Eclipse:

Here are the step filters that should be enabled to skip over Spring's dynamic proxy code:

• $Proxy*
• java.*
• javax.*
• org.apache.*
• org.springframework.*
• sun.*
• java.lang.ClassLoader