# What's New for Packaged Java Control Authors

Release: WebLogic Workshop version 8.1 Service Pack 2

## Overview

Workshop SP2 introduces automatic installation support for packaged 3rd-party controls. To take advantage of this support, the control must be packaged into a ZIP file with a specified format. This ZIP file may include control help files and control samples. Workshop also now supports a "control stub" file that appears to the user as an available control. If requested by the user, Workshop will initiate a download of a control deliverable from a URL specified in the stub. See the help topic Packaging Controls for details on the new control packaging and installation support.

Control help files can now be included in this ZIP file and will participate in the automatic installation process. The 3rd-party directory structure for help files has changed from 8.1.1 to accomodate this feature. Also, the toc.xml entries for 3rd party help are now under the "extensions" anchor. Please see the topic Help Authoring Guide for more details on integrating help in Workshop.

## Control Deliverable Format

Control deliverables are ZIP files expected to contain three top-level directories:

- controls — contains the control implementation JAR, and any dependency JARs
- help — documentation and Javadoc around the control
- samples — samples that use the control

This ZIP file is the same as produced by starting with a Control Deliverable project, adding some help and samples content files to the appropriate directories in the tree, and using the Build Control Deliverable command. By default, any JARs found in APP-INF/lib at build time are assumed to be required for the control and are bundled into the ZIP.

Note that only a single control implementation JAR can live in the controls folder of the ZIP file. Multiple controls, however, may be bundled into the control implementation JAR. For each application, when a user first tries to install the 3rd-party control into it, the control implementation JAR and all its dependency JARs will be copied to the application's Libraries folder.
The help directory must be organized in the following format:
help
doc
en
partners
<vendor name>
java-class
javadoc-tag

ja (for Japanese content)
partners
...

The samples directory must be organized in the following format:
samples
partners
<vendor name>
sample1

## Control deliverable installation process

When a control deliverable or stub is found on the External Components path it becomes "available". Workshop automatically adds the control title and its icon to the Insert -> Controls menu and the Application context (right-click) Install menu. If the user chooses to add an available control to an Application, Workshop does the control installation as follows:

- If a control stub, the user is asked whether he or she wants to download the control implementation.
- If the user answers yes, Workshop attempts to download the control deliverable from the location specifed in the jc-stub.xml.
- When the download is complete the ZIP file is checked for a signature and the user is prompted with the results of this check. If the user agrees, the stub file is moved to the <BEA_HOME>/ext_components/.installed_subs directory and installation now proceeds as if the control deliverable itself were found on the External Components path.
- Any JAR files found under the /controls directory are copied to the current Application's Libraries folder (APP-INF/lib). This may include associated JARs needed by the control.
- If this is the first time a the user has installed the control into any application, the contents of the "help" folder will be copied to $BEA_HOME/$WEBLOGIC_HOME/workshop/help/
- If this is the first time a the user has installed the control into any application, the contents of the "samples" folder will be copied to $BEA_HOME/$WEBLOGIC_HOME/samples/partners/
- Workshop initiates a rebuild of the help index to incoporate the control's help content.

Related Topics

None.