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

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. Use open() 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. Use close() 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.