leisenfels mit schrift und slogan 48

How to Use JarInfo

Please read the following steps to add the JarInfo component properly to your Java library archives:

 


Step 1: Download jarinfo.zip

First of all please download the current jarinfo.zip file onto your computer. This ZIP archive may be unzipped directly from Ant build scripts using the unzip task into the directories which are to be added to the target JAR archive. Of course you can extract the jarinfo.zip file manually with WinZIP or other ZIP extraction tools. The listing below shows the contents of the current jarinfo.zip file.

    com/
com/lf/
com/lf/commons/
com/lf/commons/info/
com/lf/commons/info/JarInfo$1.class
com/lf/commons/info/JarInfo$2.class
com/lf/commons/info/JarInfo$3$1.class
com/lf/commons/info/JarInfo$3.class
com/lf/commons/info/JarInfo$4.class
com/lf/commons/info/JarInfo$5.class
com/lf/commons/info/JarInfo.class
com/lf/commons/info/JarInfo.properties
com/lf/commons/info/JarInfo_de.properties
com/lf/commons/info/resource/
com/lf/commons/info/resource/jarinfo.properties

The jarinfo.zip file contains various files and resources in the com.lf.commons.info package. Besides the JarInfo Java classes there is the resource bundle for English and German localization (files JarInfo.properties and JarInfo_de.properties). The configuration file jarinfo.properties is expected to reside in the resource sub-directory. This file is commented out so that the default settings are used by JarInfo. You can use the included jarinfo.properties file as skeleton for your own settings.

 


Step 2: Prepare jarinfo.properties

The JarInfo component can be configured by setting variable/value pairs found in the jarinfo.properties resource file. This files is expected to reside in the com/lf/commons/info/resource/ sub-directory. The default file that comes as part of the jarinfo.zip looks as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# Copyright (c) 2005-2011 Leisenfels. All rights reserved.
# Use is subject to license terms.
 
#! encoding=ISO-8859-1 Unicode Escapes
 
# Window and appearance
#JAVAINFO_LOCALE=(auto|en|de) (Default: auto, fallback is current system locale, then English)
#JAVAINFO_PLAF=(auto|com.apple.laf.AquaLookAndFeel|...) (Default: auto -> current system look & feel)
#JAVAINFO_WINDOW_TITLE=[e.g. "JarInfo"] (Default: JarInfo)
#JAVAINFO_WINDOW_ICON=[e.g. "resource/cubes_16.png"] (Default: none = Java cup)
#JAVAINFO_WINDOW_WIDTH=[e.g. 640] (Default: 580)
#JAVAINFO_WINDOW_HEIGHT=[e.g. 480] (Default: 420)
#JAVAINFO_WINDOW_LOCATION_X=(value|center) (Default: center)
#JAVAINFO_WINDOW_LOCATION_Y=(value|center) (Default: center)
#JAVAINFO_INITIAL_TAB=(notice|manifest|entries|services) (Default: not set = first tab)
 
# File path (top)
#JAVAINFO_SHOW_FILENAME=(true|false) (Default: true)
#JAVAINFO_FILENAME_MODE=(fullpath|nameonly) (Default: fullpath)
 
# Copyright (bottom)
#JAVAINFO_SHOW_COPYRIGHT=(true|false) (Default: true)
#JAVAINFO_COPYRIGHT=[e.g. "Copyright (c) 2011 MyCompany.com"] (Default: not set = JarInfo copyright)
 
# Notice tab
#JAVAINFO_SHOW_TAB_NOTICE=(true|false) (Default: false)
#JAVAINFO_NOTICE=[e.g. "This is a Java library archive."] (Default: not set = localized notice text)
 
# Manifest tab
#JAVAINFO_SHOW_TAB_MANIFEST=(auto|true|false) (Default: auto)
#JAVAINFO_MANIFEST_MODE=(plain_wrapped|plain_unwrapped) (Default: plain_unwrapped)
 
# Files tab
#JAVAINFO_SHOW_TAB_ENTRIES=(true|false) (Default: true)
#JAVAINFO_ENTRIES_MODE=(text|tree) (Default: text)
#JAVAINFO_ENTRIES_EXPAND_TREE=(true|false) (Default: false)
#JAVAINFO_ENTRIES_SHOW_EXTRACT=(true|false) (Default: false)
 
# Services tab
#JAVAINFO_SHOW_TAB_SERVICES=(auto|true|false) (Default: auto)
#JAVAINFO_SERVICES_AUTO_SELECT=[e.g. "com.lf.commons.i18n.spi.Localization"] (Default: not set)

Default jarinfo.properties file

All settings are commented out (not used) so that the default values as described are used by JarInfo. You should extract a copy of the sample file as skeleton for your own settings. To activate a settings please remove the leading # character of the variable/value lines. Remember to replace the comments from the lines to the right of the = character by the values you want to set for the properties.

For some properties like JAVAINFO_LOCALE a list of values can be used (here: auto for automatic locale setting, en for English, de for German). Since properties files are based on the Java ISO-8859-1 Unicode Escapes encoding, German umlauts etc. need to be escaped using the hexadecimal Unicode sequences like \u00E4 for the ä character.

If a variable value is not properly set it will be simply ignored by JarInfo. If a setting is not being activated please check the properties file for wrong characters etc. first. Most of the shown values are self-explanatory. If you like to add own resources please store them into the com/lf/commons/info/resource/ sub-directory along with the jarinfo.properties file. The sample file shows the resource/cubes_16.png image to use as window icon. In order to make this setting work, a file named cubes_16.png needs to be copied into the resource sub-directory.

The window location values can either be set as absolute screen coordinates with (0,0) as the upper left corner or using the center value. In the latter case the JarInfo window is centered on the X or Y axis (or both) on the basis of the total screen dimensions.

Each tab can be (de)activated so that you have full control what the user/developer sees. Special components like the header label showing the file name/path, the bottom label showing the copyright info, and the Extract button are configured separately. You can set an own copyright text in order to smoothly integrate the JarInfo component into your libraries.

The Notice tab can show either plain text or formatted HTML text including images which need to be stored into the com/lf/commons/info/resource/ sub-directory again. The next code block shows a HTML fragment including an image. The resources cannot be referenced directly but must be surrounded with % characters to be replaced by JarInfo. Here, the image pattern %information_32.png% is replaced by the URL associated with resource/information_32.png in the target JAR archive. When the fragment is set as value of the JAVAINFO_NOTICE variable then it must be converted to a single-line pattern.

1
2
3
4
5
6
7
8
9
10
<html>
 <table>
 <tr>
 <td><img src="%information_32.png%"/></td>
 <td> </td>
 <td>Dies ist ein Java-Archiv, das nicht direkt ausgef\u00FChrt werden kann.<br>
Bitte entnehmen Sie den korrekten Aufruf der Programm-Dokumentation.</td>
 </tr>
 </table>
</html>

A sample customized HTML notice text including an image

The variables JAVAINFO_SHOW_TAB_MANIFEST and JAVAINFO_SHOW_TAB_SERVICES may be set to auto which means that these tabs are only displayed if the archive contains a manifest file or service provider declarations at all. The plain_wrapped value of the JAVAINFO_MANIFEST_MODE variable causes JarInfo to print the MANIFEST.MF file without any modifications while plain_unwrapped concatenates the lines that have been separated due to the JAR file format specification (looks better).

The entries of the JAR archive (files and folders) can be presented in two different modes: as text or as tree. If you set the JAVAINFO_ENTRIES_MODE variable to text then the entries are printed as plain text which can be copied into a text editor for example. If it is set to tree then the hierarchies of the JAR file system are directly presented. Extraction can be performed no matter the presentation mode. When in tree mode then the tree may be expanded automatically once the tree has been populated by JarInfo (see JAVAINFO_ENTRIES_EXPAND_TREE).  The Extract button can be (de)activated by setting the JAVAINFO_ENTRIES_SHOW_EXTRACT variable to the desired value.

 


Step 3: Adding The Component To JAR archives

Most Java developers use Ant build scripts for the packaging and distribution of their applications and libraries. The simplest way to add the JarInfo component to an own JAR archive is to extract the original jarinfo.jar archive into a temporary directory (see the unzip Ant task), copy your own jarinfo.properties file over the extracted original file, let the jar Ant task include this directory in addition to the other resources, and set the main class in the META-INF/MANIFEST.MF to com.lf.commons.info.JarInfo. It's simple as that.

A sample Ant build script showing these steps and a sample jarinfo.properties file showing entries as text look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?xml version="1.0" encoding="UTF-8"?>
 
<!--
Copyright (c) 2005-2011 Leisenfels. All rights reserved.
Use is subject to license terms.
-->
 
<project name="jarinfo" basedir=".">
 
<target name="jar" description="Creates a JAR file including JarInfo.">
 
<!-- Create a temporary directory for the classes and resources. -->
<property name="TEMP_DIR" value="C:\Temp\jarinfo"/>
<mkdir dir="${TEMP_DIR}"/>
 
<!-- Copy the classes and resources. -->
 
<property name="SRC_DIR" value="L:\lf\commons\src"/>
<copy todir="${TEMP_DIR}/com">
<fileset dir="${SRC_DIR}/com"/>
</copy>
 
<!-- Set the jarinfo.properties for this package. -->
<copy todir="${TEMP_DIR}/com/lf/commons/info/resource" overwrite="true">
<fileset file="jarinfo.properties"/>
</copy>
 
<!-- Copy some extra resources for JarInfo. -->
<copy todir="${TEMP_DIR}/com/lf/commons/info/resource">
<fileset file="${SRC_DIR}/com/lf/commons/resource/cubes_16.png"/>
</copy>
 
<!-- Create the JAR including the JarInfo component. -->
<jar jarfile="sample.jar"
basedir="${TEMP_DIR}" excludes="**/*.java **/*.jfd **/*.html **/Thumbs.db"
level="9" includes="com/lf/commons/info/**">
<manifest>
<attribute name="Main-Class" value="com.lf.commons.info.JarInfo"/>
 
</manifest>
</jar>
 
<!-- Cleanup. -->
<delete quiet="true" dir="${TEMP_DIR}"/>
 
</target>
 
</project>
 

Sample Ant build target to create a JAR archive including JarInfo (download build-sample.xml)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Copyright (c) 2005-2011 Leisenfels. All rights reserved.
# Use is subject to license terms.
 
#! encoding=ISO-8859-1 Unicode Escapes
 
JAVAINFO_LOCALE=auto
JAVAINFO_PLAF=
JAVAINFO_WINDOW_TITLE=
JAVAINFO_WINDOW_ICON=resource/cubes_16.png
JAVAINFO_WINDOW_WIDTH=640
JAVAINFO_WINDOW_HEIGHT=460
JAVAINFO_WINDOW_LOCATION_X=center
JAVAINFO_WINDOW_LOCATION_Y=center
JAVAINFO_INITIAL_TAB=entries
JAVAINFO_SHOW_FILENAME=true
JAVAINFO_FILENAME_MODE=fullpath
JAVAINFO_SHOW_COPYRIGHT=true
JAVAINFO_COPYRIGHT=
JAVAINFO_SHOW_TAB_NOTICE=false
JAVAINFO_NOTICE=
JAVAINFO_SHOW_TAB_MANIFEST=auto
JAVAINFO_MANIFEST_MODE=plain_unwrapped
JAVAINFO_SHOW_TAB_ENTRIES=true
JAVAINFO_ENTRIES_MODE=text
JAVAINFO_ENTRIES_EXPAND_TREE=
JAVAINFO_ENTRIES_SHOW_EXTRACT=true
JAVAINFO_SHOW_TAB_SERVICES=auto
JAVAINFO_SERVICES_AUTO_SELECT=

Sample jarinfo.properties file (download jarinfo.properties)

 


Step 4: Testing

For Windows and Mac OS systems a simple click or double-click on a JAR file from file system browsers like the Windows Explorer or Finder opens the archive. The JarInfo main class is then executed automatically. If the systems lacks a graphical environment then JarInfo prints some data on the command line. This works if a suitable Java runtime environment is installed on the target platform. The JarInfo component currently requires Java 1.4 or newer.

The JAR archive including JarInfo can be executed from the command line using the following command:

Java 1.4+java -jar [JAR file]

Print Email