Prerequisites

Hardware and Software Prerequisites

The following sections describe the minimum hardware and software requirements for installing and running the Java Message Queue product. For a complete list of supported operating system and JDK levels, see the product README file.

At a minimum, your Solaris deployment or development system should satisfy the following requirements:

Solaris Operating Environment (SPARC Platform Edition)

• Sun Ultra[tm] 1 (or compatible) workstation (must be TCP/IP networked)
• 64 Mbytes RAM
• Solaris 2.6 operating environment (SunOS[tm] 5.6) plus patch 105792-03
• Java Development Kit (JDK [tm]) 1.1.8, production (not reference) version

The compressed installation file is approximately 3.1 Mbytes.
The temporary "working" directory used for extracting the installation files requires an additional 11 Mbytes.
The installed product requires approximately 5 Mbytes of hard drive space.

NOTE: ou can download the supported JDK from the following webpages:

http://java.sun.com/products/jdk/1.2/index.html
http://java.sun.com/products/jdk/1.1/index.html

Windows NT Systems

At a minimum, your Windows deployment or development system should satisfy the following requirements:

• Intel Pentium 166 MHz (or compatible) PC that is TCP/IP networked
• 64 Mbytes RAM
• Windows NT 4.0 with Service Pack 4
• Java Development Kit (JDK) 1.1.8, production (not reference) version

The self-extracting installation file is approximately 3.0 Mbytes.
Your temporary directory (used for extracting the installation files) requires an additional 3.5 Mbytes. The installed product requires approximately 5 Mbytes of hard drive space.

NOTE: you can download the supported JDK from the following webpages:

http://java.sun.com/products/jdk/1.2/index.html
http://java.sun.com/products/jdk/1.1/index.html

Java Message Queue Releases

The product is currently available in the following release packaging:

• Developer Edition
  
  Includes files necessary to write and run Java Message Queue clients in a development environment.
  
  • Runtime-environment
    
  • Command-line utilities
    
  • Documentation
    
  • Examples
    
  • 5-connection router for development-only use.
    
  
  
  The product license allows you to run one router instance. To run multiple router instances, you must purchase additional licenses. For example, running one router on one subnet and another router on another subnet requires you to have two licenses (regardless of whether you are running the routers on the same host or different hosts).
  
• Business Edition
  
  Includes files necessary to write and run Java Message Queue clients in a deployment environment.
  
  • Runtime-environment
    
  • Command-line utilities
    
  • Documentation
    
  • Examples
    
  • Unlimited-connection router deployment or development use.
    

  To run multiple router instances, you must purchase additional licenses (see Developer Edition for details).
  
  

• Business Edition 10-Pack
  
  Similar to the standard Business Edition but license allows up to 10 router instances on the same host, or up to 10 router instances (total) across several hosts.

Installation Instructions

Installing in the Solaris Operating Environment

NOTE:
It is highly recommended that you keep your Operating System up to date by installing the full set of patches available for your platform, rather than just the minimal set of patches for running the desired JDK. This recommendation is made because other bugs may exist on your platform which may interact unfavorably with your applications and result in minor to major inconveniences for you.

Recommended and security patches for Solaris are publicly available and provided at no charge. For the latest set of patches for your operating system level, see:
http://sunsolve.sun.com/
In the left-hand navigation panel, click Patches.

When downloading the Java Message Queue product from the Sun website, installation is simplest if the bundle is downloaded into an empty, current working directory.

1. Run the command script:
   sh jmq1_1-XXX-solsparc.sh

   where XXX is one of:

   • dev for Developer Edition
     
   • bus for Business Edition
     
   • ten for Business Edition 10-pack
     

   This displays the first portion of the license for the product. To display the entire license a page at a time, repeatedly press the space bar.

2. Read the product license. Installation and use of the product is subject to acceptance of the license agreement.

   If you choose to accept the agreement, type yes or y and the installation continues.

   If you choose not to accept the license agreement, type no or n and the installation terminates.

   If you chose to accept the agreement, the following files are extracted:
   

   • jmq1_1-XXX-solsparc.tar.Z
     where XXX is one of: dev, bus, or ten
     
     
   • COPYRIGHT
   • INSTALL
   • LICENSE
   • README
   • RELEASENOTES
   • UNINSTALL

   The LICENSE file is a copy of the license agreement.

3. Read the Release Notes and README.
   

   Release Notes might include last-minute information that was not available when the other documentation was sent to production. In addition, the Release Notes always contain information on code and documentation changes, open bugs, and important technical notes.

   README includes where to find documentation, news, and updates, and how to send feedback.

4. Uncompress the file archive:
   
   uncompress jmq1_1-XXX-solsparc.tar.Z
   
   
5. Extract the archived files:
   
   

   (Because problems have been experienced using the GNU tar utility in the Java Message Queue installation, its use is not recommended.)

   tar xvfp jmq1_1-XXX-solsparc.tar
   

   A new directory called jmq1_1-pkgs is created.

6. Change directories:
   
   cd jmq1_1-pkgs
   

   The contents of the directory vary depending on the product release.

   TABLE 1 Contents of jmq1_1-pkgs Directory

   Package Name Developer Edition Business Edition Business 10-pack Edition SUNWjqapi Yes Yes Yes SUNWjqrtr Yes Yes Yes SUNWjqrun Yes Yes Yes SUNWjqdev Yes No No SUNWjqent No Yes Yes

7. Become root:
   
   su root
   
   
8. Run the pkgadd command to install the packages:
   
   pkgadd -d ./
   
   

   The pkgadd utility will list the names of all packages in the directory available for installation. When prompted, indicate you want to install all packages by typing:
   
   all

   The Java Message Queue product is installed primarily into the /opt/SUNWjmq/ with a few files placed in the /var/opt/SUNWjmq/ directory.

   Note: On Solaris, you should install JMQ 1.1 in only the default location (/opt/SUNjmq). If you do not install JMQ in /opt/SUNWjmq, you must adjust the LD_LIBRARY_PATH environment variable before running the irouter.

9. Choose to install the router for automatic or manual startup
   

   When installing the SUNWjqrtr pkg, the install script will ask if you want the router to start automatically on system reboot. (If the router is started automatically, it is not affected if any user logs on or off. If the router is started manually by a user, the process terminates when that user's session ends.)

   To have the router installed to start automatically, type y.

   To have the router installed to be started manually, type n.

   You can later choose to have the router start automatically. Simply read and follow the instructions provided in the installed /opt/SUNWjmq/etc/jmq file.

10. Exit the root shell.
    
    
11. Backup your .sh file, then clear temporary installation files.
    When you have completed installation, you may want to clean up the files in the temporary working directory you were using. Below is the list of files and their suggested disposition.
    

    Suggested handling

    COPYRIGHT Delete. This file is copied to the install directory during pkgadd. INSTALL Delete. This file is copied to the install directory during pkgadd. LICENSE Delete. This file is copied to the install directory during pkgadd. README Delete. This file is copied to the install directory during pkgadd. RELEASENOTES Copy to install directory (by default: /opt/SUNWjmq/). UNINSTALL Delete. This file is copied to the install directory during pkgadd. jmq1_1-pkgs/ Delete. This is an intermediary directory which is recoverable from the .sh file. jmq1_1-XXX-solsparc.sh Create backup copy. This is your logical media. You should treat this file as you would any other installation media. Place a copy in a safe location in case you encounter a situation (such as a system failure) that requires re-installation of the product. jmq1_1-XXX-solsparc.tar Delete. This is an intermediary file which is recoverable from the .sh file.

    
    

12. Reboot your machine if necessary.
    

    If you installed the router to start automatically, you can start the router in either of the following ways:
    

    • Reboot your machine, or
      
    • Type the following command
      
      /etc/init.d/jmq start

    NOTE: You must manually create the JMQ_HOME environment variable and set it to the directory into which you installed the Java Message Queue product (by default, /opt/SUNWjmq/).

Installing on Windows Systems

When downloading the product from the Sun website, installation is simplest if the Java Message Queue executable is downloaded into an empty, current working directory.

NOTE: If you are installing Java Message Queue after a previous uninstall, be sure to remove any references to the previous Java Message Queue installation from the System's PATH environment variable (Windows NT or 2000) or the autoexec.bat file (Windows 95 or 98) before re-installing.

1. Extract the installation files and launch setup.

   In the Windows Explorer, double-click on the self-extracting file's icon. The file has a name of the form:
   
   jmq1_1-XXX-win.exe
   
   where XXX is one of:
   
   

   • dev for Developer Edition
     
   • bus for Business Edition
     
   • ten for Business 10-pack Edition
     

2. Read the warning message.

   Having more than one copy of the Java Message Queue software installed on a single machine will cause problems with the program's operation. The installation program displays a warning message to this effect.

   If you have no other installed copies of Java Message Queue on your machine, simply click Resume Setup.

   If you think you might have previously installed copies still on your machine, click Exit Setup. Uninstall those prior copies before restarting this installation.

3. Follow the setup program's instructions.

   • Select type of installation:
     

     • Custom - installs only the components you select.

     • Typical - installs everything to run the router and clients for that release of the software.

     • Minimal - installs only the files necessary to run that release. No documentation or examples are installed.

     • Upgrade Connection Capacity - installs only the files necessary to upgrade the router's connection enabler file. It does not overwrite any of the Java Message Queue files or user-created files already installed on the system.

   • Choose a location for installation.

   • Choose or create a folder for the installation

     This is the folder that will be reflected when you choose Programs from the Windows Start menu.

   • Decide whether to install the router as a Windows service.

     NOTE: This option is only available on Windows NT or 2000 systems and requires Windows Administrator group privileges.

     Installing the router as a Windows service enables you to manage the router process through the Windows Services Manager. The Windows Services Manager provides the ability to manually start a service, automatically start a service (on every system reboot), pass startup options to the service, or stop the service.

     If you don't choose to install the router as a Windows service now but later change your mind, you can use the jmqsvcadmin utility to do so. Please see the Deployment Guide for information on using the jmqsvcadmin utility.

   • Read the README file and Release Notes.

     The README includes information on where to find documentation, news and updates, and how to send feedback.

     The Release Notes might include last-minute information that was not available when the other documentation was sent to production. In addition, the Release Notes always contain information on code and documentation changes, open bugs, and important technical notes.

   • Reboot if prompted.

Troubleshooting Installation Problems

If the Java Message Queue installation program does not complete successfully on your Windows platform (for example, if it stops responding at some stage), try the following:

1. Use the Windows Task Manager to end the Java Message Queue installation program.
2. Clear any temporary directories (for example, temp or tmp).
3. Start the Java Message Queue installation again, being certain to install to the same directory as the initial installation attempt.

If your Windows installation of the Java Message Queue product is still not successful, try this more comprehensive procedure:

1. Use the Windows Task Manager to end the Java Message Queue installation program.
2. Clear any temporary directories (for example, temp or tmp).
3. In the Services control panel, temporarily stop any non-Windows network-related services (for example, a Solstice NFS Server service).
4. Delete the JavaMessageQueue1.1 directory and all its contents.
5. In your Systems control panel, remove all references to JavaMessageQueue1.1 from your environment settings.
6. Restart your Windows operating system.
7. Reinstall Java Message Queue to the *same* location as the initial failed installation.
8. Reset any services in the Services (Control Panel) that you stopped in step 3.

Installed Image (Solaris and Windows Environments)

NOTE: This install image below reflects a full Solaris installation (all packages) or "Typical" Windows installation. The installed components might vary if not all Solaris packages are added or another Windows setup option (such as Custom or Minimal) is chosen.

COPYRIGHT*

INSTALL*

LICENSE*

README*

RELEASENOTES* (Windows only)

UNINSTALL*

* On Windows platforms, these files have a .txt filename extension.

admin directory

Contains the jndi.properties file.
(On Solaris, this directory is not located under the main installation directory but rather under the /var/opt/SUNWjmq/ secondary directory.)

bin directory

Contains the executables for the router (irouter) and utilities: the router connection program (ircmd), the remote monitor (irmon), the administration tool (jmqadmin), and the program for configuring administered objects (jmqconfig).

On Windows, this directory also includes the dynamic link libraries (.dll) and the utility to install the router as a Windows Service (jmqsvcadmin).

doc directory

Contains user information (for developing, deploying, and administering Java Message Queue applications) as well as reference information (such as the JMS API Specification).

etc directory (Solaris only).

Contains a script that can be used if automatic startup is desired.

examples directory

Contains subdirectories of source code and scripts for examples.

lib directory

Contains the .jar files used to build and run Java Message Queue clients. On Solaris, this directory also contains the dynamic Java Message Queue libraries.

res directory (Windows only).

Contains sys/ and user/ subdirectories where resource files are stored. (Resource definition files are used to save information for retrieval--such as start-up defaults and connection configurations.) Persistent messages are also stored in the res directory.

(On Solaris, this directory is not located under the main installation directory but rather under the /var/opt/SUNWjmq/ secondary directory.)

security directory

Contains the jmqadmin, jmqclient, and jmqexamples policy files for controlling access to critical system resources when running the product, client applications, or examples in a Java 2 environment.

Installation Defaults