Module openj9.sharedclasses
Package com.ibm.oti.shared

Interface SharedClassTokenHelper

All Superinterfaces:
SharedClassHelper, SharedHelper
public interface SharedClassTokenHelper extends SharedClassHelper

SharedClassHelper API that stores and finds classes using String tokens.

Description

A SharedClassTokenHelper is obtained by calling getTokenHelper(ClassLoader) on a SharedClassHelperFactory.

The SharedClassTokenHelper, which is the most simple type of helper, 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 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.

The ClassLoader is responsible for coordinating the creation of token Strings.

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). 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.

For example, 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 by 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.

See Also:

  • Method Details

    • findSharedClass

      byte[] findSharedClass(String token, String className)
      Finds a class in the shared cache by 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(String token, Class<?> clazz)
      Stores a class in the shared cache by using a specific token.

      The class that is 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 that is 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