Creating a Queue
In order to create a queue, first of all you must create your nSession object, which is your effectively your logical and physical connection to a Universal Messaging Realm. This is achieved by using the correct RNAME for your Universal Messaging Realm when constructing the nSessionAttributes object, as shown below:
String[] RNAME={"nsp://127.0.0.1:9000"};
nSessionAttributes nsa=new nSessionAttributes(RNAME);
nSession mySession=nSessionFactory.create(nsa);
mySession.init();
Once the nSession.init() method is successfully called, your connection to the realm will be established.
Using the nSession objects instance 'mySession', we can then begin creating the queue object. Queues have an associated set of attributes, that define their behaviour within the Universal Messaging Realm Server. As well as the name of the queue, the attributes determine the availability of the events published to a queue to any consumers wishing to consume them.
To create a queue, we do the following:
nChannelAttributes cattrib = new nChannelAttributes();
cattrib.setChannelMode(nChannelAttributes.QUEUE_MODE);
cattrib.setMaxEvents(0);
cattrib.setTTL(0);
cattrib.setType(nChannelAttributes.PERSISTENT_TYPE);
cattrib.setName("myqueue");
nQueue myQueue=mySession.createQueue(cattrib);
Now we have a reference to a Universal Messaging queue within the realm.
Note:
For information about the set of permissible characters you can use to name a queue, see the section
Creating Queues in the Enterprise Manager section of the
Administration Guide.
Setting User and Group Permissions during Queue Creation
User and a group permissions can be created using the factory methods defined in the nStorePermission class.
For example, a user permission can be created with
nStorePermission.createForUser(<username>, <host>, <permission_mask>)
or
nStorePermission.createForUser(<subject>, <permission_mask>)
where <username> and <host> are String parameters, <subject> is a String in the format "<username>@<host>" and <permission_mask> is a long representing the mask for the corresponding user/group.
The permission mask must be generated using the nStorePermissionGenerator class. The utility provides methods for building queue permissions from an EnumSet. The following enumeration is defined:
nQueueStorePermission - for all permissions that can be applied on a queue
Here is an example for generating the permission mask:
long queuePermission = nStorePermissionGenerator.getQueuePermissions
(EnumSet.of(nQueueStorePermission.MANAGE, nQueueStorePermission.PUSH));
The Client API contains the following method which is accessible from a session instance:
createQueue(nChannelAttributes attributes, Collection<nStorePermission> queuePermissions)
The method for creating multiple stores is overloaded and accepts collection with permissions that can be applied to the corresponding store. Here is an example:
create(nChannelAttributes[] attr, Collection<Collection<nStorePermission>> permissionsList)
The permissions for each store are also a collection, since multiple permissions can be applied on a single store during creation. If the create procedure fails for one of the stores, the others are created successfully. The reason for the failure can be found using the methods defined in the nCreateResult class which is used as a returned value for each store when multiple queues are requested to be created from the client.
If applying the requested permissions fails when attempting to create a single queue, an nSecurityException is thrown containing the name of the subject for which the operation has failed. For example, if the client tries to grant permissions for a group which does not exist, the operation will fail and the queue will not be created. The client is authorized to grant permissions on store creation only for existing groups.
Here is a code sample illustrating the usage for creating a queue:
long userPermission = nStorePermissionGenerator.getQueuePermissions(
EnumSet.of(nQueueStorePermission.MANAGE, nQueueStorePermission.PUSH));
long groupPermissionMask = nStorePermissionGenerator.getQueuePermissions(
EnumSet.of(nQueueStorePermission.PEEK, nQueueStorePermission.PURGE));
nStorePermission firstPermission = nStorePermission.createForUser(
"user", "127.0.0.1", userPermission);
nStorePermission secondPermission = nStorePermission.createForUser(
"secondUser", "10.0.34.71", secondUserPermission);
Collection<nStorePermission> queuePermissions =
Arrays.asList(firstPermission, secondPermission);
nChannelAttributes channelAttributes = new nChannelAttributes("queueToCreate");
session.createQueue(channelAttributes, queuePermissions);