Jar Tool

User Guide

1

Creating new archive

By clicking on the icon in the tool bar or by using the "New Archive" from the project menu you can  start creating the new  archive project.  It will bring up the input box to define the name of the archive.

This will create a file in the sub folder "archive_projects" (if not exists) and .jarprj  (jar project) file with the specified name.  This action also will open the jar project editor window to you to configure your build. You can create as many as archive project files within any idea project.

2

Opening the existing archive project

By simply clicking on the .jarprj file it will open the editor window back.
NOTE : you will be prompting to register the file type .jarprj on first use.  Register the file type in the category "Archive Files" (any other file type except "GUI form" will not give problems)

3

Archive Properties

Essential details of the archive can be defined in this screen.  All the relevant details will be set with default values based on the IDEA project information and the name you have given to the .jarprj file.

• Archive Name - Name of the archive will be set default based on the .jarprj file name.  You can change it to your preference.

• Include All Project Resources - This  tick box will indicate that all the resources in the output path of your project should be included to the build. When the project is consisting of multiple modules, output paths of all the modules based on the module dependencies will be selected to the archive build.

• Archive Target Dir. - The directory where you need to create the archive build need to be defined here.  By default this will be set to the IDEA project directory. You can either edit the path or use the IDEA directory chooser to change the target directory.

• Path To Signed Libraries - Third party signed libraries cannot be directly included in to your jar archive. If your project uses signed third party libraries they will be copied in to a subfolder defined by this field. The manifest file of your archive will be inserted with the class path entry for these libraries.  Each build archive action will clear all the items of this folder and copy libraries back again. If you don't specify the path and have used signed libraries, then they will be copied in to the archive target directory. No files will be deleted from that directory up on building the archive, but latest version of the libraries will be brought in to the directory.

• Main Class - If the build is an executable jar archive, then you need to define the main class of the build. You can either edit on the field or use the IDEA class browser to select the class. Class browser will list the classes with main methods. By default this will be kept blank.

• Build Source Archive - If you are intending to  build the source archive with the binary build, then you should select this. All the sources of the classes selected to the build will be included in to the source archive.  If the project includes multiple modules relevant sources from modules will be taken in to the source archive.

• Extract and add library sources - Sources of third party libraries can also be included in to your source archive. Source of project libraries will be given as jar archives or zip archives.  If selected all the library source archives will be extracted and added to your archive as one source. Otherwise  each library source archive will be added to your source archive as a single entry.

• Source archive name - This defines the name of the source archive.  By default this value is set to  "archive_name-src.jar"

• Source Target Dir. - The target directory where you need to place the source build is defined here. You can use the IDEA directory chooser or edit the field to change the target directory.

• Build project before archiving - If this is selected IDEA project will be compiled before building the archive. Otherwise current compiled output will be used  to build the archive.

4

Project Resources

This screen will provide you the facility of selecting the classes & resources from your project output paths in to the archive.

All the contents of your IDEA project output paths including other modules will be listed down in this screen.  All the directories of the output paths are displayed on the top table and the classes are listed in the bottom table. This will enable you to select or deselect the entire directory by a single click. Select / Deselect All menus on right click will facilitate you to choose the resources easily.
If the "Include All Project Resources" tick box is selected on the "Archive" tab, then the directories table will be hidden and the list will be made non editable.
Upon selection of classes/directories they will be highlighted by different colour.  
If the directory is selected and a new class is added to the project in the same directory, they will be automatically selected in to the build archive. It is not required to go and select the newly added classes again in to the project.
By clicking on the table header, you can sort the classes / directories which will enable you to find them easily.

5

Libraries

You can include required third party libraries into to your archive build.  This will enable you to distribute your work as a single jar archive file.

Selected libraries

When you select your libraries they will be listed in this table. You can use the right click menu or the Del key to remove them.

By selecting the tick box on "Signed" column, you can defined the signed libraries. Signed libraries cannot be directly added in to your archive. They will be copied to the directory defined by "Path to Signed Libraries"  and the Manifest file will be altered in order to define the class path for these selected entries.

Selecting Libraries

When right click and select the "Add Jars" menu, this screen will appear.  You don't have to search or browse for libraries, this will list all the libraries which are selected to your project.  Previously selected libraries will be automatically selected when you are coming back to the screen.

Library order

The order of the libraries are important when more than one version of the same class is available in different libraries. After selecting the libraries you can set the order of the libraries using the up & down arrow buttons on the screen. You can select multiple rows once and shift them up or down using the buttons.  If duplicate libraries are available, classes of top most libraries will be added in to your archive.
When selecting new libraries in to the project, it will keep the existing order and add the newly selected libraries to the end of the list.

6

Other files

Other  files like configurations, settings, images etc.  can be included in to your archive. If these are available in the IDEA project output directory, then you don't have to add them in to this list. They will be picked from the project resources tables.  The idea file chooser is provided from the right click to navigate and select the files easily.
When the files are added,  if they are in the IDEA project directory or in a subdirectory of the project directory, they will be added to the archive while maintaining the directory hierarchy.  It will automatically create the directory structure within the archive based on the folder structure. Files outside the project directory will be added to the root directory of the archive.  

7

Library Sources

Source files of the libraries can be added in to your archive. Selected libraries will be listed down in this screen.

Selected source archives

Selecting source archives

If you have specified the sources paths when defining the Libraries in to the IDEA project, then all these sources will be listed down in this screen. Source paths from the JDK paths will also be included in to the list.

8

Building the Archive

After making all your settings you can simply build the archive by clicking on the "Make" button. This will bring up a progress bar  and a message window, indicating the steps of the process.  You can set the progress bar to background mode which will enable you to continue your work on the project at the same time while the archive is being made. "Clean " will delete both your binary archive and source.  You can also build the archive by selecting the .jarprj  jar project file and "Make Archive" from the project pop-up menu. This will enable you to select multiple jar  projects and build them at once.

9

Save & Refresh

"Save" will store all your configurations on the project file and "Refresh" will bring the file data in to the UI. "Refresh" will enable you to undo and revert back to the original file.  Saving the changes will be automatically done when you exit from the jar project editor.

10

Issues & Bugs

• With the use of Progress bar, when accessing the files and doing I/O operations within the progress bar IDEA throws an exception "Write access is allowed inside write-action only". With idea 5.x with this exception the Jar Tool  works but with IDEA 6 this doesn't work.  Need some help to solve this issue by using  ApplicationManager.getApplication().runWriteAction() along with the Progress indicator.
  In IDEA 5.x this could lead to indicating error messages on status bar.

• IDEA Open API method VirtualFile.isDirectory() returns true for a .jar file, which is handled within the Jar Tool, but apparent to be a bug.

11

Feedback

Please send your feed back on the "Jar Tool" plugin to ruwanpls@gmail.com

Copyright © 2006 Sanjeewa Ruwanpathirana
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.