com.ibm.as400.access

Class UserSpace

  • All Implemented Interfaces:
    Serializable


    public class UserSpace
    extends Object
    implements Serializable
    Represents a user space object in the IBM i operating system.

    Usage note: By default, the UserSpace class will make use of two different host servers. For performance reasons, the File Server will be used for read() and write() requests, and the Remote Command Host Server will be used for create() and other requests. This behavior can be changed with the setMustUseProgramCall() method.

    Similarly, when running directly on IBM i, by default the UserSpace class will call internal API's and commands on-thread when possible, bypassing the Remote Command Host Server. This behavior can be changed with the setMustUseSockets() method.

    As a performance optimization, when running directly on IBM i, it is possible to use native methods to access the user space from the current job. To enable this support, use the setMustUseNativeMethods() method.

    For applications that access user spaces located in QTEMP, users are strongly advised to keep everything in the same job, by calling setMustUseProgramCall(true) and setMustUseSockets(true), since different jobs have different QTEMP libraries.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static String DOMAIN_DEFAULT
      Constant representing the default domain for the user space.
      static String DOMAIN_SYSTEM
      Constant indicating the domain for the user space is *SYSTEM.
      static String DOMAIN_USER
      Constant indicating the domain for the user space is *USER.
      static int FORCE_ASYNCHRONOUS
      Force to auxiliary storage option that allows 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 allows changes to be forced synchronously.
    • Constructor Summary

      Constructors 
      Constructor and Description
      UserSpace()
      Constructs a UserSpace object.
      UserSpace(AS400 system, String path)
      Constructs a UserSpace object.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addPropertyChangeListener(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(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, String extendedAttribute, byte initialValue, String textDescription, String authority)
      Creates the user space.
      void create(String domain, int length, boolean replace, String extendedAttribute, byte initialValue, String textDescription, 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.
      String getName()
      Returns the user space name.
      String getPath()
      Returns the integrated file system path name of the object represented by the user space.
      AS400 getSystem()
      Returns the system object for this user space.
      boolean isAutoExtendible()
      Indicates if the user space is auto extendible.
      boolean isMustUseNativeMethods()
      Indicates if the native methods will be used internally to perform user space read and write requests.
      boolean isMustUseProgramCall()
      Indicates if the Toolbox ProgramCall class will be used internally to perform user space read and write requests.
      boolean isMustUseSockets()
      Indicates whether sockets must be used when internally calling programs and commands.
      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.
      String read(int userSpaceOffset, int length)
      Returns a string from the user space beginning at userSpaceOffset.
      void removePropertyChangeListener(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(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 setMustUseNativeMethods(boolean useNativeMethods)
      Specifies whether native methods are used by the current to perform user space read and write operations.
      void setMustUseProgramCall(boolean useProgramCall)
      Specifies the API set that is used to perform user space read and write operations.
      void setMustUseSockets(boolean mustUseSockets)
      Sets this object to using sockets.
      void setPath(String path)
      Sets the path for the user space.
      void setSystem(AS400 system)
      Sets the system object 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(String data, int userSpaceOffset)
      Writes a string into the user space beginning at userSpaceOffset.
    • Field Detail

      • FORCE_ASYNCHRONOUS

        public static final int FORCE_ASYNCHRONOUS
        Force to auxiliary storage option that allows changes to be forced asynchronously.
        See Also:
        Constant Field Values
      • 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.
        See Also:
        Constant Field Values
      • FORCE_SYNCHRONOUS

        public static final int FORCE_SYNCHRONOUS
        Force to auxiliary storage option that allows changes to be forced synchronously.
        See Also:
        Constant Field Values
      • DOMAIN_DEFAULT

        public static final String DOMAIN_DEFAULT
        Constant representing the default domain for the user space. The QALWUSRDMN system value is used to determine the domain.
        See Also:
        Constant Field Values
      • DOMAIN_USER

        public static final String DOMAIN_USER
        Constant indicating the domain for the user space is *USER.
        See Also:
        Constant Field Values
      • DOMAIN_SYSTEM

        public static final String DOMAIN_SYSTEM
        Constant indicating the domain for the user space is *SYSTEM.
        See Also:
        Constant Field Values
    • Constructor Detail

      • UserSpace

        public UserSpace()
        Constructs a UserSpace object. The system and path properties must be set before using any method requiring a connection to the system.
      • UserSpace

        public UserSpace(AS400 system,
                 String path)
        Constructs a UserSpace object. It creates a UserSpace instance that represents the user space path on system.
        Parameters:
        system - The system that contains the user space.
        path - The fully qualified integrated file system path name to the user space.

    • Method Detail

      • addPropertyChangeListener

        public void addPropertyChangeListener(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 listener object.
      • addUserSpaceListener

        public void addUserSpaceListener(UserSpaceListener listener)
        Adds a listener to be notified when a UserSpaceEvent is fired.
        Parameters:
        listener - The listener object.
      • addVetoableChangeListener

        public void addVetoableChangeListener(VetoableChangeListener listener)
        Adds a listener to be notified when the value of any constrained property is changed.
        Parameters:
        listener - The listener object.
      • close

        public void close()
                   throws IOException
        Closes the user space and releases any system resources associated with the stream. This will not close the connection to the Host Server job held by the associated AS400 object. Note: Closing the user space does not delete it. It simply closes this UserSpace object's file stream connection to the user space.
        Throws:
        IOException
        See Also:
        delete()
      • create

        public void create(int length,
                  boolean replace,
                  String extendedAttribute,
                  byte initialValue,
                  String textDescription,
                  String authority)
                    throws AS400SecurityException,
                           ErrorCompletingRequestException,
                           InterruptedException,
                           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. User spaces with lengths of 16,773,120 or less will be created with optimum space alignment. These user spaces can not be resized to greater than 16,773,120 bytes. For performance, lengths of 16,773,120 or less are recommended.
        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.
        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.
      • create

        public void create(String domain,
                  int length,
                  boolean replace,
                  String extendedAttribute,
                  byte initialValue,
                  String textDescription,
                  String authority)
                    throws AS400SecurityException,
                           ErrorCompletingRequestException,
                           InterruptedException,
                           IOException,
                           ObjectDoesNotExistException
        Creates the user space.
        Parameters:
        domain - The domain into which the user space is created. Valid value are:
        length - The initial size (in bytes) of the user space. Valid values are 1 through 16,776,704. User spaces with lengths of 16,773,120 or less will be created with optimum space alignment. These user spaces can not be resized to greater than 16,773,120 bytes. For performance, lengths of 16,773,120 or less are recommended.
        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.
        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.
      • getName

        public String getName()
        Returns the user space name.
        Returns:
        The name of the user space.
      • getPath

        public 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 system object for this user space.
        Returns:
        The system object for this user space.
      • isMustUseProgramCall

        public boolean isMustUseProgramCall()
        Indicates if the Toolbox ProgramCall class will be used internally to perform user space read and write requests. If false, Toolbox Integrated File System classes will be used to perform user space read and write requests.
        Returns:
        true if user space read and write requests will be performed via program call; false otherwise.
        See Also:
        setMustUseProgramCall(boolean)
      • isMustUseNativeMethods

        public boolean isMustUseNativeMethods()
        Indicates if the native methods will be used internally to perform user space read and write requests. If false, either ProgramCall or Toolbox Integrated File System classes will be used to perform user space read and write requests.
        Returns:
        true if user space read and write requests will be performed via native methods; false otherwise.
        See Also:
        setMustUseNativeMethods(boolean)
      • removePropertyChangeListener

        public void removePropertyChangeListener(PropertyChangeListener listener)
        Removes this listener from being notified when a bound property changes.
        Parameters:
        listener - The listener object.
      • removeUserSpaceListener

        public void removeUserSpaceListener(UserSpaceListener listener)
        Removes a listener from the UserSpace listeners list.
        Parameters:
        listener - The listener object.
      • removeVetoableChangeListener

        public void removeVetoableChangeListener(VetoableChangeListener listener)
        Removes this listener from being notified when a constrained property changes.
        Parameters:
        listener - The listener object.
      • setMustUseProgramCall

        public void setMustUseProgramCall(boolean useProgramCall)
        Specifies the API set that is used to perform user space read and write operations. This method is useful when using ProgramCall or CommandCall objects in conjunction with user spaces. If false (the default), read and write requests are made via the 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, which are made via the Remote Command Host Server. In general, requests made via the File object are faster, but the behavior of requests made via a ProgramCall object is more consistent with user space API's.

        If accessing user spaces located in QTEMP, it is strongly advised that setMustUseProgramCall(true) be called. In addition, depending on whether subsequent accesses of the user space (such as by program calls) will be run on- or off-thread, you should also call setMustUseSockets(true).

        This property cannot be reset once a connection has been established.

        Parameters:
        useProgramCall - Internally use ProgramCall to perform read and write requests.
        See Also:
        isMustUseProgramCall()
      • setMustUseNativeMethods

        public void setMustUseNativeMethods(boolean useNativeMethods)
                                     throws UnsupportedEncodingException,
                                            CharConversionException,
                                            UnsatisfiedLinkError,
                                            SecurityException
        Specifies whether native methods are used by the current to perform user space read and write operations. This option can only be set to true when the application is running on the System i. This method may only be called after the path to the user space is set.

        It is not advised to use native methods to access user spaces in QTEMP because toolbox does not provide a method to create a user space in QTEMP of the current job.

        The programmer must be aware that no locking occurs when native methods are used to read and write from the user space. If a user space is being used by multiple threads or processes, the values read may reflect a partial operation performed by another thread or process.

        Parameters:
        useNativeMethods - Internally use ProgramCall to perform read and write requests.
        Throws:
        CharConversionException
        UnsupportedEncodingException
        SecurityException
        UnsatisfiedLinkError
        See Also:
        isMustUseNativeMethods()
      • setPath

        public void setPath(String path)
                     throws 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 to the user space.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • setSystem

        public void setSystem(AS400 system)
                       throws PropertyVetoException
        Sets the system object for the user space. The system can only be set before a connection has been established.
        Parameters:
        system - The system that contains the user space.
        Throws:
        PropertyVetoException - If the change is vetoed.
      • write

        public void write(byte[] dataBuffer,
                 int userSpaceOffset,
                 int dataOffset,
                 int length,
                 int forceAuxiliary)
                   throws AS400SecurityException,
                          ErrorCompletingRequestException,
                          InterruptedException,
                          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.
        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.
      • setMustUseSockets

        public void setMustUseSockets(boolean mustUseSockets)
        Sets this object to using sockets. This method is useful when running directly on IBM i, using ProgramCall or CommandCall objects in conjunction with user spaces. When your Java program runs on the IBM i system, some Toolbox classes access data via a direct API call instead of making a socket call to the system (for example, to the Remote Command Host Server). There are minor differences in the behavior of the classes when they use direct API calls instead of socket calls. If your program is affected by these differences you can use this method to force the Toolbox classes to use socket calls instead of direct API calls. The default is false.

        Note: This method has no effect if the Java application is running remotely, that is, not running directly on an IBM i system. When running remotely, the Toolbox submits all program and command calls via sockets, regardless of the setting of this property.

        This property cannot be reset once a connection has been established.

        Parameters:
        mustUseSockets - true to use sockets; false otherwise.
        See Also:
        isMustUseSockets(), CommandCall.setThreadSafe(Boolean), ProgramCall.setThreadSafe(boolean)
      • isMustUseSockets

        public boolean isMustUseSockets()
        Indicates whether sockets must be used when internally calling programs and commands. When your Java program runs on the system, some Toolbox classes access data via a direct call to an API instead of making a socket call to the system (for example, to the Remote Command Host Server). There are minor differences in the behavior of the classes when they use direct API calls instead of socket calls. If your program is affected by these differences you can check whether this object will use socket calls instead of API calls by using this method.
        Returns:
        true if this object must use sockets; false otherwise.
        See Also:
        setMustUseSockets(boolean)