Eclipse: What, exactly, does the "Add External Class Folder" button really do?

[Rob Phair]

Hey, all,

I'm having an issue with a third-party API I'm trying to write a web service around. I have my web service built in Eclipse Helios as an EJB project, which is packaged up in an EAR file and deployed to a JBOSS 6.0 application server. The API is... well, it's a little different than what I'm used to. Usually, I find that a Java API will give you one or more .jar files, which you include in your EAR Libraries, and then perhaps some configuration files that you specify. The configuration files are what's giving me trouble here.

The API documentation -- which is, unfortunately, pretty sparse -- instructs me to put the directory containing the config files on the classpath. I've tried a few different ways of doing this, but every time, I deploy my web service and immediately get an error message in the JBOSS console saying that it can't instantiate my class because it cannot locate the .xml file it's looking for. Here's the screwy bit: the exception stack trace actually tells me that it's looking for a specific directory structure -- what I assume is the "default" location of the config file -- of "/opt/<api_name>/conf/<file>.xml". If, however, I put the expected XML file in the exact directory specified in the trace, I still receive the same error.

Looking to simplify the problem a bit and isolate the issue, I constructed a plain Java project, with a main method that simply instantiates the API, retrieves one piece of information to confirm connectivity to the system server, and then exits. I then run this project from Eclipse by right-clicking the main class and choosing Run As... > Java Application. So far, the *only* way I've been able to get a successful result -- meaning that the config file was read correctly and information was retrieved as expected -- is if I include the config file directory as an external class folder.

I've tried exporting the test project as a runnable .jar file, thinking that I might be able to package the configuration information into that, but received the same error as before. Thinking that perhaps it wasn't including anything from the external source folder in the .jar export because there were no Java classes there, I then packed up the config files into their own .jar file, and added that to the project. This was exported correctly -- I opened the project .jar file after export and confirmed that my config folder was there -- but I still received the error that the program could not find the configuration directory upon running the .jar file. I also tried running the .jar file with the -classpath option pointing to the config directory on the hard drive, but no luck there, either.

I don't expect anyone to be able to tell me why an ancient third-party API that I have no source code for is not able to find it's configuration; that's for me to figure out. What I do know is, when I add the config directory as an external class folder in Eclipse, I can get the program to work as expected, and so far, that's the only way I've been able to do so. Classpath-related issues have always been my weak point with Java, and they only get more complicated when factoring in EJBs, EARs, and application servers.

So, the root question here is, what is Eclipse doing at the classpath level when you use the Add External Class Folder button in the Project Properties > Java Build Path > Libraries tab? How is that class folder related to the rest of the project? I've tried to provide as much info as I can on the issue at hand, but if I've left out anything glaringly obvious, please let me know. I would appreciate any help that anyone can offer me with this. If I can figure out what Eclipse does when you add one of these class folders, and how it's different from what I have already tried or am trying to do, maybe I can figure out what the real issue here is.

Thanks in advance, everyone.

[Tim Holloway]

A Java project in Eclipse has a build classpath, and and run profiles have classpaths as well.

The build classpath is nothing more nor less than the classpath for finding referenced classes when editing/compiling. So, for example, if I add the external jar "/usr/local/apache-tomcat/lib/servlet-api.jar" to my project's classpath, I will be able to edit without getting ugly red splotches all over my editor window when I create code using things like HttpServletRequest and HttpSession.

As always in Java, classpath elements can be either single jars or folders containing class files (but NOT folders containing jars!). An external folder is simply one that's outside of the directories in your current Eclipse workspace.

You can also define a symbolic name for external resources in Eclipse, which can be helpful if someone else takes a copy of my project, but they're using "/home/fred/tomcat6/lib/servlet-api.jar" for their J2EE definitions, since the project itself doesn't have to be customized, only the user's workspace symbolic paths.

I mentioned that run profiles have classpaths, too. These are the build classpaths plus any additional classpath information needed to actually run/debug classes in the project. For example, you may provide an external jar with a JDBC driver in it. You generally don't need to see the jar's classes directly in your project (since JDBC provides the interface), but you need them to run. So you add the driver jar to the run profile.

[Rob Phair]

Thanks for the quick reply, Tim. So, if I understand your reply correctly, you're saying that each project has a build classpath, and when a run configuration is created, the run configuration's classpath includes all entries on the project build classpath, plus any additional entries that you define in the run configuration interface?

As I understand it, when you export an executable .jar file from Eclipse, you provide a run configuration, which supplies the .jar file with appropriate metadata. What I'm seeing now is that, when I have that external class folder defined on my build classpath, that folder does not get included in the export. That may be because there's only configuration information in the folder; no actual .class files exist here, so it's not really a "class" folder, per se. Regardless of whether I choose the "Extract required libraries into generated JAR" or the "Package required libraries into JAR" option on the Eclipse .jar export dialog, I still fail to see my configuration folder included in the .jar file.

My new question, then, is, can I include a folder containing non-Java files (.xml, .properties, etc.) in a .jar file using Eclipse's .jar export dialog? I think that, if I can get the config folder into the root of the .jar file, I might be able to get this to work. Is there any way to force Eclipse to include a specific folder structure as part of the archive when exporting .jar or EAR/EJB files? Simply including the folder on the build path doesn't seem to work.

Thanks again for any help you can offer!

[Tim Holloway]

Rob Phair wrote:Thanks for the quick reply, Tim. So, if I understand your reply correctly, you're saying that each project has a build classpath, and when a run configuration is created, the run configuration's classpath includes all entries on the project build classpath, plus any additional entries that you define in the run configuration interface?

Yep.

Rob Phair wrote:
As I understand it, when you export an executable .jar file from Eclipse, you provide a run configuration, which supplies the .jar file with appropriate metadata. What I'm seeing now is that, when I have that external class folder defined on my build classpath, that folder does not get included in the export. That may be because there's only configuration information in the folder; no actual .class files exist here, so it's not really a "class" folder, per se. Regardless of whether I choose the "Extract required libraries into generated JAR" or the "Package required libraries into JAR" option on the Eclipse .jar export dialog, I still fail to see my configuration folder included in the .jar file.

My new question, then, is, can I include a folder containing non-Java files (.xml, .properties, etc.) in a .jar file using Eclipse's .jar export dialog? I think that, if I can get the config folder into the root of the .jar file, I might be able to get this to work. Is there any way to force Eclipse to include a specific folder structure as part of the archive when exporting .jar or EAR/EJB files? Simply including the folder on the build path doesn't seem to work.

Thanks again for any help you can offer!

I don't use Eclipse to export executable jars. My projects are generally too complex for the Eclipse builders to create deployables from, so I use Maven or Ant to help out. The only "export" in Eclipse I do is when I back up a project by exporting it as a ZIP file. Maven makes creating an executable ZIP pretty easy, so actually the "hard" part would be to set up the extra stuff in the Maven POM that copies external folders into the target executable jar. Which isn't really that hard, either.