Sun Java SystemTM Message Queue data is stored in different locations on different operating system platforms. The tables that follow show the location of various types of Message Queue data on the following platforms:
In the tables, instanceName denotes the name of the broker instance with which the data is associated.
Table A–1 shows the location of Message Queue data on the Solaris operating system. If you are using Message Queue on Solaris with the standalone version of Sun Java System Application Server, the directory structure is like that described under Windows .
Table A–1 Message Queue Data Locations on Solaris Platform
Table A–2 shows the location of Message Queue data on the Linux operating system.
Table A–2 Message Queue Data Locations on Linux Platform
Table A–3 shows the location of Message Queue data on the Windows operating system. The table also applies to the Solaris platform when Message Queue is bundled with the standalone version of Sun Java System Application Server. That version of Application Server is bundled with neither Solaris nor Sun Java Enterprise System. Use the path names in Table A–3, but change the direction of the slash characters from the Windows backslash (\) to the Solaris forward slash (/). See Directory Variable Conventions for definitions of the IMQ_HOME and IMQ_VARHOME directory variables.
Table A–3 Message Queue Data Locations on Windows Platform
Sun Java SystemTM Message Queue uses many interfaces that can help administrators automate tasks. This appendix classifies the interfaces according to their stability. The more stable an interface is, the less likely it is to change in subsequent versions of the product.
Any interface that is not listed in this appendix is private and not for customer use.
Appendix B, Stability of Message QueueTM Interfaces describes the stability classification scheme.
Table B–1 Interface Stability Classification Scheme
Classification |
Description |
---|---|
Private |
Not for direct use by customers. May change or be removed in any release. |
Evolving |
For use by customers. Subject to incompatible change at a major (e.g. 3.0, 4.0) or minor (e.g. 3.1, 3.2) release. The changes will be made carefully and slowly. Reasonable efforts will be made to ensure that all changes are compatible but that is not guaranteed. |
Stable |
For use by customers. Subject to incompatible change at a major (for example, 3.0 or 4.0) release only. |
Standard |
For use by customers. These interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare. |
Unstable |
For use by customers. Subject to incompatible change at a major (e.g. 3.0, 4.0) or minor (e.g. 3.1, 3.2) release. Customers are advised that these interfaces may be removed or changed substantially and in an incompatible way in a future release. It is recommended that customers not create explicit dependencies on unstable interfaces. |
Appendix B, Stability of Message QueueTM Interfaces lists the interfaces and their classifications.
Table B–2 Stability of Message Queue Interfaces
Interface |
Classification |
---|---|
Command Line Interfaces | |
imqbrokerd command line interface |
Evolving |
imqadmin command line interface |
Unstable |
imqcmd command line interface |
Evolving |
imqdbmgr command line interface |
Unstable |
imqkeytool command line interface |
Evolving |
imqobjmgr command line interface |
Evolving |
imqusermgr command line interface |
Unstable |
Output from imqbrokerd, imqadmin, imqcmd, imqdbmgr, imqkeytool, imqobjmgr, imqusermgr |
Unstable |
Commands | |
imqobjmgr command file |
Evolving |
imqbrokerd command |
Stable |
imqadmin command |
Unstable |
imqcmd command |
Stable |
imqdbmgr command |
Unstable |
imqkeytool command |
Stable |
imqobjmgr command |
Stable |
imqusermgr command |
Unstable |
APIs | |
JMS API (javax.jms) |
Standard |
JAXM API (javax.xml) |
Standard |
C-API |
Evolving |
C-API environment variables |
Unstable |
Message-based monitoring API |
Evolving |
Administered Object API (com.sun.messaging) |
Evolving |
.jar and .war Files |
|
imq.jar location and name |
Stable |
jms.jar location and name |
Evolving |
imqbroker.jar location and name |
Private |
imqutil.jar location and name |
Private |
imqadmin.jar location and name |
Private |
imqservlet.jar location and name |
Evolving |
imqhttp.war location and name |
Evolving |
imqhttps.war location and name |
Evolving |
imqjmsra.rar location and name |
Evolving |
imqxm.jar location and name |
Evolving |
jaxm-api.jar location and name |
Evolving |
saaj-api.jar location and name |
Evolving |
saaj-impl.jar location and name |
Evolving |
activation.jar location and name |
Evolving |
mail.jar location and name |
Evolving |
dom4j.jar location and name |
Private |
fscontext.jar location and name |
Unstable |
Files | |
Broker log file location and content format |
Unstable |
password file |
Unstable |
accesscontrol.properties file |
Unstable |
System Destinations | |
mq.sys.dmq destination |
Stable |
mq.metrics.* destinations |
Evolving |
Configuration Properties | |
Message Queue JMS Resource Adapter configuration properties |
Evolving |
Message Queue JMS Resource Adapter JavaBean and ActivationSpec configuration properties |
Evolving |
Message Properties and Formats | |
Dead message queue message property, JMSXDeliveryCount |
Standard |
Dead message queue message properties, JMS_SUN_* |
Evolving |
Message Queue client message properties: JMS_SUN_* |
Evolving |
JMS message format for metrics or monitoring messages |
Evolving |
Miscellaneous | |
Message Queue JMS Resource Adapter package, com.sun.messaging.jms.ra |
Evolving |
JDBC schema for storage of persistent messages |
Evolving |
Message QueueTM, Enterprise Edition includes support for a Java client to communicate with the broker by means of an HTTP or secure HTTP (HTTPS) transport, rather than a direct TCP connection. HTTP/HTTPS support is not available for C clients.
This appendix describes the architecture used to enable this support and explains the setup work needed to allow clients to use HTTP-based connections for Message Queue messaging. It has the following sections:
Message Queue messaging can run on top of HTTP/HTTPS connections. Because HTTP/HTTPS connections are normally allowed through firewalls, this allows client applications to be separated from a broker by a firewall.
Figure C–1 shows the main components involved in providing HTTP/HTTPS support.
On the client side, an HTTP or HTTPS transport driver encapsulates the Message Queue message into an HTTP request and makes sure that these requests are sent to the Web server/application server in the correct sequence.
The client can use an HTTP proxy server to communicate with the broker if necessary. The proxy’s address is specified using command line options when starting the client. See Using an HTTP Proxy for more information.
An HTTP or HTTPS tunnel servlet (both bundled with Message Queue) is loaded in a Web server/application server and used to pull payload messages out of client HTTP requests before forwarding them to the broker. The HTTP/HTTPS tunnel servlet also sends broker messages back to the client in response to HTTP requests made by the client. A single HTTP/HTTPS tunnel servlet can be used to access multiple brokers.
On the broker side, the httpjms or httpsjms connection service unwraps and demultiplexes incoming messages from the corresponding tunnel servlet.
If the Web server/application server fails and is restarted, all connections are restored and there is no effect on clients. If the broker fails and is restarted, an exception is thrown and clients must re-establish their connections. In the unlikely case that both the Web server/application server and the broker fail, and the broker is not restarted, the Web server/application server will restore client connections and continue waiting for a broker connection— without notifying clients. To avoid this situation, always restart the broker.
As you can see from Figure C–1, the architecture for HTTP and HTTPS support is very similar. The main difference is that, in the case of HTTPS (httpsjms connection service), the tunnel servlet has a secure connection to both the client application and broker.
The secure connection to the broker is provided through an SSL-enabled tunnel servlet—Message Queue’s HTTPS tunnel servlet—which passes a self-signed certificate to any broker requesting a connection. The certificate is used by the broker to set up an encrypted connection to the HTTPS tunnel servlet. Once this connection is established, a secure connection between a client application and the tunnel servlet can be negotiated by the client application and the Web server/application server.
The following sections describe the steps you need to take to enable HTTP support.
Deploy the HTTP tunnel servlet. You can deploy the HTTP tunnel servlet on the following:
Configure the broker’s httpjms connection service and start the broker.
Configure an HTTP connection.
You can deploy the HTTP tunnel servlet as a Web archive (.war) file on a Sun Java System Web Server or Sun Java System Application Server.
Deploying the HTTP tunnel servlet as a .war file consists of using the deployment mechanism provided by the Web server/application server. The HTTP tunnel servlet .war file (imqhttp.war) is located in the directory containing .jar, .war, and .rar files, and depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).
The .war file includes a deployment descriptor that contains the basic configuration information needed by the Web server/application server to load and run the servlet. Depending on the Web server/application server, you might also need to specify the context root portion of the servlet’s URL.
Deploying as a Web Archive File
For deployment on a Sun Java System Web Server, see Deploying the HTTP Tunnel Servlet on Sun Java System Web Server.
For deployment on a Sun Java System Application Server, see Deploying the HTTP Tunnel Servlet on Sun Java System Application Server.
The instructions below refer to deployment on Sun Java System Web Server. You can verify successful HTTP tunnel servlet deployment by accessing the servlet URL using a Web browser. It should display status information.
In the browser-based administration GUI, select the Virtual Server Class tab and select Manage Classes.
Select the appropriate virtual server class name (for example, defaultClass) and click the Manage button.
Select Manage Virtual Servers.
Select an appropriate virtual server name and click the Manage button.
Select the Web Applications tab.
Click on Deploy Web Application.
Select the appropriate values for the WAR File On and WAR File Path fields so as to point to the imqhttp.war file, which can be found in a directory that depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).
Enter a path in the Application URI field.
The Application URI field value is the /contextRoot portion of the tunnel servlet URL:
http://hostName :portNumber / contextRoot/tunnel
For example, if you set the contextRoot to imq, the Application URI field would be:
/imq
Enter the installation directory path (typically somewhere under the Sun Java System Web Server installation root) where the servlet should be deployed.
Click OK.
Restart the Web server instance.
The servlet is now available at the following address:
http://hostName:portNumber/ contextRoot/tunnel |
Clients can now use this URL to connect to the message service using an HTTP connection.
You do not have to disable the server access log, but you will obtain better performance if you do.
Select the Status tab.
Choose the Log Preferences Page.
Use the Log client accesses control to disable logging.
This section describes how you deploy the HTTP tunnel servlet as a .war file on the Sun Java System Application Server, and then configure the tunnel servlet to accept connections from a Message Queue broker.
Two steps are required:
Deploy the HTTP tunnel servlet using the Application Server deployment tool.
Modify the application server instance’s server.policy file.
In the Web-based administration GUI, choose
App Server > Instances > server1 > Applications > Web Applications.
Click the Deploy button.
In the File Path: text field, enter the location of the HTTP tunnel servlet .war file (imqhttp.war), and click OK.
The location of the imqhttp.war file depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).
Set the value for the Context Root text field, and click OK.
The Context Root field value is the /contextRoot portion of the tunnel servlet URL:
http://hostName :portNumber / contextRoot/tunnel
For example, you could set the Context Root field to /imq.
The confirmation screen that appears confirms that the tunnel servlet has been successfully deployed, is enabled by default, and in this case is located at:
/var/opt/SUNWappserver8/domains/domain1/server1/applications/ j2ee-modules/imqhttp_1 |
The servlet is now available at the following URL:
http://hostName:portNumber/ contextRoot/tunnel |
Clients can now use this URL to connect to the message service using an HTTP connection.
The Application Server enforces a set of default security policies that, unless modified, would prevent the HTTP tunnel servlet from accepting connections from the Message Queue broker.
Each application server instance has a file that contains its security policies, or rules. For example, the location of this file for the server1 instance on Solaris is:
/var/opt/SUNWappserver8/domains/domain1/server1/config/ server.policy
To configure the tunnel servlet to accept connections from the Message Queue broker, an additional entry is required in this file.
Open the server.policy file.
Add the following entry:
grant codeBase "file:/var/opt/SUNWappserver8/domains/domain1/server1/ applications/j2ee-modules/imqhttp_1/-” { permission java.net.SocketPermission "*", “connect,accept,resolve"; }; |
HTTP support is not activated for a broker by default, so you need to reconfigure the broker to activate the httpjms connection service. Once reconfigured, the broker can be started as outlined in Starting Brokers.
Open the broker’s instance configuration file.
The instance configuration file is stored in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):
…/instances/ instanceName/props/config.properties
Add the httpjms value to the imq.service.activelist property:
imq.service.activelist=jms,admin,httpjms |
At startup, the broker looks for a Web server/application server and HTTP tunnel servlet running on its host machine. To access a remote tunnel servlet, however, you can reconfigure the servletHost and servletPort connection service properties.
You can also reconfigure the pullPeriod property to improve performance. The httpjms connection service configuration properties are detailed in Step 2. Configure the httpjms Connection Service.
A client application must use an appropriately configured connection factory administered object to make an HTTP connection to a broker. This section discusses HTTP connection configuration issues.
To enable HTTP support, you need to set the connection factory’s imqAddressList attribute to the HTTP tunnel servlet URL. The general syntax of the HTTP tunnel servlet URL is the following:
http://hostName:portNumber /contextRoot/tunnel
where hostName:portNumber is the name and port of the Web server/application server hosting the HTTP tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the Web server/application server.
For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer's Guide for Java Clients.
You can set connection factory attributes in one of the following ways:
Using the -o option to the imqobjmgr command that creates the connection factory administered object (see Adding a Connection Factory), or set the attribute when creating the connection factory administered object using the Administration Console (imqadmin).
Using the -D option to the command that launches the client (see the Message Queue Developer's Guide for Java Clients).
Using an API call to set the attributes of a connection factory after you create it programmatically in client code (see the Message Queue Developer's Guide for Java Clients).
You do not need to configure multiple Web servers/application servers and servlet instances if you are running multiple brokers. You can share a single Web server/application server and HTTP tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:
http://hostName:portNumber /contextRoot/tunnel?ServerName= bkrHostName:instanceName
Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.
To check that you have entered the correct strings for bkrHostName and instanceName, generate a status report for the HTTP tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:
HTTP tunnel servlet ready. Servlet Start Time : Thu May 30 01:08:18 PDT 2005 Accepting TCP connections from brokers on port : 7675 Total available brokers = 2 Broker List : jpgserv:broker2 cochin:broker1 |
If you are using an HTTP proxy to access the HTTP tunnel servlet:
Set http.proxyHost system property to the proxy server host name.
Set http.proxyPort system property to the proxy server port number.
You can set these properties using the -D option to the command that launches the client application.
The following sections describe the steps to enable HTTPS support. They are similar to those in Enabling HTTP Support with the addition of steps needed to generate and access SSL certificates.
Generate a self-signed certificate for the HTTPS tunnel servlet.
Modify the HTTP tunnel servlet .war file’s deployment descriptor to:
Deploy the HTTP tunnel servlet. You can deploy the HTTP tunnel servlet on the following:
Configure the broker’s httpsjms connection service and start the broker.
Configure an HTTPS connection.
Each of these steps is discussed in more detail in the sections that follow.
Message Queue’s SSL support is oriented toward securing on-the-wire data with the assumption that the client is communicating with a known and trusted server. Therefore, SSL is implemented using only self-signed server certificates.In the httpsjms connection service architecture, the HTTPS tunnel servlet plays the role of server to both broker and application client.
Run the keytool utility to generate a self-signed certificate for the tunnel servlet. Enter the following at the command prompt:
JRE_HOME/bin/keytool -servlet keyStoreLocation
The utility will prompt you for the information it needs. (On Unix systems you may need to run keytool as the superuser (root) in order to have permission to create the key store.)
First, keytool prompts you for a key store password, and then it prompts you for some organizational information, and then it prompts you for confirmation. After it receives the confirmation, it pauses while it generates a key pair. It then asks you for a password to lock the particular key pair (key password); you should enter Return in response to this prompt: this makes the key password the same as the key store password.
Remember the password you provide: you must provide this password later to the tunnel servlet so it can open the key store.
The JDK keytool utility generates a self-signed certificate and places it in Message Queue’s key store file located as specified in the keyStoreLocation argument.
The HTTPS tunnel servlet must be able to see the key store. Make sure you move/copy the generated key store located in keyStoreLocation to a location accessible by the HTTPS tunnel servlet (see Step 3. Deploying the HTTPS Tunnel Servlet).
The HTTP Tunnel Servlet’s .war file includes a deployment descriptor that contains the basic configuration information needed by the Web server/application server to load and run the servlet.
The deployment descriptor of the imqhttps.war file cannot know where you have placed the key store file needed by the tunnel servlet. This requires you to edit the tunnel servlet’s deployment descriptor (an XML file) to specify the key store location and password before deploying the imqhttps.war file.
Copy the .war file to a temporary directory.
cp /usr/share/lib/imq/imqhttps.war /tmp (Solaris)
cp /opt/sun/mq/share/lib/imqhttps.war /tmp (Linux)
cp IMQ_HOME/lib/imqhttps.war /tmp (Windows)
Make the temporary directory your current directory.
$ cd /tmp
Extract the contents of the .war file.
$ jar xvf imqhttps.war
List the .war file’s deployment descriptor.
$ ls -l WEB-INF/web.xml
Edit the web.xml file to provide correct values for the keystoreLocation and keystorePassword arguments (as well as servletPort and servletHost arguments, if necessary).
Reassemble the contents of the .war file.
$ jar uvf imqhttps.war WEB-INF/web.xml
You are now ready to use the modified imqhttps.war file to deploy the HTTPS tunnel servlet. (If you are concerned about exposure of the key store password, you can use file system permissions to restrict access to the imqhttps.war file.)
You can deploy the HTTP tunnel servlet as a Web archive (WAR) file on a Sun Java System Web Server or Sun Java System Application Server.
Deploying the HTTPS tunnel servlet as a .war file consists of using the deployment mechanism provided by the Web server/application server. The HTTPS tunnel servlet .war file (imqhttps.war) is located in a directory that depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).
You should make sure that encryption is activated for the Web server, enabling end-to-end secure communication between the client and broker.
For deployment on a Sun Java System Web Server, see Deploying the HTTPS Tunnel Servlet on Sun Java System Web Server.
For deployment on a Sun Java System Application Server, see Deploying the HTTPS Tunnel Servlet on Sun Java System Application Server.
This section describes how you deploy the HTTPS tunnel servlet as a .war file on the Sun Java System Web Server. You can verify successful HTTPS tunnel servlet deployment by accessing the servlet URL using a Web browser. It should display status information.
Before deploying the HTTPS tunnel servlet, make sure that JSSE .jar files are included in the Web server’s classpath. The simplest way to do this is to copy the files jsse.jar, jnet.jar, and jcert.jar to WebServer_TOPDIR/bin/https/jre/lib/ext .
In the browser-based administration GUI, select the Virtual Server Class tab. Click Manage Classes.
Select the appropriate virtual server class name (for example, defaultClass) and click the Manage button.
Select Manage Virtual Servers.
Select an appropriate virtual server name and click the Manage button.
Select the Web Applications tab.
Click on Deploy Web Application.
Select the appropriate values for the WAR File On and WAR File Path fields so as to point to the modified imqhttps.war file (see Step 2. Modifying the HTTP Tunnel Servlet .war File’s Descriptor File.)
Enter a path in the Application URI field.
The Application URI field value is the /contextRoot portion of the tunnel servlet URL:
https://hostName :portNumber / contextRoot/tunnel
For example, if you set the contextRoot to imq, the Application URI field would be:
/imq
Enter the installation directory path (typically somewhere under the Sun Java System Web Server installation root) where the servlet should be deployed.
Click OK.
Restart the Web server instance.
The servlet is now available at the following URL:
https://hostName:portNumber/imq/tunnel |
Clients can now use this URL to connect to the message service using a secure HTTPS connection.
You do not have to disable the server access log, but you will obtain better performance if you do.
Select the Status tab.
Choose the Log Preferences Page.
Use the Log client accesses control to disable logging.
This section describes how you deploy the HTTPS tunnel servlet as a .war file on the Sun Java System Application Server.
Two steps are required:
Deploy the HTTPS tunnel servlet using the Application Server deployment tool.
Modify the application server instance’s server.policy file.
The following procedure shows how to deploy the HTTPS tunnel servlet in an Application Server environment.
In the Web-based administration GUI, choose
App Server > Instances > server1 > Applications > Web Applications
Click the Deploy button.
In the File Path: text field, enter the location of the HTTPS tunnel servlet .war file (imqhttps.war), and click OK.
The location of the imqhttps.war file depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).
Set the value for the Context Root text field, and click OK.
The Context Root field value is the /contextRoot portion of the tunnel servlet URL:
https://hostName :portNumber / contextRoot/tunnel
For example, you could set the Context Root field to:
/imq
The next screen shows that the tunnel servlet has been successfully deployed, is enabled by default, and in this case is located at:
/var/opt/SUNWappserver8/domains/domain1/server1/applications/ j2ee-modules/imqhttps_1 |
The servlet is now available at the following URL:
https://hostName:portNumber/ contextRoot/tunnel |
Clients can now use this URL to connect to the message service using an HTTPS connection.
Application Server enforces a set of default security policies that unless modified would prevent the HTTPS tunnel servlet from accepting connections from the Message Queue broker.
Each application server instance has a file that contains its security policies or rules. For example, the location of this file for the server1 instance on Solaris is:
/var/opt/SUNWappserver8/domains/domain1/server1/config/ server.policy
To make the tunnel servlet accept connections from the Message Queue broker, an additional entry is required in this file.
Open the server.policy file.
Add the following entry:
grant codeBase "file:/var/opt/SUNWappserver8/domains/domain1/server1/ applications/j2ee-modules/imqhttps_1/-” { permission java.net.SocketPermission "*", “connect,accept,resolve"; }; |
HTTPS support is not activated for a broker by default, so you need to reconfigure the broker to activate the httpsjms connection service. Once reconfigured, the broker can be started as outlined in Starting Brokers.
Open the broker’s instance configuration file.
The instance configuration file is stored in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):
…/instances/ instanceName/props/config.properties
Add the httpsjms value to the imq.service.activelist property:
imq.service.activelist=jms,admin,httpsjms |
At startup, the broker looks for a Web server and HTTPS tunnel servlet running on its host machine. To access a remote tunnel servlet, however, you can reconfigure the servletHost and servletPort connection service properties.
You can also reconfigure the pullPeriod property to improve performance. The httpsjms connection service configuration properties are detailed in Step 4. Configuring the httpsjms Connection Service.
A client application must use an appropriately configured connection factory administered object to make an HTTPS connection to a broker.
However, the client must also have access to SSL libraries provided by the Java Secure Socket Extension (JSSE) and must also have a root certificate. The SSL libraries are bundled with JDK 1.4. If you have an earlier JDK version, see Configuring JSSE otherwise proceed to Importing a Root Certificate
Once these issues are resolved, you can proceed to configuring the HTTPS connection.
Copy the JSSE .jar files to the JRE_HOME/lib/ext directory.
jsse.jar, jnet.jar, jcert.jar |
Statically add the JSSE security provider by adding
security.provider.n=com.sun.net.ssl.internal.ssl.Provider |
to the JRE_HOME/lib/security/java.security file (where n is the next available priority number for security provider package).
If not using JDK1.4, you need to set the following JSSE property using the -D option to the command that launches the client application:
java.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol |
If the root certificate of the CA who signed your Web server’s certificate is not in the trust database by default or if you are using a proprietary Web server/application server certificate, you must add that certificate to the trust database. If this is the case, follow the instruction below, otherwise go to Configuring the Connection Factory
Assuming that the certificate is saved in certFile and that trustStoreFile is your key store, run the following command:
JRE_HOME/bin/keytool -import -trustcacerts -alias aliasForCertificate -file certFile -keystore trustStoreFile
Answer YES to the question: Trust this certificate?
You also need to specify the following JSSE properties using the -D option to the command that launches the client application:
javax.net.ssl.trustStore=trustStoreFile javax.net.ssl.trustStorePassword=trustStorePasswd
To enable HTTPS support, you need to set the connection factory’s imqAddressList attribute to the HTTPS tunnel servlet URL. The general syntax of the HTTPS tunnel servlet URL is the following:
https://hostName:portNumber /contextRoot/tunnel
where hostName:portNumber is the name and port of the Web server hosting the HTTPS tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the Web server.
For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer's Guide for Java Clients.
You can set connection factory attributes in one of the following ways:
Using the -o option to the imqobjmgr command that creates the connection factory administered object (see Adding a Connection Factory), or set the attribute when creating the connection factory administered object using the Administration Console (imqadmin).
Using the -D option to the command that launches the client application (see the Message Queue Developer's Guide for Java Clients).
Using an API call to set the attributes of a connection factory after you create it programmatically in client application code (see the Message Queue Developer's Guide for Java Clients).
You do not need to configure multiple Web servers and servlet instances if you are running multiple brokers. You can share a single Web server and HTTPS tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:
https://hostName:portNumber /contextRoot/tunnel?ServerName= bkrHostName:instanceName
Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.
To check that you have entered the correct strings for bkrhostName and instanceName, generate a status report for the HTTPS tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:
HTTPS tunnel servlet ready. Servlet Start Time : Thu May 30 01:08:18 PDT 2002 Accepting secured connections from brokers on port : 7674 Total available brokers = 2 Broker List : jpgserv:broker2 cochin:broker1 |
If you are using an HTTP proxy to access the HTTPS tunnel servlet:
Set http.proxyHost system property to the proxy server host name.
Set http.proxyPort system property to the proxy server port number.
You can set these properties using the -D option to the command that launches the client application.
This section describes possible problems with an HTTP or HTTPS connection and provides guidance on how to handle them.
If the Web server fails and is restarted, all connections are restored and there is no effect on clients. However, if the broker fails and is restarted, an exception is thrown and clients must re-establish their connections.
If both the Web server and the broker fail, and the broker is not restarted, the Web server restores client connections and continues waiting for a broker connection without notifying clients. To avoid this situation, always make sure the broker is restarted.
If an HTTPS client cannot connect to the broker through the tunnel servlet, do the following:
Start the servlet and the broker.
Use a browser to manually access the servlet through the HTTPS tunnel servlet URL.
Use the following administrative commands to pause and resume the connection:
imqcmd pause svc -n httpsjms -u admin imqcmd resume svc -n httpsjms -u admin |
When the service resumes, an HTTPS client should be able to connect to the broker through the tunnel servlet.
This appendix lists some frequently used Message QueueTM Command utility ( imqcmd) commands. For a comprehensive list of command options and attributes available to you from the command line, refer to Command Utility in Command Utility
imqcmd subcommand argument [ options] imqcmd -h|H imqcmd -v
-H or -h provides comprehensive help. The -v subcommand provides version information.
When you use imqcmd, the Command utility prompts you for a password. To avoid the prompt (and to increase security), you can use the -passfile pathToPassfile option to point the utility to a password file that contains the administrator username and password.
Example: imqcmd query bkr -u adminUserName -passfile pathToPassfile -b myServer:7676
imqcmd query bkr imqcmd pause bkr imqcmd restart bkr imqcmd resume bkr imqcmd shutdown bkr -b myBroker:7676 imqcmd update bkr -o "imq.system.max_count=1000" imqcmd reload cls
Broker Configuration Properties (-o option) lists frequently used broker configuration properties. For a full list of broker configuration properties and their descriptions, see Chapter 14, Broker Properties Reference
Table D–1 Broker Configuration Properties ( -o option)
Property |
Notes |
---|---|
imq.autocreate.queue | |
imq.autocreate.queue.maxNumActiveConsumers |
Specify -1 for unlimited |
imq.autocreate.queue.maxNumBackupConsumers |
Specify -1 for unlimited |
imq.autocreate.topic | |
imq.cluster.url | |
imq.destination.DMQ.truncateBody | |
imq.destination.logDeadMessages | |
imq.log.file.rolloverbytes |
Specify -1 for unlimited |
imq.log.file.rolloversecs |
Specify -1 for unlimited |
imq.log.level |
NONEERRORWARNINGINFO |
imq.message.max_size |
Specify -1 for unlimited |
imq.portmapper.port | |
imq.system.max_count |
Specify -1 for unlimited |
imq.system.max_size |
Specify -1 for unlimited |
imqcmd list svc imqcmd query svc imqcmd update svc -n jms -o "minThreads=200" -o "maxThreads=400" -o "port=8995" imqcmd pause svc -n jms imqcmd resume svc -n jms imqcmd list cxn -svn jms imqcmd query cxn -n 1234567890
imqcmd list dur -d MyTopic imqcmd destroy dur -n myDurSub -c "clientID-111.222.333.444" imqcmd purge dur -n myDurSub -c "clientID-111.222.333.444"
imqcmd list txn imqcmd commit txn -n 1234567890 imqcmd query txn -n 1234567890 imqcmd rollback txn -n 1234567890
imqcmd create dst -n MyQueue -t q -o "maxNumMsgs=1000" -o "maxNumProducers=5" imqcmd update dst -n MyTopic -t t -o "limitBehavior=FLOW_CONTROL| REMOVE_OLDEST|REJECT_NEWEST|REMOVE_LOW_PRIORITY" imqcmd compact dst -n MyQueue -t q imqcmd purge dst -n MyQueue -t q imqcmd pause dst -n MyQueue -t q -pst PRODUCERS|CONSUMERS|ALL imqcmd resume dst -n MyQueue -t q imqcmd destroy dst -n MyQueue -t q imqcmd query dst -n MyQueue -t q imqcmd list dst -tmp
Destination Configuration Properties (-o option) lists frequently used destination configuration properties. For a full list of destination configuration properties and their descriptions, see Chapter 15, Physical Destination Property Reference
Table D–2 Destination Configuration Properties (-o option)
Property |
Notes |
---|---|
consumerFlowLimit |
Specify -1 for unlimited |
isLocalOnly (create only) | |
limitBehavior |
FLOW_CONTROLREMOVE_OLDESTREJECT_NEWESTREMOVE_LOW_PRIORITY |
localDeliveryPreferred (queue only) | |
maxNumActiveConsumers (queue only) |
Specify -1 for unlimited |
maxNumBackupConsumers (queue only) |
Specify -1 for unlimited |
maxBytesPerMsg |
Specify -1 for unlimited |
maxNumMsgs |
Specify -1 for unlimited |
maxNumProducers |
Specify -1 for unlimited |
maxTotalMsgBytes |
Specify -1 for unlimited |
useDMQ |
imqcmd metrics bkr -m cxn|rts|ttl -int 5 -msp 20 imqcmd metrics svc -m cxn|rts|ttl imqcmd metrics dst -m con|dsk|rts|ttl