com.ibm.as400.access.list
Class OpenList

java.lang.Object
  com.ibm.as400.access.list.OpenList

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

SpooledFileOpenList

public abstract class OpenList
extends Object
implements Serializable

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

The way an open list works is that a request is initially sent to the system with selection, filter, and sort information that is to be applied to the list of resources. The system 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 system 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 system. 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 system. 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

Modifier and Type	Field and Description
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

Modifier	Constructor and Description
protected	OpenList(AS400 system) Called by subclasses to construct an OpenList object.

Method Summary

Modifier and Type	Method and Description
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 system.
protected void	finalize() Attempts to close the list on the system when this OpenList object is garbage collected.
protected abstract 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 system and cache.
Enumeration	getItems() Returns the list of items.
Object[]	getItems(int listOffset, int number) Returns an array of items, which can be a subset of the entire list built on the system.
int	getLength() Returns the number of items in the list the system 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 system.
void	setEnumerationBlockSize(int enumerationBlockSize) Sets the number of items that Enumerations returned by this OpenList's getItems() method will attempt to retrieve from the system 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 object representing the system on which the list exists. This cannot be null.

Method Detail

callOpenListAPI

protected abstract byte[] callOpenListAPI()
                                   throws AS400SecurityException,
                                          ErrorCompletingRequestException,
                                          InterruptedException,
                                          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.

Throws:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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

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

close

public void close()
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException

Closes the list on the system. 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:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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

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

finalize

protected void finalize()
                 throws Throwable

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

Overrides:

finalize in class Object

Throws:

Throwable

formatOutputData

protected abstract Object[] formatOutputData(byte[] data,
                                             int recordsReturned,
                                             int recordLength)
                                      throws AS400SecurityException,
                                             ErrorCompletingRequestException,
                                             InterruptedException,
                                             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.

Throws:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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

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

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 system. 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 system and cache. A larger number will result in fewer calls to the system but will take more memory.

Returns:

The block size. The default is 1000 items.

getLength

public int getLength()
              throws AS400SecurityException,
                     ErrorCompletingRequestException,
                     InterruptedException,
                     IOException,
                     ObjectDoesNotExistException,
                     OpenListException

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

Returns:

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

Throws:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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:

open()

getItems

public Enumeration getItems()
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            InterruptedException,
                            IOException,
                            ObjectDoesNotExistException,
                            OpenListException

Returns the list of items. The Enumeration will retrieve the items from the list built on the system in blocks for performance. The chunk size can be adjusted by using the setEnumerationBlockSize() method. This method implicity calls open() to instruct the system 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:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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:

close(), open()

getItems

public Object[] getItems(int listOffset,
                         int number)
                  throws AS400SecurityException,
                         ErrorCompletingRequestException,
                         InterruptedException,
                         IOException,
                         ObjectDoesNotExistException,
                         OpenListException

Returns an array of items, which can be a subset of the entire list built on the system. This method allows the user to retrieve the item list from the system 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 array 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 system, and the specified listOffset.

Throws:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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 system.

open

public void open()
          throws AS400SecurityException,
                 ErrorCompletingRequestException,
                 InterruptedException,
                 IOException,
                 ObjectDoesNotExistException,
                 OpenListException

Loads the list of items on the system. This method instructs the system 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:

AS400SecurityException - If a security or authority error occurs.

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

InterruptedException - If this thread is interrupted.

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:

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 system. 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 system 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 enumerationBlockSize)

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

Parameters:

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