Component Library Package File Specification

This specification describes a package file format containing a set of third-party components that can be imported into an IDE. As of this writing, NetBeans-based IDEs like Visual Web Pack (VWP) and Sun Java Studio Creator use this format to allow third parties to extend the set of built-in components in the IDE. For more information see AllAboutComplibs.

Please email comments to EdwinGoei. Thanks for the feedback.

Details

A component library contains a set of related components that can be packaged and distributed together in a single complib file. A complib file is a JAR file with an extension of ".complib" instead of the usual extension of ".jar". Its contents contain the components themselves and their design-time JavaBeans which themselves are packaged in jar files. It also may contain other items such as source code zip files, javadoc zip files, and other jar files used at runtime and design-time. Each complib file must contain a logical table of contents, which is physically split into multiple files, that provide information on the complib and lists its contents. Thus, a complib file is similar to a web archive war file in that it contains other jars and content files within it and metadata about its contents.

Resources that may be found in a complib file are defined below:

• runtime jar := a jar file that will be deployed as part of an application at runtime.
• design-time jar := a jar file that will only be used by an IDE at design-time which will not be deployed. A design-time jar file contains metadata on components in the form of standard javabeans BeanInfo classes. It may also contain classes that describe dynamic design-time behavior for components. Because no such java standard yet exists, in the short-term, the dynamic behavior can be specified using the CreatorDesignTimeApi which extends the standard javabeans API. In the future when the dynamic design-time API is standardized, the IDE will support the standard API and the Creator Design-Time API will be deprecated. Other resources used only at design time such as icons may also be contained in the design-time jar.
• javadoc := files produced by the javadoc program to provide API docs which are used by the IDE as an aid to the developer. Not deployed. Optional.
• source := source files which allow IDE end-users to browse component source code. Not deployed. Optional.
• archive := a jar or zip file

The META-INF/MANIFEST.MF of the package jar file contains the following main attributes (ie. headers):

• Required
  • X-Rave-API-Compatibility-Version: 2.0 or 1.0 = specifies the IDE interfaces this component library depends upon. If the value is "2.0", then the following attribute is also required. "1.0" is deprecated.
  • X-Rave-Complib-Configuration: = specifies a path to a complib configuration file that conforms to a specific schema (TODO: provide link). For example, "complib-config.xml".

Examples

A sample META-INF/MANIFEST.MF file is:

X-Rave-API-Compatibility-Version: 2.0
X-Rave-Complib-Configuration: META-INF/complib-config.xml

The contents of META-INF/complib-config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<complibConfiguration
  version="1.1"
  resourceBundleBaseName="ComplibBundle">
  <identifier>
    <!-- Use a URI to uniquely identify your package namespace independent
         of version -->
    <uri>http://www.example.com/products/sample-simple</uri>
    <version>2.3</version>
  </identifier>
  <titleKey>SampleTitleKey</titleKey>

  <runtimePath>
    <pathElement>sample-simple.jar</pathElement>
  </runtimePath>
  <designTimePath>
    <pathElement>sample-simple-dt.jar</pathElement>
  </designTimePath>
  <javadocPath>
    <pathElement>sample-simple-doc.zip</pathElement>
  </javadocPath>
  <sourcePath>
    <pathElement>sample-simple-src.zip</pathElement>
  </sourcePath>
  <webResourcePath>
    <pathElement>web-resources.zip</pathElement>
  </webResourcePath>

  <!-- Help will be implemented in NetBeans 6 -->
  <helpPath helpSetFile="help/help.hs">
    <!-- This JavaHelp jar should contain a HelpSet file "help/help.hs" -->
    <pathElement>sample-simple-help.jar</pathElement>
  </helpPath>

  <!-- Optionally specify a Java EE version API dependency. Default is "1.4".
  <eeSpecification version="5"/>
  -->

  <initialPalette>
    <folder key="MainCategory">
      <item className="com.example.component.DatePicker"/>
      <item className="com.example.convert.SqlUtilDateConverter"/>
      <item className="com.example.component.PopupCalendar"/>
    </folder>
    <!-- 
    <folder key="MiscCategory">
      <item className="com.example.component.DateDisplayer"/>
      <item className="com.example.component.DatePicker"/>
    </folder>
    -->
  </initialPalette>
</complibConfiguration>

The contents of META-INF/ComplibBundle.properties:

# ResourceBundle for complib-config.xml
#
MainCategory=Sample Simple Components
MiscCategory=Miscellaneous

#Complib Title
SampleTitleKey=Sample Simple Components

See CustomComponentLibraries for a complete example.

Updates

• 2007-03-27 Updated for NetBeans Visual Web Pack (VWP)

-- EdwinGoei