Creating a Channel
Channels can be created programmatically as detailed below, or they can be created using the Enterprise Manager.
In order to create a channel, first of all you must create an nSession object, which is effectively your logical and physical connection to a Universal Messaging realm. This is achieved by using an 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 channel object. Channels have an associated set of attributes, that define their behaviour within the Universal Messaging Realm Server. As well as the name of the channel, the attributes determine the availability of the events published to a channel to any subscribers wishing to consume them.
To create a channel, we do the following:
nChannelAttributes cattrib = new nChannelAttributes();
cattrib.setMaxEvents(0);
cattrib.setTTL(0);
cattrib.setType(nChannelAttributes.PERSISTENT_TYPE);
cattrib.setName("mychannel");
nChannel myChannel=mySession.createChannel(cattrib);
Now we have a reference to a Universal Messaging channel within the realm.
Note:
The set of permissible characters you can use to name a channel is described in the section
Creating Channels in the Enterprise Manager section of the
Administration Guide.
Setting User and Group Permissions during Channel 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 channel permissions from an EnumSet. The following enumeration is defined:
nChannelStorePermission - for all permissions that can be applied on a channel
Here is an example for generating the permission mask:
long channelPermission = nStorePermissionGenerator.getChannelPermissions
(EnumSet.of(nChannelStorePermission.MANAGE, nChannelStorePermission.PUBLISH,
nChannelStorePermission.PURGE));
The Client API contains the following method which is accessible from a session instance:
createChannel(nChannelAttributes attributes, long initialEid,
Collection<nStorePermission> channelPermissions)
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 channels are requested to be created from the client.
If applying the requested permissions fails when attempting to create a single channel, 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 channel 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 channel:
long userPermission = nStorePermissionGenerator.getChannelPermissions(
EnumSet.of(nChannelStorePermission.MANAGE, nChannelStorePermission.PUBLISH));
long secondUserPermission = nStorePermissionGenerator.getChannelPermissions(
EnumSet.of(nChannelStorePermission.PUBLISH, nChannelStorePermission.PURGE));
nStorePermission firstPermission = nStorePermission.createForUser(
"user", "127.0.0.1", userPermission);
nStorePermission secondPermission = nStorePermission.createForUser(
"username@127.0.0.1", secondUserPermission);
Collection<nStorePermission> channelPermissions =
Arrays.asList(firstPermission, secondPermission);
nChannelAttributes channelAttributes = new nChannelAttributes("channelToCreate");
session.createChannel(channelAttributes, 0, channelPermissions);