Interface SharedClassURLHelper

All Superinterfaces:

SharedClassHelper, SharedHelper

public interface SharedClassURLHelper
extends SharedClassHelper

SharedClassHelper API that stores and finds classes by using URL paths.

Description

A SharedClassURLHelper is obtained by calling getURLHelper(ClassLoader) on a SharedClassHelperFactory.

The SharedClassURLHelper is designed for ClassLoaders that load classes from many different locations, without the concept of a classpath. A ClassLoader may find and store classes in the cache using any URL.

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 calls defineClass on the byte[] that is returned.

The ClassLoader calls storeSharedClass immediately after a class is defined, unless the class that is being defined was loaded from the shared cache.

If partitions are required, the ClassLoader is responsible for coordinating the creation and use of partition Strings.

Classes can be stored only by using URLs that have file or jar protocols, and that refer to existing resources. The presence of any other protocol in a URL prevents SharedClassURLHelper from locating and storing classes in the shared cache.

Dynamic Cache Updates

Because the shared cache persists beyond the lifetime of a JVM, classes in the shared cache can become out of date (stale).

Classes in the cache are automatically kept up to date by default:

If findSharedClass is called for a class that exists in the cache but which has been updated on the filesystem since it was stored, then the old version in the cache is automatically marked stale and findSharedClass returns null. The ClassLoader should then store the updated version of the class.

Note that jar/zip updates will cause all cache entries that are loaded from that jar/zip to be marked stale.

(This behaviour can be disabled by using the correct command-line option. See -Xshareclasses:help)

It is also assumed that the ClassLoader maintains a read lock on jar/zip files opened during its lifetime, preventing their modification. This prevents the cache from having to constantly check for updates.

Partitions

A partition can be used when finding or storing a class, which allows modified versions of the same class to be stored in the cache, effectively creating partitions in the cache.

Partitions are designed for bytecode modification such as the use of Aspects. It is the responsibility of the ClassLoader to create partitions that describe the type of modification performed on the class bytes.

If a class is updated on the filesystem and automatic dynamic updates are enabled, then all versions of the class across all partitions will be marked stale.

Class metadata

A ClassLoader might create metadata when loading and defining classes, such as a jar manifest or security data. None of this metadata can be stored in the cache, so if a ClassLoader is finding classes in the shared cache, it must load any metadata that it needs from disk before defining the classes.

Security

A SharedClassHelper will only allow classes that were defined by the ClassLoader that owns the SharedClassHelper to be stored in the cache.

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 by using the SharedClassURLHelper can be retrieved by using the SharedClassURLClasspathHelper and vice versa. This is also true for partitions that can be used across these two helpers.

See Also:

• SharedClassURLHelper
• SharedClassHelperFactory
• SharedClassPermission

Method Summary

Modifier and Type	Method	Description
byte[]	findSharedClass(String partition, URL path, String className)	Finds a class in the shared cache by using a specific URL, class name, and user-defined partition (see Partitions).
byte[]	findSharedClass(URL path, String className)	Finds a class in the shared cache by using a specific URL and class name.
boolean	setMinimizeUpdateChecks()	Minimizes update checking on jar files for optimal performance.
boolean	storeSharedClass(String partition, URL path, Class<?> clazz)	Stores a class in the shared cache by using the URL location it was loaded from and a user-defined partition (see Partitions).
boolean	storeSharedClass(URL path, Class<?> clazz)	Stores a class in the shared cache by using the URL location it was loaded from.

Methods declared in interface com.ibm.oti.shared.SharedClassHelper

getSharingFilter, setSharingFilter

Methods declared in interface com.ibm.oti.shared.SharedHelper

getClassLoader

Method Details

findSharedClass

byte[] findSharedClass(URL path,
 String className)

Finds a class in the shared cache by using a specific URL and class name. A class will be returned if it was stored against the same URL.

Null is returned if the class cannot be found or if it is stale (see Dynamic cache updates).

To obtain an instance of the class, the byte[] returned must be passed to defineClass by the caller ClassLoader.

Also returns false if the URL at foundAtIndex is not a file URL or if the resource it refers to does not exist.

Parameters:

path - URL. A URL path. Cannot be null.

className - String. The name of the class to be found

Returns:

byte[]. A byte array describing the class found, or null.

findSharedClass

byte[] findSharedClass(String partition,
 URL path,
 String className)

Finds a class in the shared cache by using a specific URL, class name, and user-defined partition (see Partitions).

A class returned only if it was stored against the same URL, and was using the same partition. Null is returned if the class cannot be found or if it is stale (see Dynamic cache updates).

To obtain an instance of the class, the byte[] returned must be passed to defineClass by the caller ClassLoader.

Also returns false if the URL at foundAtIndex is not a file URL or if the resource it refers to does not exist.

Parameters:

partition - String. User-defined partition if finding modified bytecode (see Partitions). Passing null is equivalent of calling non-partition findSharedClass call.

path - URL. A URL path. Cannot be null.

className - String. The name of the class to be found

Returns:

byte[]. A byte array describing the found class, or null.

storeSharedClass

boolean storeSharedClass(URL path,
 Class<?> clazz)

Stores a class in the shared cache by using the URL location it was loaded from. The class that is being stored must have been defined by the caller ClassLoader and must exist in the URL location specified. Returns true if the class is stored successfully or false otherwise.

Will return false if the class that is being stored was not defined by the caller ClassLoader.

Also returns false if the URL at foundAtIndex is not a file URL or if the resource it refers to does not exist.

Parameters:

path - URL. The URL path that the class was loaded from. Cannot be null.

clazz - Class. The class to store in the shared cache

Returns:

boolean. True if the class was stored successfully, false otherwise.

storeSharedClass

boolean storeSharedClass(String partition,
 URL path,
 Class<?> clazz)

Stores a class in the shared cache by using the URL location it was loaded from and a user-defined partition (see Partitions).

The class being stored must have been defined by the caller ClassLoader and must exist in the URL location specified. 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.

Also returns false if the URL at foundAtIndex is not a file URL or if the resource it refers to does not exist.

Parameters:

partition - String. User-defined partition if storing modified bytecode (see Partitions). Passing null is equivalent of calling non-partition storeSharedClass call.

path - URL. The URL path that the class was loaded from. Cannot be null.

clazz - Class. The class to store in the shared cache

Returns:

boolean. True if the class was stored successfully, false otherwise.

setMinimizeUpdateChecks

boolean setMinimizeUpdateChecks()

Minimizes update checking on jar files for optimal performance.

By default, when a class is loaded from the shared class cache, the timestamp of the container it was originally loaded from is compared with the timestamp of the actual container on the filesystem. If the two do not match, the original class is marked stale and is not returned by findSharedClass(). These checks are not performed if the container is held open by the ClassLoader.

If the ClassLoader does not want to open the container, but doesn't want the timestamp to be constantly checked when classes are loaded, it should call this function immediately after the SharedClassURLHelper object has been created. After this function has been called, each container timestamp is checked once and then is only checked again if the container jar file is opened.

This feature cannot be unset.

Returns:

boolean. True if the feature has been successfully set, false otherwise.