UserQueue

java.lang.Object
- com.ibm.as400.access.UserQueue

```
public class UserQueue
extends java.lang.Object
```
The UserQueue class represents an IBM i user queue object.
This class is currently in pre-BETA status and its existence serves as a placeholder for code under development.
This class currently will only function when running on the IBM i using native Methods.
This class requires native method support which is still under development.
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.

Field Summary

Fields
Modifier and Type	Field and Description
`static byte`	`QUEUE_TYPE_FIRST_IN_FIRST_OUT` Queue type is first-in first-out
`static byte`	`QUEUE_TYPE_KEYED` Queue type is keyed
`static byte`	`QUEUE_TYPE_LAST_IN_FIRST_OUT` Queue type is last-in first-out

Constructor Summary

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`UserQueue(AS400 system, java.lang.String path)` Constructs a UserQueue object.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`create(java.lang.String extendedAttribute, byte queueType, int keyLength, int maximumMessageSize, int initialNumberOfMessages, int additionalNumberOfMessages, java.lang.String authority, java.lang.String description, java.lang.String replace)` Creates a user queue on the system.
`void`	`delete()` Deletes the user queue.
`java.lang.String`	`dequeue()` Dequeues the next entry from a FIFO or LIFO queue as a string
`int`	`dequeue(byte[] dequeueMessagePrefixBytes, byte[] outputBytes)` Dequeues an entry from the user queue.
`void`	`enqueue(byte[] enqueueMessagePrefixBytes, byte[] entryBytes)` Enqueues an entry on the user queue using the ENQ MI instruction.
`void`	`enqueue(java.lang.String value)` Enqueues a string on the user queue
`static int`	`getDequeueMessagePrefixBytesLength(byte[] deqMsgPrefixBytes)` Returns the output length from the deqMsgPrefixBytes buffer
`boolean`	`isMustUseNativeMethods()` Indicates if the native methods will be used internally to perform user queue dequeue and enqueue requests.
`static void`	`resetDequeueMessagePrefixBytes(byte[] dequeueMessagePrefixBytes)` Resets the dequeueMessagePrefixBytes to zero
`static void`	`resetEnqueueMessagePrefixBytes(byte[] enqueueMessagePrefixBytes)` Resets the enqueueMessagePrefixBytes to zero The format of the enqueueMessagePrefix is the following Offset Dec Hex Field Name Data Type and Length 0 0 Size of message to be enqueued Bin(4) 4 4 Enqueue key value Char(key length) (ignored for FIFO/LIFO queues with key lengths equal to 0)
`static void`	`setEnqueueMessagePrefixBytesEnqueueKey(byte[] enqueueMessagePrefixBytes, byte[] keyBytes)`
`static void`	`setEnqueueMessagePrefixBytesMessageSize(byte[] enqueueMessagePrefixBytes, int messageSize)`
`void`	`setMustUseNativeMethods(boolean useNativeMethods)` Specifies whether native methods are used by the current job to perform user queue operations.
`java.lang.String`	`toString()` Returns the String representation of this user queue object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - QUEUE_TYPE_FIRST_IN_FIRST_OUT
```
public static final byte QUEUE_TYPE_FIRST_IN_FIRST_OUT
```
    Queue type is first-in first-out
    
    See Also:
    Constant Field Values
  - QUEUE_TYPE_KEYED
```
public static final byte QUEUE_TYPE_KEYED
```
    Queue type is keyed
    
    See Also:
    Constant Field Values
  - QUEUE_TYPE_LAST_IN_FIRST_OUT
```
public static final byte QUEUE_TYPE_LAST_IN_FIRST_OUT
```
    Queue type is last-in first-out
    
    See Also:
    Constant Field Values
- Constructor Detail
  - UserQueue
```
public UserQueue(AS400 system,
         java.lang.String path)
          throws java.io.UnsupportedEncodingException,
                 java.io.CharConversionException
```
    Constructs a UserQueue object.
    
    Parameters:
    system - The system object representing the system on which the user queue exists.
    path - The fully qualified integrated file system path name of the user queue.
    
    Throws:
    
    java.io.UnsupportedEncodingException
    
    java.io.CharConversionException
- Method Detail
  - create
```
public void create(java.lang.String extendedAttribute,
          byte queueType,
          int keyLength,
          int maximumMessageSize,
          int initialNumberOfMessages,
          int additionalNumberOfMessages,
          java.lang.String authority,
          java.lang.String description,
          java.lang.String replace)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   IllegalObjectTypeException,
                   java.lang.InterruptedException,
                   ObjectAlreadyExistsException,
                   ObjectDoesNotExistException
```
    Creates a user queue on the system. The queue will be created with the attributes provided.
    Parameters:
    extendedAttribute - The extended attribute of the user queue to be created.
    queueType - The type of the queue, which indicates the sequences in which messages are to be dequeued from the queue. Valid values are QUEUE_TYPE_FIRST_IN_FIRST_OUT, QUEUE_TYPE_KEYED, QUEUE_TYPE_LAST_IN_FIRST_OUT.
    keyLength - The length in bytes of the message key from 1 to 256, if the type of the queue is QUEUE_TYPE_KEYED. Otherwise, the value must be 0.
    maximumMessageSize - The maximum allowed size of messages to be placed on the queue. The maximum size allowed is 64,0000 bytes.
    initialNumberOfMessages - The initial number of messages that the queue can contain.
    additionalNumberOfMessages - The amount to increase the maximum number of messages value when the queue is full. If set to 0, the queue cannot be extended and an error message is returned when attempting to enqueue an additional entry.
    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.io.IOException - If an error occurs while communicating with the system.
    
    IllegalObjectTypeException - If the object on the system is not the required type.
    
    java.lang.InterruptedException - If this thread is interrupted.
    
    ObjectAlreadyExistsException - If the object already exists on the system.
    
    ObjectDoesNotExistException - If the library does not exist on the system.
  - delete
```
public void delete()
```
    Deletes the user queue.
  - dequeue
```
public java.lang.String dequeue()
                         throws IllegalObjectTypeException,
                                java.io.UnsupportedEncodingException
```
    Dequeues the next entry from a FIFO or LIFO queue as a string
    
    Throws:
    
    IllegalObjectTypeException
    
    java.io.UnsupportedEncodingException
  - dequeue
```
public int dequeue(byte[] dequeueMessagePrefixBytes,
          byte[] outputBytes)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   IllegalObjectTypeException,
                   java.lang.InterruptedException,
                   ObjectDoesNotExistException
```
    Dequeues an entry from the user queue.
    Parameters:
    dequeueMessagePrefixBytes - A Dequeue Message Prefix byte array used by the DEQI MI instruction. This provides both input and output information for the dequeue operation. The format of this byte array is as follows. For more information, see http://publib.boulder.ibm.com/infocenter /iseries/v7r1m0/index.jsp?topic=/rzatk/DEQ.htm.
    Offset Dec Hex Field Name Data Type and Length 0 0 Timestamp of enqueue of message Char(8) ++ 8 8 Dequeue wait time-out value Char(8) + 16 10 Size of message dequeued Bin(4) ++ 20 14 Access state modification option Char(1) + indicator and message selection criteria 21 15 Search key (ignored for FIFO/LIFO Char(key length) + queues but must be present for FIFO/LIFO queues with nonzero key length values) * Message key Char(key length) ++ Note: Fields shown here with one plus sign (+) indicate input to the instruction, and fields shown here with two plus signs (++) are returned by the machine.
    outputBytes - Byte array to receive the bytes contained in the queue entry.
    
    Returns:
    Returns 1 if a message was dequeued, 0 if a message was not dequeued.
    
    Throws:
    
    AS400SecurityException - If a security or authority error occurs.
    
    ErrorCompletingRequestException - If an error occurs before the request is completed.
    
    java.io.IOException - If an error occurs while communicating with the system.
    
    IllegalObjectTypeException - If the object on the system is not the required type.
    
    java.lang.InterruptedException - If this thread is interrupted.
    
    ObjectDoesNotExistException - If the object does not exist on the system.
  - toString
```
public java.lang.String toString()
```
    Returns the String representation of this user queue object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    The String representation of this user queue object.
  - enqueue
```
public void enqueue(java.lang.String value)
             throws java.io.UnsupportedEncodingException,
                    IllegalObjectTypeException
```
    Enqueues a string on the user queue
    
    Throws:
    
    java.io.UnsupportedEncodingException
    
    IllegalObjectTypeException
  - enqueue
```
public void enqueue(byte[] enqueueMessagePrefixBytes,
           byte[] entryBytes)
             throws java.lang.Exception
```
    Enqueues an entry on the user queue using the ENQ MI instruction.
    Parameters:
    enqueueMessagePrefixBytes - A byte array representing the message prefix passed to the ENQ MI instruction. A value of null may be passed when using a FIFO to LIFO queue.
    The format of the message prefix is the following. For more information, see http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0 /index.jsp?topic=/rzatk/ENQ.htm
    Offset Dec Hex Field Name Data Type and Length 0 0 Size of message to be enqueued Bin(4) 4 4 Enqueue key value (ignored for Char(key length) FIFO/LIFO queues with key lengths equal to 0)
    The static method setEnqueueMessagePrefixBytesMessageSize() can be used to set the size. The static method setEnqueueMessagePrefixBytesEnqueueKey() can be used to set the size.
    entryBytes - A byte array representing the entry to add to the queue.
    
    Throws:
    
    AS400SecurityException - If a security or authority error occurs.
    
    ErrorCompletingRequestException - If an error occurs before the request is completed.
    
    java.io.IOException - If an error occurs while communicating with the system.
    
    IllegalObjectTypeException - If the object on the system is not the required type.
    
    java.lang.InterruptedException - If this thread is interrupted.
    
    ObjectDoesNotExistException - If the object does not exist on the system.
    
    java.lang.Exception
  - isMustUseNativeMethods
```
public boolean isMustUseNativeMethods()
```
    Indicates if the native methods will be used internally to perform user queue dequeue and enqueue requests.
    
    Returns:
    true if user dequeue and enqueue requests will be performed via native methods; false otherwise.
    See Also:
    setMustUseNativeMethods(boolean)
  - setMustUseNativeMethods
```
public void setMustUseNativeMethods(boolean useNativeMethods)
```
    Specifies whether native methods are used by the current job to perform user queue operations. This option can only be set to true when the application is running on the System i.
    
    Parameters:
    useNativeMethods - Internally use native methods to perform read and write requests.
    See Also:
    isMustUseNativeMethods()
  - resetDequeueMessagePrefixBytes
```
public static void resetDequeueMessagePrefixBytes(byte[] dequeueMessagePrefixBytes)
```
    Resets the dequeueMessagePrefixBytes to zero
  - getDequeueMessagePrefixBytesLength
```
public static int getDequeueMessagePrefixBytesLength(byte[] deqMsgPrefixBytes)
```
    Returns the output length from the deqMsgPrefixBytes buffer
  - resetEnqueueMessagePrefixBytes
```
public static void resetEnqueueMessagePrefixBytes(byte[] enqueueMessagePrefixBytes)
```
    Resets the enqueueMessagePrefixBytes to zero The format of the enqueueMessagePrefix is the following Offset Dec Hex Field Name Data Type and Length 0 0 Size of message to be enqueued Bin(4) 4 4 Enqueue key value Char(key length) (ignored for FIFO/LIFO queues with key lengths equal to 0)
  - setEnqueueMessagePrefixBytesMessageSize
```
public static void setEnqueueMessagePrefixBytesMessageSize(byte[] enqueueMessagePrefixBytes,
                                           int messageSize)
```
  - setEnqueueMessagePrefixBytesEnqueueKey
```
public static void setEnqueueMessagePrefixBytesEnqueueKey(byte[] enqueueMessagePrefixBytes,
                                          byte[] keyBytes)
```

Methods inherited from class java.lang.Object

QUEUE_TYPE_FIRST_IN_FIRST_OUT

QUEUE_TYPE_KEYED

QUEUE_TYPE_LAST_IN_FIRST_OUT

UserQueue

create

delete

dequeue

dequeue

toString

enqueue

enqueue

isMustUseNativeMethods

setMustUseNativeMethods

resetDequeueMessagePrefixBytes

getDequeueMessagePrefixBytesLength

resetEnqueueMessagePrefixBytes

setEnqueueMessagePrefixBytesMessageSize

setEnqueueMessagePrefixBytesEnqueueKey