How to run a Java application with library dependencies

Typical Java applications consist of an application-specific code, and various reusable library code that you have implemented or that has been implemented by third parties. The latter are commonly referred to as library dependencies, and are typically packaged as JAR files.

Java is a dynamically bound language. When you run a Java application with library dependencies, the JVM needs to know where the dependencies are so that it can load classes as required. Broadly speaking, there are two ways to deal with this: 

  • The application and its dependencies can be repackaged into a single JAR file that contains all of the required classes and resources.
  • The JVM can be told where to find the dependent JAR files via the runtime classpath. 

For an executable JAR file, the runtime classpath is specified by the "Class-Path" manifest attribute. (Editorial Note: This should be described in a separate Topic on the jar command.) Otherwise, the runtime classpath needs to be supplied using the -cp option or using the CLASSPATH environment variable. 

For example, suppose that we have a Java application in the "myApp.jar" file whose entry point class is com.example.MyApp. Suppose also that the application depends on library JAR files "lib/library1.jar" and "lib/library2.jar". We could launch the application using the java command as follows in a command line: 

#Alternative (preferred)

$ java -cp myApp.jar:lib/library1.jar:lib/library2.jar com.example.MyApp
#Alternative 2
$ export CLASSPATH=myApp.jar:lib/library1.jar:lib/library2.jar
$ java com.example.MyApp

(On Windows, you would use ; instead of : as the classpath separator, and you would set the (local) CLASSPATH variable using set rather than export.)

While a Java developer would be comfortable with that, it is not "user friendly". So it is common practice to write a simple shell script (or Windows batch file) to hide the details that the user doesn't need to know about. For example, if you put the following shell script into a file called "myApp", made it executable, and put it into a directory on the command search path:

# The 'myApp' wrapper script

export DIR=/usr/libexec/myApp
export CLASSPATH=$DIR/myApp.jar:$DIR/lib/library1.jar:$DIR/lib/library2.jar java com.example.MyApp

then you could run it as follows:

 $ myApp arg1 arg2 ...

Any arguments on the command line will be passed to the Java application via the "$@" expansion. (You can do something similar with a Windows batch file, though the syntax is different.)