com.ibm.as400.access
Class UserSpace

java.lang.Object
  |
  +--com.ibm.as400.access.UserSpace

All Implemented Interfaces:

java.io.Serializable

public class UserSpace

extends java.lang.Object

implements java.io.Serializable

The UserSpace class represents a user space on the AS/400.

See Also:

Serialized Form

Field Summary

static int	FORCE_ASYNCHRONOUS Force to Auxiliary Storage option that allow changes to be forced asynchronously.
static int	FORCE_NONE Force to Auxiliary Storage option that does not allow changes to be forced.
static int	FORCE_SYNCHRONOUS Force to Auxiliary Storage option that allow changes to be forced synchronously.

Constructor Summary

UserSpace()
Constructs a UserSpace object.

UserSpace(AS400 system, java.lang.String path)
Constructs a UserSpace object.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a listener to be notified when the value of any bound property is changed.
void	addUserSpaceListener(UserSpaceListener listener) Adds a listener to be notified when a UserSpaceEvent is fired.
void	addVetoableChangeListener(java.beans.VetoableChangeListener listener) Adds a listener to be notified when the value of any constrained property is changed.
void	close() Closes the user space and releases any system resources associated with the stream.
void	create(int length, boolean replace, java.lang.String extendedAttribute, byte initialValue, java.lang.String textDescription, java.lang.String authority) Creates the user space.
void	create(java.lang.String domain, int length, boolean replace, java.lang.String extendedAttribute, byte initialValue, java.lang.String textDescription, java.lang.String authority) Creates the user space.
void	delete() Deletes the user space.
boolean	exists() Determines if the user space exists.
byte	getInitialValue() Returns the initial value used for filling in the user space during creation and extension.
int	getLength() Returns the size (in bytes) of the user space.
java.lang.String	getName() Returns the user space name.
java.lang.String	getPath() Returns the integrated file system path name of the object represented by the user space.
AS400	getSystem() Returns the AS400 system object for the user space.
boolean	isAutoExtendible() Indicates if the user space is auto extendible.
boolean	isMustUseProgramCall() Indicates if Toolbox ProgramCall will be used internally to perform user space read and write requests.
int	read(byte[] dataBuffer, int userSpaceOffset) Reads up to dataBuffer.length bytes from the user space beginning at userSpaceOffset into dataBuffer.
int	read(byte[] dataBuffer, int userSpaceOffset, int dataOffset, int length) Reads up to length bytes from the user space beginning at userSpaceOffset into dataBuffer beginning at dataOffset.
java.lang.String	read(int userSpaceOffset, int length) Returns a string from the user space beginning at userSpaceOffset.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes this listener from being notified when a bound property changes.
void	removeUserSpaceListener(UserSpaceListener listener) Removes a listener from the UserSpace listeners list.
void	removeVetoableChangeListener(java.beans.VetoableChangeListener listener) Removes this listener from being notified when a constrained property changes.
void	setAutoExtendible(boolean autoExtendibility) Sets the auto extend attribute if possible.
void	setInitialValue(byte initialValue) Sets the initial value to be used during user space creation or extension.
void	setLength(int length) Sets the size (in bytes) of the user space.
void	setMustUseProgramCall(boolean useProgramCall) Sets the method used to carry out user space read and write operations.
void	setPath(java.lang.String path) Sets the path for the user space.
void	setSystem(AS400 system) Sets the AS400 system for the user space.
void	write(byte[] dataBuffer, int userSpaceOffset) Writes up to dataBuffer.length bytes from dataBuffer into the user space beginning at userSpaceOffset.
void	write(byte[] dataBuffer, int userSpaceOffset, int dataOffset, int length) Writes up to length bytes from dataBuffer beginning at dataOffset into the user space beginning at userSpaceOffset.
void	write(byte[] dataBuffer, int userSpaceOffset, int dataOffset, int length, int forceAuxiliary) Writes up to length bytes from dataBuffer beginning at dataOffset into the user space beginning at userSpaceOffset.
void	write(java.lang.String data, int userSpaceOffset) Writes a string into the user space beginning at userSpaceOffset.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORCE_ASYNCHRONOUS

public static final int FORCE_ASYNCHRONOUS

Force to Auxiliary Storage option that allow changes to be forced asynchronously.

FORCE_NONE

public static final int FORCE_NONE

Force to Auxiliary Storage option that does not allow changes to be forced. It uses normal system writes.

FORCE_SYNCHRONOUS

public static final int FORCE_SYNCHRONOUS

Force to Auxiliary Storage option that allow changes to be forced synchronously.

Constructor Detail

UserSpace

public UserSpace()

Constructs a UserSpace object. It creates a default UserSpace object. The system and path properties must be set before attempting a connection.

UserSpace

public UserSpace(AS400 system,
                 java.lang.String path)

Constructs a UserSpace object. It creates a UserSpace instance that represents the user space path on system.

Parameters:

system - The AS400 that contains the file.

path - The fully qualified integrated file system path name.

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a listener to be notified when the value of any bound property is changed. It can be removed with removePropertyChangeListener.

Parameters:

listener - The PropertyChangeListener.

addUserSpaceListener

public void addUserSpaceListener(UserSpaceListener listener)

Adds a listener to be notified when a UserSpaceEvent is fired.

Parameters:

listener - The object listener.

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)

Adds a listener to be notified when the value of any constrained property is changed.

Parameters:

listener - The VetoableChangeListener.

close

public void close()
           throws java.io.IOException

Closes the user space and releases any system resources associated with the stream.

create

public void create(int length,
                   boolean replace,
                   java.lang.String extendedAttribute,
                   byte initialValue,
                   java.lang.String textDescription,
                   java.lang.String authority)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException,
                   ObjectDoesNotExistException

Creates the user space.

Parameters:

length - The initial size (in bytes) of the user space. Valid values are 1 through 16,776,704.

replace - The value indicating if an existing user space is to be replaced.

extendedAttribute - The user-defined extended attribute of the user space. This string must be 10 characters or less.

initialValue - The value used in creation and extension.

textDescription - The text describing the user space. This string must be 50 characters or less.

authority - The public authority for the user space. This string must be 10 characters or less. Valid values are:

• *ALL
• *CHANGE
• *EXCLUDE
• *LIBCRTAUT
• *USE
• authorization-list name.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

create

public void create(java.lang.String domain,
                   int length,
                   boolean replace,
                   java.lang.String extendedAttribute,
                   byte initialValue,
                   java.lang.String textDescription,
                   java.lang.String authority)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException,
                   ObjectDoesNotExistException

Creates the user space.

Parameters:

domain - The domain into which the user space is created. Valid value are: *DEFAULT, *USER, or *SYSTEM. DEFAULT uses the allow user domain system value to determine if *USER or *SYSTEM will be used.

length - The initial size (in bytes) of the user space. Valid values are 1 through 16,776,704.

replace - The value indicating if an existing user space is to be replaced.

extendedAttribute - The user-defined extended attribute of the user space. This string must be 10 characters or less.

initialValue - The value used in creation and extension.

textDescription - The text describing the user space. This string must be 50 characters or less.

authority - The authority given to users. This string must be 10 characters or less. Valid values are:

• *ALL
• *CHANGE
• *EXCLUDE
• *LIBCRTAUT
• *USE
• authorization-list name

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

delete

public void delete()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.lang.InterruptedException,
                   java.io.IOException,
                   ObjectDoesNotExistException

Deletes the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

exists

public boolean exists()
               throws AS400SecurityException,
                      ErrorCompletingRequestException,
                      java.lang.InterruptedException,
                      java.io.IOException

Determines if the user space exists.

Returns:

true if the user space exists; false otherwise.

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 AS/400.

getInitialValue

public byte getInitialValue()
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            java.lang.InterruptedException,
                            java.io.IOException,
                            ObjectDoesNotExistException

Returns the initial value used for filling in the user space during creation and extension.

Returns:

The initial value used during user space creation and extension.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

getLength

public int getLength()
              throws AS400SecurityException,
                     ErrorCompletingRequestException,
                     java.lang.InterruptedException,
                     java.io.IOException,
                     ObjectDoesNotExistException

Returns the size (in bytes) of the user space.

Returns:

The size (in bytes) of the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

getName

public java.lang.String getName()

Returns the user space name.

Returns:

The name of the user space.

getPath

public java.lang.String getPath()

Returns the integrated file system path name of the object represented by the user space.

Returns:

The integrated file system path name of the object represented by the user space.

getSystem

public AS400 getSystem()

Returns the AS400 system object for the user space.

Returns:

The AS400 system object for the user space.

isAutoExtendible

public boolean isAutoExtendible()
                         throws AS400SecurityException,
                                ErrorCompletingRequestException,
                                java.lang.InterruptedException,
                                java.io.IOException,
                                ObjectDoesNotExistException

Indicates if the user space is auto extendible. When running on a workstation the auto extend attribute is always true and cannot be changed, so the attribute value returned should be ignored. The auto extend attribute can be used when running on the AS/400's JVM with the optimizations that are a part of OS/400.

Returns:

true if the user space is auto extendible; false otherwise.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

isMustUseProgramCall

public boolean isMustUseProgramCall()

Indicates if Toolbox ProgramCall will be used internally to perform user space read and write requests. If false, Toolbox Integrated File System classes will be used tp perform user space read and write reqeusts.

Returns:

true if user space read and write requests will be performed via program call; false otherwise.

See Also:

setMustUseProgramCall(boolean)

read

public int read(byte[] dataBuffer,
                int userSpaceOffset)
         throws AS400SecurityException,
                ErrorCompletingRequestException,
                java.lang.InterruptedException,
                java.io.IOException,
                ObjectDoesNotExistException

Reads up to dataBuffer.length bytes from the user space beginning at userSpaceOffset into dataBuffer.

Parameters:

dataBuffer - The buffer to fill with data. Buffer.length() bytes will be read from the user space.

userSpaceOffset - The offset in the user space from which to start reading.

Returns:

The total number of bytes read into the buffer, or -1 if the userSpaceOffset is beyond the end of the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

read

public int read(byte[] dataBuffer,
                int userSpaceOffset,
                int dataOffset,
                int length)
         throws AS400SecurityException,
                ErrorCompletingRequestException,
                java.lang.InterruptedException,
                java.io.IOException,
                ObjectDoesNotExistException

Reads up to length bytes from the user space beginning at userSpaceOffset into dataBuffer beginning at dataOffset.

Parameters:

dataBuffer - The buffer to fill with data.

userSpaceOffset - The offset in the user space from which to start reading.

dataOffset - The starting offset in the data buffer for the results of the read.

length - The number of bytes to read.

Returns:

The total number of bytes read into the buffer, or -1 if the userSpaceOffset is beyond the end of the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

read

public java.lang.String read(int userSpaceOffset,
                             int length)
                      throws AS400SecurityException,
                             ErrorCompletingRequestException,
                             java.lang.InterruptedException,
                             java.io.IOException,
                             ObjectDoesNotExistException

Returns a string from the user space beginning at userSpaceOffset. Data is read from the user space as if by the read(byte[],int,int,int) method. The resulting byte array is then converted into a String.

Parameters:

userSpaceOffset - The offset in the user space from which to start reading.

length - The number of bytes to read.

Returns:

The string value from the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes this listener from being notified when a bound property changes.

Parameters:

listener - The PropertyChangeListener.

removeUserSpaceListener

public void removeUserSpaceListener(UserSpaceListener listener)

Removes a listener from the UserSpace listeners list.

Parameters:

listener - The user space listener.

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)

Removes this listener from being notified when a constrained property changes.

Parameters:

listener - The VetoableChangeListener.

setAutoExtendible

public void setAutoExtendible(boolean autoExtendibility)
                       throws AS400SecurityException,
                              ErrorCompletingRequestException,
                              java.lang.InterruptedException,
                              java.io.IOException,
                              ObjectDoesNotExistException

Sets the auto extend attribute if possible. When running on a workstation the Toolbox cannot set the auto extend attribute so this method is ignored and auto extend is always true. Auto extend can be set when running on the AS/400's JVM with the optimizations that are a part of OS/400.

Parameters:

autoExtendibility - The attribute for user space auto extendibility.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

setInitialValue

public void setInitialValue(byte initialValue)
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            java.lang.InterruptedException,
                            java.io.IOException,
                            ObjectDoesNotExistException

Sets the initial value to be used during user space creation or extension.

Parameters:

initialValue - The new initial value used during future extensions. For best performance set byte to hexadecimal zeros.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

setLength

public void setLength(int length)
               throws AS400SecurityException,
                      ErrorCompletingRequestException,
                      java.lang.InterruptedException,
                      java.io.IOException,
                      ObjectDoesNotExistException

Sets the size (in bytes) of the user space. Valid values are 1 through 16,776,704.

Parameters:

length - The new size (in bytes) of the user space.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

setMustUseProgramCall

public void setMustUseProgramCall(boolean useProgramCall)

Sets the method used to carry out user space read and write operations. If false (the default) read and write requests are made via the AS/400 file server. Internally, an IFSRandomAccessFile object is used to perform read and write requests. If true, internally a ProgramCall object is used to perform read and write requests. In general, requests made via the file object are faster but the behavior of requests made via a ProgramCall object are more consistent with AS/400 user space APIs. This option cannot be reset once a connection has been established.

Parameters:

useProgramCall - Internally use ProgramCall to carry out read and write requests.

setPath

public void setPath(java.lang.String path)
             throws java.beans.PropertyVetoException

Sets the path for the user space. The path can only be set before a connection has been established.

Parameters:

path - The fully qualified integrated file system path name.

Throws:

java.beans.PropertyVetoException - If the change is vetoed.

setSystem

public void setSystem(AS400 system)
               throws java.beans.PropertyVetoException

Sets the AS400 system for the user space. The system can only be set before a connection has been established.

Parameters:

system - The AS400 system.

Throws:

java.beans.PropertyVetoException - If the change is vetoed.

write

public void write(byte[] dataBuffer,
                  int userSpaceOffset)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException,
                  ObjectDoesNotExistException

Writes up to dataBuffer.length bytes from dataBuffer into the user space beginning at userSpaceOffset.

Parameters:

dataBuffer - The data buffer to be written.

userSpaceOffset - The position in the user space to start writing.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

write

public void write(byte[] dataBuffer,
                  int userSpaceOffset,
                  int dataOffset,
                  int length)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException,
                  ObjectDoesNotExistException

Writes up to length bytes from dataBuffer beginning at dataOffset into the user space beginning at userSpaceOffset.

Parameters:

dataBuffer - The data buffer to be written.

userSpaceOffset - The position in the user space to start writing.

dataOffset - The position in the write data buffer from which to start copying.

length - The length (in bytes) of data to be written.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

write

public void write(byte[] dataBuffer,
                  int userSpaceOffset,
                  int dataOffset,
                  int length,
                  int forceAuxiliary)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException,
                  ObjectDoesNotExistException

Writes up to length bytes from dataBuffer beginning at dataOffset into the user space beginning at userSpaceOffset.

Parameters:

dataBuffer - The data buffer to be written to the user space.

userSpaceOffset - The position in the user space to start writing.

dataOffset - The position in the write data buffer from which to start copying.

length - The length (in bytes) of data to be written.

forceAuxiliary - The method of forcing changes made to the user space to auxiliary storage. Valid values are:

• FORCE_NONE
• FORCE_ASYNCHRONOUS
• FORCE_SYNCHRONOUS

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.

write

public void write(java.lang.String data,
                  int userSpaceOffset)
           throws AS400SecurityException,
                  ErrorCompletingRequestException,
                  java.lang.InterruptedException,
                  java.io.IOException,
                  ObjectDoesNotExistException

Writes a string into the user space beginning at userSpaceOffset. String is converted into bytes and written to the user space as if by the write(byte[],int) method.

Parameters:

data - The data buffer to be written to the user space.

userSpaceOffset - The position in the user space to start writing.

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 AS/400.

ObjectDoesNotExistException - If the AS400 object does not exist.