com.safmq
Class MQConnection

java.lang.Object
  com.safmq.MQConnection

public class MQConnection
extends java.lang.Object

This class provides an interface to communicate with a SAFMQ message queue server. Typically instances of this class are constructed by the MQBuilder class, however constructing the class directly is also allowed.

Once constructed, this class may be used to construct instances of the class MessageQueue to abstract the connection interface to the message queue level.

Note: This class is not thread safe, and applications should take precautions to not initiate communications with a message queue via more than one (1) thread simultaneously.

See Also:

MQBuilder.buildConnection(URI,String,String), MessageQueue

Nested Class Summary

class	MQConnection.QueueData Result data from a call to MQConnection.EnumerateQueues(Vector).
class	MQConnection.QueuePermissions Contains an entity's permission when accessing a queue.
class	MQConnection.UserDescription Result data from a call to MQConnection.EnumerateUsers(Vector).

Constructor Summary

MQConnection(java.net.Socket s, java.lang.String user, java.lang.String password)
Constructs the object from the name of the server, the tcp/ip port to be used the user's name and password.

Method Summary

int	AddUserIdentity(java.lang.String subjectDN, java.lang.String issuerDN, java.lang.String username) Adds an X509 digitital certificate identity mapping.
int	AdvanceCursor(QueueHandle qhandle, CursorHandle cursorID) Advances the cursor to the next message in the queue.
int	BeginTransaction() Begins a transaction which causes all Retrieve & Enqueue operations to be committed atomically.
void	Close() Closes the connection to the server.
int	CloseCursor(QueueHandle qhandle, CursorHandle cursorID) Closes a cursor when it is no longer needed to access the queue.
int	CloseQueue(QueueHandle handle) Closes a queue which was previously opened.
int	CommitTransaction() Commits a group of Retrieve & Enqueue operations atomically.
int	CreateGroup(java.lang.String groupname) Creates a new security group on the SAFMQ server.
int	CreateQueue(java.lang.String queuename) Creates a new queue on the SAFMQ server.
int	CreateTempQueue(java.lang.String[] tmpQueueName, QueueHandle tmpQueue) Creates a new temporary message queue.
int	CreateUser(java.lang.String username, java.lang.String password, java.lang.String description) Create a new user by providing a user name, password and description.
int	DeleteGroup(java.lang.String groupname) Removes the security group from the SAFMQ server.
int	DeleteQueue(java.lang.String queuename) Attempts to remove a queue fromt he SAFMQ server.
int	DeleteUser(java.lang.String username) Delete a user from the SAFMQ server.
int	EndTransaction() Commits and closes a group of Retrieve & Enqueue operations.
int	Enqueue(QueueHandle handle, QueueMessage msg) Places a message on the queue.
int	EnqueueWithRelay(java.net.URI uri, QueueMessage msg) Enqueues a message for message relay forwarding to another queue/queue server.
int	EnumerateGroups(java.util.Vector groups) Retrieves a list of all groups available on the SAFMQ server.
int	EnumerateQueues(java.util.Vector qnames) Retrieves a list of all queues served by the connection and the queue's owner.
int	EnumerateUserIdentities(java.lang.String username, java.util.Vector ids) Lists a set of X509 subject name and issuer names associated with the passed SAFMQ user login id.
int	EnumerateUsers(java.util.Vector users) Retrieves a list of users which may access the SAFMQ server.
MQConnection.UserDescription	genDesc(java.lang.String name, java.lang.String desc) For external use of UserDescriptions.
int	GetQueueStatistics(QueueHandle qhandle, boolean includeStorageBytes, boolean includeMessageBytes, QueueStatistics stats) Gets statistics about an open queue.
int	GetServerMajorProtocolVersion()
int	GetServerMinorProtocolVersion()
int	GetServerStatistics(QueueStatistics stats) Gets statistics for an entire server.
int	GroupAddUser(java.lang.String groupname, java.lang.String username) Adds a user to a group.
int	GroupDeleteUser(java.lang.String groupname, java.lang.String username) Deletes a user from a group.
int	GroupGetPermissions(java.lang.String groupname, ActorPermissions actorPerms) Retrieves the permissions of a specific group.
int	GroupGetUsers(java.lang.String groupname, java.util.Vector users) Retrieves a the list of users in a group.
int	GroupSetPermissions(java.lang.String groupname, boolean modifyqueues, boolean modifyusers, boolean modifygroups) Changes the permissions for the specified group.
int	OpenCursor(QueueHandle qhandle, CursorHandle cursorID) Opens a cursor for sequential reading of the queue.
int	OpenQueue(java.lang.String queuename, QueueHandle handle) Opens a queue for reading and writing.
int	PeekCursor(QueueHandle qhandle, boolean retrievebody, CursorHandle cursorID, QueueMessage msg) Retrieves the message pointed to by cursorID.
int	PeekFront(QueueHandle qhandle, boolean retrievebody, int timeoutseconds, QueueMessage msg) Gathers the highest priority FIFO message present on the queue.
int	PeekID(QueueHandle qhandle, boolean retrievebody, UUID id, int timeoutseconds, QueueMessage msg) Gathers the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage).
int	QueueDeleteGroupPermission(java.lang.String queuename, java.lang.String groupname) Removes permissions for a specified group.
int	QueueDeleteUserPermission(java.lang.String queuename, java.lang.String username) Removes permissions for a specified user.
int	QueueEnumeratePermissions(java.lang.String queuename, java.util.Vector perms) Retrieves the permission profile for the specified queue.
int	QueueSetGroupPermission(java.lang.String queuename, java.lang.String groupname, boolean rd, boolean wr, boolean destroy, boolean changesecurity) Attempts to set the security profile for a specified group.
int	QueueSetUserPermission(java.lang.String queuename, java.lang.String username, boolean rd, boolean wr, boolean destroy, boolean changesecurity) Attempts to set the security profile for a specified user.
int	RemoveUerIdentity(java.lang.String subjectDN, java.lang.String issuerDN) Removes an X509 digitital certificate identity mapping.
int	Retrieve(QueueHandle qhandle, boolean retrievebody, int timeoutseconds, QueueMessage msg) Retrieves the highest priority FIFO message present on the queue.
int	RetrieveCursor(QueueHandle qhandle, boolean retrievebody, CursorHandle cursorID, QueueMessage msg) Retrieves the message pointed to by cursorID.
int	RetrieveID(QueueHandle qhandle, boolean retrievebody, UUID id, int timeoutseconds, QueueMessage msg) Retrieves the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage).
int	RollbackTransaction() Rolls back or "undoes" a group of Retrieve & Enqueue operations atomically.
int	SeekID(QueueHandle qhandle, UUID id, int timeoutseconds, CursorHandle cursorID) Attempts to locate the messaged indicated by id.
int	SetPassword(java.lang.String username, java.lang.String password) Changes the password for the specified user.
int	TestCursor(QueueHandle qhandle, CursorHandle cursorID) Determines whether the cursor indicated by cursorID is still a valid cursor, and has not been invalidated by other queue readers.
int	UserGetGroups(java.lang.String username, java.util.Vector groups) Retrieves a the list of groups the in which the user resides.
int	UserGetPermissions(java.lang.String username, ActorPermissions actorPerms) Retrieve the permissions for a specific user.
int	UserSetPermissions(java.lang.String username, boolean modifyqueues, boolean modifyusers, boolean modifygroups) Change the user's permissions to those specified.

Methods inherited from class java.lang.Object

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

Constructor Detail

MQConnection

public MQConnection(java.net.Socket s,
                    java.lang.String user,
                    java.lang.String password)
             throws MQException,
                    java.io.IOException

Constructs the object from the name of the server, the tcp/ip port to be used the user's name and password.

Parameters:

s - A socket connected to the server.

user - The name of the user wishing to connect to the server

password - The password of the user wishing to connect to the server

Throws:

MQException - In the case that the supplied credentials are not accepted by the SAFMQ server. The value of MQException.getErrorCode() could be but is not limited to:

Safmq.EC_LOGIN

The login credentials supplied were not accepted.

java.io.IOException - In the case the SAFMQ server was not able to be contacted via TCP/IP.

Method Detail

genDesc

public MQConnection.UserDescription genDesc(java.lang.String name,
                                            java.lang.String desc)

For external use of UserDescriptions.

Parameters:

name - Name of the account

desc - Description of the account

Returns:

A newly allocated UserDescription object.

Close

public void Close()

Closes the connection to the server.

GetServerMajorProtocolVersion

public int GetServerMajorProtocolVersion()

GetServerMinorProtocolVersion

public int GetServerMinorProtocolVersion()

OpenQueue

public int OpenQueue(java.lang.String queuename,
                     QueueHandle handle)

Opens a queue for reading and writing. The queue is then after referenced by the parameter handle for calls such as Enqueue(QueueHandle,QueueMessage) and Retrieve(QueueHandle,boolean,int,QueueMessage).

Note: Queues which have been opened by a call to OpenQueue() must be closed by a call to CloseQueue(QueueHandle) if the queue is not closed, resources allocated by a call to OpenQueue() will not be released.

Parameters:

queuename - The name of the queue

handle - Receives a reference to the queue

Returns:

Safmq.EC_NOERROR on success otherwise errors such as these, but not limited to could be produced:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_DOESNOTEXIST	The queue does not exist on the server specified.

See Also:

CloseQueue(QueueHandle handle)

CloseQueue

public int CloseQueue(QueueHandle handle)

Closes a queue which was previously opened.

Parameters:

handle - Reference to the previously opened queue

Returns:

Safmq.EC_NOERROR on success otherwise errors such as these, but not limited to could be produced:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTOPEN	The queue was not currently in an open status in the context of this connection.

GetQueueStatistics

public int GetQueueStatistics(QueueHandle qhandle,
                              boolean includeStorageBytes,
                              boolean includeMessageBytes,
                              QueueStatistics stats)

Gets statistics about an open queue. Places statistic information into the parameter stats.

Parameters:

qhandle - Handle to an open queue

includeStorageBytes - Causes server to calculate the number of bytes on disk

includeMessageBytes - Causes the server to calculate the number of bytes in queue, may be less than bytes on disk

stats - Receives the statistics information.

Returns:

Safmq.EC_NOERROR on success
Safmq.EC_NETWORKERROR
Safmq.EC_NOTOPEN

GetServerStatistics

public int GetServerStatistics(QueueStatistics stats)

Gets statistics for an entire server.

Parameters:

stats - Receives the statistics information.

Returns:

Safmq.EC_NOERROR on success
Safmq.EC_NETWORKERROR
Safmq.EC_NOTOPEN

EnqueueWithRelay

public int EnqueueWithRelay(java.net.URI uri,
                            QueueMessage msg)

Enqueues a message for message relay forwarding to another queue/queue server. After completion, the return code will be EC_NOERROR on success and the msg's time stamp and message will have been set. It is important to note if the response queue name is not set, any errors from the final destination queue/queue server will be lost. It is suggested to use round tripping unless error determination is not required, otherwise errors generated by the final destination server such as:

EC_DOESNOTEXIST

EC_NOTAUTHORIZED

EC_WRONGMESSAGETYPE

EC_NOTOPEN

EC_FORWARDNOTALLOWED

EC_DUPLICATEMSGID

will not returned to the client.

Parameters:

uri - A safmq URI in the format safmq://user:password@server:port/queuename -or- for ssl safmqs://user:password@server:port/queuename.
Note: the port specification is optional.

msg - The message to be sent.

Returns:

Safmq.EC_NOERROR on success
Safmq.EC_INVALIDNAME in case of an invalid URL
Safmq.EC_NETWORKERROR
Safmq.EC_NOTAUTHORIZED
Safmq.EC_NOTOPEN
Safmq.EC_WRONGMESSAGETYPE
Safmq.EC_FORWARDNOTALLOWED

Enqueue

public int Enqueue(QueueHandle handle,
                   QueueMessage msg)

Places a message on the queue. The object msg must have been previously prepared before calling this method. Upon successful sending of the message, the message id and message time stamp will be set by the server and may be retrieved by a call to QueueMessage.getMessageID() and QueueMessage.getTimeStamp() respectively.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Parameters:

handle - A reference to a queue opened by a call to OpenQueue()

msg - The message to be placed on the queue

Returns:

Safmq.EC_NOERROR on success, Otherwise results may be such listed below but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to write messages to this queue.

See Also:

OpenQueue(String, QueueHandle)

Retrieve

public int Retrieve(QueueHandle qhandle,
                    boolean retrievebody,
                    int timeoutseconds,
                    QueueMessage msg)

Retrieves the highest priority FIFO message present on the queue. The results are placed in the object msg.

Note: Retrieved messages are removed from the queue

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

timeoutseconds - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR is returned and the resulting message is placed in msg, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_TIMEDOUT	The operation timed out before a message became available.

See Also:

OpenQueue(String, QueueHandle)

RetrieveID

public int RetrieveID(QueueHandle qhandle,
                      boolean retrievebody,
                      UUID id,
                      int timeoutseconds,
                      QueueMessage msg)

Retrieves the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage). The results are placed in the object msg.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Note: Retrieved messages are removed from the queue.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

id - The UUID of the message to be retrieved.

timeoutseconds - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_TIMEDOUT	The operation timed out before a message became available.

See Also:

Enqueue(QueueMessage), OpenQueue(String, QueueHandle)

RetrieveCursor

public int RetrieveCursor(QueueHandle qhandle,
                          boolean retrievebody,
                          CursorHandle cursorID,
                          QueueMessage msg)

Retrieves the message pointed to by cursorID. The results are placed in the object msg.

Note: Retrieved messages are removed from the queue.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

cursorID - The cursor indicating the current position in the queue to be read from

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_CURSORINVALIDATED	The cursor no longer points to a valid location in the queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.

See Also:

OpenQueue(String, QueueHandle)

PeekFront

public int PeekFront(QueueHandle qhandle,
                     boolean retrievebody,
                     int timeoutseconds,
                     QueueMessage msg)

Gathers the highest priority FIFO message present on the queue. The results are placed in the object msg. Any errors from the operation are returned on the stack. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

timeoutseconds - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_TIMEDOUT	The operation timed out before a message became available.

See Also:

OpenQueue(String, QueueHandle)

PeekID

public int PeekID(QueueHandle qhandle,
                  boolean retrievebody,
                  UUID id,
                  int timeoutseconds,
                  QueueMessage msg)

Gathers the message identified by id in the message's receipt id, set prior to the message having been enqueued (See: Enqueue(QueueMessage). The results are placed in the object msg. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Note: Message responders will typically place the message id of the original message in the receipt id of the message being returned. This round-trip message identification is provided by SAFMQ as a method for coordinated two-way communications.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

id - The UUID of the message to be retrieved.

timeoutseconds - The number of seconds to wait before returning, a value of zero (0) will cause the method to return immediately if no messages are present on the queue, a value of (-1) will cause the method to wait until a message is placed on the queue.

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_TIMEDOUT	The operation timed out before a message became available.

See Also:

Enqueue(QueueMessage), OpenQueue(String, QueueHandle)

PeekCursor

public int PeekCursor(QueueHandle qhandle,
                      boolean retrievebody,
                      CursorHandle cursorID,
                      QueueMessage msg)

Retrieves the message pointed to by cursorID. The results are placed in the object msg. The message retrieved is not removed from the queue and is available for reading by other queue readers.

Note: Retrieved messages are removed from the queue.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

retrievebody - A flag indicating whether the body of the message should be retrieved

cursorID - The cursor indicating the current position in the queue to be read from

msg - Receives the contents of the message.

Returns:

Upon success a value of Safmq.EC_NOERROR, otherwise errors such as but not limited to could occur:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOMOREMESSAGES	The queue is empty and no more messages are available.
Safmq.EC_ALREADYCLOSED	The queue reference is not valid as it has been closed.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_CURSORINVALIDATED	The cursor no longer points to a valid location in the queue.

See Also:

OpenQueue(String, QueueHandle)

OpenCursor

public int OpenCursor(QueueHandle qhandle,
                      CursorHandle cursorID)

Opens a cursor for sequential reading of the queue. The newly opened cursor points to the oldest, highest priority message in the queue.

Cursors may be used to violate the priority FIFO nature of the queue by scanning the queue and only retreiving messages which meet the criteria of the reader. Cursor access is sequential when used in conjunction with AdvanceCursor(CursorHandle), however specific messages may be sought out by a call to SeekID(UUID,int,CursorHandle).

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

cursorID - A previously allocated reference to a CursorHandle which will receive the reference to the cursor.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.

See Also:

OpenQueue(String, QueueHandle)

CloseCursor

public int CloseCursor(QueueHandle qhandle,
                       CursorHandle cursorID)

Closes a cursor when it is no longer needed to access the queue. The cursor is invalidated after a call to CloseCursor() and should not be used again.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

cursorID - The cursor to be closed.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.

See Also:

OpenQueue(String, QueueHandle)

AdvanceCursor

public int AdvanceCursor(QueueHandle qhandle,
                         CursorHandle cursorID)

Advances the cursor to the next message in the queue.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

cursorID - The cursor to be advanced.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_CURSORINVALIDATED	The cursor is no longer valid.

See Also:

OpenQueue(String, QueueHandle)

SeekID

public int SeekID(QueueHandle qhandle,
                  UUID id,
                  int timeoutseconds,
                  CursorHandle cursorID)

Attempts to locate the messaged indicated by id. If the message is succesfully located, the cursor will point to the message idenfified and the message may be retrieved there after.

Parameters:

qhandle - A handle to a queue previously opened by a call to OpenQueue(String)

id - The receipt UUID of the message to be located

timeoutseconds - The maximum number of seconds the call should be allowed before resulting in a "timeout".

cursorID - The cursor which should be be assigned the position of the message indicated by id

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The user is not authorized to read messages from this queue.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_CURSORINVALIDATED	The cursor is no longer valid.

See Also:

OpenQueue(String, QueueHandle)

TestCursor

public int TestCursor(QueueHandle qhandle,
                      CursorHandle cursorID)

Determines whether the cursor indicated by cursorID is still a valid cursor, and has not been invalidated by other queue readers.

Parameters:

cursorID - The cursor which should be be evaluated

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTOPEN	The queue specified has not been opened by this connection.
Safmq.EC_CURSORINVALIDATED	The cursor is no longer valid.

See Also:

OpenQueue(String, QueueHandle)

BeginTransaction

public int BeginTransaction()

Begins a transaction which causes all Retrieve & Enqueue operations to be committed atomically.

Returns:

Safmq.EC_NOERROR, Safmq.EC_NETWORKERROR, Safmq.EC_ALREADYOPEN if a transaction is already open

CommitTransaction

public int CommitTransaction()

Commits a group of Retrieve & Enqueue operations atomically.

Returns:

Safmq.EC_NOERROR, Safmq.EC_NETWORKERROR

RollbackTransaction

public int RollbackTransaction()

Rolls back or "undoes" a group of Retrieve & Enqueue operations atomically.

Returns:

Safmq.EC_NOERROR, Safmq.EC_NETWORKERROR

EndTransaction

public int EndTransaction()

Commits and closes a group of Retrieve & Enqueue operations.

Returns:

Safmq.EC_NOERROR, Safmq.EC_NETWORKERROR, Safmq.EC_NOTOPEN in the case that a transaction was not open.

EnumerateQueues

public int EnumerateQueues(java.util.Vector qnames)

Retrieves a list of all queues served by the connection and the queue's owner. The passed Vector qnames receives MQConnection.QueueData objects to enumerate the queue.

Parameters:

qnames - The vector which will be emptied then populated with MQconnection.QueueData objects.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR

A networking error has occurred and the connection is no longer valid.

See Also:

MQConnection.QueueData

EnumerateUsers

public int EnumerateUsers(java.util.Vector users)

Retrieves a list of users which may access the SAFMQ server. The result user information is in the form of MQConnection.UserDescription objects placed in the passed Vector, users.

Parameters:

users - The vector which will be emptied then populated with MQConnection.UserDescription objects

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR

A networking error has occurred and the connection is no longer valid.

See Also:

MQConnection.UserDescription

EnumerateGroups

public int EnumerateGroups(java.util.Vector groups)

Retrieves a list of all groups available on the SAFMQ server. The result group information is in the form of String objects representing the name of the group.

Parameters:

groups - The vector which will be emptied then populated with String objects containing the names of the groups.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR

A networking error has occurred and the connection is no longer valid.

CreateUser

public int CreateUser(java.lang.String username,
                      java.lang.String password,
                      java.lang.String description)

Create a new user by providing a user name, password and description.

Parameters:

username - The name of the new user

password - The password for the new user, cannot be null

description - The description for the new user.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_ALREADYDEFINED	A user with this name already exists
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create users.

DeleteUser

public int DeleteUser(java.lang.String username)

Delete a user from the SAFMQ server.

Parameters:

username - The name of the suer to delete.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create users.
Safmq.EC_DOESNOTEXIST	The user specified does not exist.

UserSetPermissions

public int UserSetPermissions(java.lang.String username,
                              boolean modifyqueues,
                              boolean modifyusers,
                              boolean modifygroups)

Change the user's permissions to those specified.

Parameters:

username - Name of the user to change

modifyqueues - Allow the user to create queues

modifyusers - Allow the user to create and delete users and set permmsions

modifygroups - Allow the user to create, delete, and change group membership and permissions

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to modify user permissions.
Safmq.EC_DOESNOTEXIST	The specified user does not exist on the SAFMQ server.

UserGetPermissions

public int UserGetPermissions(java.lang.String username,
                              ActorPermissions actorPerms)

Retrieve the permissions for a specific user.

Parameters:

username - The name of the user

actorPerms - Receives the permissions for the user, must not be null.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_DOESNOTEXIST	The specified user does not exist on the SAFMQ server, or the user has no permissions set.

SetPassword

public int SetPassword(java.lang.String username,
                       java.lang.String password)

Changes the password for the specified user.

Parameters:

username - Name of the user

password - New password for the user.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create users.
Safmq.EC_DOESNOTEXIST	The specified user does not exist on the SAFMQ server.

AddUserIdentity

public int AddUserIdentity(java.lang.String subjectDN,
                           java.lang.String issuerDN,
                           java.lang.String username)

Adds an X509 digitital certificate identity mapping. This method should be used to provide for a passwordless authentication using SSL and X509 digital certificates.

Example: (the sample X509 certificate shipped with SAFMQ source)

        Subject: C=US, ST=Nebraska, L=Omaha, O=SAFMQ, CN=Matthew Battey/emailAddress=mattbattey@users.sourceforge.net
        Issuer:  C=US, ST=Nebraska, L=Omaha, O=SAFMQ, CN=Matthew Battey/emailAddress=mattbattey@users.sourceforge.net
        

Thawte's Issuer DN:

        Issuer: C=ZA, ST=Western Cape, L=Cape Town, O=Thawte Consulting cc, OU=Certification Services Division, CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
        

In this case the issuer and subject are the same value, because the certificate shipped with SAFMQ is a "self-signed" certificate. Typically the Subject DN will be set by you and the Issuer DN will be determined by the organization certifying the authenticity of the certificate's origin.

Note: The Java implentation produces distinguished name strings in reverse order in comparison to the default output from tools like OpenSSL. SAFMQ uses OpenSSL so these must be in the order that OpenSSL would report the value pair order.

Parameters:

subjectDN - [in] the Subject Distinguished Name of the certificate

issuerDN - [in] the Issuer Distinguished Name of the certificate

username - [in] the target SAFMQ login id (username)

Returns:

EC_NOERROR upon success, EC_DOESNOTEXIST if the user ID does not exist, EC_NOTAUTHORIZED, EC_NETWORKERROR

RemoveUerIdentity

public int RemoveUerIdentity(java.lang.String subjectDN,
                             java.lang.String issuerDN)

Removes an X509 digitital certificate identity mapping. This method should be used to provide for a passwordless authentication using SSL and X509 digital certificates.

Parameters:

subjectDN - [in] the Subject Distinguished Name of the certificate

issuerDN - [in] the Issuer Distinguished Name of the certificate

Returns:

EC_NOERROR upon success, EC_DOESNOTEXIST if the user ID does not exist, EC_NOTAUTHORIZED, EC_NETWORKERROR

EnumerateUserIdentities

public int EnumerateUserIdentities(java.lang.String username,
                                   java.util.Vector ids)

Lists a set of X509 subject name and issuer names associated with the passed SAFMQ user login id.

Parameters:

username - [in] The user name used to search for X509 identities.

ids - [out] This vector of safmq::X509Identity objects is populated upon successful return

Returns:

EC_NOERROR on success, EC_NETWORKERROR on network issue

CreateGroup

public int CreateGroup(java.lang.String groupname)

Creates a new security group on the SAFMQ server.

Parameters:

groupname - Name of the group to create.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_ALREADYDEFINED	A group with this name already exists
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create groups.

DeleteGroup

public int DeleteGroup(java.lang.String groupname)

Removes the security group from the SAFMQ server.

Parameters:

groupname - The name of the group

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create groups.
Safmq.EC_DOESNOTEXIST	The group specified does not exist.

GroupSetPermissions

public int GroupSetPermissions(java.lang.String groupname,
                               boolean modifyqueues,
                               boolean modifyusers,
                               boolean modifygroups)

Changes the permissions for the specified group.

Parameters:

groupname - The name of the group

modifyqueues - Whether the group may create queues

modifyusers - Whether the group may create and delete users and set permissions

modifygroups - Whether the gorup may create, delete and change group membership and permissions

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to modify group permissions.
Safmq.EC_DOESNOTEXIST	The specified group does not exist on the SAFMQ server.

GroupGetPermissions

public int GroupGetPermissions(java.lang.String groupname,
                               ActorPermissions actorPerms)

Retrieves the permissions of a specific group.

Parameters:

groupname - The name of the group

actorPerms - Receives the permissions, must not be null

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_DOESNOTEXIST	The specified group does not exist on the SAFMQ server, or no permissions have been set for that group.

GroupAddUser

public int GroupAddUser(java.lang.String groupname,
                        java.lang.String username)

Adds a user to a group.

Parameters:

groupname - The name of the group

username - The name of the user

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to modify group permissions.
Safmq.EC_DOESNOTEXIST	The specified group does not exist on the SAFMQ server.

GroupDeleteUser

public int GroupDeleteUser(java.lang.String groupname,
                           java.lang.String username)

Deletes a user from a group.

Parameters:

groupname - The name of the group

username - The name of the user

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to modify group permissions.
Safmq.EC_DOESNOTEXIST	The specified group does not exist on the SAFMQ server.

GroupGetUsers

public int GroupGetUsers(java.lang.String groupname,
                         java.util.Vector users)

Retrieves a the list of users in a group. The names of the users are deposited into the Vector users in the form of String objects.

Parameters:

groupname - The name of the users.

users - A vector receiving String objects containing the user's name.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_DOESNOTEXIST	The specified group does not exist on the SAFMQ server.

UserGetGroups

public int UserGetGroups(java.lang.String username,
                         java.util.Vector groups)

Retrieves a the list of groups the in which the user resides. The names of the groups are deposited into the Vector users in the form of String objects.

Parameters:

username - The name of the users.

groups - A vector receiving String objects containing the group's name.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_DOESNOTEXIST	The specified user does not exist on the SAFMQ server.

CreateQueue

public int CreateQueue(java.lang.String queuename)

Creates a new queue on the SAFMQ server. The queue's owner is automatically set to the current logged in user.

Parameters:

queuename - The name of the new queue to be created.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_ALREADYDEFINED	A queue with this name already exists
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to create queues.

CreateTempQueue

public int CreateTempQueue(java.lang.String[] tmpQueueName,
                           QueueHandle tmpQueue)

Creates a new temporary message queue. The queue is removed from the server once all clients close their handles to the queue, explicitly or implicity by disconnecting from the server.
After calling CreateTempQueue the SAFMQ server has created a queue, flagged as temporary, returns the server generated name of the queue, and a handle to that queue. Closing the queue removes it from the system, there is no need to explicitly delete it. Using the Closing technique, it is possible that the queue may remain open, because other clients have access to the queue.

Parameters:

tmpQueueName - [out] Receives the name of the temporary queue, relative to the server, when supplying this queue name to other clients, the server URL must be prepended to the name. i.e. If the url safmq://localhost was used to open the connection use "safmq://localhost/" + tmpQueue when supplying the queue name to other clients. Must be an array of atleast one element, first element will receive the name.

tmpQueue - [out] Receives a handle to the open queue

Returns:

EC_NOERROR, EC_NETWORKERROR, EC_ALREADYDEFINED, EC_NOTAUTHORIZED

DeleteQueue

public int DeleteQueue(java.lang.String queuename)

Attempts to remove a queue fromt he SAFMQ server. Queues may only be removed if the user has the rights to do so and the queue is not currently in use.

Parameters:

queuename - The name of the queue to be removed.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_QUEUEOPEN	The queue is currently in use by some connection.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to delete this queue.

QueueSetUserPermission

public int QueueSetUserPermission(java.lang.String queuename,
                                  java.lang.String username,
                                  boolean rd,
                                  boolean wr,
                                  boolean destroy,
                                  boolean changesecurity)

Attempts to set the security profile for a specified user. When a queue is first created only the queue's creator (owner) may alter the queue's security.

Parameters:

queuename - Name of the queue

username - Name of the user

rd - User may read from the queue

wr - User may write to the queue

destroy - User may delete the queue

changesecurity - User may alter security of the queue

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to change the permissions of the user.

QueueDeleteUserPermission

public int QueueDeleteUserPermission(java.lang.String queuename,
                                     java.lang.String username)

Removes permissions for a specified user.

Parameters:

queuename - The name of the queuee

username - The name of the user

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to change the permissions of the user.
Safmq.EC_DOESNOTEXIST	The security record for that user does not exist.

QueueSetGroupPermission

public int QueueSetGroupPermission(java.lang.String queuename,
                                   java.lang.String groupname,
                                   boolean rd,
                                   boolean wr,
                                   boolean destroy,
                                   boolean changesecurity)

Attempts to set the security profile for a specified group. When a queue is first created only the queue's creator (owner) may alter the queue's security.

Parameters:

queuename - Name of the queue

groupname - Name of the group

rd - Group may read from the queue

wr - Group may write to the queue

destroy - Group may delete the queue

changesecurity - Group may alter security of the queue

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to change the permissions of the user.

QueueDeleteGroupPermission

public int QueueDeleteGroupPermission(java.lang.String queuename,
                                      java.lang.String groupname)

Removes permissions for a specified group.

Parameters:

queuename - The name of the queue

groupname - The name of the group

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR	A networking error has occurred and the connection is no longer valid.
Safmq.EC_NOTAUTHORIZED	The current logged in user is not authorized to change the permissions of the group.
Safmq.EC_DOESNOTEXIST	The security record for that group does not exist.

QueueEnumeratePermissions

public int QueueEnumeratePermissions(java.lang.String queuename,
                                     java.util.Vector perms)

Retrieves the permission profile for the specified queue. Resultant permissions are placed in the Vector perms as QueuePermissions objects.

Parameters:

queuename - The name of the queue.

perms - The vector which will be emptied and populated with MQConnection.QueuePermissions objects.

Returns:

Safmq.EC_NOERROR upon success, otherwise errors returned could be but are not limited to:

Safmq.EC_NETWORKERROR

A networking error has occurred and the connection is no longer valid.

See Also:

MQConnection.QueuePermissions