com.ibm.as400.access

Class ObjectList

  • java.lang.Object
    • com.ibm.as400.access.ObjectList
  • All Implemented Interfaces:
    java.io.Serializable


    public class ObjectList
    extends java.lang.Object
    implements java.io.Serializable
    Represents a list of system objects in a specific library, multiple libraries, or system-wide.

    Implementation note: This class internally uses the Open List APIs (e.g. QGYOLOBJ).

    See Also:
    ObjectDescription, Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.lang.String ALL
      Selection value representing *ALL.
      static java.lang.String ALL_USER
      Selection value representing *ALLUSR.
      static java.lang.String ASP_NAME_ALL
      Constant indicating that the auxiliary storage pools that are currently part of the the thread's library name space will be searched to locate the library.
      static java.lang.String ASP_NAME_ALLAVL
      Constant indicating that all available ASPs will be searched.
      static java.lang.String ASP_NAME_CURASPGRP
      Constant indicating if the thread has an ASP group, the primary and secondary ASPs in the ASP group will be searched to locate the library.
      static java.lang.String ASP_NAME_SYSBAS
      Constant indicating that the system ASP (ASP 1) and all defined basic user ASPs (ASPs 2-32) will be searched to locate the library.
      static java.lang.String ASP_SEARCH_TYPE_ASP
      Constant indicating that only the single ASP named in the auxiliary storage pool device name field will be searched.
      static java.lang.String ASP_SEARCH_TYPE_ASPGRP
      Constant indicating that all ASPs in the auxiliary storage pool group named in the auxiliary storage pool device name field will be searched.
      static java.lang.String AUTH_ALL
      Selection value representing an authority of *ALL.
      static java.lang.String AUTH_ANY
      Selection value representing an authority of *ANY.
      static java.lang.String AUTH_CHANGE
      Selection value representing an authority of *CHANGE.
      static java.lang.String AUTH_DATA_ADD
      Selection value representing a data authority of *ADD.
      static java.lang.String AUTH_DATA_DELETE
      Selection value representing a data authority of *DLT.
      static java.lang.String AUTH_DATA_EXECUTE
      Selection value representing a data authority of *EXECUTE.
      static java.lang.String AUTH_DATA_READ
      Selection value representing a data authority of *READ.
      static java.lang.String AUTH_DATA_UPDATE
      Selection value representing a data authority of *UPD.
      static java.lang.String AUTH_LIST_MANAGEMENT
      Selection value representing an authority of *AUTLMGT.
      static java.lang.String AUTH_OBJECT_ALTER
      Selection value representing an object authority of *OBJALTER.
      static java.lang.String AUTH_OBJECT_EXISTENCE
      Selection value representing an object authority of *OBJEXIST.
      static java.lang.String AUTH_OBJECT_MANAGEMENT
      Selection value representing an object authority of *OBJMGT.
      static java.lang.String AUTH_OBJECT_OPERATIONAL
      Selection value representing an object authority of *OBJOPR.
      static java.lang.String AUTH_OBJECT_REFERENCE
      Selection value representing an object authority of *OBJREF.
      static java.lang.String AUTH_USE
      Selection value representing an authority of *USE.
      static java.lang.String CURRENT_LIBRARY
      Selection value representing *CURLIB.
      static java.lang.String IBM
      Selection value representing *IBM.
      static java.lang.String LIBRARY_LIST
      Selection value representing *LIBL.
      static byte STATUS_ANY
      Selection value representing any status.
      static java.lang.String USER_LIBRARY_LIST
      Selection value representing *USRLIBL.
    • Constructor Summary

      Constructors 
      Constructor and Description
      ObjectList(AS400 system)
      Constructs an ObjectList object.
      ObjectList(AS400 system, java.lang.String objectLibrary, java.lang.String objectName, java.lang.String objectType)
      Constructs an ObjectList with the specified selection criteria.
      ObjectList(AS400 system, java.lang.String objectLibrary, java.lang.String objectName, java.lang.String objectType, java.lang.String aspDeviceName)
      Constructs an ObjectList with the specified selection criteria.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addLibraryAuthorityCriteria(java.lang.String authority)
      Adds a library authority as part of the selection criteria for generating the list of objects.
      void addObjectAttributeToRetrieve(int attribute)
      Adds an object attribute to retrieve when this list is built.
      void addObjectAttributeToSortOn(int attribute, boolean sortOrder)
      Adds an object attribute used to sort the list.
      void addObjectAuthorityCriteria(java.lang.String authority)
      Adds an object authority as part of the selection criteria for generating the list of objects.
      void addObjectSelectionCriteria(byte status)
      Adds an object attribute used to filter the list.
      void clearLibraryAuthorityCriteria()
      Clears the library authority criteria used to filter the list.
      void clearObjectAttributesToRetrieve()
      Clears the object attribtues to retrieve as part of this list.
      void clearObjectAttributesToSortOn()
      Clears the object attributes used to sort the list.
      void clearObjectAuthorityCriteria()
      Clears the object authority criteria used to filter the list.
      void clearObjectSelectionCriteria()
      Clears the object statuses used to filter the list and resets the object selection to include objects in the list (true).
      void close()
      Closes the object list on the system.
      protected void finalize()
      Closes the list on the system when this object is garbage collected.
      java.lang.String getAspDeviceName()
      Returns the name of an auxiliary storage pool (ASP) device in which storage is allocated for the library that contains the object.
      java.lang.String getAspSearchType()
      Returns the type of search to be used withn a specific auxiliary storage pool device name is specified.
      int getLength()
      Returns the number of objects in the object list.
      java.lang.String getLibrary()
      Returns the library used to filter this list.
      java.lang.String getName()
      Returns the object name used to filter this list.
      java.util.Enumeration getObjects()
      Returns the list of objects in the object list.
      ObjectDescription[] getObjects(int listOffset, int number)
      Returns a subset of the list of objects.
      AS400 getSystem()
      Returns the system.
      java.lang.String getType()
      Returns the object type used to filter this list.
      void load()
      Loads the list of objects on the system.
      void setAspSearchType(java.lang.String aspSearchType)
      Specifies the type of the search when a specific auxiliary storage pool device name is specified for the ASP device name.
      void setObjectSelection(boolean select)
      Sets whether or not the object selection criteria are used to include objects in the list or to omit them from the list.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • ALL

        public static final java.lang.String ALL
        Selection value representing *ALL.
        See Also:
        Constant Field Values
      • ALL_USER

        public static final java.lang.String ALL_USER
        Selection value representing *ALLUSR.
        See Also:
        Constant Field Values
      • ASP_NAME_ALL

        public static final java.lang.String ASP_NAME_ALL
        Constant indicating that the auxiliary storage pools that are currently part of the the thread's library name space will be searched to locate the library. This includes the system ASP (ASP 1), all defined basic user ASPs (ASPs 2-32), and, if the thread has an ASP group, the primary and secondary ASPs in the thread's ASP group.
        See Also:
        Constant Field Values
      • ASP_NAME_SYSBAS

        public static final java.lang.String ASP_NAME_SYSBAS
        Constant indicating that the system ASP (ASP 1) and all defined basic user ASPs (ASPs 2-32) will be searched to locate the library. No primary or secondary ASPs will be searched, even if the thread has an ASP group.
        See Also:
        Constant Field Values
      • ASP_NAME_CURASPGRP

        public static final java.lang.String ASP_NAME_CURASPGRP
        Constant indicating if the thread has an ASP group, the primary and secondary ASPs in the ASP group will be searched to locate the library. The system ASP (ASP 1) and defined basic user ASPs (ASPs 2-32) will not be searched.
        See Also:
        Constant Field Values
      • ASP_NAME_ALLAVL

        public static final java.lang.String ASP_NAME_ALLAVL
        Constant indicating that all available ASPs will be searched. This includes the system ASP (ASP 1), all defined basic user ASPs (ASPs 2-32), and all available primary and secondary ASPs (ASPs 33-255 with a status of 'Available'). The ASP groups are searched in alphabetical order by the primary ASP. The system ASP and all defined basic user ASPs are searched after the ASP groups. ASPs and libraries to which the user is not authorized are bypassed and no authority error messages are sent. The search ends when the first object is found of the specified object name, library name, and object type. If the user is not authorized to the object, an authority error message is sent.
        See Also:
        Constant Field Values
      • ASP_SEARCH_TYPE_ASP

        public static final java.lang.String ASP_SEARCH_TYPE_ASP
        Constant indicating that only the single ASP named in the auxiliary storage pool device name field will be searched.
        See Also:
        Constant Field Values
      • ASP_SEARCH_TYPE_ASPGRP

        public static final java.lang.String ASP_SEARCH_TYPE_ASPGRP
        Constant indicating that all ASPs in the auxiliary storage pool group named in the auxiliary storage pool device name field will be searched. The device name must be the name of the primary auxiliary storage pool in the group.
        See Also:
        Constant Field Values
      • AUTH_ALL

        public static final java.lang.String AUTH_ALL
        Selection value representing an authority of *ALL.
        See Also:
        Constant Field Values
      • AUTH_ANY

        public static final java.lang.String AUTH_ANY
        Selection value representing an authority of *ANY.
        See Also:
        Constant Field Values
      • AUTH_CHANGE

        public static final java.lang.String AUTH_CHANGE
        Selection value representing an authority of *CHANGE.
        See Also:
        Constant Field Values
      • AUTH_DATA_ADD

        public static final java.lang.String AUTH_DATA_ADD
        Selection value representing a data authority of *ADD.
        See Also:
        Constant Field Values
      • AUTH_DATA_DELETE

        public static final java.lang.String AUTH_DATA_DELETE
        Selection value representing a data authority of *DLT.
        See Also:
        Constant Field Values
      • AUTH_DATA_EXECUTE

        public static final java.lang.String AUTH_DATA_EXECUTE
        Selection value representing a data authority of *EXECUTE.
        See Also:
        Constant Field Values
      • AUTH_DATA_READ

        public static final java.lang.String AUTH_DATA_READ
        Selection value representing a data authority of *READ.
        See Also:
        Constant Field Values
      • AUTH_DATA_UPDATE

        public static final java.lang.String AUTH_DATA_UPDATE
        Selection value representing a data authority of *UPD.
        See Also:
        Constant Field Values
      • AUTH_LIST_MANAGEMENT

        public static final java.lang.String AUTH_LIST_MANAGEMENT
        Selection value representing an authority of *AUTLMGT.
        See Also:
        Constant Field Values
      • AUTH_OBJECT_ALTER

        public static final java.lang.String AUTH_OBJECT_ALTER
        Selection value representing an object authority of *OBJALTER.
        See Also:
        Constant Field Values
      • AUTH_OBJECT_EXISTENCE

        public static final java.lang.String AUTH_OBJECT_EXISTENCE
        Selection value representing an object authority of *OBJEXIST.
        See Also:
        Constant Field Values
      • AUTH_OBJECT_MANAGEMENT

        public static final java.lang.String AUTH_OBJECT_MANAGEMENT
        Selection value representing an object authority of *OBJMGT.
        See Also:
        Constant Field Values
      • AUTH_OBJECT_OPERATIONAL

        public static final java.lang.String AUTH_OBJECT_OPERATIONAL
        Selection value representing an object authority of *OBJOPR.
        See Also:
        Constant Field Values
      • AUTH_OBJECT_REFERENCE

        public static final java.lang.String AUTH_OBJECT_REFERENCE
        Selection value representing an object authority of *OBJREF.
        See Also:
        Constant Field Values
      • AUTH_USE

        public static final java.lang.String AUTH_USE
        Selection value representing an authority of *USE.
        See Also:
        Constant Field Values
      • CURRENT_LIBRARY

        public static final java.lang.String CURRENT_LIBRARY
        Selection value representing *CURLIB.
        See Also:
        Constant Field Values
      • IBM

        public static final java.lang.String IBM
        Selection value representing *IBM.
        See Also:
        Constant Field Values
      • LIBRARY_LIST

        public static final java.lang.String LIBRARY_LIST
        Selection value representing *LIBL.
        See Also:
        Constant Field Values
      • USER_LIBRARY_LIST

        public static final java.lang.String USER_LIBRARY_LIST
        Selection value representing *USRLIBL.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ObjectList

        public ObjectList(AS400 system)
        Constructs an ObjectList object. The selection values default to:
        • Object library - ALL
        • Object name - ALL
        • Object type - ALL
        Parameters:
        system - The system.
      • ObjectList

        public ObjectList(AS400 system,
                  java.lang.String objectLibrary,
                  java.lang.String objectName,
                  java.lang.String objectType)
        Constructs an ObjectList with the specified selection criteria.
        Parameters:
        system - The system.
        objectLibrary - The library or set of libraries that are searched for objects. Valid values are a specific name, a generic name, or one of the following special values:
        objectName - The object name. Valid values are a specific name, a generic name, or one of the following special values:
        • ALL - All object names are searched.
        • ALL_USER - All objects that are libraries in QSYS or the library list are searched. The object library must either be LIBRARY_LIST or QSYS. The object type must be *LIB. A list of user libraries is returned.
        • IBM - All objects that are libraries in QSYS or the library list are searched. The object library must either be LIBRARY_LIST or QSYS. The object type must be *LIB. A list of saved (SAVLIB) and restored (RSTLIB) libraries is returned.
        objectType - The type of objects that are searched. Valid values include a specific object type (*LIB, *FILE, *OUTQ, etc) or ALL.
      • ObjectList

        public ObjectList(AS400 system,
                  java.lang.String objectLibrary,
                  java.lang.String objectName,
                  java.lang.String objectType,
                  java.lang.String aspDeviceName)
        Constructs an ObjectList with the specified selection criteria.
        Parameters:
        system - The system.
        objectLibrary - The library or set of libraries that are searched for objects. Valid values are a specific name, a generic name, or one of the following special values:
        objectName - The object name. Valid values are a specific name, a generic name, or one of the following special values:
        • ALL - All object names are searched.
        • ALL_USER - All objects that are libraries in QSYS or the library list are searched. The object library must either be LIBRARY_LIST or QSYS. The object type must be *LIB. A list of user libraries is returned.
        • IBM - All objects that are libraries in QSYS or the library list are searched. The object library must either be LIBRARY_LIST or QSYS. The object type must be *LIB. A list of saved (SAVLIB) and restored (RSTLIB) libraries is returned.
        objectType - The type of objects that are searched. Valid values include a specific object type (*LIB, *FILE, *OUTQ, etc) or ALL.
        aspDeviceName - The name of an auxiliary storage pool (ASP) device in which storage is allocated for the library that contains the object or one of the following special values:
    >
    • Method Detail

      • addObjectAttributeToRetrieve

        public void addObjectAttributeToRetrieve(int attribute)
        Adds an object attribute to retrieve when this list is built. The attribute is cached as part of the ObjectDescription objects that are returned by this list, so that another call to the system is not necessary. Adding attributes to retrieve may increase list build time on the system, as well as increasing the amount of storage used to hold the list on the system.

        The object NAME, LIBRARY, and TYPE are always retrieved. By default, these are the only attributes that are retrieved. If no other attributes are added, the statuses of the objects (returned by ObjectDescription.getStatus()) are unknown. Any attributes that are not retrieved via this interface will require another call to the system to retrieve them when ObjectDescription.getValue() is called. The exceptions to this are the various attributes that represent Date objects, as they need to be converted from system timestamp format, which always requires another call to the system.

        Parameters:
        attribute - The attribute to retrieve. Valid values include any of the attributes on the ObjectDescription class.
        See Also:
        clearObjectAttributesToRetrieve()
      • addObjectAuthorityCriteria

        public void addObjectAuthorityCriteria(java.lang.String authority)
        Adds an object authority as part of the selection criteria for generating the list of objects. Objects for which the user has the specified authorities are searched. If no object authority criteria are added, the default is AUTH_ANY. A maximum of 11 authorities can be added.
        Parameters:
        authority - The authority to search. Valid values are:
        See Also:
        clearObjectAuthorityCriteria()
      • clearObjectAttributesToRetrieve

        public void clearObjectAttributesToRetrieve()
        Clears the object attribtues to retrieve as part of this list. This resets the attributes to retrieve back to the default NAME, LIBRARY, and TYPE.
        See Also:
        addObjectAttributeToRetrieve(int)
      • clearObjectAttributesToSortOn

        public void clearObjectAttributesToSortOn()
        Clears the object attributes used to sort the list. This resets all of the object sort parameters to their default values.
        See Also:
        addObjectAttributeToSortOn(int, boolean)
      • getAspDeviceName

        public java.lang.String getAspDeviceName()
        Returns the name of an auxiliary storage pool (ASP) device in which storage is allocated for the library that contains the object.
        Returns:
        The auxiliary storage pool (ASP) device name or null if no ASP device name has been set.
      • getAspSearchType

        public java.lang.String getAspSearchType()
        Returns the type of search to be used withn a specific auxiliary storage pool device name is specified.
        Returns:
        The search type.
      • getLibrary

        public java.lang.String getLibrary()
        Returns the library used to filter this list.
        Returns:
        The library.
      • getName

        public java.lang.String getName()
        Returns the object name used to filter this list.
        Returns:
        The object name.
      • getObjects

        public ObjectDescription[] getObjects(int listOffset,
                                     int number)
                                       throws AS400Exception,
                                              AS400SecurityException,
                                              ErrorCompletingRequestException,
                                              java.lang.InterruptedException,
                                              java.io.IOException,
                                              ObjectDoesNotExistException
        Returns a subset of the list of objects. This method allows the user to retrieve the object list from the system in pieces. If a call to load() is made (either implicitly or explicitly), then the objects at a given list offset will change, so a subsequent call to getObjects() with the same listOffset and number will most likely not return the same ObjectDescriptions as the previous call.
        Parameters:
        listOffset - The offset in the list of objects (0-based). This value must be greater than or equal to 0 and less than the list length; or specify -1 to retrieve all of the objects.
        number - The number of objects 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 ObjectDescription objects. 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:
        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.
        See Also:
        Job, close(), load()
      • getSystem

        public AS400 getSystem()
        Returns the system.
        Returns:
        The system.
      • getType

        public java.lang.String getType()
        Returns the object type used to filter this list. (For example: *LIB, *FILE, *OUTQ, etc)
        Returns:
        The object type.
      • setAspSearchType

        public void setAspSearchType(java.lang.String aspSearchType)
                              throws ExtendedIllegalArgumentException
        Specifies the type of the search when a specific auxiliary storage pool device name is specified for the ASP device name.
        Parameters:
        aspSearchType - The type of search to be used. One of the following values may be specified: The default value is ASP_SEARCH_TYPE_ASP.
        Throws:
        ExtendedIllegalArgumentException - if an invalid search type is specified.
      • setObjectSelection

        public void setObjectSelection(boolean select)
        Sets whether or not the object selection criteria are used to include objects in the list or to omit them from the list. The default is true, which is to include objects in the list with the specified criteria as added by addObjectSelectionCriteria().
        Parameters:
        select - true to include objects in the list that have the specified statuses, false to omit objects from the list that have the specified statuses.
        See Also:
        addObjectSelectionCriteria(byte), clearObjectSelectionCriteria()
      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Closes the list on the system when this object is garbage collected.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable