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

Interface SharedDataHelper

  • All Superinterfaces:
    SharedHelper
    public interface SharedDataHelper
extends SharedHelper

    SharedDataHelper API that stores and finds byte data using String tokens.

    Description

    A SharedDataHelper is obtained by calling getSharedDataHelper(ClassLoader) on a SharedDataHelperFactory.

    The SharedDataHelper allows byte data to be written into the shared class cache and shared with other VMs.

    Byte data to be stored in the cache should exist in a java.nio.ByteBuffer which is copied to the cache when storeSharedData() is called. The function returns a read-only java.nio.ByteBuffer which is the shared copy of the data. Any subsequent changes to the ByteBuffer are therefore not reflected in the cache unless it is re-stored.

    Byte data is found in the cache by calling findSharedData() which returns a read-only java.nio.ByteBuffer which maps to the byte data that exists in the cache.

    Tokens

    A String token is chosen/generated by the application which is using the Helper and should ideally include a unique identifier and some kind of versioning information. Eg. com.foo.myApp31_myDoozerData_003. The important factor is that other VMs running the same application should be able to apply the same algorithm and find the data.

    Dynamic Cache Updates

    Since the shared cache is persistent beyond the lifetime of a JVM, data in the shared cache may become out-of-date (stale). Using this helper, it is entirely the responsibility of the application to ensure that cache entries are kept up-to-date. Tokens have no meaning to the cache, so effectively turn it into a dictionary of classes.

    E.g. A token may be the location where the class was found, combined with some type of versioning data.

    If an application stores multiple versions of the same data using the same token, only the most recent will be returned by findSharedData.

    See Also:
    SharedHelper, SharedDataHelperFactory, SharedClassPermission

    • Method Detail

      • findSharedData

        ByteBuffer findSharedData​(String token)
        Find data in the shared cache using a specific token.

        Data will be returned only for an exact String match of the token. Otherwise, null is returned.
        The ByteBuffer returned is read-only and cannot be modified.
        If a SecurityManager is installed, findSharedData can only be called by code whose caller-classloader has been granted read permissions to the shared class cache.

        Parameters:
        token - a token to be used as a key
        Returns:
        ByteBuffer a read-only ByteBuffer containing the cached data, or null

      • storeSharedData

        ByteBuffer storeSharedData​(String token,
                           ByteBuffer data)
        Store data in the shared cache using a specific token.

        If the data is stored successfully, the shared read-only copy of the data is returned. Otherwise, null is returned.
        If data already exists for the token specified, the old data is marked stale in the cache and is replaced by the new data.
        If the exact same data already exists in the cache under the same token, the data is not duplicated and the cached version is returned.
        If null is passed as the data argument, the data currently stored against that token is marked stale and null is returned.
        If a SecurityManager is installed, storeSharedData can only be called by code whose caller-classloader has been granted write permissions to the shared class cache.

        Parameters:
        token - a token to be used as a key
        data - a ByteBuffer of data to copy to the cache
        Returns:
        ByteBuffer a read-only ByteBuffer containing the cached data, or null