com.ibm.as400.access
Class ObjectList

java.lang.Object
  extended by com.ibm.as400.access.ObjectList
All Implemented Interfaces:
Serializable

public class ObjectList
extends Object
implements 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
static String ALL
          Selection value representing *ALL.
static String ALL_USER
          Selection value representing *ALLUSR.
static 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 String ASP_NAME_ALLAVL
          Constant indicating that all available ASPs will be searched.
static 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 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 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 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 String AUTH_ALL
          Selection value representing an authority of *ALL.
static String AUTH_ANY
          Selection value representing an authority of *ANY.
static String AUTH_CHANGE
          Selection value representing an authority of *CHANGE.
static String AUTH_DATA_ADD
          Selection value representing a data authority of *ADD.
static String AUTH_DATA_DELETE
          Selection value representing a data authority of *DLT.
static String AUTH_DATA_EXECUTE
          Selection value representing a data authority of *EXECUTE.
static String AUTH_DATA_READ
          Selection value representing a data authority of *READ.
static String AUTH_DATA_UPDATE
          Selection value representing a data authority of *UPD.
static String AUTH_LIST_MANAGEMENT
          Selection value representing an authority of *AUTLMGT.
static String AUTH_OBJECT_ALTER
          Selection value representing an object authority of *OBJALTER.
static String AUTH_OBJECT_EXISTENCE
          Selection value representing an object authority of *OBJEXIST.
static String AUTH_OBJECT_MANAGEMENT
          Selection value representing an object authority of *OBJMGT.
static String AUTH_OBJECT_OPERATIONAL
          Selection value representing an object authority of *OBJOPR.
static String AUTH_OBJECT_REFERENCE
          Selection value representing an object authority of *OBJREF.
static String AUTH_USE
          Selection value representing an authority of *USE.
static String CURRENT_LIBRARY
          Selection value representing *CURLIB.
static String IBM
          Selection value representing *IBM.
static String LIBRARY_LIST
          Selection value representing *LIBL.
static byte STATUS_ANY
          Selection value representing any status.
static String USER_LIBRARY_LIST
          Selection value representing *USRLIBL.
 
Constructor Summary
ObjectList(AS400 system)
          Constructs an ObjectList object.
ObjectList(AS400 system, String objectLibrary, String objectName, String objectType)
          Constructs an ObjectList with the specified selection criteria.
ObjectList(AS400 system, String objectLibrary, String objectName, String objectType, String aspDeviceName)
          Constructs an ObjectList with the specified selection criteria.
 
Method Summary
 void addLibraryAuthorityCriteria(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(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.
 String getAspDeviceName()
          Returns the name of an auxiliary storage pool (ASP) device in which storage is allocated for the library that contains the object.
 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.
 String getLibrary()
          Returns the library used to filter this list.
 String getName()
          Returns the object name used to filter this list.
 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.
 String getType()
          Returns the object type used to filter this list.
 void load()
          Loads the list of objects on the system.
 void setAspSearchType(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 String ALL
Selection value representing *ALL.

See Also:
Constant Field Values

ALL_USER

public static final String ALL_USER
Selection value representing *ALLUSR.

See Also:
Constant Field Values

ASP_NAME_ALL

public static final 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 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 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 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 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 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 String AUTH_ALL
Selection value representing an authority of *ALL.

See Also:
Constant Field Values

AUTH_ANY

public static final String AUTH_ANY
Selection value representing an authority of *ANY.

See Also:
Constant Field Values

AUTH_CHANGE

public static final String AUTH_CHANGE
Selection value representing an authority of *CHANGE.

See Also:
Constant Field Values

AUTH_DATA_ADD

public static final String AUTH_DATA_ADD
Selection value representing a data authority of *ADD.

See Also:
Constant Field Values

AUTH_DATA_DELETE

public static final String AUTH_DATA_DELETE
Selection value representing a data authority of *DLT.

See Also:
Constant Field Values

AUTH_DATA_EXECUTE

public static final String AUTH_DATA_EXECUTE
Selection value representing a data authority of *EXECUTE.

See Also:
Constant Field Values

AUTH_DATA_READ

public static final String AUTH_DATA_READ
Selection value representing a data authority of *READ.

See Also:
Constant Field Values

AUTH_DATA_UPDATE

public static final String AUTH_DATA_UPDATE
Selection value representing a data authority of *UPD.

See Also:
Constant Field Values

AUTH_LIST_MANAGEMENT

public static final String AUTH_LIST_MANAGEMENT
Selection value representing an authority of *AUTLMGT.

See Also:
Constant Field Values

AUTH_OBJECT_ALTER

public static final String AUTH_OBJECT_ALTER
Selection value representing an object authority of *OBJALTER.

See Also:
Constant Field Values

AUTH_OBJECT_EXISTENCE

public static final String AUTH_OBJECT_EXISTENCE
Selection value representing an object authority of *OBJEXIST.

See Also:
Constant Field Values

AUTH_OBJECT_MANAGEMENT

public static final String AUTH_OBJECT_MANAGEMENT
Selection value representing an object authority of *OBJMGT.

See Also:
Constant Field Values

AUTH_OBJECT_OPERATIONAL

public static final String AUTH_OBJECT_OPERATIONAL
Selection value representing an object authority of *OBJOPR.

See Also:
Constant Field Values

AUTH_OBJECT_REFERENCE

public static final String AUTH_OBJECT_REFERENCE
Selection value representing an object authority of *OBJREF.

See Also:
Constant Field Values

AUTH_USE

public static final String AUTH_USE
Selection value representing an authority of *USE.

See Also:
Constant Field Values

CURRENT_LIBRARY

public static final String CURRENT_LIBRARY
Selection value representing *CURLIB.

See Also:
Constant Field Values

IBM

public static final String IBM
Selection value representing *IBM.

See Also:
Constant Field Values

LIBRARY_LIST

public static final String LIBRARY_LIST
Selection value representing *LIBL.

See Also:
Constant Field Values

STATUS_ANY

public static final byte STATUS_ANY
Selection value representing any status.

See Also:
addObjectSelectionCriteria(byte), Constant Field Values

USER_LIBRARY_LIST

public static final 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:

Parameters:
system - The system.

ObjectList

public ObjectList(AS400 system,
                  String objectLibrary,
                  String objectName,
                  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,
                  String objectLibrary,
                  String objectName,
                  String objectType,
                  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

addLibraryAuthorityCriteria

public void addLibraryAuthorityCriteria(String authority)
Adds a library authority as part of the selection criteria for generating the list of objects. Libraries for which the user has the specified authorities are searched. If no library authority criteria are added, the default is AUTH_DATA_EXECUTE. A maximum of 10 authorities can be added.

Parameters:
authority - The authority to search. Valid values are:
See Also:
clearLibraryAuthorityCriteria()

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()

addObjectAttributeToSortOn

public void addObjectAttributeToSortOn(int attribute,
                                       boolean sortOrder)
Adds an object attribute used to sort the list. The attribute is automatically added as an attribute to retrieve.

The list of object attributes to sort on is maintained internally even when this ObjectList is closed and re-used. To start over with a new set of object attributes to sort on, call clearObjectAttributesToSortOn().

Parameters:
attribute - The object attribute on which to sort. Possible values are all object attributes contained in the ObjectDescription class, excluding the following:
sortOrder - true to sort ascending; false to sort descending.
See Also:
clearObjectAttributesToSortOn(), addObjectAttributeToRetrieve(int), ObjectDescription

addObjectAuthorityCriteria

public void addObjectAuthorityCriteria(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()

addObjectSelectionCriteria

public void addObjectSelectionCriteria(byte status)
Adds an object attribute used to filter the list. If no statuses are added as selection criteria, the default is to include objects with STATUS_ANY. A maximum of 5 statuses can be added.

Parameters:
status - The object information status criteria. Possible values include:
See Also:
clearObjectSelectionCriteria(), setObjectSelection(boolean)

clearLibraryAuthorityCriteria

public void clearLibraryAuthorityCriteria()
Clears the library authority criteria used to filter the list.

See Also:
addLibraryAuthorityCriteria(java.lang.String)

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)

clearObjectAuthorityCriteria

public void clearObjectAuthorityCriteria()
Clears the object authority criteria used to filter the list.

See Also:
addObjectAuthorityCriteria(java.lang.String)

clearObjectSelectionCriteria

public void clearObjectSelectionCriteria()
Clears the object statuses used to filter the list and resets the object selection to include objects in the list (true).

See Also:
addObjectSelectionCriteria(byte), setObjectSelection(boolean)

close

public void close()
           throws AS400Exception,
                  AS400SecurityException,
                  ErrorCompletingRequestException,
                  InterruptedException,
                  IOException,
                  ObjectDoesNotExistException
Closes the object list on the system. This releases any system resources previously in use by this object list.

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.
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.
See Also:
load()

getAspDeviceName

public 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 String getAspSearchType()
Returns the type of search to be used withn a specific auxiliary storage pool device name is specified.

Returns:
The search type.

getLength

public int getLength()
              throws AS400Exception,
                     AS400SecurityException,
                     ErrorCompletingRequestException,
                     InterruptedException,
                     IOException,
                     ObjectDoesNotExistException
Returns the number of objects in the object list. This method implicitly calls load().

Returns:
The number of objects, or 0 if no list was retrieved.
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.
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.
ServerStartupException - If the host server cannot be started.
UnknownHostException - If the system cannot be located.
See Also:
load()

getLibrary

public String getLibrary()
Returns the library used to filter this list.

Returns:
The library.

getName

public String getName()
Returns the object name used to filter this list.

Returns:
The object name.

getObjects

public Enumeration getObjects()
                       throws AS400Exception,
                              AS400SecurityException,
                              ErrorCompletingRequestException,
                              InterruptedException,
                              IOException,
                              ObjectDoesNotExistException,
                              RequestNotSupportedException
Returns the list of objects in the object list.

Returns:
An Enumeration of ObjectDescription objects.
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.
InterruptedException - If this thread is interrupted.
IOException - If an error occurs while communicating with the system.
ObjectDoesNotExistException - If the system object does not exist.
RequestNotSupportedException - If the requested function is not supported because the system is not at the correct level.
See Also:
close(), load()

getObjects

public ObjectDescription[] getObjects(int listOffset,
                                      int number)
                               throws AS400Exception,
                                      AS400SecurityException,
                                      ErrorCompletingRequestException,
                                      InterruptedException,
                                      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.
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.
See Also:
Job, close(), load()

getSystem

public AS400 getSystem()
Returns the system.

Returns:
The system.

getType

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

Returns:
The object type.

load

public void load()
          throws AS400Exception,
                 AS400SecurityException,
                 ErrorCompletingRequestException,
                 InterruptedException,
                 IOException,
                 ObjectDoesNotExistException
Loads the list of objects on the system. This method informs the system to build a list of objects. This method blocks until the system returns the total number of objects it has compiled. A subsequent call to getObjects() will retrieve the actual object information and attributes for each object in the list from the system.

This method updates the list length.

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.
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.
ServerStartupException - If the host server cannot be started.
UnknownHostException - If the system cannot be located.
See Also:
getLength(), close()

setAspSearchType

public void setAspSearchType(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:
ExtendedIllegalArgumentExceptiion - if an invalid search type is specified.
ExtendedIllegalArgumentException

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 Throwable
Closes the list on the system when this object is garbage collected.

Overrides:
finalize in class Object
Throws:
Throwable