This document provides an overview of SLEE 1.1 library components and how they can be used to include external libraries in the SLEE.
What is a Library Component?
A library component is a SLEE component that provides a common set of functionality or resources to other components installed in the SLEE. A libray component may add or extend support for a standard API to the SLEE, for example JAIN SIP, Java Mail and the JavaBeans Activation Framework, or Apache log4j, add some useful utility classes, or just allow access to a set of resource files included with it.
A library component is a passive component. At the most basic level, a library component does nothing more than add a set of classes and/or resources to the classpath of any component that references it. Other components installed in the SLEE interact in the first instance with the library, rather than the other way around. The SLEE itself never has any direct interaction with a library component.
Library components supercede the SLEE 1.0 use of manifest classpath entries to reference jars containing common functionality. The use of manifest classpaths was ill-defined by the SLEE 1.0 specification and was also very limited in scope. Shared access of manifest classpath jars between components within the same deployable unit was undefined, and as manifest classpath jars had no component identity, they could not be shared between deployable units. Library components solve these problems by formalising a description of what constitutes a library, and providing libraries with component identity that may be referenced by all other components in the SLEE.
Why Use a Library Component?
A library component is ideal for use where it is desired to use a predefined and prepackaged Java API in the SLEE. JAIN SIP, JAIN TCAP, Java Mail, Apache log4j, and so on are all good examples. These APIs stand alone in their own right, have an obvious name, vendor, and version, and are cleary designed to be shared between many different applications.
Library components can also be used to solve classloading issues between components deployed in the SLEE. The following examples illustrate some cases where library components could be used to solve such problems:
- Two profile specifications, defined in different component jars, make use the same class XYZ. Class XYZ has public visibility to an SBB which depends on both the profile specifications. If class XYZ is included in each profile specification then it's possible for the SLEE to end up with two copies of the class loaded in the JVM - one for each profile specification. The SBB will inherit one of the XYZ class definitions (whichever happens to be loaded first by the SBB's classloader hierarchy), and since the JVM considers the two class instances to be different classes, problems will occur when the SBB tries to interact with the profile specification for which the SBB's XYZ class is not compatible. The problem can be resolved by moving class XYZ into a library then updating the profile specifications so they both reference the library. The result is one definiton of class XYZ being loaded by the JVM and shared by all of the profile specifications and the SBB.
- An SBB uses a profile specification to store a value obtained from a resource adaptor in a profile table. The value is an instance of a class defined by the resource adaptor type. Profile specifications can only reference libraries and other profile specifications, therefore a profile specification cannot inheirit the class definition for the value from the resource adaptor type. The only way such a scenario could work successfully is if the the value class was defined in a library component which was referenced by both the resource adaptor type and the profile specification. Only with such a dependency structure could compatible value arguments be passed between the SBB and profile specification, and vice versa.
Structure of a Library Component Jar
A library component jar is typically structured by adopting one of the following strategies:
- Class and resource files are included directly in the library component jar. The SLEE includes the component jar in the classloader for the library so that the classes and resources can be accessed.
- Prepackaged jars containing class and resource files are included in the library component jar, ie. jars within the jar. The SLEE extracts nested jars from the component jar upon deployment and includes the extracted jars in the classloader for the library so that the classes and resources contained by them can be accessed.
For all cases where an API is released as one or more prepackaged jars, it is recommended to include those jars, as is, in a library component, rather than extracting their contents and packaging them differently. By leaving the jars untouched it ensures that any jar meta information, security signing, or any other aspect of the jar is maintained and carried forward to the library component. There should be never any need to repackage a jar just to encase it in a SLEE library component. A library component jar containing the JAIN SIP 1.2 API might, for example, contain the following files:
If you are not dealing with prepackaged jars, it generally makes sense to include the classes directly in the library component jar. For example, the OpenCloud SIP Extensions library jar looks like:
Assigning Security Permissions to Library Classes
The library component deployment descriptor allows security permissions above and beyond what SLEE provides as standard to be granted to library classes. Security permissions may be granted to:
- the component jar, in which case any classes included directly in the component jar receive the permissions; and
- prepackaged jars nested in the component jar, in which case any classes included in the nested jars receive the permissions.
Nested jars do not inherit security permissions granted to the component jar. If a nested jar requires security permissions to function correctly then the permissions must be specified for the jar rather than relying on any permissions defined for the component jar. This is a common error.
The deployment descriptor fragment below illustrates where security permissions can be specified.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE library-jar PUBLIC "-//Sun Microsystems, Inc.//DTD JAIN SLEE Library 1.1//EN" "http://java.sun.com/dtd/slee-library-jar_1_1.dtd">
Security permissions for nested-jar-1.jar are declared here
Security permissions for nested-jar-2.jar are declared here
Security permissions for classes included directly in the component jar are declared here