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:
    AspOpenList, SpooledFileOpenList

    public abstract class OpenList
extends java.lang.Object
implements java.io.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

      Fields 
      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

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

    • Method Summary

      Methods 
      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 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 system 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 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,
                                          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.
        Throws:
        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.

      • 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
        Throws:
        java.lang.Throwable

      • formatOutputData

        protected abstract java.lang.Object[] formatOutputData(byte[] data,
                                  int recordsReturned,
                                  int recordLength)
                                                throws 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.
        Throws:
        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.

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

      • getItems

        public java.util.Enumeration getItems()
                               throws 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 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.
        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:
        close(), open()

      • getItems

        public java.lang.Object[] getItems(int listOffset,
                          int number)
                            throws 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 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.
        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 system.

      • 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.
JTOpen 10.7