Introduction

The Extension toolkit contains classes to represent entrys for "Optional Package" instances (formerly known as "Standard Extension") as described in the manifest of a JAR file. The toolkit can also parse and represent Specification sections described in manifests.

Extensions

The "Optional Package" mechanism can be used to declare is used to declare dependencies on libraries. Prior to JDK1.3, an "Optional Package" was known as an Extension . The specification for this mechanism is available in the JDK1.3 documentation in the directory $JDK_HOME/docs/guide/extensions/versioning.html . Alternatively it is available online at http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html .

Support for the "Optional Package" specification is being mandated by other specifications such as the Servlet 2.3 API . Thus we are likely to see an increase of jars using this mechanism to specify dependencies.

The "Optional Package" mechanism allows jars to specify dependencies on other jars that implement a particular specification at particular version levels. For example you could specify a dependency on the Trax 1.1 API by adding the following to the manifest of your jar.

Extension-List: trax
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
            

In some cases you may also wish to specify a dependency on a specific vendors implementation. For instance you may need to use xalan due to it implementing a particular extension you need. In that case you manifest may contain;

Extension-List: trax
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
trax-Implementation-Title: org.apache.xalan.xslt
trax-Implementation-Version: 2.1.0
trax-Implementation-Vendor: Apache Software Foundation
            

In many cases there will be no distinction between the specification and the implementation of a library. For instance the Velocity project only has one implementation and one specification. In which case it is sufficient to just declare a dependency on the Velocity "Specification". A library that uses both the Trax API and the Velocity project may look like;

Extension-List: trax velocity
velocity-Extension-Name: org.apache.velocity
velocity-Specification-Version: 1.0
trax-Extension-Name: Java API for XML Parsing
trax-Specification-Version: 1.1
trax-Implementation-Title: org.apache.xalan.xslt
trax-Implementation-Version: 2.1.0
trax-Implementation-Vendor: Apache Software Foundation
            

To make other jars available as possible to libraries to add libraries as "Optional Packages" or Extensions then you need to add a few lines to the manifest of the other jar. The minimal manifest is the following;

Extension-Name: org.realityforge.dve
Specification-Vendor: Peter Donald
Specification-Version: 1.0
            

It is important to note that resolving dependencies is recursive. For example, if the library depends upon jar A and and A depends on B then both A and B will need to be loaded by the container.

Using Extension

The Extension class is responsible for both parsing and representing information about Extensions. Example usage;

      
//Get manifest file for library
final Manifest manifest = ...;

// Get a list of extensions that this
// library can provide to other librarys
Extension[] available = Extension.getAvailable( manifest );

// Get a list of extensions that this
// library requires to work
Extension[] required = Extension.getRequired( manifest );