com.ibm.oti.shared
Interface SharedClassTokenHelper

All Superinterfaces:
SharedClassHelper
All Known Implementing Classes:
SharedClassTokenHelperImpl

public interface SharedClassTokenHelper
extends SharedClassHelper

Shared Class Helper API that stores and finds classes using String tokens.

- Description

A SharedClassTokenHelper is obtained by calling getSharedClassTokenHelper(ClassLoader) on a SharedClassHelperFactory.
The SharedClassTokenHelper is the most simple type of helper, which uses generated String tokens to find and store classes.

- Usage

The ClassLoader should call findSharedClass after looking in its local cache and asking its parent (if one exists). If findSharedClass does not return null, the ClassLoader should call defineClass on the byte[] returned.
The ClassLoader should call storeSharedClass immediately after a class has been defined, but NOT if the class being defined was loaded from the shared cache.
The ClassLoader is reponsible for coordinating the creation of token Strings.

- Dynamic Cache Updates

Since the shared cache is persistent beyond the lifetime of a JVM, classes in the shared cache may become out-of-date ("stale"). Using this helper, it is entirely the responsibility of the ClassLoader to ensure that cache entries are kept up-to-date. Tokens have no meaning to the cache, so effectively turn the it into a dictionary of classes.
Eg. A token may be the location where the class was found, combined with some type of versioning data.
If a ClassLoader stores multiple versions of the same class using the same token, only the most recent will be returned by findSharedClass.

- Security

A SharedClassHelper will only allow classes to be stored in the cache which were defined by the ClassLoader that owns the SharedClassHelper.
If a SecurityManager is installed, SharedClassPermissions must be used to permit read/write access to the shared class cache. Permissions are granted by ClassLoader classname in the java.policy file and are fixed when the SharedClassHelper is created.
Note also that if the createClassLoader RuntimePermission is not granted, ClassLoaders cannot be created which in turn means that SharedClassHelpers cannot be created.

- Compatibility with other SharedClassHelpers

Classes stored using the SharedClassTokenHelper cannot be retrieved using any other type of helper and vice-versa.

Version:
initial
Author:
OTI
See Also:
SharedClassHelper, SharedClassHelperFactory, SharedClassPermission

Method Summary
 byte[] findSharedClass(java.lang.String token, java.lang.String className)
          Find a class in the shared cache using a specific token and class name.
 boolean storeSharedClass(java.lang.String token, java.lang.Class clazz)
          Store a class in the shared cache using a specific token.
 
Methods inherited from interface com.ibm.oti.shared.SharedClassHelper
getClassLoader
 

Method Detail

findSharedClass

byte[] findSharedClass(java.lang.String token,
                       java.lang.String className)
Find a class in the shared cache using a specific token and class name.

A class will be returned only for an exact String match of both the token and class name. Otherwise, null is returned.
To obtain an instance of the class, the byte[] returned must be passed to defineClass by the caller ClassLoader.

Parameters:
token - String. A token generated by the ClassLoader
className - String. The name of the class to be found
Returns:
byte[]. A byte array describing the class found, or null.

storeSharedClass

boolean storeSharedClass(java.lang.String token,
                         java.lang.Class clazz)
Store a class in the shared cache using a specific token.

The class being stored must have been defined by the caller ClassLoader.
Returns true if the class is stored successfully or false otherwise.
Will return false if the class being stored was not defined by the caller ClassLoader.

Parameters:
token - String. A token generated by the ClassLoader
clazz - Class. The class to store in the shared cache
Returns:
boolean. True if the class was stored successfully, false otherwise.