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()
andget()
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 theClusteredHashTableEntry
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. UsegenerateKey()
to generate a universally unique key. Theelements()
method will return a list of all that keys in the clustered hash table. It is recommended toclose()
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.
-
-
-
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
-
addPropertyChangeListener
public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a listener to be notified when the value of any bound property is changed.- Parameters:
listener
- The PropertyChangeListener.- See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener)
-
close
public void close() throws AS400Exception, AS400SecurityException, ErrorCompletingRequestException, java.io.IOException, java.lang.InterruptedException, ObjectDoesNotExistException
Closes a connection to the Clustered Hash Table server. After this method is called, the clustered hash table server will not allow any more requests with the specified connection handle. Useopen()
to establish a connection to a new Clustered Hash Table server.- 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 on the system.
-
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.
-
generateKey
public byte[] generateKey() throws AS400Exception, AS400SecurityException, ErrorCompletingRequestException, java.io.IOException, java.lang.InterruptedException, ObjectDoesNotExistException
Generates a 16-byte universally unique key. This key can be used to put() information in the Clustered Hash Table. 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:
- The generated 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.
-
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.
-
open
public void open() throws AS400Exception, AS400SecurityException, ErrorCompletingRequestException, java.io.IOException, java.lang.InterruptedException, ObjectDoesNotExistException
Opens a connection to the Clustered Hash Table server. The name and system must be set before invoking this method. The name and system are committed at this time. Useclose()
to close the connection from the Clustered Hash Table server.Restrictions:
- The Clustered Hash table server must be active on the system.
- 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.
-
size
public int size() throws AS400Exception, AS400SecurityException, ErrorCompletingRequestException, java.io.IOException, java.lang.InterruptedException, ObjectDoesNotExistException
Return the number of entries 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.
- Returns:
- The number of entries 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.
-
-