Sun ONE Application Framework Component Author's Guide

---

Component Library Overview

Sun ONE Application Framework components are packaged and distributed in ordinary JAR files. The JAR file must contain:

• A component library manifest (/COMP-INF/complib.xml)
• Component library specific Java resources (component classes, ComponentInfo classes, resource bundles, component icon images, and any other ancillary files). Any classes (component, ComponentInfo, and any other ancillary files) should be placed in the JAR in accordance with standard Java convention.

Optionally, a Sun ONE Application Framework component library JAR may contain:

• A special directory named /webapp

The contents of the /webapp directory are called the "Additional Files". This is a Sun ONE Application Framework IDE toolset value add feature that allows developers to distribute arbitrary additional files inside their component library JAR. The Sun ONE Application Framework Sun ONE Application Framework IDE toolset will "unpack" these additional files into the Web application development environment. See Automated Unpacking of "Additional Files" below.

---

Component Library Structure

The contents of a Sun ONE Application Framework component library JAR must be structured as follows:

The Component Manifest

Sun ONE Application Framework requires that each component library JAR contain a special Sun ONE Application Framework component library manifest file. The component library manifest file is a simple XML document that describes the collection of components within the library. A component library manifest may declare any number of components and associated Sun ONE Application Framework component model resources.

The IDE toolset automatically introspects each JAR file mounted in an Sun ONE Application Framework application's WEB-INF/lib directory. It specifically looks inside the JAR for the component library manifest file. If the IDE toolset finds a valid component library manifest file in the prescribed location within the JAR file, the IDE toolset will expose any properly declared components for design time utilization within the IDE toolset. If it does not find the component library manifest file in the expected location within the JAR file, or if the component library manifest is invalid, the IDE toolset will not recognize the JAR as a component library.

The component library manifest must comply with the following strict rules:

• The component library manifest file must be named complib.xml.
• The complib.xml file must be a well formed XML file.
• The complib.xml file must comply with the jato-component-library_1_0.dtd (shown below).
• The complib.xml file must be located in the component library JAR's /COMP-INF directory.

jato-component-library_1_0.dtd

<!--

The component-library element is the root element of the component manifest

-->

<!ELEMENT component-library (tool-info, library-name, display-name, 

	description?, legal-notice?, icon?, interface-version, implementation-version, 

	author-info?, taglib*, component*, extensible-component*, 

	configurable-bean*)>

<!--

The tool-info elements contains information about the tool environment this 

library was written against

-->

<!ELEMENT tool-info (tool-version)>

<!--

The tool-version element contains the interface version of Sun ONE Application 

Framework/JATO this library targets.  Should be a dot-separated version number, 

for example "2.1.0".

-->

<!ELEMENT tool-version (#PCDATA)>

<!--

The library-name element contains the internal name of the component library.  

This name is expected to be globally unique, and should follow the standard 

Java package naming convention. For example, the library name of the Sun ONE 

Application Framework/JATO component library is "com.iplanet.jato", the root of 

its package structure.

-->

<!ELEMENT library-name (#PCDATA)>

<!--

The display-name element contains a short display name of the library which 

will be presented in GUI tools.

-->

<!ELEMENT display-name (#PCDATA)>

<!--

The description element is used to contain descriptive text about its parent

element.

-->

<!ELEMENT description (#PCDATA)>

<!--

The legal-notice element contains legal or copyright text that should accompany 

this library.  This element is meant to provide an additional opportunity to

keep this information in proximity to the library itself; however it should not 

be considered a sufficient means of conveying licensing terms or other legally

binding terms to users of the library.

-->

<!ELEMENT legal-notice (#PCDATA)>

<!--

The icon element contains a small-icon and a large-icon element

which specify the location within the Web application for a small and

large image used to represent the Web application in a GUI tool. At a

minimum, tools must accept GIF format images.

-->

<!ELEMENT icon (large-icon?, small-icon?)>

<!--

The large-icon element contains the resource name within the library

of a file containing a large (32x32 pixel) icon image. The resource name must 

follow standard Java resource name syntax, with individual path elements 

separated by forward slashes ("/").

-->

<!ELEMENT large-icon (#PCDATA)>

<!--

The small-icon element contains the resource location within the library

of a file containing a small (16x16 pixel) icon image.  The resource name must 

follow standard Java resource name syntax, with individual path elements 

separated by forward slashes ("/").

-->

<!ELEMENT small-icon (#PCDATA)>

<!--

The author-info element contains information on the author(s) of this library.

-->

<!ELEMENT author-info (author*, info-resource*) >

<!--

The author element contains information about a particular author of the 

library.

-->

<!ELEMENT author (author-name, description?, author-contact?) >

<!--

The author-name element contains the author's full name.

-->

<!ELEMENT author-name (#PCDATA)>

<!--

The author-contact element contains the author's contact information, usually

an email address.

-->

<!ELEMENT author-contact (#PCDATA)>

<!--

The info-resource element contains information describing external 

informational resources relevant to this library, such as a link to a 

publisher's homepage, a public link to API documentation, or a support email

address.

-->

<!ELEMENT info-resource (info-resource-name, description?, info-resource-contact?) >

<!--

The info-resource-name element contains an arbitrary descriptive name of the 

resource that can be presented to the user of the library.

-->

<!ELEMENT info-resource-name (#PCDATA)>

<!--

The info-resource-contact elements contains the actual contact information

for the resource, such as an email address or HTTP link.

-->

<!ELEMENT info-resource-contact (#PCDATA)>

<!--

The interface-version element contains the interface version of this library, 

used to determine interface compatibility of the contained code.  The version 

should be a dot-separated numeric version number, such as "1.0.0".  The version 

number can contain as many dot-separated elements as desired.

-->

<!ELEMENT interface-version (#PCDATA)>

<!--

The implementation-version element contains the interface version of this 

library, used to determine the implementation version of the contained code.  

This version number usually takes the form of a timestamp or build number.

The version should be a dot-separated numeric version number, such as 

"2003.1.31".  The version number can contain as many dot-separated elements as 

desired.

-->

<!ELEMENT implementation-version (#PCDATA)>

<!--

The taglib element declares any JSP tag libraries included in this library.  

Declared tag libraries will be automatically unpacked from the library and 

registered in the web.xml of the application under this URI.

-->

<!ELEMENT taglib (taglib-uri, taglib-resource, taglib-default-prefix)>

<!--

The taglib-uri element contains a logical URI that will be used to identify the 

tag library within the application.  This URI will be registered to the declared

tab library descriptor in the application's web.xml file.  Note that this URI 

is purely logical and need not have any relation to the physical location of 

the tag library descriptor file (which will be unpacked into a physical location 

determined solely by the GUI tool).  This URI must match the TaglibURI property 

value in a component's JspTagDescriptor.

-->

<!ELEMENT taglib-uri (#PCDATA)>

<!--

The taglib-resource element contains the resource name of the tag library's 

taglib descriptor (.tld) file.  The resource name must follow standard Java 

resource name syntax, with individual path elements separated by forward 

slashes ("/").  This file will automatically be extracted and registered with 

the application.

-->

<!ELEMENT taglib-resource (#PCDATA)>

<!--

The taglib-default-prefix element specifies the tag prefix that should be used

for this tag library in JSP pages that use the tag library.  For example, the

default prefix for the Sun ONE Application Framework/JATO tag library is "jato".  

This prefix may be changed by the JSP author on any given page; this element simply 

gives the default name of the prefix when the tag library declaration is automatically

added to a page.

-->

<!ELEMENT taglib-default-prefix (#PCDATA)>

<!--

The component element declares a non-extensible component within this library.

All components must be declared in the component manifest in order to be

recognized at design-time.

-->

<!ELEMENT component (component-class, component-info-class, design-reference-resource?)>

<!--

The extensible-component element declares an extensible component within this 

library.  All extensible components must be declared in the component manifest 

in order to be recognized at design-time.

-->

<!ELEMENT extensible-component (component-class, component-info-class)>

<!--

The component-class element specifies the fully-qualified class name of the 

component.

-->

<!ELEMENT component-class (#PCDATA)>

<!--

The component-info-class element specifies the fully-qualified name of the 

component's ComponentInfo class.

-->

<!ELEMENT component-info-class (#PCDATA)>

<!--

The design-reference-resource specifies the metadata file resource that will

be used at design-time to inspect the component.  Components without this

declaration will generally not be inspectable at design-time other than through

ComponentInfo. The resource name must follow standard Java resource name 

syntax, with individual path elements separated by forward slashes ("/").

-->

<!ELEMENT design-reference-resource (#PCDATA)>

<!--

The configurable-bean element declares a non-visual bean component contained

within this library.

-->

<!ELEMENT configurable-bean (bean-class)>

<!--

The configurable-bean element specifies the fully-qualified class name of the

non-visual component bean.

-->

<!ELEMENT bean-class (#PCDATA)>

Automated Unpacking of Component Tag Libraries (TLD) Files

As part of a Sun ONE Application Framework component library, a library developer may provide one or more tag libraries to support rendering of the library's View components. Tag libraries are declared in the component library's component manifest file, and when the IDE toolset recognizes the component library, its tag library descriptors (.tld files) are automatically unpacked from the library JAR file for use by the application. In addition, the IDE toolset automatically adds tag library entries to the web.xml file.

Tag library descriptor files are unpacked to a special location under the application's WEB-INF/tld directory based on the name of the library to ensure that same-named files from different libraries do not conflict. In this scheme, library names are converted to directory names by replacing dots (".") with underscores ("_"). For example, the Sun ONE Application Framework Component Library's internal library name is "com.iplanet.jato", which is translated to "com_iplanet_jato" when unpacking the tag library descriptor. The SCL's tag descriptor file ultimately appears under the WEB-INF/tld/com_iplanet_jato directory in your application.

The tag descriptor's derived physical directory name is automatically registered to a logical resource name in the web.xml file for use by the application. This logical name is chosen by the component library author and specified in the component library manifest. In the SCL's case, the descriptor is registered as the resource /WEB-INF/jato.tld.

The tag descriptor unpacking mechanism makes use of timestamps to determine if an existing file should be overwritten when a new version of the library is added to an application. This feature ensures that upgrading of an application's component libraries is just a single step for a developer.

Referring to the example "mycomponents" library described in this guide. The library author has created a tag library tld file called mycomplib.tld and arbitrarily placed it in the mycomponents package. Therefore, looking into the mycomponents.jar file, the tld appears physically located as follows:

Inside of the complib.xml, the component author has declared a taglib element as follows:

Based on the configuration described by the taglib element, whenever the mycomponens.jar is deployed into a Sun ONE Application Framework Web application's WEB-INF/lib directory, the IDE toolset will automatically perform the following steps. These steps will allow the run-time JSP engine to properly locate the tag library. This frees the application developer from having to perform any configuration.

• Automatically adds the following entry to the Web application's web.xml file, which sets up a conventional servlet container run-time mapping between the logical resource and its physical location.

<taglib> <taglib-uri>/WEB-INF/mycomplib.tld</taglib-uri> <taglib-location>/WEB-INF/tld/mycomponents/mycomplib.tld</taglib-location> </taglib>

• Automatically extracts the mycomplib.tld file from the mycomponents.jar, and places it into the following location:

[current app]/WEB-INF/tld/mycomponents/mycomplib.tld

Also, at design-time, as the developer builds application Views, the IDE toolset will perform the following:

• Automatically ensure that the appropriate tag library declaration is present in any associated JSP files. This declaration contains the "prefix" as specified by the component author in the complib.xml's taglib element.

<%@taglib uri="/WEB-INF/mycomplib.tld" prefix="mycomp"%>

• Automatically ensures that as the IDE toolset adds additional component library specific tags to the JSP, it also utilizes the prefix declared in the taglib directive. For example:

<mycomp:validatingTextField name="validatingTextField1"/>

Sun ONE Application Framework recognizes that taglib prefix is a JSP page specific directive. J2EE allows each page to declare arbitrary prefixes for the included tag libraries via the tablib directive. The IDE toolset will always utilize the current taglib directive declared prefix as it parses the JSP looking for tags, or whenever it automatically inserts additional tags into the JSP in conjunction with the developer's View design decisions. The IDE toolset merely utilizes the complib.xml specified taglib "prefix" to insert an initial taglib directive into the application JSP files. Application developers can subsequently manually change the prefix declared in the page specific taglib directive. The IDE toolset thereafter utilizes the newly declared prefix for any additional tags, but it will not automatically change any already declared tags to coincide with the adjusted prefix. This is an application developer issue. It is mentioned here so that component authors fully understand the design-time usage of complib.xml's taglib element.

Automated Unpacking of "Additional Files"

Optionally, a Sun ONE Application Framework component library JAR might contain arbitrary "Additional Files" arranged hierarchically underneath the /webapp directory.

Do not confuse a Sun ONE Application Framework component library JAR's internal /webapp directory with the common servlet container directory called "webapps". There is absolutely no relationship between the two.

The hierarchical arrangement of the files within the Sun ONE Application Framework component library JAR's /webapp root is totally up to the discretion of the component library author. As a value added feature, the Sun ONE Application Framework IDE tools will "unpack" these additional files into the Web application development environment in direct correspondence to the additional files location relative to the /webapp root.

For example, consider a mycomponents.jar that contains the following /webapp structure:

When the mycomponents.jar, with the above content, is deployed into a Sun ONE Application Framework application, the IDE toolset will extract the /webapp content into the particular Sun ONE Application Framework application's structure.

For example, consider a Sun ONE Application Framework application called "AppOne" which has the following initial structure created by the Sun ONE Application Framework IDE toolset.

After "deploying" the mycomponents.jar (for example, dropping it into AppOne/Web-INF/lib), the IDE toolset will discover that it is a Sun ONE Application Framework component library and extract the "additional files" which will result in the creation of the following integrated structure:

Component library authors can leverage the Additional Files Feature to provide any arbitrary resources which they consider appropriate for extraction. Examples of common Additional Files are (but not limited to):

• Component specific JSP files (for example, component pagelets).
• Arbitrary Web application document resources (for example, images, static HTML pages, style sheets, JavaScript).
• Additional arbitrary JAR files.

For example, assume that the component library relies on a custom XML parsing library. The component author can "bundle" that JAR inside the component library JAR. This is potentially a more convenient distribution model than requiring the application developer to deploy these extra libraries manually.

• Arbitrary Web application WEB-INF resources.

For example suppose the component author designs a set of components which support extra configuration via arbitrary configuration file(s). These configuration files can be "bundled" with the component library and extracted into the appropriate location via the Additional Files mechanism.

Sun ONE Application Framework Component Author's Guide

817-4362-10

Copyright © 2003, Sun Microsystems, Inc. All rights reserved.