COMP 310	Libraries in Java

You often want to make use of libraries distributed by others in your programs. Typically these libraries are distributed as JAR  (Java ARchive) files.  Here, we will show how to utilize JAR file libraries in your application, using the World Wind Java ("WWJ") mapping library as an example.

Getting the Libraries

The World Wind Java libraries are available in the Subversion repository at the following location: https://svn.rice.edu/r/comp310/course/WWJ/verXYZ  (where "XYZ" is the current version number, e.g. "1.4" or "2.0.0").

You will want to include this in your project.  To do this perform the following steps:

1. Create a folder named libs at the top level of your project (i.e., in FINAL, not in the src directory, as the libraries are not source files).

2. Add the libs directory to version control and commit it.

3. Set the svn:externals property on the libs directory to be "WWJ https://svn.rice.edu/r/comp310/course/WWJ/verXYZ/"  (e.g ".../WWJ/ver2.0.0")

4. Commit the change and then do an Update To HEAD

Inside the libs directory, you should now have a WWJ directory which has a few subdirectories of its own.

Including the Libraries in your Project

Adding JAR Files to the Build Path

Just because the are JAR files located somewhere in your project does not mean that they will be included when you run your program.  You have to tell Eclipse which JAR files need to be included in your program.

There are multiple versions of the WWJ library, for 32-bit and 64-bit machines Windows, Mac and Linux machines.  You need to determine which type of maching you have before continuing. 

To get eclipse to include the libraries in your project you should perform the following steps:

1. Right click the project and select "Properties".
2. Choose "Java Build Path" from the options on the left.
3. Click the "Libraries" tab.
4. Select the "Modulepath" location
5. Push the "Add Jars" button.
6. Navigate to the libs/WWJ/code folder
7. Select the following 5 JAR files in that directory.   Do not select any of the files that do not have a ".jar" extension:
   • gdal.jar
   • gluegen-rt.jar
   • jogl-all.jar 
   • worldwind.jar
   • worldwindx.jar
8. For each of the above JAR files, expand its description and check that it says "Is Modular" and that when the Edit button is clicked that the "Defines one or more modules" box is checked.
   • If the description says "Is not modular", be sure that the JAR file is in the modulepath and make sure that the "Defines one or more modules" box is checked.

The JAR files will now be included in your project. 

Specifying the Location of Native Libraries

Two of the above jar files actually make calls to "native" (i.e., C) functions.  You have to tell Eclipse where these native functions are.  For both gluegen-rt.jar and jogl-all.jar, perform the following steps:

1. In the projects's Properties/Java Build Path/Libraries tab, click the triangle to expand the library (JAR file).

2. Select "Native library location".

3. Click the "Edit..." button.

4. Click the "Workspace" button.

5. Navigate to the same folder as where the JAR files are located in "WWJ" (the libs/WWJ/code folder) and select it.

Eclipse will now be able to find the native libraries.

Library Documentation

The worldwind.jar and worldwindx.jar files have documentation associated with them.  We need to tell Eclipse where it is.  To do so, perform the following steps:

1. In the projects's Properties/Java Build Path/Libraries tab, click the triangle to expand the worldwind.jar library.

2. Select "Javadoc location".

3. Click the "Edit..." button.

4. Select "Javadoc in archive"

5. Select "Workspace file"

6. For the Archive path, navigate to libs/WWJ/doc/worldwind-docs.zip (or similarly named file) and select it.

7. For the Path within archive, navigate to the "api" directory and select it.

8. Click the "Validate" button, it should tell you that the location is "likely valid".

9. Click OK.

10. Do the same for the worldwindx.jar library as well.

Library Source Code

The worldwind.jar and worldwindx.jar files also have source code associated with them.   Having the source code available will help in tracking down issues when using the WWJ libraries.  To tell Eclipse where the source code can be found, perform the following steps:

1. In the projects's Properties/Java Build Path/Libraries tab, click the triangle to expand the worldwind.jar library.

2. Select "Source attachment".

3. Click the "Edit..." button.

4. Select "Workspace location"

5. Click the Browse button and navigate to libs/WWJ/code/src folder and select it.

6. Click OK.

7. Do the same for the worldwindx.jar library as well.

module-info.java Settings

Add the following lines to your project's module-info.java file:

	requires transitive worldwind;
	requires transitive worldwindx;
	requires transitive jogl.all;
	requires transitive gdal;
	requires transitive gluegen.rt;

Since WWJ was not created with Java modules in mind, they are being included as "automatic modules" and the module names used in the module-info file are the module names automatically derived from the JAR file names. It is normal to have warnings that module names auto-generated from JAR file names are "unstable" (because they are).

Additional requires and exports lines may be needed to grant the needed access to the WWJ services.

You should now commit all of your changes, if you have not already done so.

After performing all of these steps, the World Wind Java libraries should be accessible to your application.  The documentaiton should also be available as normal.  If you and your partner have different systems (one 32-bit and one 64-bit) you need to be very careful that you don't mess up each other's native libraries!    Contact the staff right away if you encounter problems!

More WorldWind Specific Information...

© 2017 by Stephen Wong