JBoss.orgCommunity Documentation

JBoss Communications JAIN SLEE Jopr Plugin User Guide


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to JBoss Operations Network and JBoss Communications JAIN SLEE Plugin
2. Installing JBoss Operations Network and JBoss Communications JAIN SLEE Plugin
2.1. Pre-Install Requirements and Prerequisites
2.1.1. Hardware Requirements
2.1.2. Software Prerequisites
2.2. Install JBoss Operations Network and JBoss Communications JAIN SLEE Plugin
2.2.1. Installing JBoss Operations Network Server and Agent
2.2.2. Installing the JBoss Communications JAIN SLEE Plugin
3. Managing JBoss Communications JAIN SLEE with JBoss Operations Network
3.1. JBoss Operations Network JAIN SLEE Plugin Main View
3.2. Managing and Monitoring JAIN SLEE Container
3.2.1. View JAIN SLEE Server Version and State
3.2.2. Monitor JAIN SLEE Availability over time
3.2.3. View installed JAIN SLEE Components
3.2.4. Install/Uninstall JAIN SLEE Deployable Units
3.2.5. Start/Stop/Shutdown JBoss Communications JAIN SLEE Server
3.2.6. List All Activity Contexts
3.2.7. Query Activity Context Liveness
3.2.8. Change Container Logging Configuration
3.2.9. Edit Container Logging Configurations
3.2.10. View Event Router Statistics
3.2.11. Managing Congestion Control
3.3. Managing and Monitoring JAIN SLEE Deployable Units
3.3.1. View JAIN SLEE Deployable Unit Summary
3.3.2. Monitor JAIN SLEE DU Availability over time
3.3.3. List Component IDs
3.4. Managing and Monitoring JAIN SLEE Resource Adaptors
3.4.1. View JAIN SLEE Resource Adaptor Summary
3.4.2. Monitor JAIN SLEE RA Availability over time
3.4.3. Monitor JAIN SLEE RA Active Entities over time
3.4.4. View, Create and Remove Resource Adaptor Entities
3.4.5. Configure a Resource Adaptor
3.5. Managing and Monitoring JAIN SLEE Resource Adaptor Entities
3.5.1. View Resource Adaptor Entity Summary
3.5.2. Monitor JAIN SLEE RA Entity Availability over time
3.5.3. Monitor JAIN SLEE RA Entity Activities over time
3.5.4. View, Create and Remove Resource Adaptor Entity Links
3.5.5. Configure a Resource Adaptor Entity
3.5.6. Activate/Deactivate RA Entity
3.5.7. List Activity Context
3.6. Managing and Monitoring JAIN SLEE Resource Adaptor Entity Links
3.6.1. View Resource Adaptor Entity Link Summary
3.6.2. Monitor JAIN SLEE RA Entity Link Availability over time
3.6.3. List SBBs bound to RA Entity Link
3.7. Managing and Monitoring JAIN SLEE Service Building Blocks (SBBs)
3.7.1. View SBB Summary
3.7.2. Monitor JAIN SLEE SBB Availability over time
3.8. Managing and Monitoring JAIN SLEE Services
3.8.1. View Service Summary
3.8.2. Monitor JAIN SLEE Service Availability over time
3.8.3. Activate/Deactivate a JAIN SLEE Service
3.8.4. Retrieve SBB Entities
3.9. Monitoring JAIN SLEE Event Router Executors
3.9.1. View Event Router Executors Summary
3.9.2. Monitor Event Router Executors metrics
A. Java Development Kit (JDK): Installing, Configuring and Running
B. Setting the JBOSS_HOME Environment Variable
C. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product ${product.name}, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier:

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Ensure that the following requirements have been met before continuing with the install.

JDK 5 or Higher

A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run the JBoss Operations Network. Note that JBoss Enterprise Application Platform is a runtime dependency, but comes bundled with the binary distribution.

For instructions on how to install the JDK, refer to Appendix A, Java Development Kit (JDK): Installing, Configuring and Running.

External Database

In order to run JBoss Operations Network, an external database must be installed.

Use of Embedded H2 database

JBoss Operations Network is distributed with a Java embedded database called "H2", so if you are just running JBoss Operations Network to test it out and play with it, you can use that and not install an external database. But this Embedded H2 database is to be considered only for demo'ing and testing purposes. For production systems, you will need to install an external database.

The supported databases are:

PostgreSQL

Postgres versions 8.2.4 and higher are supported.

Oracle

Oracle versions 10g and 11g are supported.

After installing the database, make note of the JDBC URL, username and password for the database. This information is required during the JBoss Operations Network Server installation.

JBoss Operations Network is based on and plugin-compatible with the multi-vendor RHQ management project. For the JBoss Communications Plugin to work correctly, version 1.4.x of RHQ is required.

Since there's no released version of JBoss Operations Network based on RHQ 1.4.x yet, RHQ itself will be used instead.

  1. Download RHQ Server from SourceForge. This is the platform server, which will be responsible for storing, processing and presenting the data received by the agent(s).

  2. Unzip the distribution in a suitable place (i.e. in a directory not too deeply nested and with no spaces or non-ASCII characters in its name)

  3. This step is optional, if you're using Embedded H2 Database, you can skip to next

    Install a database like PostgreSQL (version 8.2.4 +, please choose C locale for initdb), create a database instance called 'rhq' in it and a user 'rhqadmin' that owns this 'rhq' database.

    create user rhqadmin password 'rhqadmin';
    
    	create database rhq owner rhqadmin;
  4. Eventually set RHQ_SERVER_JAVA_HOME or RHQ_SERVER_JAVA_EXE_FILE_PATH env variables appropriately. This is needed if your JAVA_HOME does not point to a java installation that is valid with JBoss Operations Network (e.g. JAVA 1.4); JBoss Operations Network requires JAVA 5+.

  5. In a terminal console, cd into the installation directory and start the Server:

    bin/rhq-server.[sh|bat] console
  6. After a few seconds, the messages on the console will stop. When this happens, point your browser to http://localhost:7080/ and run the installer:

    1. Click on Click here to continue the installation

    2. Choose your desired and installed database from the Database Type drop down list. If you don't want to install/use an external Database, choose H2 (embedded).

    3. Default settings should be fine to install the server correctly. To test the DB connection, please click Test Connection button.

      Warning

      If the Test Connection button was used, make sure that the Database Password field is still filled, as some browsers lose the data in there. Default password is rhqadmin.

    4. Review the seleceted settings, click Install Server! and wait for it to complete.

    5. Click on Done! Click here to get started! when the progress bar stops.

  7. Log in (default user/password are: rhqadmin/rhqadmin), it is time to download and install the Agent.

    The Agent is the component where our plugin will be running at. It is responsible for communicating with the managed resource (in this situation, the JAIN SLEE Server) to obtain vital data (eg: availability), metrics, operations execution, etc. and report back to the Server, who will process and display that data.

    To download it, follow these steps:

    1. Click on AdministrationDownload.

      Figure 2.1. Accessing Download Menu


    2. Click on Download Agent Installer and save it to where you wish to have it installed.

    3. In a second terminal console, cd into the directory containing the downloaded jar and install it:

      java -jar <agent-download.jar> --install[=<new agent dir>]

      The optional parameter, new agent dir indicates where the files will be installed, and defaults to the path where the jar is at.

    4. cd into the newly created rhq-agent directory and start the Agent by issuing:

      bin/rhq-agent.[sh|bat]
    5. Answer the questions asked by the Agent, if any. Default setting should be sufficient.

    6. There should be a console with a '> ' prompt. Don't close it, leave it running, it's the agent who will perform all the work.

For more detailed and up to date information, visit the JBoss Operations Network installation instructions.

JBoss Communications JAIN SLEE Plugin is the interface between JBoss Operations Network and JBoss Communications JAIN SLEE. It is responsible for gathering data from SLEE and transform it to JBoss Operations Network format. It is an agent plugin, since it runs on the agent side.

JBoss Communications JAIN SLEE Plugin, may be installed in two ways:

Using the GUI

In the JBoss Operations Network GUI, in the top menu, head to AdministrationSystem ConfigurationPlugins:

Figure 2.2. Accessing Plugins Menu


On the Agent Plugins tab (selected by default), on the bottom of the page, click Add..., browse to the JBoss Operations Network plugin JAR file and select it. It will be listed for upload, as it can be seen in the following figure:

Figure 2.3. Uploading Plugin


Finally, click the Upload button and the plugin will be deployed. Click Scan for Updates and it should be shown in the list as "Mobicents JSLEE Server 2.x".

If the agent is not running, start it and it will automatically download the new plugin. If it was already running, you should run the following command in it's console to download/update the plugin:

> plugins update
Copying the JAR File

The plugin can be deployed simply by copying it to the right folder, by following these steps:

  1. Stop the JBoss Operations Network server and agent if they are running.

  2. Copy the mobicents-slee-jopr-as-5-plugin-<version>.jar to the jopr-server/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-plugins/ directory, and it will be automatically deployed.

  3. Start the JBoss Operations Network server.

  4. Start the JBoss Operations Network agent.

After the plugin is installed, the server must be added to the managed resources. Choose OverviewAuto Discovery Queue:

Figure 2.4. Accessing Auto Discovery Queue Menu


Note

Please make sure that the JAIN SLEE Server is running at this time, otherwise it won't be shown under Auto Discovery.

JAIN SLEE Server not showing in Auto Discovery?

If the JAIN SLEE Server is running but not shown in the list, issue the following commands in th Jopr Agent console:

> plugins update
...

> discovery

Back in the web console, refresh the Auto Discovery view and it should be present!

Check the option referring to JAIN SLEE Server (as in the figure below), and click IMPORT button.

Figure 2.5. Selecting the server to be imported into JBoss Operations Network.


Now the server is being can be managed and monitored with JBoss Operations Network.

3.1. JBoss Operations Network JAIN SLEE Plugin Main View
3.2. Managing and Monitoring JAIN SLEE Container
3.2.1. View JAIN SLEE Server Version and State
3.2.2. Monitor JAIN SLEE Availability over time
3.2.3. View installed JAIN SLEE Components
3.2.4. Install/Uninstall JAIN SLEE Deployable Units
3.2.5. Start/Stop/Shutdown JBoss Communications JAIN SLEE Server
3.2.6. List All Activity Contexts
3.2.7. Query Activity Context Liveness
3.2.8. Change Container Logging Configuration
3.2.9. Edit Container Logging Configurations
3.2.10. View Event Router Statistics
3.2.11. Managing Congestion Control
3.3. Managing and Monitoring JAIN SLEE Deployable Units
3.3.1. View JAIN SLEE Deployable Unit Summary
3.3.2. Monitor JAIN SLEE DU Availability over time
3.3.3. List Component IDs
3.4. Managing and Monitoring JAIN SLEE Resource Adaptors
3.4.1. View JAIN SLEE Resource Adaptor Summary
3.4.2. Monitor JAIN SLEE RA Availability over time
3.4.3. Monitor JAIN SLEE RA Active Entities over time
3.4.4. View, Create and Remove Resource Adaptor Entities
3.4.5. Configure a Resource Adaptor
3.5. Managing and Monitoring JAIN SLEE Resource Adaptor Entities
3.5.1. View Resource Adaptor Entity Summary
3.5.2. Monitor JAIN SLEE RA Entity Availability over time
3.5.3. Monitor JAIN SLEE RA Entity Activities over time
3.5.4. View, Create and Remove Resource Adaptor Entity Links
3.5.5. Configure a Resource Adaptor Entity
3.5.6. Activate/Deactivate RA Entity
3.5.7. List Activity Context
3.6. Managing and Monitoring JAIN SLEE Resource Adaptor Entity Links
3.6.1. View Resource Adaptor Entity Link Summary
3.6.2. Monitor JAIN SLEE RA Entity Link Availability over time
3.6.3. List SBBs bound to RA Entity Link
3.7. Managing and Monitoring JAIN SLEE Service Building Blocks (SBBs)
3.7.1. View SBB Summary
3.7.2. Monitor JAIN SLEE SBB Availability over time
3.8. Managing and Monitoring JAIN SLEE Services
3.8.1. View Service Summary
3.8.2. Monitor JAIN SLEE Service Availability over time
3.8.3. Activate/Deactivate a JAIN SLEE Service
3.8.4. Retrieve SBB Entities
3.9. Monitoring JAIN SLEE Event Router Executors
3.9.1. View Event Router Executors Summary
3.9.2. Monitor Event Router Executors metrics

This section describes the main view of JBoss Operations Network JAIN SLEE Plugin.

In order to access this, go to the top menu and select ResourcesServers. A list should be presented, where JAIN SLEE server is present. Click it to access server details.

You should have something similar to the following figure:

Figure 3.1. JBoss Operations Network JAIN SLEE Plugin Main View.


As you can see in the left side menu you have the following components that can be managed by JBoss Operations Network:

  • Deployable Units

  • Resource Adaptors

  • SBBs

  • Services

Each one will be described and explained in it's own section.

Not a component of JAIN SLEE itself, but as a crucial part of it's core is the Event Router and it's Executors. This component is also described in it's own section.

By accessing the INVENTORY tab a table presenting the installed components and deployable units is shown.

Figure 3.4. JBoss Operations Network JAIN SLEE Plugin Inventory View.


Components deployed outside JBoss Operations Network

If components are installed outside JBoss Operations Network, after JBoss Operations Network Agent is started, the list of installed components will not be updated in a reasonable time.

For performance reasons, JBoss Operations Network servers childs (such as Deployable Units, Resource Adaptors, SBBs and Services in SLEE) are checked for changes every 24 hours.

To force a service discovery, there are two options:

  • In the JBoss Operations Network web app, right-click the root item (Platform) of the JAIN SLEE Server and select Execute OperationManual Autodiscovery. Select Yes in Detailed Discovery and run the discovery by clicking the SCHEDULE button.

  • In the JBoss Operations Network agent console, run a full discovery, by issuing the following command:

    > discovery -f

In the INVENTORY tab it's possible to Install/Uninstall JAIN SLEE Deployable Units.

In order to install a deployable unit, select DeployableUnits on the Create New: option box and click OK, the following page will be shown:

Figure 3.5. Installing a Deployable Unit with JBoss Operations Network JAIN SLEE Plugin.


Click the UPLOAD FILE... button, a new browser window will be shown to upload the JAIN SLEE Deployable Unit. Click Add..., select the Deployable Unit to be installed, click Upload to confirm and close this browser window.

Warning

You browser might ask you if you want to resend the information. Please accept it. Google Chrome browser may not support this operation!

Back on the main window for installing the DU, select either to do a persistent deploy (copy file to deploy folder) or not (simply call install on the DU).

Persistent vs JMX Deployment

When doing a persistent deployment, further installation actions are automatically performed by the JBoss Communications JAIN SLEE Deployer. If the DU is not deployed in a persistent way (JMX), component installation actions (such as Resource Adaptor entities creation, activation, Service activation) should be performed manually.

To confirm the deployment, click CREATE. The success of the operation should be displayed on the main view.

To uninstall a deployable unit, simply check the desired installed deployable unit on the INVENTORY tab and press DELETE. A confirmation dialog be displayed. The success of the operation will be shown on the main view.

Figure 3.6. Uninstalling a Deployable Unit with JBoss Operations Network JAIN SLEE Plugin.


Persistent vs JMX Undeployment

When undeploying a DU it's automatically detected either if it is to do a Persistent (file is deleted from the deploy folder!) or a non Persistent undeployment, where only the uninstall command is called on the DU, requiring prior uninstalling actions (eg: remove RA Links and Entities) to have already been performed.

Under the OPERATIONS tab, an operation for Changing the JAIN SLEE container state can be found: Change Slee State.

Clicking on the operation, a new pane opens so the parameters can be selected:

Figure 3.7. Changing JAIN SLEE State.


Change Slee State Parameters

Action (required)
  • start - Changes SLEE State to RUNNING state.

  • stop - Changes SLEE State to STOPPED state.

  • shutdown - Completely shutsdown SLEE. Requires to be in STOPPED state.

Note

As any operation on JBoss Operations Network, this operation can be scheduled for a later time, have a defined timeout and/or include additional notes.

Clicking on the SCHEDULE executes (if Immediately is selected) or schedules the operation. After being executed, it's shown in HISTORY, Completed Operations. Clicking on its name shows the result(s).

It is possible to customize the above mentioned logging configurations, or also the currently in use container logging configuration. To perform this action, two operations should be executed:

First, to retrieve the current logging configuration, the Get Logging Profile Configuration operation, in OPERATIONS tab should be used. One of the following options should be selected:

After being executed, it's shown in HISTORY, Completed Operations. Clicking on its name shows the result, which is the actual logging configuration.

The result of the operation should be copied into your favourite XML editor and edited as desired.

When the editing is completed, the Update Logging Profile Configuration operation should be used to update the logging configuration contents.

Select the desired configuration to be updated from the similar list as presented above, and paste the edited contents in the Contents field of the operation.

Clicking on the SCHEDULE executes (if Immediately is selected) or schedules the operation. After being executed, it's shown in HISTORY, Completed Operations. Clicking on its name shows the result(s).

In the INVENTORY tab it's possible to View, Create and Remove Resource Adaptor Entities.

Figure 3.14. Resource Adaptor Entities Listing


To create a RA Entity, select ResourceAdaptorEntity on the Create New: option box and click OK, the following page will be shown:

Figure 3.15. Create New Resource Adaptor Entity


Fill the Resource Name and Entity Name with the desired new entity name. If desired, provide extra properties for the entity in the Properties table by clicking Add New, which will present the following screen:

Figure 3.16. Add Property to New Resource Adaptor Entity


After adding the properties, click the SUBMIT button and the new RA Entity will be created. The success of the operation will be shown in the main view.

In the top, at the summary section, some details regarding the Resource Adaptor Entity can be seen, such as the Resource Adaptor it belongs to (in Description), the current State and its Parent Component (Resource Adaptor).

Figure 3.19. Resource Adaptor Entity Summary View.


Change State/Metrics update interval

By default, State property (as other metric values) is updated every 10 minutes. To set it to a shorter value (minimum: 30 seconds) go to SCHEDULES sub-menu under MONITOR tab, check the desired option(s), enter the desired amount of time in the Collection Interval textbox, select the units (seconds, minutes, hours) and click SET.

Figure 3.20. Change Collection Interval value for measurements.


In the INVENTORY tab it's possible to View, Create and Remove Resource Adaptor Entity Links.

Figure 3.22. Resource Adaptor Entity Links Listing


To create a RA Entity Link, select ResourceAdaptorEntityLink on the Create New: option box and click OK, the following page will be shown:

Figure 3.23. Create New Resource Adaptor Entity Link


Fill the Resource Name and Link Name with the desired new entity link name. Click the SUBMIT button and the new RA Entity will be created. The success of the operation will be shown in the main view.

Under the CONFIGURATION tab Resource Adaptor Entity properties can be defined, changed and or removed.

Figure 3.25. Configuring a Resource Adaptor Entity with JBoss Operations Network JAIN SLEE Plugin.


In the OPERATIONS tab, an operation to Activate/Deactivate the RA Entity is available, named Change Ra Entity State.

Clicking on the operation, a new pane opens so the parameters can be selected:

Figure 3.26. Changing the Resource Adaptor Entity State.


Change Ra Entity State Parameters

Action (required)
  • Activate - Activate the RA Entity.

  • Deactivate - Deactivate the RA Entity.

Note

As any operation on JBoss Operations Network, this operation can be scheduled for a later time, have a defined timeout and/or include additional notes.

Clicking on the SCHEDULE executes (if Immediately is selected) or schedules the operation. After being executed, it's shown in HISTORY, Completed Operations. Clicking on it shows the result(s).

In the top, at the summary section, some details regarding the SBB can be seen, such as the Component ID (in Description), the Version, the State Code (UP/DOWN) and its Parent Component (JSLEE Server).

Figure 3.31. SBB Summary View.


Change State/Metrics update interval

By default, State property (as other metric values) is updated every 10 minutes. To set it to a shorter value (minimum: 30 seconds) go to SCHEDULES sub-menu under MONITOR tab, check the desired option(s), enter the desired amount of time in the Collection Interval textbox, select the units (seconds, minutes, hours) and click SET.

Figure 3.32. Change Collection Interval value for measurements.


In the top, at the summary section, some details regarding the Service can be seen, such as the Component ID (in Description), the Version, the State and its Parent Component (JSLEE Server).

Figure 3.34. Service Summary View.


Change State/Metrics update interval

By default, State property (as other metric values) is updated every 10 minutes. To set it to a shorter value (minimum: 30 seconds) go to SCHEDULES sub-menu under MONITOR tab, check the desired option(s), enter the desired amount of time in the Collection Interval textbox, select the units (seconds, minutes, hours) and click SET.

Figure 3.35. Change Collection Interval value for measurements.


Under the OPERATIONS tab, an operation for changing the state of the service can be found: Change Service State.

Clicking on the operation, a new pane opens so the parameters can be selected:

Figure 3.37. Changing Service State.


Change Service State Parameters

Action (required)
  • Activate - Activate the Service.

  • Deactivate - Deactivate the Service.

Note

As any operation on JBoss Operations Network, this operation can be scheduled for a later time, have a defined timeout and/or include additional notes.

Clicking on the SCHEDULE executes (if Immediately is selected) or schedules the operation. After being executed, it's shown in HISTORY, Completed Operations. Clicking on it shows the result(s).

Event Router Executors are the heart of the JAIN SLEE Core, they are responsible for executing critical tasks for the container.

In order to have a better view over the JAIN SLEE container health, a few metrics are made available in this section.

By accessing the MONITOR tab it's possible to see a lot of metrics for each executor:

This metrics can also be seen in a table, in the TABLES sub-menu, in MONITOR tab.

It is possible to enable and disable metrics and also set the collection interval by accessing the SCHEDULES sub-menu, in MONITOR tab.

The JBoss Communications Platform is written in Java; therefore, before running any JBoss Communications server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run JBoss Communications must be version 5 or higher[1].

Should I Install the JRE or JDK?

Although you can run JBoss Communications servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBoss Communications-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.

Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?

Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:

  • Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.

  • 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.

  • Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

  • Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.

Downloading

You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.

The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running JBoss Communications in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

You can determine whether JAVA_HOME is set on your system by echoing it on the command line:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

You should also set this environment variable for any other users who will be running JBoss Communications (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 Using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.

As the root user, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

root@localhost ~]$ /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java


Enter to keep the current selection[+], or type selection number:

In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the one currently being used. As per alternatives' instructions, pressing Enter will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.

Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable, as the root user:

~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.



[1] At this point in time, it is possible to run most JBoss Communications servers, such as the JAIN SLEE, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the JBoss Communications web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.

The JBoss Communications Platform (JBoss Communications) is built on top of the JBoss Enterprise Application Platform. You do not need to set the JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The JBoss Communications Platform and most JBoss Communications servers are built on top of the JBoss Enterprise Application Platform (JBoss Enterprise Application Platform). When the JBoss Communications Platform or JBoss Communications servers are built from source, then JBOSS_HOME must be set, because the JBoss Communications files are installed into (or “over top of” if you prefer) a clean JBoss Enterprise Application Platform installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss Enterprise Application Platform installation into which you want it to install the JBoss Communications files.

This guide does not detail building the JBoss Communications Platform or any JBoss Communications servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the JBoss Communications ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

You DO NOT NEED to set JBOSS_HOME if...

You MUST set JBOSS_HOME if...

Naturally, if you installed the JBoss Communications Platform or one of the JBoss Communications server binary releases which do not bundle JBoss Enterprise Application Platform, yet requires it to run, then you should install before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure B.1. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the JBoss Communications installation. Note that if you are installing one of the standalone JBoss Communications servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.



[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

Revision History
Revision 1.0Thu Dec 31 2009Alexandre Mendonça
Creation of the JBoss Communications JBoss Operations Network JAIN SLEE Plugin User Guide.