Plug-In Packaging

A plug-in is packaged as a Java Archive (JAR) file. The contents and instructions for interpreting the contents of the JAR file are contained in an optionally signed plugin-descriptor.xml file located in the top-level directory of the JAR file. The syntax of the plug-in descriptor is specified using XML Schema as per the May 2, 2001 W3C Recommendation (http://www.w3.org/TR/2001/xmlschema-0-20010502/). The schema can be used in conjunction with a validating parser to determine the syntactical validity of a plug-in descriptor file.

Recommended Naming

To avoid potential conflicts, you should use a Java package naming convention for plug-ins (com.companyname.productname, for example, com.sun.solaris). Any objects that can be in a folder should be placed in a folder directory structure that mirrors the plug-in name, such as /com/sun/solaris. The plug-in JAR file name should use the convention pluginname_version.jar, for example com.sun.solaris_1.1.jar.

Installation Considerations

To install a plug-in, service provisioning administrators load the plug-in JAR file.

Plug-In Upgrade Considerations

To upgrade from an existing version of a plug-in to a newer version of a plug-in, you provide a patch JAR file that contains only the contents needed for the patch . For example, if you only changed two component types between version 1.2 and version 1.3, then your upgrade patch would contain only those new component type XML files. Define your patch so that it can be applied in series to upgrade multiple versions . For example, to upgrade from version 1.0 to version 1.2, a user would first apply the upgrade from 1.0 to 1.1, then apply the upgrade from version 1.1 to version 1.2. Update patches are strictly additive with respect to the previously loaded version of the plug-in. You can also create a patch that would upgrade from a specific existing version (for example, 1.0) to a specific newer version (for example, 1.3). However, you cannot create a patch to upgrade from any arbitrary version to a higher version.

Uninstalling Plug-In Versions

You cannot uninstall an individual patch of a plug-in, and you cannot delete objects created by previous versions of a plug-in. To remove this content, you would need to uninstall the current version of the plug-in and reinstall the older version of the plug-in. Alternatively, you could create an anti-patch that would install the old plug-in version's code while creating new versions of the plug-in defined objects.

Component Versions and Dependencies

Objects that are defined by a plug-in are loaded at installation time in the order in which they are defined in the plug-in descriptor file. These objects may only reference other objects that were defined either earlier in the plug-in or in a plug-in on which the defining plug-in directly depends. Any dependencies must be declared in the plug-in descriptor file. If a plug-in attempts to create a versioned object that matches a same typed and named object existing in the system, a new version of the object is created. The minor version of this object is incremented unless the plug-in definition explicitly defines the object as requiring a major version increment. If a plug-in attempts to create a non-versioned object that matches a same typed and named existing object, the plug-in object replaces the previous definition of the object. In both the versioned and unversioned cases, the existing object must have been created by a prior version of the same plug-in that is attempting to create the new version of the object.

Certificates

If the plug-in descriptor file is signed for one version of a plug-in, then the file must be signed for any subsequent versions of that plug-in. Use the standard jarsigner tool to sign the plug-in descriptor file. If the file is signed, the signature will be verified against the public certificate when the plug-in is installed. When upgrading a plug-in, the certificate used to sign the newer version is matched against the certificate used to sign the existing version in the system. The upgrade will not succeed if certificates have expired between plug-in versions.

You should sign all entries in the plug-in JAR (not just the plug-in descriptor file) with the same certificate. Only a single certificate may be attached to each entry.

Security Considerations

A plug-in does not include facilities for defining groups or permissions. This is because permission management depends highly on the environment into which the plug-in is loaded, and cannot be effectively modeled for all environments.

The administrator who adds the plug-in must decide what permissions are appropriate. The general expectation is that plug-ins are designed to be used by everyone. However, certain clients may wish to limit the use of a plug-in to a certain group. Plug-ins may also have certain folders that are meant to have different execution permissions.

Plug-In readme.txt File

You can provide a readme.txt file with your plug-in, if needed. The plug-in readme.txt file is intended as the holding place for instructions on configuring the system for a plug-in. In general, the readme.txt file should document the permissions, session variables, and other instance-specific settings required for the plug-in to function. Specifically, the readme.txt should contain instructions for setting permissions on plug-in created folders, as well as enumerating expected session variables, their descriptions and encryption methods.