[Top]

Packaging Composer Plug-ins

Before you can run your compiled plug-in in the Composer, you have two more steps to follow:

1. Package the Composer plug-in a Java ARchive (JAR) or zip file.
2. Install the plug-in by moving the archive to the plug-ins directory for your platform.

This section compares JAR and zip archives and outlines the basic steps in using them to package a Composer plug-in, including naming rules for archives. The next sections describe using a batch file to create a zip archive and using the JARscript packager to create a JAR archive either at the command line or through a batch file.

The zip or JAR archive is made up of a configuration file plus all of the plug-in class files for the plug-in. You can place all the files for several plug-ins in the same archive. For example, the Composer Plug-in Kit uses a JAR archive, cpTest.jar (in the samples directory), to package its sample plug-ins.

During learning and testing, you do not have to place your plug-in in a package. Make this one of your last steps before shipping. In fact, you can wait to package the plug-in until after it returns from beta testing.

• Comparing JAR Archives and Zip Files
• Overview of Packaging a Plug-in

The information in this guide applies only to Composer plug-ins. For more general information and instructions for creating JAR archives, see Using  the JAR Packager and Using JAR Installation Manager for SmartUpdate.

[Top] [Packaging Composer Plug-ins]

Comparing JAR Archives and Zip Files

Although you can use either JAR or zip archives to package plug-ins, JAR archives offer several helpful features:

• Since JAR archives do not end in .zip, users are not tempted to unzip them.
  
  
• JAR archives are clearly identified as Java files, rather than as generic archive files.
  
  
• JAR archives can be compressed.
  
  
• JAR archives can be signed. For more information, see "Signing Files" in Using  the JAR Packager; also see Netscape Object Signing.

[Top] [Packaging Composer Plug-ins]

Overview of Packaging a Plug-in

This section describes the basic steps you follow whether you are using a zip or JAR archive to package Composer plug-ins, regardless of your operating system platform. You also have the option of using a batch file to package plug-ins in a zip (MS Windows only) or JAR archive.

You follow the same basic guidelines to package a completed plug-in in a zip or JAR archive:

1. Create an uncompressed zip or JAR archive with the filename cpXXX.zip, where XXX can be any unique descriptive text. You could use your company name or the plug-in name.

Important:
The names of all plug-in zip or JAR archives must start with "cp" and must be eight characters or less in length. See naming rules for archives at the end of this section.

2. Place all the classes associated with your plug-in in the zip or JAR archive.
   
   
3. At the top level of the archive, place the configuration file netscape_plugin_composer.ini, which contains the names and the user interface strings for the plug-in classes.
   
   
4. The next step is installing the plug-in. Place the archive file in the plug-in directory for your platform (Plugins on MS Windows or Plug-ins on Mac OS), where the Composer can automatically find and load it. A Composer Plug-in runs from the zip or JAR archive, so it is never unzipped.

Note:
You can download a freeware zip encoder at this URL.

Naming Rules for JAR and Zip Archives:
The names of all Composer plug-in JAR or zip archives must follow these rules:

• Archive names must start with "cp" so that Communicator can identify them.
  
  
• Archive names must be eight characters or less in length, so that they can work in MS Windows 3.1. For example:
  Good: cpMyPlug.jar
  Bad: MyPlugin.jar -- Name does not start with "cp."
  Bad: cpMyPlugin.jar -- Name is ten characters long.

[Top] [Packaging Composer Plug-ins]

Using a Batch File to Create a Zip Archive

MS Windows 95 or NT only

If you are using MS Windows 95 or NT, you can use a batch file, genplug.bat, to package your Composer plug-in. When you run this file from the command line, it creates the class tree for your plug-in (if you leave the code that does this) and the zip archive you need for running in Communicator, and deletes any temporary files created during the process.

This section gives directions for using a batch file to create a zip archive. For more information, see "Packaging Composer Plug-ins."

You can edit the genplug.bat file to handle any plug-in you write. You will find genplug.bat file in the source directory of the Composer Plug-in Kit.

To use genplug.bat to package your plug-in, follow these steps: 

1. From the source/netscape/test/plugin/composer directory of the Composer Plug-in Kit, copy the genplug.bat and netscape_plugin_composer.ini files to the work directory of your plug-in.
   
   
2. Open your copy of netscape_plugin_composer.ini. Edit and save this file. For details, see "Creating the Configuration File." Replace the sample class names and paths with those of your plug-in file.
   
   
3. Open your copy of genplug.bat.
   
   
4. Create the plug-in class tree.
   
   Because the plug-ins belong to the netscape.test.plugin.composer class, the file path inside the zip archive should be netscape\test\plugin\composer. The Composer Plug-in Kit file already contains a series of mkdir and cd commands that accomplish this. If you leave this code, it builds the class tree. This code assumes that you used the composer directory for your work directory when you wrote the plug-in.

mkdir netscape
cd netscape
mkdir test
cd test
mkdir plugin
cd plugin
mkdir composer
cd composer
copy ..\..\..\..\*.class
REM Delete any Testbed classes that were copied.
del Test.class TestDocument.class TestDocumentStream.class ImageEncoderTest.class
cd ..\..\..\..

5. Add this line, which replaces the original zip archive name with a name for your plug-in (for example, cpRedLet.zip)

set PLUGFILE=cpRedLet.zip

Note:
Remember that the name of the zip archive must start with cp.

6. Delete the old zip archive in the directory.

del %PLUGFILE%

7. Make sure that the paths are correct for your system.
   
   
8. Create the zip archive. Do not use file compression. Use this command:

zip -r %PLUGFILE% -n .ini;.class netscape_plugin_composer.ini *.class

Where:

• -r flag: Recursive. For debugging only, add a -v flag (verbose).
• -n .ini;.class: Do not compress files with the .ini or .class extension.
• *.class: All class files in the current directory.

Make sure that all paths in genplug.bat point to the correct locations for your files. Make sure that you have the right name for the Plugins directory.

If present, remove the ECHO OFF setting; this allows you to see more of the processing and makes debugging easier.

9. Clean up any temporary files that were created.

rmdir /s /q netscape

10. When complete, place the plug-in's zip archive (for example, cpTest.zip or cpRedLet.zip) in the Communicator Plugin directory and restart the Communicator.

set PLUGDIR=C:\Program Files\Netscape\Communicator\Program\Plugins
mkdir %PLUGDIR%
copy cpRedLet.zip %PLUGDIR%

Your plug-ins are ready to run in Composer.

Note:
Remember to quit and restart Communicator to make the newly installed Composer Plug-in available. 

Mac OS and Unix:

If you are using Mac OS or Unix, you may want to handle the packaging step by writing a script using one of the scripting languages available on your platform.

[Top] [Using a Batch File to Create a Zip Archive]

Using the JARscript Packager

This section gives directions for packaging a Composer Plug-in in a JAR archive, and provides some troubleshooting tips for JAR processing. For a comparison of JAR and zip archives and an outline of the basic steps in creating a zip or JAR archive, see "Packaging Composer Plug-ins."

The JARscript packager is a command line utility that produces a SmartUpdate installer for a Composer Plug-in. The JARscript packager creates a signed JAR archive that contains the plug-in, places this archive in a signed file with a JavaScript installation script, and installs the signed file in the location you set. For more information aabout signing, see "JARscript and Signing." For information about SmartUpdate, see Using JAR Installation Manager for SmartUpdate.

The end product of the packager is a file called install.jar, which installs itself when dragged to a Composer window. Alternately, the web page author can place a link to the archive on an HTML page. When the user clicks the link, the installation script in the archive runs, installing the plug-in.

You can either run the packager from the command line or use jarscipt.bat, a sample batch file included with the packager application. Although you do not need the batch file to use the packager, using it can save development time.

Both methods draw on settings you create in the JARscript configuration file, packager.ini. If you use the command line, you can override values set in the configuration file if you like. If you use the batch file, the packager draws directly on the values set in the configuration file.

For command line directions, see "Running the JARscript Packager." For batch file directions, see "Using the JARscipt.bat file."

This guide uses cpTest.zip, an archive that contains several working Composer plug-ins, as an example to test the JARscript packager. You can download this file from the Composer Plug-in Samples Page.

• JARscript and Signing
• What You Need
• Using the JARscript Packager to Package a Plug-in
• Troubleshooting for JAR Archives
• Feedback Hints
• Using the JARscipt.bat file
• Tutorial: Packaging cpTest.zip
• Troubleshooting for JARscript Packager

[Top] [Using the JARscript Packager]

JARscript and Signing

A Composer plug-in is a multiple file item that, like a Java applet, must be signed in order to have access to system information. An install file, like the one created by JARscript, must always be signed. For information about security and signing, see Using  the JAR Packager and Netscape Object Signing.

The JARscript packager uses the JAR Packager Command Line, also known as "zigbert," as its signing tool. For more information about zigbert and object signing, see "Object-Signing Command Line Tools for Windows 95 and NT." For download information, see "What You Need."

The packager first determines whether the plug-in needs to be signed. If it does, it unzips the plug-in zip file into the working directory, signs the plug-in with the plug-in certificate, and places the plug-in in a new jar file. If the plug-in does not need to be signed, the packager simply copies it to the working directory and prepares it for the install script.

For both signed and unsigned plug-in files, the packager creates the install.js script and places it in the same directory as the plug-in. It signs the install files by running the batch file template.bat, then it places the plug-in in a new install.jar file.

[Top]  [Using the JARscript Packager]

What You Need

[Top]  [Using the JARscript Packager]

Using the JARscript Packager to Package a Plug-in

To use the JARscript Packager to package a plug-in, follow the steps summarized here. Each step links to a further explanation in the sections that follow.

[Top] [Using the JARscript Packager]

Preparing to Use the JARscript Packager

Before you can use the JARscript command line or batch file to package and install your Composer plug-in, get it ready by following these steps:

Place the Composer Plug-in project in an uncompressed zip or JAR archive.

For directions for creating zip archives, see your zip program documentation. For directions for creating JAR archives, see Using the JAR Packager.

Important:
The names of all Composer plug-in zip or JAR archives must start with "cp" and must be eight characters or fewer in length. See "Naming Rules for JAR and Zip Archives."

Download the JARscript packager and unzip it.

Use a zip program that preserves the directory structure. See "What You Need."

Enter the file location and names in the configuration file, packager.ini.

Open packager.ini in a text editor, in the install directory. This file provides the locations of the zigbert signing tool, the zip utility in use, a working directory, and signing certificate information. If you use the run command, you can override configuration file values at the command line. If you use a batch file, you use only the configuration file settings.

Configuration file settings:

-zl	Enter the location of the zigbert signing tool and the filename without the extension, for example: -zl = d:\\zigbert\\zigbert
-db	Enter the location of your certificate database, for example: -db = c:\\progra~1\\netscape\\users\\testuser\\
-pc	Optional. Enter the certificate used to sign the plug-in. If not used or needed, enter NONE, for example: -pc = NONE
-ic	Enter the Install Certificate used to sign the install file, for example: -ic = Test Object Signer If the name of the Install Certificate includes spaces, you must set the name here; you cannot enter a name with spaces at the command line.
-tools	Enter the location of the zip.exe and unzip.exe tools, for example: -tools = d:\\tools
-w	Enter the path of an empty temporary working directory, for example: -w = d:\\temp

Note:
Use '\\' to represent one backslash in this file. The only initial setting that requires a trailing backslash is the Certificate Database location.

After you change the settings in the configuration file, you use the run command or a batch file to package your plug-in.

[Top] [Using the JARscript Packager]

Running the JARscript Packager

Before you can run the JARscript packager from the command line, follow the steps in "Preparing to Use the JARscript Packager." This includes editing the settings in the configuration file, packager.ini.

This run command places cpTest.zip in a JAR archive and installs it in the Plugins directory. The packager produces a signed file that contains a signed plug-in JAR file and a JavaScript installation script. You can transfer the link to this archive to the server. When a web page writer places a link to this archive on an HTML page, a user can click the link to run the installation script and install the plug-in.

Enter the run command at the command line. Use this format:

java packager %1 %2 -p %3 -loc %4 -vMaj %5 -vMin %6 -vRel %7 -vBld %8

The run command parameters have these values:

$%1

%2

-p %3

-loc %4

-vMaj %5

-vMin %6

-vRel %7

-vBld %8

For example, this command places the cpTest.zip archive in a JAR archive and installs it in the Plugins directory.

java packager d:\test\cpTest.zip d:\work\inTest.jar
-p firewoman -ic "Test Object Signer" -loc plugins
-vMaj 4 -vMin 0 -vRel 7 -vBld 12345

Note that the command changes the plug-in name to inTest.jar. You can use a name change to signal a potential user that the plug-in is ready to download and install. To see how this works, see the Composer Plug-in Samples Page. The icons of the plug-ins on this page have names starting with "in-". When a user downloads one of the plug-ins, the name prefix is automatically changed back to "cp-" during installation.

The -p parameter represents the password, firewoman, for the certificate database.

You can override any configuration setting in the packager.ini file by entering the parameter name and a value for it. This example overrides the -ic setting in the configuration file with the name of a certificate database, "Test Object Signer." Generally, if this name contains spaces, you should set it in the configuration file and not override it at the command line.

The -loc parameter installs the plug-in in the plugins directory, where the Composer can find it.

The last set of parameters, -vMaj-4, -vMin 0, -vRel 7, and -vBld 12345, indicate the Major, Minor, and release versions and the build version number, respectively.

[Top] [Using the JARscript Packager]

Troubleshooting for JAR Archives

These troubleshooting tips can help whether you are using the JARscript program or another method to construct your JAR archive. Remember to follow the general guidelines in "Overview of Packaging a Plug-in" as you construct the JAR archive. For more information about JAR, see Using  the JAR Packager.

If you encounter problems as you create the JAR archive for your Composer Plug-in, check the troubleshooting tips in this section. Go through this list from start to finish. Also, check the feedback hints in this section.

These troubleshooting tips assume that your plug-in already works with the Composer Testbed. If it doesn't, see the tips in "Troubleshooting."

	Make sure that your JAR filename starts with "cp" and is eight characters or less in length.
	Check that your JAR archive is in your work directory, or at least in the directory you expect.
	Make sure that the netscape_plugin_composer.ini configuration file exists, and that this file is at the top level of your JAR archive.
	Does the configuration file have the full name of your plug-in class (packagename.classname)?
	Use the Privilege Manager. This line of code allows your plug-in to read and write files: netscape.security.PrivilegeManager.enablePrivilege("UniversalFileAccess"); You use a different string depending on the privilege you are granting. For more information, see Using  the JAR Packager and Netscape  Object Signing.

[Top] [Using the JARscript Packager]

Feedback Hints

These feedback hints can help whether you are using the JARscript program or another method to construct your JAR archive.

You have several options for checking the feedback from the JAR creation process.

	If yours is the only plug-in and Java starts up when you go to a Composer window, then you can assume that the JAR archive name starts with cp as it should, and that it is in the right directory. See the first two tips in the troublehooting list above.
	Look at the Java Console. Does it say "Can't load class yourClassName"? The Java Console is a Navigator window that displays Java messages produced using thejava.lang.System class variables out or err. To see the Java Console, choose Show Java Console from the Options menu.
	Is your plug-in listed in the Tools menu?
	Do you see the "security exception" message? Follow these two steps (it doesn't matter which you do first) to enable stack tracing for debugging: Quit Communicator and add these two lines to your prefs.js file (in your users/yourUserName directory). user_pref("signed.applets.codebase_principal_support", true); This line lets you test your security code without requiring an object signing certificate. You see the Grant Permission dialogue box only once. user_pref("signed.applets.verbose_security_exception", true); This line prints out stack crawls when security exceptions are thrown. Rename the JIT ("just in time") file (in Communicator program/java/bin directory). The name of the JIT file depends upon your Communicator version. In Windows 4.0, it is called jit3240.dll (32 bit, Communicator version 4.0). This takes the JIT file out of action, and allows stack tracing. Note: After you are done debugging, you can restore the orginal name of the JIT file to turn the JIT back on.

[Top] [Using the JARscript Packager]

Using the JARscipt.bat file

You can save time by using jarscript.bat, the batch file included in the installer directory of the JARscript program. If you use this batch file, you do not need to add flags or call Java; jarscript.bat does this for you.

Before you can run the JARscript packager from the batch file, follow the steps in "Preparing to Use the JARscript Packager." This includes editing the settings in the configuration file, packager.ini, in the installer directory of the JARscript program.

To use jarscript.bat, follow these steps:

Open the jarscript.bat file in a text editor. Edit your path settings if necessary. The path gives the location of the root directory and your Java installation, as in this example:

path = %SystemRoot%\system32;%SystemRoot%;G:\Cafe\Java\Bin;

Save and close the file when you are finished making changes.

Run the batch file from the command line.

The batch file executes this command to run the JARscript executable, Packager, using the path set in the batch file and the command line parameters set in packager.ini.

java Packager %1 %2 -p %3 -loc %4 -vMaj %5 -vMin %6 -vRel %7 -vBld %8

To run jarscript.bat from the command line, use this format:

JARscript %1 %2 %3 %4 %5 %6 %7 %8

Replace each %# parameter with the value for your plug-in. For example, this command places the cpTest.zip plug-in in a JAR archive and installs it in the Plugins directory.

JARscript d:\test\cpTest.zip d:\work\inTest.jar
firewoman "Test Object Signer" plugins 4 0 7 12345

The run command parameters have these values:

$%1

%2

-p %3

-loc %4

-vMaj %5

-vMin %6

-vRel %7

-vBld %8

[Top] [Using the JARscipt.bat file] [Using the JARscript Packager]

Tutorial: Packaging cpTest.zip

By following the steps on this page, you can package and install cpTest.zip, an archive that contains several working Composer plug-ins. This tutorial includes alternate steps for command line and batch file use.

If you have not yet done this, download the JARscript packager and unzip it.

Use a zip program that preserves the directory structure. See "What You Need."

Since cpTest.zip is a zip archive that contains plug-in files, you do not have to place the plug-in files in an uncompressed zip or JAR archive. Note that the plug-in name follows Composer plug-in naming rules: it begins with "cp" and is fewer than eight characters long. See "Preparing to Use the JARscript Packager."

Open and edit the JARscript configuration file, packager.ini.

Enter the file paths and names for your system. Use '\\' to represent one backslash.

• For the -zl setting, enter the location of the zigbert signing tool and filename without the extension, in this example:
  -zl = d:\\zigbert\\zigbert
  Be sure to use '\\' to represent one backslash in this file.
• For the -db setting, enter the location of your certificate database, in this example:
  -db = c:\\progra~1\\netscape\\users\\testuser\\
  Add a trailing backslash to this location only.
• No certificate is used to sign this plug-in; enter NONE:
  -pc = NONE
• For the -ic setting, enter the Install Certificate used to sign the install file, in this example:
  -ic = Test Object Signer
• For the -tools setting, enter the location of the zip.exe and unzip.exe tools, in this example:
  -tools = d:\\tools
• For the -w setting, enter the path of an empty temporary working directory, in this example:
  -w = d:\\temp

Save and close the configuration file. To run the packager from the command line, go to the next step. If you are using a batch file, skip to the following step.

If you are using the command line, enter the run command.
(If you are using jarscript.bat, go to the next step.)

The run command places the plug-in in a JAR archive and installs it in the Plugins directory. In this example, the plug-in is cpTest.zip; the command installs it in the Plugins directory.

java packager d:\test\cpTest.zip d:\work\inTest.jar
-p firewoman -ic "Test Object Signer" -loc plugins
-vMaj 4 -vMin 0 -vRel 7 -vBld 12345 

The plug-in name is changed to inTest.jar. You do not have to change the name, but it offers an advantage.

The password for the certificate database is firewoman.

The example overrides the -ic setting in the configuration file with the name of a certificate database, "Test Object Signer." You can override any configuration file setting at the command line.

The -loc parameter installs the plug-in in the Plugins directory.

The last set of parameters, -vMaj-4, -vMin 0, -vRel 7, and -vBld 12345, indicate the Major, Minor, and release versions and the build version number, respectively.

For more information, see "Running the JARscript Packager." This step places cpTest.zip in a JAR archive and installs it in the Plugins directory. Go on to the last step.

If you are using jarscript.bat, edit the path setting.

Open the jarscript.bat file in a text editor. Edit the path for the packager and parameters of the run command to reflect your system.

The path gives the location of the root directory and your Java installation, as in this example:

path = %SystemRoot%\system32;%SystemRoot%;G:\Cafe\Java\Bin;

Save and close jarscript.bat. For more information, see "Using a Batch File."

Run jarscript.bat from the command line.

The batch file places the plug-in in a JAR archive and installs it in the Plugins directory. In this example, the plug-in is cpTest.zip; the command installs it in the Plugins directory.

JARscript d:\test\cpTest.zip d:\work\inTest.jar
firewoman "Test Object Signer" plugins 4 0 7 12345

For more information, see "Using the JARscipt.bat file." Go on to the last step.

Transfer the link to the archive to the server.

The signed archive produced by the JARscript packager contains a signed plug-in JAR file and a JavaScript installation script.

[Top] [Tutorial] [Using the JARscript Packager]

Troubleshooting for JARscript Packager

	Make sure that your packager.ini file is in the same directory as the executable.
	Check that your packager.ini file information is correct.
	Make sure that you are not missing a component. For example, the globaldata.txt file is required.
	Make sure that the certificate database is valid and correct. This database must be correct if you are working with security.

[Top] [Using the JARscript Packager]

Installing Composer Plug-ins

If you make your plug-in easy to install, you increase the chances that it will be used. You can arrange for users to install your plug-ins in several ways:

• The Communicator JAR Installation Manager (JIM) feature. Designed originally for plug-ins that run in Navigator, you can also use JIM to install Composer Plug-ins. You set up your plug-in so that this feature is triggered when the user displays an HTML page that calls a Composer Plug-in that is not installed.
  
  
• Manual installation. The user copies the plug-in to the appropriate directory by hand.

Plug-ins reside in the following directories, depending on the platform:

• Mac OS: Plug-ins folder or folder targeted by plug-in alias in the Plug-ins folder
• MS Windows: plugins directory
• Unix: Set by the environment variable NPX_PLUGIN_PATH, which defaults to /usr/local/netscape/plugins, ~/.netscape/plugins

The plug-ins directory is in the same directory as the Communicator application.

• Automatic installation. You provide an installation script with the plug-in.

The names of installed Composer Plug-ins appear in the Tools menu.

[Top] 

JAR Installation Manager

The fastest way to install your plug-in on your potential user's hard drive, and the most convenient way for that user, is to take advantage of the Communicator 4.0 JAR Installation Manager (JIM) facility. JIM automatically starts when the user browses to an HTML page that contains a JavaScript install script.

This section is a brief overview of the way that JIM works and how you can prepare your plug-ins to use it. For a thorough discussion of the issues and detailed steps to follow, see Using JAR Installation Manager for Smart Update.

• From the User's Point of View
• Preparing Your Plug-in to Use JIM

[Top] [Installing Plug-ins] 

From the User's Point of View

This is what the user sees when JAR Installation Manager (JIM) starts up:

• The user browses to a web page that contains a JavaScript install script.
  
  
• The Safe Download dialog box appears, and Communicator starts downloading a JAR (Java ARchive) file. The user can stop the download at any time by clicking the Cancel button.
  
  
• When download is complete, one of two security dialog boxes appears, depending on whether the JAR archive is signed or not. The user decides whether to click Install to complete the installation, or Cancel to terminate it.
  
  
• When the installation is complete, the user has access to the new Composer Plug-in.

Note: 
Remember to quit and restart Communicator to make the newly installed Composer Plug-in available. 

[Top] [Installing Plug-ins] 

Preparing Your Plug-in to Use JAR Installation Manager

To give your users the easy access to your plug-ins that JAR Installation Manager (JIM) provides, you add only a few steps to your development process.

• Write an installation script. Writing a JavaScript script gives you two advantages: your script is reusable on any platform, and you can track your software with the Netscape version registry.

Note:
If you use an existing installer, you must write a JavaScript script that starts the installer. 

• Place your plug-in files and the installation script in a JAR (Java ARchive) file. If you decide to use the digital signature security feature, you also include digitally signed files. 
  
  
• Make the JAR file available to users and web page writers at a URL. 

For detailed steps to follow, including a sample installation script and an example that demonstrates installing a plug-in from JavaScript, see the Using JAR Installation Manager for Smart Update.

[Top] [Installing Plug-ins] [Contents] [Previous] [Next] [Last]