com.ibm.as400.access

Class ClusteredHashTable

  • java.lang.Object
    • com.ibm.as400.access.ClusteredHashTable
  • All Implemented Interfaces:
    java.io.Serializable


    public class ClusteredHashTable
    extends java.lang.Object
    implements java.io.Serializable
    Provides access to an IBM i highly available Clustered Hash Table. A Clustered Hash Table is represented as an IBM i server job. A Clustered Hash Table is a container for small to medium-sized non-persistent data that is replicated to the Clustered Hash Table domain. The Clustered Hash Table domain is comprised of nodes defined in a cluster. The Clustered Hash Table domain is defined using the STRCHTSVR CL command.

    For further details on a cluster, see the Cluster Resource Services APIs and the Clustering topic in the IBM i Information Center.

    The purpose of this class is to provide interfaces to the Clustered Hash Table APIs. An instance of this class can be used to put() and get() keyed entries from the Clustered Hash Table. The entries stored in the Clustered Hash Table are replicated to cluster nodes defined in the Clustered Hash Table domain.

    A connection to the Clustered Hash Table server is required to access the Clustered Hash Table. Call open() to obtain the connection. After the open() is complete, entries defined by the ClusteredHashTableEntry class can be put into the table or retrieved from the table, using the methods put() or get(). A key is required to put() an entry in the Clustered Hash Table. Use generateKey() to generate a universally unique key. The elements() method will return a list of all that keys in the clustered hash table. It is recommended to close() the active connection when done to release system resources that are no longer needed.

    This class uses the ClusteredHashTableEntry class for the get(), elements() and put() methods.

    Example Usage:

    import com.ibm.as400.access.*;
    import java.io.*;
    import java.net.*;
    import java.util.*;

    public class MyFile extends Object
    {
    public static void main(String args[]) {

    ClusteredHashTableEntry myEntry = null;
    String myData = new String("This is my data");

    try{
    AS400 the400 = new AS400();

    // CHTSVR01 is the clustered hash table server name
    ClusteredHashTable cht = new ClusteredHashTable(the400,"CHTSVR01");

    cht.open(); // make a connection

    byte[] key = null;
    key = cht.generateKey(); // get a key to access data with

    // key is the key generated to access the data with
    // myData is a byte array of data to be stored
    // 2400 is the time to live in seconds
    // ENTRY_AUTHORITY_ANY_USER indicates any user can access the data
    // DUPLICATE_KEY_FAIL indicates if the key already exists in the hash table to not allow the request to succeed.
    myEntry = new ClusteredHashTableEntry(key,myData.getBytes(),2400,ClusteredHashTableEntry.ENTRY_AUTHORITY_ANY_USER,ClusteredHashTableEntry.DUPLICATE_KEY_FAIL);

    cht.put(myEntry); // store the entry in the hash table

    ClusteredHashTableEntry output = cht.get(key); // retrieve the data

    cht.close();
    }
    catch(Exception e){}

    }
    }

    Note: This class uses APIs that are available only when connecting to systems running OS/400 V5R2M0 or later.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int ALL_ENTRIES
      Entry status value to retrieve all entries on a node.
      static int CONSISTENT_ENTRIES
      Entry status value to limit retrieved entries to only those which are consistent between nodes.
      static int INCONSISTENT_ENTRIES
      Entry status value to limit retrieved entries to only those which are inconsistent between nodes.
    • Constructor Summary

      Constructors 
      Constructor and Description
      ClusteredHashTable()
      Constructs a default ClusteredHashTable object.
      ClusteredHashTable(AS400 system, java.lang.String name)
      Constructs a ClusteredHashTable object that represents the IBM i clustered hash table server.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
      Adds a listener to be notified when the value of any bound property is changed.
      void close()
      Closes a connection to the Clustered Hash Table server.
      boolean containsKey(byte[] key)
      Indicates if the specified key is in the clustered hash table.
      ClusteredHashTableEntry[] elements()
      Retrieves a list of entries that exist in the clustered hash table for the specified user profile.
      ClusteredHashTableEntry[] elements(java.lang.String userProfile, java.lang.String lastModifiedProfile, int status)
      Retrieves a list of entries that exist in the clustered hash table for the specified user profile.
      byte[] generateKey()
      Generates a 16-byte universally unique key.
      ClusteredHashTableEntry get(byte[] key)
      Returns information from the clustered hash table for the specified key.
      java.lang.String getHandle()
      Returns the name of the clustered hash table connection handle.
      java.lang.String getName()
      Returns the name of the clustered hash table server.
      AS400 getSystem()
      Returns the system object for the clustered hash table.
      boolean isEmpty()
      Indicates if the clustered hash table contains any keys.
      void open()
      Opens a connection to the Clustered Hash Table server.
      void put(ClusteredHashTableEntry entry)
      Put an entry in the clustered hash table identified by the connection handle.
      void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
      Removes the listener from being notified when a bound property changes.
      void setName(java.lang.String name)
      Sets the name for the clustered hash table server.
      void setSystem(AS400 system)
      Sets the node of the clustered hash table.
      int size()
      Return the number of entries in the clustered hash table.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • CONSISTENT_ENTRIES

        public static final int CONSISTENT_ENTRIES
        Entry status value to limit retrieved entries to only those which are consistent between nodes.
        See Also:
        Constant Field Values
      • INCONSISTENT_ENTRIES

        public static final int INCONSISTENT_ENTRIES
        Entry status value to limit retrieved entries to only those which are inconsistent between nodes.
        See Also:
        Constant Field Values
      • ALL_ENTRIES

        public static final int ALL_ENTRIES
        Entry status value to retrieve all entries on a node.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ClusteredHashTable

        public ClusteredHashTable()
        Constructs a default ClusteredHashTable object. The hash table serevr name and system must be set before opening a connection.
      • ClusteredHashTable

        public ClusteredHashTable(AS400 system,
                          java.lang.String name)
        Constructs a ClusteredHashTable object that represents the IBM i clustered hash table server.
        Parameters:
        system - The system that contains the clustered hash table server.
        name - The name of an clustered hash table server. This is a 10-byte string that identifies the Clustered Hash Table server to use.
    >
    • Method Detail

      • containsKey

        public boolean containsKey(byte[] key)
                            throws AS400Exception,
                                   AS400SecurityException,
                                   ErrorCompletingRequestException,
                                   java.io.IOException,
                                   java.lang.InterruptedException,
                                   ObjectDoesNotExistException
        Indicates if the specified key is in the clustered hash table. Expired entries will not be included. This method implicitly opens the connection to the clustered hash table server.

        Restrictions:

        • The clustered hash table server must be active on the system.
        Parameters:
        key - The possible key.
        Returns:
        Returns true if and only if the specified key is in this clustered hash table; false otherwise.
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • elements

        public ClusteredHashTableEntry[] elements()
                                           throws AS400Exception,
                                                  AS400SecurityException,
                                                  ErrorCompletingRequestException,
                                                  java.io.IOException,
                                                  java.lang.InterruptedException,
                                                  ObjectDoesNotExistException
        Retrieves a list of entries that exist in the clustered hash table for the specified user profile. *ALL can be used for either user profile to retrieve all entries. This method will create a temporary user space on the system in the QUSRSYS library. If the user space exists, it will be deleted and recreated. This method implicitly opens the connection to the clustered hash table server.

        Restrictions:

        • The Clustered Hash table server must be active on the system.
        Returns:
        Returns an array of all the ClusteredHashTableEntry objects including keys but not data.
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • elements

        public ClusteredHashTableEntry[] elements(java.lang.String userProfile,
                                         java.lang.String lastModifiedProfile,
                                         int status)
                                           throws AS400Exception,
                                                  AS400SecurityException,
                                                  ErrorCompletingRequestException,
                                                  java.io.IOException,
                                                  java.lang.InterruptedException,
                                                  ObjectDoesNotExistException
        Retrieves a list of entries that exist in the clustered hash table for the specified user profile. *ALL can be used for either user profile to retrieve all entries. Only entries that match the specified status will be returned. This method will create a temporary user space on the system in the QUSRSYS library. If the user space exists, it will be deleted and recreated. This method implicitly opens the connection to the clustered hash table server.

        Restrictions:

        • The Clustered Hash table server must be active on the system.
        Parameters:
        userProfile - The owner of the entries to be returned. If null is specified, *ALL will be used and the results will depend upon the lastModifiedProfile. If both the userProfile and the lastModifiedProfile profiles are null, all the entries in the clustered hash table that meet the criteria specified for the other parameters will be returned.
        lastModifiedProfile - The most recent modifier of the entries to be returned. If null is specified, *ALL will be used and the returned entries will depend on the value passed in for the userProfile.
        status - The type of entries to return. Possible values are:
        • CONSISTENT_ENTRIES
        • INCONSISTENT_ENTRIES
        • ALL_ENTRIES
        Returns:
        Returns an array of all the ClusteredHashTableEntry objects including keys but not data.
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • get

        public ClusteredHashTableEntry get(byte[] key)
                                    throws AS400Exception,
                                           AS400SecurityException,
                                           ErrorCompletingRequestException,
                                           java.io.IOException,
                                           java.lang.InterruptedException,
                                           ObjectDoesNotExistException
        Returns information from the clustered hash table for the specified key. If the entry exists, is not expired, and the requesting user is authorized, the information will be returned. The time to live and update option parameters can not be retrieved from the hash table and so will be given defaulted values. This method implicitly opens the connection to the clustered hash table server.

        Restrictions:

        • The Clustered Hash table server must be active on the IBM i system.

        For information on the authority considerations, see the Clustered Hash Table APIs.

        Parameters:
        key - The key to use to return information.
        Returns:
        The entry for the specified key
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • getHandle

        public java.lang.String getHandle()
        Returns the name of the clustered hash table connection handle.
        Returns:
        Returns the clustered hash table connection handle name as a 16-byte string, or null if it hasn't been set yet.
      • getName

        public java.lang.String getName()
        Returns the name of the clustered hash table server.
        Returns:
        Returns the clustered hash table server name.
      • getSystem

        public AS400 getSystem()
        Returns the system object for the clustered hash table.
        Returns:
        The system object for the clustered hash table.
      • isEmpty

        public boolean isEmpty()
                        throws AS400Exception,
                               AS400SecurityException,
                               ErrorCompletingRequestException,
                               java.io.IOException,
                               java.lang.InterruptedException,
                               ObjectDoesNotExistException
        Indicates if the clustered hash table contains any keys. Expired entries will not be included for purposes of determining if the hash table is empty. This method implicitly opens the connection to the clustered hash table server.

        Restrictions:

        • The Clustered Hash table server must be active on the system.
        Returns:
        Returns true if the clustered hash table does not contain any keys; false if the clustered hash table contains keys.
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • put

        public void put(ClusteredHashTableEntry entry)
                 throws AS400Exception,
                        AS400SecurityException,
                        ErrorCompletingRequestException,
                        java.io.IOException,
                        java.lang.InterruptedException,
                        ObjectDoesNotExistException
        Put an entry in the clustered hash table identified by the connection handle. The storage for the entry is not persistent. Not persistent means the storage for the entry is only known to the clustered hash table server on the local node and only available until the clustered hash table server is ended.

        This request to store an entry is replicated to other nodes in the clustered hash table domain. Control will not be returned until the entry is stored in the clustered hash table on all active nodes in the clustered hash table domain.

        There is no encrypting of the information that is replicated and stored in the clustered hash table.

        When an entry is stored, a time to live value is specified. The entry can become expired, when the time to live value has expired. Expired entries will be removed when processing various functions.

        The user that originally stores the entry will be the owner of the entry. The owning user profile will be used in determining authorization to an entry.

        Information stored in the clustered hash table is associated with a key. The key can be generated using the generateKey() method or the user can generate their own.

        Duplicate keys are not supported. An entry associated with an existing key can be updated if the requesting user is the owner of the entry or is authorized to the entry.

        This method implicitly opens the connection to the clustered hash table server.

        Parameters:
        entry - This object describes the information to put in the clustered hash table.
        Throws:
        AS400Exception - If the system returns an error message.
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist.
      • removePropertyChangeListener

        public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
        Removes the listener from being notified when a bound property changes.
        Parameters:
        listener - The PropertyChangeListener.
        See Also:
        addPropertyChangeListener(java.beans.PropertyChangeListener)
      • setName

        public void setName(java.lang.String name)
        Sets the name for the clustered hash table server. The name can only be set while a connection is not established.
        Parameters:
        name - The name of the clustered hash table server.
        Throws:
        ExtendedIllegalArgumentException - If the user specifies a name longer than 10
      • setSystem

        public void setSystem(AS400 system)
        Sets the node of the clustered hash table. The system can only be set while a connection is not established.
        Parameters:
        system - The system.