Chapter 14. Messaging
The AdminTask scripting object has several groups of methods that support messaging. In this chapter, we explore some useful methods from the following groups:
SIBAdminCommands
SIBJMSAdminCommands
SIBAdminBusSecurityCommands
Depending on your version of the product, there are 125 to 175 methods in the command groups that deal with messaging. Nobody uses all of those methods every day. We have selected a manageable subset of the methods in these groups to illustrate the main tasks that have to be performed any time you configure a messaging bus. We also give information that is not well-documented elsewhere and illustrate our points with a simple example. We then list the other commands in these groups at the end of this chapter along with a brief explanation of each.
An Introduction to Messaging
Messaging can be used to integrate legacy applications, to combine existing applications to serve new business needs, and to add a façade to an existing application. It is a very loosely coupled method of performing system integration. Messaging requires you to configure two distinct pieces of plumbing within an application server.
You have to configure some plumbing that prepares the application server with other application servers. The AdminTask methods that configure this plumbing are all part of the SIBAdminCommands command group.
You have to configure some additional plumbing that allows an application to be deployed to that server to send messages and retrieve messages.1 The AdminTask methods that configure this plumbing are all part of the SIBJMSAdminCommands command group and the SIBAdminBusSecurityCommands command group.
1 A discussion of the Java Message Service is beyond the scope of this book. For a good introduction, consider Chapter 33 of http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.
Messaging Basics
Let’s use email as an example to walk through basic messaging. The sender must know the recipient’s address, but the recipient does not have to be online when the message is sent. Messaging builds on this pattern.
First, however, let’s get rid of one requirement: The sender does not have to know the recipient’s address information. So when the sender “sends” a message, you can just append that message to the end of a table in a database. You can configure2 that imaginary database to be either a file or real database. Either way, that imaginary database always isolates sender from receiver. When a recipient wants to “receive” a message, the recipient reads the last row in the data table and marks it for deletion.
2 See AdminTask.createSIBEngine(). The decision to use a database versus a filestore must be made when the messaging engine is created.
Second, you can hide all of the details from any applications that use messaging. An application will ask a factory to provide it with access to a messaging resource. The application will then either send a message or retrieve a message. The sender can determine whether a message was delivered, but the sender will not know who retrieved the message or whether the same recipient received two consecutive messages.
Messaging can be set up to deliver a message several ways. It can deliver the message to the first recipient who retrieves that message; messaging set up in this fashion is called a queue. Messaging can also be set up to retain a message until all registered listeners have acknowledged receipt of the message; messaging set up in this fashion is called a topic.
In its simplest form, configuring messaging requires you to perform the following configuration steps on the application server:
1. Create the messaging bus itself.
2. Add one or more members to the bus.
3. Create either a queue or a topic.
4. Create a connection factory.
5. Create either a JMSQueue or a JMSTopic.
We explore this in a simple example and then discuss ways in which you might need to improve this example for your environment.
Terminology
The messaging scheme described in the previous section is called a messaging bus. The queue or the topic that holds messages for a bus is called a destination. It is convenient to think of a queue or a topic as a table in an imaginary database. It is convenient also to think of sending a message as appending a row to that table, as it is convenient to think of retrieving a message as selecting a row from that table and then marking that row for deletion. There is a lot of complexity hidden under all that convenient thinking.3 But that metaphor exposes just enough of the details to allow us to configure a simple messaging bus.
3 For a lot more formal detail, consider the IBM Redbook SG247297, “Experience J2EE! Using WebSphere Application Server V6.1,” section 15.1. The additional resources listed in that chapter are also quite helpful.
Each application server and each cluster that communicates on the messaging bus is called a bus member. Each bus member has a messaging engine. The messaging engine gets created automatically when a server or a cluster is added as a member of a messaging bus. Messaging engines talk to our imaginary database. The IBM InfoCenter calls this imaginary database a message store. This message store can either be a real database or a file in the file system. You create this message store whenever you do something that creates a messaging engine.4 Messaging engines also talk to each other.
4 See AdminTask.addSIBusMember() and AdminTask.createSIBEngine() for additional details.
Example: Creating a Bus
In this very simple example, we create a simple but useful messaging queue. If you want to use this script, there are some things you will have to change:
• You will have to change the node name to a node name that exists in your cell.
• You will have to change the server name to a server that exists on that node in your cell.
• If your cell already has an SIBus with the same name used, you will have to use a different name. Each SIBus in a cell must have a unique name.
• If your cell already has any of the JNDI names that are used in this sample script, you will have to edit the names so that they do not conflict with your existing JNDI names.
• If your cell already has a queue or a connection factory or a J2C administrative object with a name used here, you will have to change the names.
The variables in Listing 14.1 are used in this example code. You should be able to download this file and adapt this sample to your environment by just changing the values assigned to the variables in lines 01 through 18.
Listing 14.1 Variables for Sample Code
The following lines create the messaging bus5 and display any messaging buses6 that exist in a cell.
5 See AdminTask.createSIBus() in the reference section of this chapter.
6 See AdminTask.listSIBuses() in the reference section of this chapter.
print AdminTask.createSIBus('[-bus ' + nameOfBus + ' ]')
print AdminTask.listSIBuses()
What you see of a bus in the configuration files at this point is nothing more than a few elements in a file called sib-bus.xml. This file lives in your configuration repository. You will find this file under cells/buses/nameOfBus. Although this line is necessary for every line of script that follows, it does not really add any functionality to any server in the cell. Until you add bus members and destinations, the messaging bus itself is nothing more than a name.
The following code configures some plumbing for one particular application server7 and displays8 the plumbing you configured.
7 See AdminTask.addSIBusMember() in the reference section of this chapter.
8 See AdminTask.listSIBusMembers() in the reference section of this chapter.
The code here does several things. It adds a busMembers element to the sib-bus.xml file. Adding a bus member creates configuration for a messaging engine inside the server or inside the cluster9 you added to the bus. A messaging engine knows how to talk to the imaginary database that will act as the middle man standing between message producer and message consumer. In this example, the imaginary database is actually a file store. If you change one argument and supply a JNDI name, you can use either an embedded database called Derby or an industrial strength database such as DB/2 or Oracle.
9 This book assumes that the reader is already familiar with clusters and the reasons for creating and using clusters. For a good discussion of the fundamentals of clusters, see the WebSphere Application Server documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.pmc.nd.iseries.doc/concepts/cjn_mdb_endpt_overview.html. For a discussion about how a cluster interacts with a messaging bus, see http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.pmc.nd.iseries.doc/concepts/cjn_mdb_endpt_overview.html. The subtopics on this page explain in detail what it means to add a cluster as a bus member.
You could easily modify the code here slightly to configure messaging plumbing for a cluster instead of a server. All you would have to do is provide the name of a cluster instead of the names of a node and server.10 Although it is easy to add a cluster as a messaging bus member, it is important to understand the default behavior of a cluster that becomes a member of a messaging bus.
10 See AdminTask.addSIBusMember() in the reference section of this chapter.
By default, if you create a cluster with five member servers11 and you make that cluster a member of a messaging bus, only one server out of the entire cluster will actually send and receive messages on the messaging bus. This is because, by default, the application server only activates one messaging engine12 no matter how many servers there are in the cluster. Therefore, in this sample cluster with five member servers, one server is actively communicating on the messaging bus, and the other four are on hot standby. It is possible to activate more than one messaging engine per cluster. Administratively, it is easy to do. It is just a matter of writing policies for the messaging engines in the cluster. There are side effects to doing this that include possible loss of message order and stranded messages. Make sure you read and understand the WebSphere Application Server documentation article on “Workload sharing with queue destinations”13 and all articles mentioned on that page before proceeding.
11 There is nothing magical about the choice of five servers. The point is that no matter how many servers you create in the cluster, only one will get an active messaging engine. The other servers will be on hot standby, doing nothing but waiting for the active server’s messaging engine to fail.
12 See “Adding a cluster to a bus” in the WebSphere Application Server documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc/concepts/cjt0005_.html.
13 See http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc/concepts/cjt0014_.html.
Given that we often use clusters to provide workload balancing for applications and (by default) clusters provide high availability, not load balancing, for messaging engines, it makes sense to create one cluster to support messaging buses and additional clusters to support applications. This is especially true for WebSphere Application Server v6.1, since v7 adds additional messaging topology options. This is called the remote messaging pattern. There are two diagrams and a short section of text that describe this pattern in an IBM Redbook®.14 Make sure you understand this material before you attempt to workload balance the messaging engines in a messaging bus.
14 See IBM Redbook SG247776, “Leading Practices for WebSphere Dynamic Process Edition v6.2,” section 7.2.2, Remote Messaging Topology Pattern. In particular, notice Figures 7-2 and 7-3.
So far, there are no tables that you need to care about in this imaginary database. That will change in the following code sample that creates a queue15 and displays the queue16 after you create it:
15 See AdminTask.createSIBDestination() in the reference section of this chapter.
16 See AdminTask.listSIBJMSQueues() in the reference section of this chapter.
When the AdminTask.createSIBDestination() method is executed, code in the application server creates the necessary tables in this imaginary database. The same method can be used to create either a queue or a topic space simply by changing the value of the “-type” option. Please note though that a separate set of methods are used to display the configuration information about queues,17 topic spaces, and any topics they might contain. Remember too that topics are hierarchical creatures that live inside a topic space. Topic spaces and topics18 have their own display methods.
17 See AdminTask.listSIBJMSQueues() and AdminTask.showSIBJMSQueue().
18 See AdminTask.listSIBJMSTopics() and AdminTask.showSIBJMSTopic().
After you create those tables, you have configured all the plumbing needed for the server or cluster to act as a part of the messaging bus you created. It is that easy. So far, we have not yet given any application the ability to use any of that plumbing. The following code changes that. Start by creating19 a connection factory and then displaying20 the newly created connection factory’s attributes, as shown in the following code lines:
19 See AdminTask.createSIBJMSConnectionFactory() in the reference section of this chapter.
20 See AdminTask.showSIBJMSConnectionFactory() in the reference section of this chapter.
A connection factory gives an application a way to find your messaging plumbing and retrieve a piece of code that will actually ask the messaging bus to send and receive messages on behalf of the client application. Think of a connection factory as something that maps the industry standard Java Messaging Service (JMS) façade to the underlying proprietary Service Integration Bus implementation. Applications use components of the Java Messaging Service. You configure service integration buses (SIB) to integrate components of your enterprise architecture. You must specify the following in order for the connection factory to do its job:
• How visible the connection factory should be. You can make a connection factory that an entire cell and an entire node can use. You can restrict the visibility of your connection factory to just one server or one cluster of servers.
• The name of the bus that will hold the queue or the topic that applications will ultimately use.
• A JNDI name that applications will use when they want to talk to a queue or a topic that this connection factory knows about. The mapping of the JNDI name to a queue or a topic on a specific bus is the glue that connects JMS to SIB.
Note
The description and the category are optional arguments that help you document your configuration decisions. Any text you supply for these arguments will also be visible to anybody who uses the Admin Console.
The following code shows how to have a connection factory create a code object—an SIBJMSQueue—that allows an application to use the messaging bus to send and receive messages.21 The line displays22 attributes of the SIBJMSQueue that was configured.
21 See AdminTask.createSIBJMSQueue() in the reference section of this chapter.
22 See AdminTask.showSIBJMSQueue() in the reference section of this chapter.
You’ve just completed everything necessary to create the simplest possible messaging queue. All you needed to accomplish this task were the following AdminTask methods:
• createSIBus
• addSIBusMember
• createSIBDestination
• createSIBJMSFactory
• createSIBJMSQueue
There are a few things you might want to change depending on the needs of your system and the needs of your customers. We used the file system for our imaginary database. You might choose to change that to a commercial database product. Extremely demanding security requirements might require additional constraints. We enable security later in this chapter.
Example: Deleting a Bus
Deleting a bus is very important during development and debugging. Very often, it is easier to start from scratch than to figure out which setting is incorrectly configured and what side effects that might have caused. To delete a messaging bus, as shown in Listing 14.2, you need to delete:
• The bus itself
• The SIBJMSQueue
• The SIBJMSConnectionFactory
Listing 14.2 Delete Our Sample Messaging Bus
If you have enabled security, you might have to delete some authentication artifacts as well. If you are using an external database, you might have to delete some DataSources and JDBC artifacts. Again, sometimes it is easier to delete the incorrect configuration, correct your create method, and recreate a configuration than it is to locate all the side effects of an improper configuration.
Listing 14.2 shows some code that deletes this sample bus. Notice that to find the SIBJMSQueue you created, you have to look for a J2CAdminObject, which is on line 50. Also worth noting is that to find SIBJMSConnectionFactory, you have to look for a ConnectionFactory—on line 55. In both cases, you also have to know the name of the object you want. You can see that while AdminTask.deleteSIBus()23 takes the name of a bus as its parameter, both AdminTask.deleteSIBJMSQueue()24 and AdminTask.deleteSIBJMSConnectionFactory()25 require configuration IDs. Unfortunately, we don’t currently have an easy way to locate the configuration ID, given the name attribute of the configuration item. Therefore, you will see a findIDbyName() method here.
23 See AdminTask.deleteSIBus() in the reference section of this chapter.
24 See AdminTask.deleteSIBJMSQueue() in the reference section of this chapter.
25 See AdminTask.deleteSIBJMSConnectionFactory() in the reference section of this chapter.
If you delete a messaging bus that uses either a filestore or a Derby database or a Cloudscape® database, you might want to make sure you delete the file system directory that contains that datastore or filestore. If you recreate the messaging bus with the same bus name as a messaging bus you deleted and the new messaging bus refuses to start, check your logs for error messages that mention a common mode error.26 If you find such an error, delete the directory that contained the database or filestore for the messaging bus. This is an operating system task. There are no scripting objects that do this for you. These databases can be found in the profile that holds the configuration information for your deployment manager. In the root of that profile, look for a directory that has a name such as databases or devicestores. The directory you need to delete will be one of the directories under that. The exact names might be version-dependent. See the WebSphere Application Server documentation for details.
26 See details in the WebSphere Application Server documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc/ref/rjk_prob0.html. Page down to the section titled “Problems when you re-create a service integration bus.”
Security
It is difficult to find any resource that concisely delineates the steps you must take to secure a messaging bus. Because of this, we created an administrative checklist for you. This checklist is not a substitute for a security audit by a qualified professional. To secure a messaging bus, you must
• Enable administrative security for the cell.
• Enable security for the bus.
• Create (or use an existing) authentication alias to use between messaging engines. This step becomes unnecessary beginning with WebSphere Application Server version 7.
• Create (or use an existing) secure transport chain to use between messaging engines.27
27 Setting up SSL from scratch can involve some work. Depending on how much has already been done and how much of that you are allowed to reuse, the work could include generating digital certificates, copying those certificates to appropriate computers, creating keystores, and configuring servers to use those keystores. Additional details can be found in the WebSphere Application Server documentation under the topic “Creating a Secure Sockets Layer configuration” at http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tsec_sslconfiguration.html.
• Disable (or delete) insecure messaging transport chains.
• Remove default authorization policies.
• Secure the Distribution and Consistency Service (DCS).
• Secure each messaging engine on the messaging bus.
• Secure any data stores used by the members of the messaging bus.
• Create (or use an existing) authentication alias for transaction recovery. This step becomes unnecessary beginning with WebSphere Application Server version 7.
When securing a messaging bus, the word “security” really means two categories of things:
• Restricting access to the messaging bus. This is often called bus security.
• Encrypting the communications involving the various components. This is often called transport security.
Enabling Bus Security
Messaging bus security is enabled by default. However, if you ever disable administrative security, you will also be disabling messaging bus security. Also if you have not yet enabled administrative security, enabling messaging bus security will have no effect. WebSphere Application Server versions 6.1 and later enable administrative security by default. Earlier versions disable it by default. Before version 6.1, administrative security was called global security.
There are five security roles that apply to messaging buses:
• Connector—This role allows you to connect to the bus.
• Browser—This role type applies to alias, port, and queue destinations.
• Receiver—This role type applies to alias, port, queue, and topic space destinations.
• Sender—This role applies to alias, foreignDestination, port, queue, and topicSpace destinations.
• Creator—This role applies to temporary destinations only.
Two special groups apply to messaging buses as well:
• AllAuthenticated—Any entity that successfully logs in belongs to this group.
• Everyone—As the name implies, all entities, whether authenticated or not, belong to this group. Giving this group access to any resource is the same as turning security off for that resource.
If you ignore the two special groups, in order to do anything useful, an application must belong to a group that has the following roles to use the following types of messaging bus components:
• Queue, port, or Web service requires sender, receiver, browser, creator roles.
• Alias requires sender, receiver, browser roles.
• Topic Space requires sender, receiver roles.
• Foreign Destinations require sender role.
By default, messaging engines communicate over the InboundBasicMessaging transport chain. Change this by specifying a secure transport chain28 as your inter-engine transport chain. In addition, you have to specify a secure transport chain for your Distribution and Consistency Services communications. By default, Distribution and Consistency Services use the DCS transport chain.
28 Setting up SSL from scratch can involve some work. Depending on how much has already been done and how much of that you are allowed to reuse, the work could include generating digital certificates, copying those certificates to appropriate computers, creating keystores, and configuring servers to use those keystores. Additional details can be found in the WebSphere Application Server documentation under the topic “Creating a Secure Sockets Layer configuration” at http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tsec_sslconfiguration.html.
There is an InboundSecureMessaging transport chain that you can use to secure communications between messaging engines and a DCS-Secure transport chain that you can use to secure Distribution and Consistency Services communications.
You should specify user groups with appropriate role permissions as authorized users of your messaging bus. While there is no mutual authentication, the receiving messaging engine authenticates incoming messages against the user registry. It checks to see that the user name specified on the incoming message matches a user name it is authorized to serve. You should not use default authorization policies in a secure environment.
Example: Enabling Bus Access Security
In the following code, you’re creating a secure messaging bus. Notice that this code depends on variables defined in Listing 14.1. A number of the settings you need in order to secure a messaging bus are, in fact, the default settings. In those cases, you do nothing to change those defaults. If, by chance, your system has different values for these attributes, you will have to write some code to change those values. If you do have to write code to change the values of attributes of the messaging bus or any of its component parts, it is extremely important to make those changes using the AdminTask.modifySIB* methods documented in the “Modifying a Bus and Bus Components” section of this chapter. Under no circumstances should you ever use AdminConfig to modify an attribute of any messaging bus component. Some of those attributes have values that are dynamically generated. The appropriate AdminTask methods respect those dynamically generated values. AdminConfig does not.
When you execute the following lines of script on your system, it should tell you that bus security is enabled.29 If not, you must set the secure attribute of your SIBus to true.
29 See AdminTask.showSIBus() in the reference section of this chapter.
print AdminTask.showSIBus('[-bus ' + nameOfBus + ' ]')
After you execute this line, look for secure=. Right after that, you should see true. Then look for permittedChains=. Right after that, you should see SSL_ENABLED. If not, you have to modify some attributes of the messaging bus.30
30 See AdminTask.modifySIBus() in the reference section of this chapter.
Any time you enable or disable bus security, be careful to modify the busSecurity argument rather than the secure argument. The names are very similar. To make matters even more confusing, the attribute name that is displayed is secure. Nevertheless, the secure argument is deprecated.
For security reasons, it is very important to remove the default authorizations for the messaging bus. You do not want to provide any known vectors of attack to an intruder.
print AdminTask.removeDefaultRoles( '[-bus ' + nameOfBus + ' ]' )
After you remove the default authorizations,31 you need to create authorized groups and/or users for your installation,32 as shown in Listing 14.3.
31 See AdminTask.removeDefaultRoles() in the reference section of this chapter.
32 See the AdminTask.addGroupTo*Role() and AdminTask.addUserTo*Role() sections of the reference portion of this chapter.
Listing 14.3 Creating New Authorized Users for Secure Messaging Bus
The code in Listing 14.3 assumes that there is a user in your user registry with a user ID and a password that matches information supplied when you created the JAASAuthData. If this is not true, you will not get any errors when you run the code in Listing 14.3. Your JAASAuthData won’t get you access when you try to use it. It will fail authentication by your user registry.33 The code in Listing 14.4 sets the correct permissions for your new user. Be aware that you can set permissions for a group instead of a user. There is a parallel series of AdminTask methods, each of which perform the same functions on a group instead of a user. You have to add a user or group to the bus connector role to allow that entity to connect to the bus at all. If you enable security for a bus and it stops working, this is something you should check. You should also check to make sure that your user is in your user registry.
33 See the WebSphere Application Server documentation for all the administrative steps to enable administrative security.
Listing 14.4 Setting Permissions for Users
Example: Enabling Transport Security
Secure chains should be enabled. Insecure transport chains must be disabled. It is not enough just to specify SSL_ENABLED chains. If lines 28 through 42 in Listing 14.5 show the wrong value, you will have to set the enabled attribute to the correct value for that chain.
Listing 14.5 Finding Secure and Insecure Transport Chains
There is nothing AdminTask specific in the code that inspects transport chains in Listing 14.5. The code just searches the entire configuration repository for every Chain34 that has a name that includes either the text SecureMessag, BasicMessag, DCS, or DCS-Secure. Any transport chain that was created by IBM to support a message bus will have the text Messag as part of its name. Because this code depends on undocumented naming conventions, you might want to print out a list of every Chain in your configuration and confirm the naming conventions that IBM used on your version of the product. Alternatively, you are free to create your own secure transport chains and use them for message bus communications.
34 Chain is a WebSphere Application Server data type. Its name is case-sensitive. Notice in the example code, we search for Chain, not TransportChain.
Message buses also communicate with Distribution and Consistency Services (DCS). This communication contains the location of messaging resources. By default, DCS requires a valid LTPA token from any entity that attempts communications with DCS, but the communications themselves are unencrypted. Thus, anybody with a network sniffer (and a lot of patience) could discover the location of all of your allegedly secure messaging resources. This would be an unacceptable security hole in many enterprises.
To close this hole, create another core group (which is described in Chapter 11, “The AdminTask Object—Server Management.”) Make any server or cluster member that will use your secure message bus a member of that core group. Specify the DCS-secure transport chain as the transport chain between that core group and DCS.
Finally, you have to provide the configuration ID of your JAAS authentication alias to two attributes of the ConnectionFactory—authDataAlias and xaRecoveryAuthAlias. This is done in the following sample code:
c = findIDbyName( 'ConnectionFactory', nameOfFactory )
AdminConfig.modify( c, [ [ 'authDataAlias', jaasID ],
[ 'xaRecoveryAuthAlias', jaasID ] ] )
Here are two separate authentications that happen on the messaging bus and its assorted components. When you send a message, you are really inserting a row into an imaginary database table. If you configure your messaging bus to use a real database,35 then sending a message might well require authentication by the database. Any real database used to support messaging is required to support transactions. When a transaction fails and it needs to be rolled back, there is a separate authentication required by the database. You are free to use the same credentials for both authentications. You just have to remember to configure for both authentications.
35 As opposed to an imaginary database like a filestore.
Reference Section
In this section, we provide detailed information about the AdminTask methods that configure messaging buses. Of the hundreds of methods in this category, detailed information is provided about the methods you will likely use most often. The methods are divided into categories. Within those categories, we present the methods in the order in which you might have to use them. We drew on numerous sources for the information we present in this section, as well as the most recent version of the help that IBM provides within the AdminTask scripting object itself. We added details from several sources within the WebSphere Application Server documentation and that folks from the IBM support staff were kind enough to provide. We also supplemented this with things we learned from our own experience.
Finally, the arguments to each method are divided into groups. The first group is made up of the required arguments. The second group are arguments that are not required but that you are very likely to have to use. The third group is comprised of arguments that are optional and are seldom used. The fourth group are arguments that you will have to supply if you are configuring a secure environment.
The general pattern for calling AdminTask methods is:
There might or might not be a target. If there is one, it might be a configuration ID, or it might be a name. Targets are usually containment parents of whatever the method touches. There might or might not be arguments. Arguments are almost always name/value pairs. And there might or might not be steps—and there might be more than one step. Think of steps as arguments that take either a list of name/value pairs as their value or no argument at all. Bundle all the arguments and all the steps into one big list and pass it to the method.
Creating Message Buses
createSIBus
This method creates a messaging bus.
Required argument:
• bus—Every bus has to have a name. This is where you specify the name of the bus you are about to create.
Optional arguments you might need if you want to secure the bus:
• busSecurity—The default value true enables messaging bus security. Change this to false to disable bus security. This argument has no effect unless you have already enabled administrative security.
• InterEngineAuthAlias—For authenticating communications between messaging engines (used by complex topologies).
• mediationsAuthAlias—For authenticating a message to a mediation layer. Only needed if you are doing mediations within your SIBus and then only in secure environments.
Optional arguments that you are likely to use:
• description—Any text you might want to add to describe this part of your bus topology.
• discardOnDelete—The default value is false. This argument decides whether messages should be deleted from the database that supports a queue if and when a queue gets deleted.
• HighMessageThreshold—The default is 50,000.
Optional arguments that you are less likely to use:
• configurationReloadEnabled—The default is true. Set this to false if you do not want to allow bus configuration information to be dynamically reloaded.
• ScriptCompatibility—Default of 6.1 works unless you have version 6 (or earlier) servers as bus members. In that case, set this value to 6.
• secure—You are not likely to use this argument because it has been deprecated. Use busSecurity instead.
addSIBusMember
This method configures the plumbing that a server uses to become a member of a bus.
Required argument:
• bus—The name of the bus that this server or cluster will join.
Although the following arguments are not marked “mandatory,” you are required to use some of them. You have to specify either the server or cluster or WebSphere MQ server that will receive the extra plumbing that will make it a member of a messaging bus. If you want to add an individual server to a messaging bus, you must specify the server name and the node name of that server. If you want to add an entire cluster to the messaging bus, you must specify the name of the cluster, and you cannot specify a node name or a server name. If you want a WMQ server to host this destination, supply a WebSphere MQ server name. Omit node, server, and cluster arguments.
• node—The name of the node that contains the server you want to add to the messaging bus.
• server—The name of the server you want to add to the messaging bus.
• cluster—The name of the cluster that you want to add to the messaging bus.
• wmqServer—The name of a WebSphere MQ server that you want to add to the messaging bus
• port—Required if you are adding a WebSphere MQ server to the messaging bus
• channel—Required if you are adding a WebSphere MQ server to the messaging bus
• securityAuthAlias—Required if you are adding a WebSphere MQ server to the messaging bus
Frequently used optional arguments:
• fileStore—Store messages in the file system instead of in the file system. Do not use this argument and the dataStore argument.
• dataStore—Store messages in a database instead of in a database. Do not use this argument and the dataStore argument.
• trustUserIds—You might choose to use this argument if you are making a WMQ server a bus member.
• transportChain—You might choose to override the default transport chain that communicates with an WMQ server.
Occasionally used optional arguments:
• logSize—The size, in megabytes, of the log file.
• logDirectory—The name of the log files directory.
• minPermanentStoreSize—The minimum size, in megabytes, of the permanent store file.
• maxPermanentStoreSize—The maximum size, in megabytes, of the permanent store file.
• unlimitedPermanentStoreSize—true if the permanent file store size has no limit; false otherwise.
• permanentStoreDirectory—The name of the store files directory for permanent data.
• minTemporaryStoreSize—The minimum size, in megabytes, of the temporary store file.
• maxTemporaryStoreSize—The maximum size, in megabytes, of the temporary store file.
• unlimitedTemporaryStoreSize—true if the temporary file store size has no limit; false otherwise.
• temporaryStoreDirectory—The name of the store files directory for temporary data.
• schemaName—The name of the database schema used to contain the tables for the data store. This only matters if you are creating data tables, and then it only matters if you have some special schema that you want to substitute for the standard schema that IBM uses.
• createDefaultDatasource—When adding a server to a bus, set this to true if a default datasource is required. When adding a cluster to a bus, this parameter must not be supplied.
• datasourceJndiName—The JNDI name of the datasource to be referenced from the datastore created when the member is added to the bus. You will only need to supply this value if you are using an external database.
• authAlias—The name of the authentication alias used to authenticate the messaging engine to the data source. You will only need to supply this value if you are using an external database.
createSIBDestination
This method creates either a queue or a topic or a link on an existing bus member to some other bus.
Required arguments:
• bus—The name of the bus that this destination will serve.
• name—Destination name.
• type—Destination type must be one of the following (Alias|Foreign|Port|Queue|TopicSpace|WebService).
Although the following arguments are not marked “mandatory,” you are required to use some of them. You have to specify either the server or the cluster or WebSphere MQ server that will host this destination. If the destination is really a link to some other bus, there are several additional arguments you must supply. If you want to an individual server to host this destination, you must specify the server name and the node name of that server. If you want an entire cluster to host this destination, you must specify the name of the cluster and you may not specify a node name or a server name. If you want to add a WMQ server as a bus member, supply a WebSphere MQ server name, a WMQ queue name, and whether or not to use RFH2. Omit node, server, and cluster arguments. If this destination will be an alias for another SIBus, then aliasBus, targetBus, and targetName must also be supplied. If this destination will be a link to a foreign bus (such as MQ Series), then foreignBus must also be supplied.
• node—To assign the destination to a server, supply node name and server name but not cluster name or WebSphere MQ server name.
• server—To assign the destination to a server, supply node name and server name but not cluster name or WebSphere MQ server name.
• wmqServer—To assign the destination to a WebSphere MQ server, supply a WebSphere MQ server name but not node, server name, or cluster name.
• wmqQueueName—The name of the WebSphere MQ queue for messages. This must be specified with the WebSphere MQ server name but not node, server name, or cluster name.
• useRFH2—Determines if messages sent to the WebSphere MQ destination have an RFH2 header or not. This must be specified with the WebSphere MQ server name but not node, server name, or cluster name.
Frequently used optional arguments:
• description—Any text you want to add to document your topology decision. This description will show up in the Admin Console.
• defaultPriority—The default priority for message flows through this destination, in the range 0 (lowest) through 9 (highest). This default priority is used for messages that do not contain a priority value.
• maxReliability—The maximum reliability quality of service that is accepted for values specified by producers.
• maxFailedDeliveries—The maximum number of times that service tries to deliver a message to the destination before forwarding it to the exception destination.
• persistentReliability—The quality of service used for inbound messages that WebSphere MQ regards as being persistent. Allowable values are (BEST_EFFORT_NONPERSISTENT | EXPRESS_NONPERSISTENT | RELIABLE_NONPERSISTENT | RELIABLE_PERSISTENT | ASSURED_PERSISTENT).
• overrideOfQOSByProducerAllowed—Controls the quality of service for message flows between producers and the destination. Select this option to use the quality of service specified by producers instead of the quality defined for the destination.
Occasionally used optional arguments:
• exceptionDestination—The name of another destination to which the system sends a message that cannot be delivered to this destination within the specified maximum number of failed deliveries. By default, messages that cannot be delivered go to the system exception destination.
• delegateAuthorizationCheckToTarget—Indicates whether the authorization check should be delegated to the alias or target destination.
• replyDestination—The name of the destination for reply messages.
• replyDestinationBus—The name of the bus on which the reply destination is configured.
• maintainStrictMessageOrder—Select this option (setting it to true) to enforce message order for this destination.
• receiveExclusive—Select this option (setting it to true) to allow only one consumer to attach to a destination.
• receiveAllowed—Clear this option (setting it to false) to prevent consumers from being able to receive messages from this destination.
• sendAllowed—Clear this option (setting it to false) to stop producers from being able to send messages to this destination.
• defaultForwardRoutingPath—You normally don’t have to set this unless you have a complex bus topology. If you do have to perform this step, these are the arguments you will have to supply. These arguments are passed as a collection.
• Destination—Destination name. This argument is mandatory.
• bus—Bus name.
createSIBEngine
This method creates a messaging engine for the specified bus member. Normally, you do not need to call this method because a messaging engine gets created when you add a member to a bus.
Required argument:
• bus—The name of the bus to which the bus member belongs.
Although the following arguments are not marked “mandatory,” you are required to use some of them. You must use at least one, and possibly two, of the next three arguments in order to properly identify the bus member that will contain this SIBEngine:
• node—To create a messaging engine on a server, supply node and server name but not cluster name.
• server—To create a messaging engine on a server, supply node and server name but not cluster name.
• cluster—To create a messaging engine on a cluster, supply cluster name but not node and server name.
Frequently used optional arguments:
• description—Use this text to describe the messaging engine.
• fileStore—Indicates that a file store is to be created. No value is needed.
• dataStore—Indicates that a data store is to be created. No value is needed.
Argument that affects bus security:
• authAlias—The name of the authentication alias used to authenticate the messaging engine to the database.
Occasionally used optional arguments:
• initialState—Whether the messaging engine is started or stopped when the associated application server is first started. Until started, the messaging engine is unavailable (Stopped | Started).
• highMessageThreshold—The maximum total number of messages that the messaging engine can place on its message points.
• logSize—The size, in megabytes, of the log file.
• minPermanentStoreSize—The minimum size in megabytes of the permanent store file.
• maxPermanentStoreSize—The maximum size, in megabytes, of the permanent store file.
• unlimitedPermanentStoreSize—true if the permanent file store size has no limit; false otherwise.
• permanentStoreDirectory—The name of the permanent store files directory.
• temporaryStoreDirectory—The name of the temporary store files directory.
• unlimitedTemporaryStoreSize—true if the temporary file store size has no limit; false otherwise.
• minTemporaryStoreSize—The minimum size in megabytes of the temporary store file.
• maxTemporaryStoreSize—The maximum size, in megabytes, of the temporary store file.
• logDirectory—The name of the log files directory.
• schemaName—The name of the database schema used to contain the tables for the data store.
• createTables—Select this option if the messaging engine creates the database tables for the data store. Otherwise, the database administrator must create the database tables.
• createDefaultDatasource—When adding a server to a bus, set this to true if a default data source is required. When adding a cluster to a bus, this parameter must not be supplied.
• datasourceJndiName—The JNDI name of the data source to be referenced from the datastore created when the member is added to the bus.
createSIBJMSConnectionFactory
This method creates an SIB JMS connection factory at the scope identified by the target object. Applications need this factory to obtain an SIBJMSQueue object or an SIBJMSTopic object.
Target (mandatory):
The management scope at which this factory is visible. This scope must be a configuration ID.
Required arguments:
• busName—The bus name.
• name—The name of the SIB JMS connection factory.
• jndiName—The JNDI name of the SIB JMS connection factory.
Optional arguments you might need if you want to secure the bus:
• xaRecoveryAuthAlias—The authentication alias used during XA recovery processing.
• userName—The user name that is used to create connections from the connection factory.
• password—The password that is used to create connections from the connection factory.
• targetTransportChain—The name of the protocol that should be used to connect to a remote messaging engine.
Frequently used optional arguments:
• description—Any text you might use to describe the connection factory. This description will show up in the Admin Console.
• category—Arbitrary text you might choose to use to classify or group the connection factory.
• persistentMapping—When a message specifies persistent mapping, what should our bus do? Must be one of (BestEffortNonPersistent | ExpressNonPersistent | ReliableNonPersistent | ReliablePersistent | AssuredPersistent | AsSIBDestination | None). Note that this value can overrule the value specified in the message and, in fact, make the message non-persistent.
• target—The name of a target that resolves to a group of messaging engines.
• targetType—Specifies the type of the name in the target parameter. Legal values are (BusMember | Custom | ME).
• targetSignificance—This property specifies the significance of the target group.
Occasionally used optional arguments:
• manageCachedHandles—Whether cached handles (handles held in instance variables in a bean) should be tracked by the container.
• logMissingTransactionContext—Whether or not the container logs that there is a missing transaction context when a connection is obtained.
• connectionProximity—The proximity of acceptable messaging engines. Legal values are (Bus | Host | Cluster | Server). The default value is Bus.
• tempQueueNamePrefix—Temporary queue name prefix.
• tempTopicNamePrefix—Temporary topic name prefix.
• shareDataSourceWithCMP—Used to control how data sources are shared.
• shareDurableSubscriptions—Used to control how durable subscriptions are shared. Legal values are (InCluster | AlwaysShared | NeverShared).
createSIBJMSQueue
This method creates the JMS wrapper object that applications use in order to interact with a queue on the bus.
Target (mandatory):
The management scope at which this queue is visible. This value must be a configuration ID.
Required arguments:
• busName—The bus name.
• name—The name of the SIB JMS queue.
• jndiName—The JNDI name of the SIB JMS queue.
• queueName—The name of the underlying SIB queue to which the queue points.
Frequently used optional arguments:
• description—Any text that describes this queue for the purpose of documenting this part of your topology. This description will show up in the Admin Console.
• priority—The priority for messages. Whole number in the range 0 to 9.
• deliveryMode—The delivery mode for messages. Legal values are (Application | NonPersistent | Persistent).
Occasionally used optional argument:
• timeToLive—The time in milliseconds to be used for message expiration.
createSIBJMSTopic
This method creates the JMS wrapper object that applications use in order to interact with a topic on the bus.
Target (mandatory):
The management scope at which this topic is visible. This scope must be a configuration ID.
Required arguments:
• busName—The bus name.
• name—The name of the SIB JMS topic.
• jndiName—The JNDI name of the SIB JMS topic.
Frequently used optional arguments:
• topicSpace—The name of the underlying SIB topic space to which the topic points.
• topicName—The topic to be used inside the topic space (for example, books/scripting/WebSphere).
• description—Any text that describes this topic for the purpose of documenting this part of your topology. This description will show up in the Admin Console.
• priority—The priority for messages. Whole number in the range 0 to 9.
• deliveryMode—The delivery mode for messages. Legal values are (Application | NonPersistent | Persistent).
Occasionally used optional argument:
• timeToLive—The time in milliseconds to be used for message expiration.
createSIBJMSActivationSpec
This method creates the plumbing that activates a Message Driven Bean when an appropriate message arrives.
Target (mandatory):
Scope of the SIB JMS resource adapter to which the activation specification will be added. This scope must be a configuration ID.
• name—Any arbitrary name you would like to call this activation specification.
• jndiName—JNDI name of the activation specification.
• destinationJndiName—JNDI name of an SIBDestination.
Optional arguments you might need if you want to secure the bus:
• authenticationAlias—Security credentials. The configuration ID of a JAASAuthData object.
• userName—User name.
• password—Password.
• targetTransportChain—The name of the protocol that should be used to connect to a remote messaging engine.
Frequently used optional arguments:
• busName—Name of the bus to connect to.
• subscriptionDurability—Whether a JMS topic subscription is durable or nondurable.
• subscriptionName—The subscription name needed for durable topic subscriptions.
• clientId—Client identifier. Required for durable topic subscriptions.
• durableSubscriptionHome—Name of the durable subscription home. This identifies the messaging engine where all durable subscriptions accessed through this activation specification are managed.
• shareDurableSubscriptions—Used to control how durable subscriptions are shared.
• shareDataSourceWithCMP—Used to control how data sources are shared.
Occasionally used optional arguments:
• acknowledgeMode—How the session acknowledges any messages it receives.
• maxBatchSize—The maximum number of messages received from the messaging engine in a single batch.
• maxConcurrency—The maximum number of endpoints to which messages are delivered concurrently.
• target—The SIB JMS activation specification new target value.
• targetType—The SIB JMS activation specification new target type value. Legal values are (BusMember | Custom | ME).
• targetSignificance—This property specifies the significance of the target group.
Deleting a Bus and Bus Components
Keep in mind that deleting a bus itself will not delete the JMS components associated with that bus. You must delete each of these separately. Deleting a messaging bus requires you to delete the bus itself, the related JMS artifacts, and possibly some JAASAuthData artifacts. The two groups of AdminTask methods that you will need any time one of your scripts deletes a messaging buses and their component parts are as follows:
SIBAdminCommands
SIBJMSAdminCommands
Of the 70+ methods36 in these two groups, the methods you are most likely to need are the following when you delete a bus or any of its components.
36 The exact number will depend on your version of WebSphere Application Server and whether you have licensed any of the more advanced product offerings.
deleteSIBJMSActivationSpec
This method deletes an SIBJMSActivationSpec.
Target (mandatory):
The configuration ID of theactivation spec to be deleted.
deleteSIBJMSQueue
This method deletes an SIBJMSQueue.
Target (mandatory):
The configuration ID of the JMS queue to be deleted.
deleteSIBJMSTopic
This method deletes an SIBJMSTopic.
Target (mandatory):
The configuration ID of the topic to be deleted.
deleteSIBJMSConnectionFactory
This method deletes an SIBJMSConnectionFactory.
Target (mandatory):
The configuration ID of the connector factory to be deleted.
deleteSIBus
This method both the bus and all of the SIB components that make up the bus. Thus, bus members, messaging engines, aliases, and foreign buses get deleted. This command also deletes the new artifacts that are created when queues are assigned or mediated to a WebSphere MQ server bus member, including the WebSphere MQ server bus members. However, none of the JMS plumbing that sits on top of the bus gets deleted. Each of the JMS components must be deleted separately. You must also separately delete queue managers that are associated with the bus using WebSphere MQ server definitions (if applicable), messages residing on WebSphere MQ queue managers (if applicable), or WebSphere MQ queues (if applicable).
• bus—The name, not the configuration ID, of the bus you wish to delete. Deleting any SIB component requires a name rather than a configuration ID.
removeSIBusMember
Remove the configuration for the plumbing that makes a server a member of a messaging bus. Use this method only if you are trying to remove one bus member. If you want to delete an entire bus, it is not necessary to call this method. AdminTask.deleteSIBus() will delete all bus members.
Required argument:
• name—The name, not the configuration ID, of the bus this member belongs to.
Frequently used optional arguments:
(You must supply at least one and possibly two of the following optional arguments.)
• node—If the bus member is an individual application server, supply the name of the node and the name of the server. Do not supply any of the other optional arguments.
• server—If the bus member is an individual application server, supply the name of the node and the name of the server. Do not supply any of the other optional arguments.
• cluster—If the bus member is a cluster, supply cluster name. Do not supply any of the other optional arguments.
• wmqServer—If the bus member is a WebSphere MQ server bus member, supply the name of the WebSphere MQ server. Do not supply any of the other optional arguments.
deleteSIBDestination
Deletes a bus destination. Use this method only if you are trying to remove one bus destination. If you want to delete an entire bus, it is not necessary to call this method. AdminTask.deleteSIBus()37 deletes all bus destinations.
37 See AdminTask.deleteSIBus() in this reference for details.
Required arguments:
• bus—The name of the bus.
• name—The name of the destination.
Frequently used optional arguments:
(You only need these arguments if the destination you are deleting is a foreign destination or an alias destination.)
• aliasBus—If the destination to be deleted is an alias destination, then the aliasBus parameter must be supplied if the alias bus for the destination is not the local bus.
• foreignBus—If the destination to be deleted is a foreign destination, then name of the foreign bus must be supplied.
Modifying a Bus and Bus Components
Again, the methods in this section come from two AdminTask groups:
SIBAdminCommands
SIBJMSAdminCommands
modifySIBus
This method modifies one or more items that are part of the configuration for a bus.
Required argument:
• bus—The name of the bus that will be modified.
Optional arguments that affect security:
• interEngineAuthAlias—Name of the authentication alias used to authorize communication between messaging engines on the bus.
• mediationsAuthAlias—Name of the authentication alias used to authorize mediations to access the bus.
• busSecurity—Enables or disables bus security. This argument has no effect unless you have already enabled administrative security.
• permittedChains—The permitted transport chains value can be set to one of the following: (ALL | SSL ENABLED | LISTED).
Frequently used optional arguments:
• highMessageThreshold—The maximum number of messages that any queue on the bus can hold.
• description—Use this field to describe the role this bus plays in your topology.
Occasionally used optional arguments:
• protocol—The protocol used to send and receive messages between messaging engines and between API clients and messaging engines.
• discardOnDelete—Indicate whether or not any messages left in a queue’s data store should be discarded when the queue is deleted.
• configurationReloadEnabled—Indicate whether configuration files should be dynamically reloaded for this bus.
• secure—You are not likely to use this argument because it has been deprecated. Use busSecurity instead.
modifySIBEngine
This method modifies an SIBEngine. Notice that this method cannot change the decision to use a filestore versus a database. That decision is made when the messaging engine is created.38
38 See AdminTask.createSIBEngine() in this reference for details.
Required argument:
• bus—The name of the bus that will be modified.
Although the following arguments are not marked “mandatory,” you are required to use some of them depending on whether you are modifying the SIBEngine of a bus member that is a server, a cluster, or a WebSphere MQ server. If the SIBEngine belongs to a server and that server’s name is not unique within the cell, then you must specify the node name as well. Remember, all of the following are names, not configuration IDs:
• node—To specify a server bus member, supply node and server name but not cluster name or WebSphere MQ server name.
• server—To specify a server bus member, supply node and server name but not cluster name or WebSphere MQ server name.
• cluster—To specify a cluster bus member, supply cluster name but not node name, server name, or WebSphere MQ server name.
• wmqServer—To specify an WebSphere MQ server bus member, supply WebSphere MQ server name but not node name, server name, or cluster name.
Frequently used optional arguments:
• initialState—Whether the messaging engine is started or stopped when the associated application server is first started. Until started, the messaging engine is unavailable (Stopped | Started).
• highMessageThreshold—The maximum total number of messages that the messaging engine can place on its message points.
• defaultBlockedRetryTimeout—The default blocked retry interval for destinations owned by this messaging engine.
modifySIBDestination
This method modifies either a queue or a topic or a link to some existing bus member or a link to some other bus. Notice that these arguments all modify transport aspects of the bus destination.
Required arguments:
• bus—The name, not the configuration ID, of the bus that this destination belongs to.
• name—The name, not the configuration ID, of the destination that is being modified.
Frequently used optional arguments:
• description—A description of the role this destination plays in your topology.
• defaultPriority—The default priority for message flows through this destination, in the range 0 (lowest) through 9 (highest). This default priority is used for messages that do not contain a priority value.
• maxReliability—The maximum reliability quality of service that is accepted for values specified by producers.
• overrideOfQOSByProducerAllowed—Controls the quality of service for message flows between producers and the destination. Select this option to use the quality of service specified by producers instead of the quality defined for the destination.
• maxFailedDeliveries—The maximum number of times that service tries to deliver a message to the destination before forwarding it to the exception destination.
• exceptionDestination—The name of another destination to which the system sends a message that cannot be delivered to this destination within the specified maximum number of failed deliveries.
Arguments that affect bus security:
• delegateAuthorizationCheckToTarget—Indicates whether the authorization check should be delegated to the alias or target destination.
• topicAccessCheckRequired—Topic access check required.
Occasionally used optional arguments:
• sendAllowed—Clear this option (by setting it to false) to stop producers from being able to send messages to this destination.
• receiveAllowed—Clear this option (by setting it to false) to prevent consumers from being able to receive messages from this destination.
• receiveExclusive—Select this option (by setting it to true) to allow only one consumer to attach to a destination.
• maintainStrictMessageOrder—Select this option (by setting it to true) to enforce message order for this destination.
• replyDestination—The name of the destination for reply messages.
• replyDestinationBus—The name of the bus on which the reply destination is configured.
Steps:
• queuePoints—This step specifies a list of the queue points that will be used by users of the alias destination. The arguments for this step are passed as a collection.
Required arguments:
• identifier—The queue point identifier.
• mediationPoints—This step specifies a list of the mediation points that will be used by users of the alias destination. The arguments for this step are passed as a collection.
Required arguments:
• identifier—The identifier for the mediation point to be used. There will be one of these for each mediation point in the list.
• defaultForwardRoutingPath—This step specifies a default forward routing path. The arguments that follow form a collection. The arguments for this step are passed as a collection.
• destination—The name, not the configuration ID, of the destination where messages get forwarded.
Optional argument:
• bus—The name, not the configuration ID, of the bus where messages get forwarded.
modifySIBJMSQueue
Modify the attributes of the supplied SIB JMS queue using the supplied attribute values. Notice that the arguments to this method pretty much focus on modifying the mapping from the JMS queue facade39—an SIBJMSQueue—to the underlying SIB queue, an SIBQueue. Contrast this method with AdminTask.modifySIBDestination().
39 A discussion of the Java Message Service is beyond the scope of this book. For a good introduction, consider Chapter 33 of http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.
Target (mandatory):
The configuration ID, not the name, of the SIB JMS queue to be modified.
Frequently used optional arguments:
• busName—The name of the bus on which the queue resides.
• name—If you are changing the name of the queue, this is the SIB JMS queue’s new name.
• jndiName—If you are changing the JNDI name for the queue, this is the SIB JMS queue’s new JNDI name.
• description—If you are changing the description of the queue, this is some text to explain the purpose of this item in your topology.
• queueName—If you are changing the mapping from the JMS queue to the underlying SIB queue, this is the name of the underlying SIB queue to which the queue will point.
• deliveryMode—The new delivery mode for messages. Legal values are (Application | NonPersistent | Persistent).
• timeToLive—The new time in milliseconds to be used for message expiration.
• priority—The new priority for messages. Whole number in the range 0 to 9.
• scopeToLocalQP—Indicates if the underlying SIB queue destination should be scoped to a local queue point when addressed using this JMS queue.
• producerBind—Indicates how JMS producers should bind to queue points of the clustered queue. true indicates that a queue point should be chosen when the session is opened and should never change; false indicates that a queue point should be chosen every time a message is sent.
• producerPreferLocal—Indicates whether queue points local to the producer should be used.
• gatherMessages—Indicates whether JMS consumers and browsers should be given messages from any queue points, rather than the single queue point that they are attached to.
modifySIBJMSTopic
Modify the attributes of the supplied SIB JMS topic using the supplied attribute values. Notice that this method focuses on modifying both the mapping from the JMS topic facade40 to some underlying SIB topic, and the structure of a topic space and the topics that are part of that topic space. Contrast this method with AdminTask.modifySIBDestination(). The JMS topic façade is an SIBJMSTopic. The underlying SIB topic is part of a SIBTopicSpace.
40 A discussion of the Java Message Service is beyond the scope of this book. For a good introduction, consider Chapter 33 of http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.
Target (mandatory):
The configuration ID, not the name, of the SIB JMS topic space or topic to be modified.
Frequently used optional arguments:
• busName—The name of the bus on which the topic resides.
• name—If you are changing the name of the topic, this is the SIB JMS topic’s new name.
• jndiName—If you are changing the JNDI name for the topic, this is the SIB JMS topic’s new JNDI name.
• description—If you are changing the description of the topic, this is some text to explain the purpose of this item in your topology.
• topicSpace—If you are changing the hierarchy of topics in an SIB topic space or if you are changing the mapping of a JMS topic to an SIB topic, this is the name of the underlying SIB topic space.
• topicName—If you are changing the hierarchy of topics in an SIB topic space or if you are changing the mapping of a JMS topic to an SIB topic, this is the SIB topic to be used inside the SIB topic space (for example, stock/IBM or stock/IBM/common or stock/IBM/preferred). In this example, stock would be the topic space. Everything below that topic space is a hierarchical list of topics.
• deliveryMode—The new delivery mode for messages. Legal values are (Application | NonPersistent | Persistent).
• timeToLive—The new time in milliseconds to be used for message expiration.
• priority—The new priority for messages. Whole number in the range 0 to 9.
Displaying Buses and Bus Components
There are two groups of methods—one that starts with list and one that starts with show. The methods that start with list just displays a list of names or configuration IDs of items in a cell. The methods that start with show provides more detailed information about one named item. The methods in this section come from two AdminTask groups:
SIBAdminCommands
SIBJMSAdminCommands
listSIBuses
This method lists the configuration ID of every bus in a cell. It requires no arguments. If you ever have to write code to change the values of attributes of the messaging bus or any of its component parts, it is extremely important to make those changes using the AdminTask.modifySIB* methods we document in the “Modifying a Bus and Bus Components” section of this chapter. Even though this method returns configuration IDs, under no circumstances should you ever use AdminConfig to modify an attribute of any messaging bus component. Some of those attributes have values that are dynamically generated. The appropriate AdminTask methods respect those values. AdminConfig does not. Extract the name attribute from the configuration ID and use the AdminTask methods.
showSIBus
This method displays some of the attributes of one particular bus.
Required argument:
• bus—The name, not the configuration ID, of the bus.
listSIBusMembers
This method lists the configuration ID of every member of a bus unless you limit the scope of this query. In spite of the fact that this method returns a configuration ID, IBM strongly discourages the use of AdminConfig methods on any part of a messaging bus configuration. You should use the various AdminTask methods to display or modify messaging bus components:
Required argument:
• bus—The name, not the configuration ID, of the bus.
showSIBusMember
This method displays selected information about a particular bus member.
Required argument:
• bus—The name, not the configuration ID, of the bus.
Frequently used optional arguments:
(These are not really optional arguments. You must use either one or two of them depending on whether you want an individual server or a cluster or an MQ server.)
• node—To specify a server bus member, supply node, and server name but not cluster name or WebSphere MQ server name
• server—To specify a server bus member, supply node, and server name but not cluster name or WebSphere MQ server name.
• cluster—To specify a cluster bus member and supply cluster name, but not node name, server name, or WebSphere MQ server name.
• wmqServer—To specify an WebSphere MQ server bus member and supply WebSphere MQ server name but not node name, server name, or cluster name.
listSIBEngines
This method lists the configuration IDs of all the messaging engines within the scope you specify. The argument(s) you must supply depend on the scope of your query. Acceptable scopes are either an entire bus, a server in a given node, or a cluster.
Frequently used optional arguments:
(These are not really optional arguments. You must use either one or two of them depending on whether you want an individual server or a cluster or an MQ server.)
• bus—The bus whose engines are to be listed. You do not have to supply a bus name unless you want to limit your query to engines that belong to one particular bus. Servers and clusters can host more than one message bus.
• node—To list messaging engines on a server, supply node and server name but not cluster name.
• server—To list messaging engines on a server, supply node and server name but not cluster name.
• cluster—To list messaging engines on a cluster, supply cluster name but not node and server name.
showSIBEngine
This method displays some attributes of one particular messaging engine. Unlike the listSIBEngines method shown earlier, you cannot request attributes from more than one messaging engine at a time. Thus, you must provide enough scoping information to narrow the search to one particular messaging engine.
Required argument:
• bus—The name, not the configuration ID, of the bus that contains the messaging engine you wish to query.
Frequently used optional arguments:
(Even though these are optional arguments, you must supply either one or two of them.)
• node—To show a messaging engine that belongs to a server, supply node, and server name but not cluster name.
• server—To show a messaging engine that belongs to a server, supply node, and server name but not cluster name.
• cluster—To show a messaging engine that belongs to a cluster and supply cluster name but not node and server name.
• engine—The name of the engine to show.
showSIBJMSConnectionFactory
Return a list containing the SIB JMS connection factory’s attribute names and values.
Target (mandatory):
The configuration ID of the SIB JMS connection factory whose attributes are required.
listSIBJMSQueues
List all SIB JMS queues at the specified scope.
Target (mandatory):
The configuration ID of the server (the scope) at which to find the SIB JMS queues to list.
showSIBJMSQueue
Return a list containing the SIB JMS queue’s attribute names and values.
Target (mandatory):
The configuration ID of the SIB JMS queue whose attributes are required.
listSIBJMSTopics
List all SIB JMS topics at the specified scope.
Target (mandatory):
The configuration ID of the server (the scope) at which to find the SIB JMS topics to list.
showSIBJMSTopic
Return a list containing the SIB JMS topic’s attribute names and values.
Target (mandatory):
The configuration ID of the SIB JMS topic whose attributes are required.
listSIBMediations
This method lists the configuration IDs of all the mediations of a given bus.
Required argument:
• bus—The name, not the configuration ID, of the bus that contains the messaging engine you wish to query.
showSIBMediation
This method displays some attributes of a given mediation of a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus that contains the messaging engine you wish to query.
• mediationName—The name, not the configuration ID, of the mediation.
Bus Security
The methods in this section come from the SIBAdminBusSecurityCommands group.
removeDefaultRoles
This method is pretty much the first step in securing a bus. As the name implies, it removes all default authorizations for a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus that contains the messaging engine you wish to query.
removeGroupFromAllRoles
This method does just what the name implies. It revokes all permissions for a given group on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group that will be denied all access to the bus.
removeUserFromAllRoles
This method does just what the name implies. It revokes all permissions for a given user on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user that will be denied all access to the bus.
addGroupToBusConnectorRole
This method gives a group permission to connect to a bus. Without this permission, no member of this group will be able to do anything on this bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group that will be allowed to connect to the bus.
addUserToBusConnectorRole
This method gives a user permission to connect to a bus. Without this permission, this user will not be able to do anything on this bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user that will be allowed to connect to the bus.
addGroupToDefaultRole
This method gives a group permission to act in some role on a given a bus. Typically, you will have to call this method several times to give a particular group enough permissions to be useful.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group that will be allowed to perform some role on the bus.
• role—The role name. Allowable values are (Sender | Receiver | Browser | Creator | IdentityAdopter).
addUserToDefaultRole
This method gives an individual user permission to act in some role on a given a bus. Typically, you will have to call this method several times to give a particular group enough permissions to be useful.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user that will be allowed to perform some role on the bus.
• role—The role name. Allowable values are (Sender | Receiver | Browser | Creator | IdentityAdopter).
addGroupToDestinationRole
This method grants a group access to a destination for the specified destination role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme. It will probably be necessary to call this method several times in order to grant a meaningful set of permissions.
• bus—The name, not the configuration ID, of the bus.
• destination—The name, not the configuration ID, of the destination.
• type—The destination type. Allowable values are (Queue | Port | Webservice | TopicSpace | ForeignDestination | Alias).
• group—The name of the group that will receive this access.
• role—The role name. Allowable values are for Queues/Ports/WebServices (Sender | Receiver | Browser | Creator | IdentityAdopter), for TopicSpaces (Sender | Receiver | IdentityAdopter), for Aliases (Sender | Receiver | Browser | IdentityAdopter), and for Foreign (Sender | IdentityAdopter).
Occasionally used optional argument:
• foreignBus—Foreign bus name. This is only necessary if you are granting permissions on the foreign bus itself.
addUserToDestinationRole
This method grants a user access to a destination for the specified destination role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme. It will probably be necessary to call this method several times in order to grant a meaningful set of permissions.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• destination—The name, not the configuration ID, of the destination.
• type—The destination type. Allowable values are (Queue | Port | Webservice | TopicSpace | ForeignDestination | Alias).
• user—The name of the user that will receive this access.
• role—The role name. Allowable values are for Queues/Ports/WebServices (Sender | Receiver | Browser | Creator | IdentityAdopter), for TopicSpaces (Sender | Receiver | IdentityAdopter), for Aliases (Sender | Receiver | Browser | IdentityAdopter), and for Foreign (Sender | IdentityAdopter).
Occasionally used optional argument:
• foreignBus—Foreign bus name. This is only necessary if you are granting permissions on the foreign bus itself.
addGroupToTopicRole
This method gives a group permission to access the topic for the specified role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme.
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group that will receive this access.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
• topic—The name of the topic.
• topicSpace—The name of the topic space that contains this topic.
addGroupToTopicSpaceRootRole
This method gives a group permission to access a given topic space root for the specified role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group that will receive this access.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
• topicSpace—The name of the topic space that contains this topic.
addUserToTopicRole
This method gives a user permission to access the topic for the specified role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user that will receive this access.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
• topic—The name of the topic.
• topicSpace—The name of the topic space that contains this topic.
addUserToTopicSpaceRootRole
This method gives a user permission to access a given topic space root for the specified role. This method is not necessary unless you are trying to implement some very fine-grained access control scheme.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user that will receive this access.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
• topicSpace—The name of the topic space that contains this topic.
listAllDestinationsWithRoles
This method lists all destinations that have roles defined for them on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• type—The destination type. Allowable values are (Queue | Port | Webservice | TopicSpace | ForeignDestination | Alias).
listAllForeignBusesWithRoles
This method lists all foreign buses that have roles defined for them on a given bus.
Required argument:
• bus—The name, not the configuration ID, of the bus.
listAllTopicsWithRoles
This method lists all topics within a given topic space that have roles defined on them for a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• topicSpace—The name of the topic space to search.
listAllRolesForGroup
This method lists all roles defined on a given group on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• group—The name of the group.
listAllRolesForUser
This method lists all roles defined on a given user on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• user—The name of the user.
listGroupsInBusConnectorRole
This method lists all groups that have permission to connect to this bus.
Required argument:
• bus—The name, not the configuration ID, of the bus.
listGroupsInDefaultRole
This lists all groups in a given role on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• role—The role name. Allowable values are (Sender | Receiver | Browser | Creator | IdentityAdopter).
listGroupsInDestinationRole
This method lists the groups in the specified role in the destination security space role for the given destination on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• destination—The name of the destination.
• type—The destination type. Allowable values are (Queue | Port | Webservice | TopicSpace | ForeignDestination | Alias)
• role—The role name. Allowable values are for Queues/Ports/WebServices (Sender | Receiver | Browser | Creator | IdentityAdopter), for TopicSpaces (Sender | Receiver | IdentityAdopter), for Aliases (Sender | Receiver | Browser | IdentityAdopter), and for Foreign (Sender | IdentityAdopter).
Occasionally used optional arguments:
• foreignBus—If you want to list groups that have privileges on the foreign bus that lives behind a given destination, name that bus.
listGroupsInTopicRole
This method lists the groups who have a given role in a given topic in a given topic space on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• topicSpace—The name of the topic space that contains the topic.
• topic—The name of the topic.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
listGroupsInTopicSpaceRootRole
This method lists the users who have a given role in a given topic space on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• topicSpace—The name of the topic space that contains the topic.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
listUsersInBusConnectorRole
This method lists all users that have permission to connect to this bus.
Required argument:
• bus—The name, not the configuration ID, of the bus.
listUsersInDefaultRole
This lists all users in a given role on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• role—The role name. Allowable values are (Sender | Receiver | Browser | Creator | IdentityAdopter).
listUsersInDestinationRole
This method lists the users in the specified role in the destination security space role for the given destination on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• destination—The name of the destination.
• type—The destination type. Allowable values are (Queue | Port | Webservice | TopicSpace | ForeignDestination | Alias).
• role—The role name. Allowable values are for Queues/Ports/WebServices (Sender | Receiver | Browser | Creator | IdentityAdopter), for TopicSpaces (Sender | Receiver | IdentityAdopter), for Aliases (Sender | Receiver | Browser | IdentityAdopter), and for Foreign (Sender | IdentityAdopter).
Occasionally used optional argument:
• foreignBus—If you want to list groups that have privileges on the foreign bus that lives behind a given destination, name that bus.
listUsersInTopicRole
This method lists the users who have a given role in a given topic in a given topic space on a given bus.
Required argument:
• bus—The name, not the configuration ID, of the bus.
• topicSpace—The name of the topic space that contains the topic.
• topic—The name of the topic.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
listGroupsInTopicSpaceRootRole
This method lists the users who have a given role in a given topic space on a given bus.
Required arguments:
• bus—The name, not the configuration ID, of the bus.
• topicSpace—The name of the topic space that contains the topic.
• role—The role name. Allowable values are (Sender | Receiver | IdentityAdopter).
Summary
Conceptually, messaging is simple. It is just an architecture for passing an arbitrary sized message from a sender (the producer) to a recipient (the consumer). There are many ways to customize41 that simple architecture. That means your configuration for messaging can be simple or complex according to the needs or your enterprise. We gave you some simple code that you can extend and enhance according to your needs, and we showed you how to secure a messaging bus. In the next chapter, we cover Web services.
41 For many useful details about both messaging architecture and configuration, see “WebSphere Application Server V7 Messaging Administration Guide,” SG247770.