com.ibm.as400.access
Class ObjectList

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

public class ObjectList
extends Object
implements Serializable

The ObjectList class represents a list of server 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 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.
 
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.
 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 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, finalize, 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

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:
objectType - The type of objects that are searched. Valid values include a specific object type (*LIB, *FILE, *OUTQ, etc) or ALL.
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 server is not necessary. Adding attributes to retrieve may increase list build time on the server, as well as increasing the amount of storage used to hold the list on the server.

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

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

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 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 server 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 server.
ObjectDoesNotExistException - If the server object does not exist.
RequestNotSupportedException - If the requested function is not supported because the server 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 server in pieces. If a call to load() is made (either implicitly or explicitly), then the objects at a given 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 into the list of objects. This value must be greater than 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 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.
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 server cannot be started.
UnknownHostException - If the system cannot be located.
See Also:
getLength(), close()

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