com.ibm.as400.access.list
Class OpenList

java.lang.Object
  |
  +--com.ibm.as400.access.list.OpenList

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

SpooledFileOpenList

public abstract class OpenList

extends java.lang.Object

implements java.io.Serializable

Abstract base class that wraps a list of resources on the iSeries server. OpenList classes are Java wrappers for system APIs that are known as "Open List APIs" or "QGY APIs".

The way an open list works is that a request is initially sent to the server with selection, filter, and sort information that is to be applied to the list of resources. The server compiles a list of resources that satisfy the requested set of selection parameters. The OpenList class can then retrieve the list all at once, or in pieces, depending upon the memory and performance requirements of the application.

The server can be told explicitly to compile the list of resources by calling open(). If open() is not called explicitly by the application, an implicit call to open() is made by any of the following methods: getLength(), getItems(), and getItems(int,int).

Once the list is open, the application can retrieve resources from the list using either getItems() or getItems(offset, length). One returns an Enumeration, the other returns an array and allows for arbitrarily indexing into the list on the server. The type of resource returned is determined by the type of subclass that extends OpenList. For example, the SpooledFileOpenList class returns SpooledFileListItem objects when getItems() is called.

When an OpenList object is no longer needed by the application, close() should be called to free up resources on the server. If close() is not explicitly called, an attempt will be made to automatically close the list when the OpenList object is garbage collected.

See Also:

Serialized Form

Field Summary

protected static ProgramParameter	EMPTY_ERROR_CODE_PARM Constant that can be used for APIs that have an error code parameter.
protected AS400	system_ The system object specified on this OpenList's constructor.

Constructor Summary

protected

OpenList(AS400 system) Called by subclasses to construct an OpenList object.

Method Summary

protected abstract byte[]	callOpenListAPI() This method should be implemented by subclasses to call a particular QGY API and return the 80-byte list information parameter.
void	close() Closes the list on the server.
protected void	finalize() Attempts to close the list on the system when this OpenList object is garbage collected.
protected abstract java.lang.Object[]	formatOutputData(byte[] data, int recordsReturned, int recordLength) Returns the actual array of Objects that getItems(int,int) returns.
protected abstract int	getBestGuessReceiverSize(int number) Returns the initial size in bytes of the receiver variable for a particular implementation of an Open List API.
int	getEnumerationBlockSize() Returns the number of items that Enumerations returned by this OpenList's getItems() method will attempt to retrieve from the server and cache.
java.util.Enumeration	getItems() Returns the list of items.
java.lang.Object[]	getItems(int listOffset, int number) Returns an array of items, which can be a subset of the entire list built on the server.
int	getLength() Returns the number of items in the list the server has built.
AS400	getSystem() Returns the system object used by this OpenList.
boolean	isOpen() Returns whether or not this list is open.
void	open() Loads the list of items on the system.
protected void	resetHandle() Resets the handle to indicate we should close the list the next time we do something, usually as a result of one of the selection criteria being changed, since that should build a new list on the server.
void	setEnumerationBlockSize(int blockSize) Sets the number of items that Enumerations returned by this OpenList's getItems() method will attempt to retrieve from the server and cache.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_ERROR_CODE_PARM

protected static final ProgramParameter EMPTY_ERROR_CODE_PARM

Constant that can be used for APIs that have an error code parameter. An empty error code parameter instructs the remote command server to return error messages via the ProgramCall message list. This allows the ProgramCall logic to handle error conditions rather than the OpenList subclass. All the caller has to do is this:

 ProgramCall pc = new ProgramCall(system, "/LIBRARY.LIB/PROGRAM.PGM", parameters);
 if (!pc.run())
 {
   AS400Message[] errorMessages = pc.getMessageList();
   throw new AS400Exception(errorMessages);
 }
 

system_

protected AS400 system_

The system object specified on this OpenList's constructor.

See Also:

getSystem()

Constructor Detail

OpenList

protected OpenList(AS400 system)

Called by subclasses to construct an OpenList object.

Parameters:

system - The system. This cannot be null.

Method Detail

callOpenListAPI

protected abstract byte[] callOpenListAPI()
                                   throws AS400Exception,
                                          AS400SecurityException,
                                          ErrorCompletingRequestException,
                                          java.lang.InterruptedException,
                                          java.io.IOException,
                                          ObjectDoesNotExistException

This method should be implemented by subclasses to call a particular QGY API and return the 80-byte list information parameter. This method is called by open().

Returns:

The output data from the list information parameter in the call to the QGY API.

AS400Exception

AS400SecurityException

ErrorCompletingRequestException

java.lang.InterruptedException

java.io.IOException

ObjectDoesNotExistException

close

public void close()
           throws AS400Exception,
                  AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException,
                  ObjectDoesNotExistException

Closes the list on the server. This releases any system resources previously in use by this OpenList.

Any Enumerations created by this OpenList by calling getItems will close, so that a call to nextElement() will throw a NoSuchElementException when they reach the end of their enumeration cache block.

Throws:

AS400Exception - If there is a problem closing the list when the QGYCLST API is called.

AS400SecurityException

ErrorCompletingRequestException

java.lang.InterruptedException

java.io.IOException

ObjectDoesNotExistException

finalize

protected void finalize()
                 throws java.lang.Throwable

Attempts to close the list on the system when this OpenList object is garbage collected.

Overrides:

finalize in class java.lang.Object

java.lang.Throwable

formatOutputData

protected abstract java.lang.Object[] formatOutputData(byte[] data,
                                                       int recordsReturned,
                                                       int recordLength)
                                                throws AS400Exception,
                                                       AS400SecurityException,
                                                       ErrorCompletingRequestException,
                                                       java.lang.InterruptedException,
                                                       java.io.IOException,
                                                       ObjectDoesNotExistException

Returns the actual array of Objects that getItems(int,int) returns. Subclasses should implement this method to return instances of their own list item classes. This method is called by getItems(int,int).

Parameters:

data - The output data from the receiver variable from the call to the QGYGTLE (Get List Entries) API.

recordsReturned - The number of records returned, as reported in the open list information returned on the call to QGYGTLE.

recordLength - The length of a record, in bytes, as reported in the open list information returned on the call to QGYGTLE.

AS400Exception

AS400SecurityException

ErrorCompletingRequestException

java.lang.InterruptedException

java.io.IOException

ObjectDoesNotExistException

getBestGuessReceiverSize

protected abstract int getBestGuessReceiverSize(int number)

Returns the initial size in bytes of the receiver variable for a particular implementation of an Open List API. Subclasses should implement this method to return an appropriate value. This method is called by getItems(int,int).

Parameters:

number - The number of records in the list on the server. This is useful if the subclass needs to return a receiver size based on how many records are in the list.

Returns:

The number of bytes to allocate for the receiver variable when the QGYGTLE (Get List Entries) API is called. This number does not have to be calculated exactly, as QGYGTLE will be called repeatedly until the correct size is known. This number is just for the initial call to QGYGTLE. Too low of a value may result in extra API calls, too high of a value may result in wasted bytes being sent and received.

getEnumerationBlockSize

public int getEnumerationBlockSize()

Returns the number of items that Enumerations returned by this OpenList's getItems() method will attempt to retrieve from the server and cache. A larger number will result in fewer calls to the server but will take more memory.

Returns:

The block size. The default is 1000 items.

getLength

public int getLength()
              throws AS400Exception,
                     AS400SecurityException,
                     ErrorCompletingRequestException,
                     java.lang.InterruptedException,
                     java.io.IOException,
                     ObjectDoesNotExistException,
                     OpenListException

Returns the number of items in the list the server has built. This method implicitly calls open() to instruct the server to build the list if it hasn't been built already.

Returns:

The number of items, or 0 if no list was retrieved.

AS400Exception

AS400SecurityException

ErrorCompletingRequestException

java.lang.InterruptedException

java.io.IOException

ObjectDoesNotExistException

OpenListException

See Also:

open()

getItems

public java.util.Enumeration getItems()
                               throws AS400Exception,
                                      AS400SecurityException,
                                      ErrorCompletingRequestException,
                                      java.lang.InterruptedException,
                                      java.io.IOException,
                                      ObjectDoesNotExistException,
                                      OpenListException

Returns the list of items. The Enumeration will retrieve the items from the list built on the server in blocks for performance. The chunk size can be adjusted by using the setEnumerationBlockSize() method. This method implicity calls open() to instruct the server to build the list if it hasn't been built already.

Note that if this OpenList is closed, the Enumeration returned by this method will also be closed, such that a subsequent call to hasMoreElements() returns false and a subsequent call to nextElement() throws a NoSuchElementException.

Calling this method in a loop without either (a) closing this OpenList or (b) calling nextElement() on the Enumerations until they are at an end, will result in a memory leak.

Returns:

An Enumeration of objects. The types of objects in the Enumeration are dependent on which particular OpenList subclass is being used.

Throws:

AS400Exception - If the AS/400 system returns an error message.

AS400SecurityException - If a security or authority error occurs.

ConnectionDroppedException - If the connection is dropped unexpectedly.

ErrorCompletingRequestException - If an error occurs before the request is completed.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the AS/400.

ObjectDoesNotExistException - If the AS/400 object does not exist.

OpenListException - If the system is unable to correctly generate the list of items.

See Also:

close(), open()

getItems

public java.lang.Object[] getItems(int listOffset,
                                   int number)
                            throws AS400Exception,
                                   AS400SecurityException,
                                   ErrorCompletingRequestException,
                                   java.lang.InterruptedException,
                                   java.io.IOException,
                                   ObjectDoesNotExistException,
                                   OpenListException

Returns an array of items, which can be a subset of the entire list built on the server. This method allows the user to retrieve the item list from the server in pieces. If a call to open() is made (either implicitly or explicitly), then the items at a given offset will change, so a subsequent call to getItems() with the same listOffset and number will most likely not return the same items as the previous call.

Parameters:

listOffset - The offset into the list of items. This value must be greater than or equal to 0 and less than the list length, or specify -1 to retrieve all of the items.

number - The number of items to retrieve out of the list, starting at the specified listOffset. This value must be greater than or equal to 0 and less than or equal to the list length. If the listOffset is -1, this parameter is ignored.

Returns:

The array of retrieved items. The types of items in the Enumeration are dependent on which particular OpenList subclass is being used. The length of this array may not necessarily be equal to number, depending upon the size of the list on the server, and the specified listOffset.

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.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the object does not exist on the system.

OpenListException - If the system is unable to correctly generate the list of items.

See Also:

Job, close(), open()

getSystem

public AS400 getSystem()

Returns the system object used by this OpenList.

Returns:

The system.

isOpen

public boolean isOpen()

Returns whether or not this list is open.

Returns:

true if this list has been either implicitly or explictly opened; false if this list has been closed, or was never opened in the first place, or has had its properties changed such that it no longer accurately represents the list that was built on the server.

open

public void open()
          throws AS400Exception,
                 AS400SecurityException,
                 ErrorCompletingRequestException,
                 java.lang.InterruptedException,
                 java.io.IOException,
                 ObjectDoesNotExistException,
                 OpenListException

Loads the list of items on the system. This method instructs the server to build the list of items. This method blocks until the system returns the total number of items it has compiled. A subsequent call to getItems() will retrieve the actual object information and attributes for each item in the list from the system.

This method updates the list length returned by getLength().

If this list is already open, close() is called implicitly.

Throws:

AS400Exception - If the system returns an error message.

AS400SecurityException - If a security or authority error occurs.

ConnectionDroppedException - If the connection is dropped unexpectedly.

ErrorCompletingRequestException - If an error occurs before the request is completed.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the object does not exist on the system.

OpenListException - If the system is unable to correctly generate the list of items.

ServerStartupException - If the server cannot be started.

UnknownHostException - If the system cannot be located.

See Also:

getLength(), close()

resetHandle

protected void resetHandle()

Resets the handle to indicate we should close the list the next time we do something, usually as a result of one of the selection criteria being changed, since that should build a new list on the server. Subclasses should call this method when their list filtering, selection, and sort criteria are changed in order to discard the stale list data on the server and build a new list when open() is called.

It is better that a subclass not allow any of its selection criteria to be changed while the list is open, but that is not always desirable, which is why this method exists.

setEnumerationBlockSize

public void setEnumerationBlockSize(int blockSize)

Sets the number of items that Enumerations returned by this OpenList's getItems() method will attempt to retrieve from the server and cache. A larger number will result in fewer calls to the server but will take more memory.

Parameters:

blockSize - The block size. The default is 1000 items. If a number less than 1 is specified, the default block size of 1000 is used.