===== The Java Archive Tool (jar) =====



==== Overview ====


The ''%%jar%%'' tool can be used to bundle multiple files into  a single file.  JAR files typically contain the class files and  resources (e.g., images) required by an application.


==== Viewing the Contents of a JAR File ====


To view the contents of a JAR file:



|   jar tf //jar-file//   |



==== Creating a JAR File ====


To create a JAR file:



|   jar cf //jar-file// //input-files//   |


where //input-files// can include ''%%.class%%'' files,  packages, and resources of various kinds.


==== Creating an Executable JAR File ====


An "executable JAR" file can be executed using the ''%%java%%''  tool with the ''%%-jar%%'' switch or, if the associations are  set properly, by "clicking" on it.



You can create an executable JAR file by including  a manifest that includes a ''%%Main-Class:%%'' directive.  For more information, see the  [[ http://java.sun.com/docs/books/tutorial/deployment/jar/appman.html | tutorial ]].

==== Running an Executable .jar File ====

You can run an executable .jar file from a command shell/terminal window as follows:

  - Open a command shell/terminal window.
  - Change the working  directory to the directory that contains the ''%%.jar%%'' file (using the  [[https://ss64.com/|cd command]])
  - Execute the application as follows: ''%% java -jar //filename//.jar %%''

You can also run an executable .jar file from a file explorer/finder by double-clicking on it. However, your associations and permissions must first be setup.

===== Permissions and Executable .jar Files =====

Depending on your operating system, you may need to change the  permissions of the executable ''%%.jar%%'' file (i.e.,  provide permission to execute). In most OSs this can be done from  the command line (using the  [[https://ss64.com/|chmod command]]) or from the GUI  (in a variety of different ways).

===== Associations and Executable .jar Files =====

You may also need to set the default manner in which it is  "opened" (i.e., instruct the OS to used the Java runtime). This is  sometimes also called the files "association" or "default  program". From the command line: in MS Windows you can  use ''%%assoc%%'', in OS X you can edit  ''%%~/Library/Preferences/com.apple.LaunchServices.plist%%'',  and in Linux you can edit  ''%%/usr/share/applications/defaults.list%%'' From the GUI:  in MS Windows you can click on <key>Start</key>+<key>Default  Programs</key>, in OS X you can right-click on the file and  use <key>File</key>+<key>Get Info</key>, and in Linux you  can right-click and select <key>Properties</key>.

==== Testing an Executable .jar File that You Created====

If you just click/double-click on an executable ''%%.jar%%''  file and the code throws an exception you (typically) won't see  it. Hence, when testing it is often useful to run the application  from the command line. To do so, see the relevant instructions above.

If you get a message like the following:

<code>
Exception in thread "main" java.lang.UnsupportedClassVersionError
The program has been compiled by a more recent version of the Java Runtime (class file version XX.0), 
this version of the Java Runtime only recognizes class file versions up to YY.0
</code>

it means that you need to update your version of Java. When doing so, you need to be careful because many systems have both the Java Runtime Environment (JRE) and the Java Development Kit (JDK) installed, and updating the one may not update the other. In Linux/OSX you can use ''%%which java%%'' and in MS-WIndows you can use ''%%where java%%'' to find the path to the Java interpreter. You can change the ''%%path%%'' environment variable (not the ''%%classpath%%'' environment variable) to change which Java interpreter is used (i.e., either the one installed with the JRE or the one installed with the JDK).

==== Using Resources in a .jar File ====


You may want to include files other than ''%%.class%%'' files  in a ''%%.jar%%'' file (e.g., images, configuration files,  input files). Such files are often called resources. See the discussion of
[[ student:java:resources | using resources ]] for more information.

==== Changing the Icon of Executable .jar Files ====


By default, executable ''%%.jar%%'' files use the Java icon.
 
To change the icon in OS X, copy the icon you want to use  (using <key>Commmand</key>+<key>c</key>), right-click on  the ''%%.jar%%'' file, pull down to <key>Get Info</key>,  click on the icon in the upper-left corner of the dialog box, and  paste the icon (using <key>Command</key>+<key>v</key>).

To change the icon in many Linux distributions, right-click on the  ''%%.jar%%'' file, pull down to <key>Properties</key>,  click on the "Basic" tab, and then click-and-drag the icon you want to use  to the icon in the upper-left corner of the dialog box.

In MS-Windows you can't change the icon of the ''%%.jar%%''  file directly.  However, you can create a shortcut and change it's  icon. To do so, right-click on the ''%%.jar%%'' file and pull  down to <key>Create shortuct</key>. Then, right-click on the  shortcut, pull down to <key>Properties</key>, click on the  "Shortcut" tab, click on <key>Change Icon...</key>, navigate  to the ''%%.ico%%'' file, click on <key>OK</key>, and  click on <key>OK</key>.


==== For More Information ====


The jar tool is very powerful and has a number of capabilities  that are not discussed here.  For more information, see the  [[ https://docs.oracle.com/javase/tutorial/deployment/jar/ | tutorial ]].