Understanding the Maximo Implementation of Java Remote Method Invocation

Technote (troubleshooting)


Problem(Abstract)

RMI (Remote Method Invocation) is a Java protocol used to allow external applications to communicate with Maximo. This document explains the Maximo implementation for RMI.

Resolving the problem

What is RMI and how does it work?
RMI Definitions

RMI stands for “Remote Method Invocation.” Java developers created this standardized system for using Java objects in a separate memory area from the one calling the remote object. Separate memory areas can reside on the same physical system or on different systems connected by a network.

RMI uses JRMP (Java Remote Method Protocol) to travel over networks to the remote server being called.

An RMI Registry is an area in memory that maintains the RMI address information of a Java object server. By default, the RMI registry is created on port 1099. This port can be changed using the mxe.registry.port property. In over simplified terms, the RMI registry can be viewed as a two column table as shown below:

RMI Server Name RMI Communication Port
MXServer 10345
MXServer2 1244
MXServer3 1166

When a new application registers itself in the registry, it registers the name used to reference the server and the port the server is bound to. More than one RMI registry can reside in memory. Each registry has a designated TCP/IP port for access.

Maximo implementation of RMI

Maximo is a collection of Java and web related objects archived in an EAR (Enterprise Archive) file. When the EAR file is deployed and started, the Java objects search for an RMI registry in the current memory area and it will attempt to register itself (under RMI Server Name) in a registry on the registry found on the mxe.registry.port specified in the properties (default 1099). If no RMI registry is found on the mxe.registry.port, the first Maximo application to start specifying that port will create the registry. (Note: the registry is then tied to that first instance of Maximo). By default, Maximo will attempt to create the RMI registry on port 1099 but this may be changed. Maximo 6 and Maximo 7 clustered environments should deploy the rmireg.war file. This is deployed as a separate server and creates the registry independent of any Maximo servers that remains in a running status regardless of any one cluster member. This can prevent loss of RMI communications if the first Maximo server to start in a cluster fails.

The RMI registry port is controlled by the mxe.registry.port property in the MXServer.properties file of Maximo 5, the maximo.properties file of Maximo 6, or the System Properties application on Maximo 7. By default, there is no mxe.registry.port property in properties files. This property must be added if the registry port needs to be controlled or modified to use a port different than 1099.

The RMI Server Name is controlled by the mxe.name property in the MXServer.properties file of Maximo 5, the maximo.properties file of Maximo 6, or the System Properties application of Maximo 7. Once the RMI registry exists, the mxe.name property is used to register the server in the RMI registry. If multiple unique Maximo applications reside on the same server and use the same mxe.registry.port, they must have unique mxe.name properties or remote methods that call them will not be able to locate the servers. If Maximo is deployed to a cluster, each server in the cluster using the same EAR file will automatically be given a unique name.

Example:

RMI Server Name RMI Communication Port
MXServer 10345
MXServerC1 1244
MXServerC2 1166

Note: Since external applications refer to a specific name to find the RMI port, only that servername and port is used. Example: If the external Application refers to MXServer and port 1099, in the above example, it will only find port 10345, because other cluster members have a different name than MXServer. This is why deploying the rmireg.war is important in clustered environments.

Note: RMI communications cannot be made fault tolerant or load balanced without multiple physical servers and a load balancer to redirect RMI requests. Each Maximo server has a specific, unique name and an associated port which are registered in the RMI Registry. Calls from remote systems must specify the specific name and the registry port in order to look up he RMI communications port. In the example, if the server MXServer does not exist in the registry (stopped or failed), the look-up will fail. Once the Maximo server is restarted, it will register itself again and RMI communications can resume.

Once the RMI registry exists, Maximo will register itself in the registry and, by default, bind itself to a random available high port (a port number higher than 1024). This port is also stored in the RMI registry. The port number used by Maximo to bind RMI/JRMP communications is controlled by the mxe.rmi.port property in the MXServer.properties file of Maximo 5, the maximo.properties file of Maximo 6 or the system properties application of Maximo 7. By default, the mxe.rmi.port is set to zero (0) and Maximo will determine the random high port on it’s own. If a specific port is required for RMI/JRMP communications, administrators may change the mxe.rmi.port property to reflect the correct port number. This may be valuable if specific external applications must always use the same port to invoke RMI. This may also be important if communications through a firewall are required. The firewall can be configured to open a specific port for RMI communications.

Note: The RMI registry name is case sensitive. Any remote calls or configuration files referring to the RMI Server Name must match the name exactly or the RMI call will fail.

RMI Registry Port and Name References

The Maximo application uses several names to refer to the RMI registry information. Each is in a different part of the application.

Maximo 5.2 Name References
(all of these are case sensitive and must match each other exactly)

MXServer.properties mxe.name
Control Center / MAXIMO.INI [AppServer]

Maximo 5.2 Port References

MXServer.properties mxe.registry.port – This is where the RMI registry is stored
MXServer.properties mxe.rmi.port – This is the port used by RMI communications

Maximo 6 Name References
(all of these are case sensitive and must match each other exactly)

maximo.properties mxe.name
Maximo installation Screen Maximo Server Name
(Encyclopedia) Installation Scree Maximo Server Name
rsse_maximo.properties maximo.servername

Maximo 6 Port References

maximo.properties mxe.registry.port – This is where the RMI registry is stored
maximo.properties mxe.rmi.port – This is the port used by RMI communications
rsse_maximo.properties maximo.port is the same as mxe.registry.port in the maximo.properties file

Maximo 7 Port References

maximo.properties mxe.registry.port – This is where the RMI registry is stored
maximo.properties mxe.rmi.port – This is the port used by RMI communications
maximo.properties mxe.rmi.enabled - Indicates whether RMI is enabled (1 is enabled, 0 is disabled). To disable RMI, add this property to maximo.properties and rebuild and redeploy the maximo.ear. By default, this property has a value of 1. It is only set to 0 in when Maximo Base Services is used in Tivoli Provisioning Manager. For more information, see this Knowledge Center article.
install.properties WAS.RMIConnectorPort - WebSphere RMI connector port. When installing Maximo and automatically configuring WebSphere Application Server, the installer uses this value populate mxe.rmi.port. Otherwise it has a value of NULL and is not used.
System Properties application
(MAXPROP and MAXPROPVALUE
table)
mxe.registry.bindcount - Represents the retry count for the system Remote Method Invocation (RMI) registry binding. When the system server starts and it runs into registry bind failures, the server tries to start for the number of attempts specified in this property.
System Properties application mxe.registry.port - see above
System Properties application mxe.rmi.port - see above
System Properties application mxe.rmi.enabled - see above
System Properties application WAS.RMIConnectorPort - see above

A typical maximo.properties or MXServer.properties file might look as shown below. Note that no mxe.registry.port property appears. This property would need to be added if the registry cannot reside on the default 1099 port. If port 1099 is not available and Maximo has not been configured to use a different port, the application will not start. There have been some reports of systems not releasing the port in a timely manner when the application is restarted thus preventing a successful restart. These have been resolved by clearing the port or specifying a different port (other than 1099) in the mxe.registry.port property.

// --------------------------------------------------------------------
// MXServer.properties : Configuration file for MXServer
// --------------------------------------------------------------------

// Name to bind the MXServer server object to in the RMI registry
     mxe.name= MXServer

// Name of the machine and port hosting MXServer
     mxe.hostname=localhost:7001

// Port used by RMI for communication, if left at 0, RMI will use any
// available port on the system.  To use a specific port, set this
// parameter to an available port number.
     mxe.rmi.port= 0

Also see documents on deploying rmireg.war:

Deploying the RMI Registry (rmireg.war) in WebSphere 6.0 and 6.1
Deploying the RMI Registry (rmireg.war) in WebSphere 7.0
Deploying the RMI Registry (rmireg.war) in WebLogic 8.1
Deploying the RMI Registry (rmireg.war) in WebLogic 9.2


Cross reference information
Segment Product Component Platform Version Edition
Systems and Asset Management Tivoli Asset Management for IT
Systems and Asset Management Tivoli Change and Configuration Management Database
Systems and Asset Management IBM Maximo Asset Management Essentials
Systems and Asset Management Tivoli Service Request Manager
Systems and Asset Management Tivoli Service Automation Manager
Systems and Asset Management IBM SmartCloud Control Desk

Historical Number

M05006

Product Alias/Synonym

Maximo

Rate this page:

(0 users)Average rating

Document information


More support for:

IBM Maximo Asset Management

Software version:

5.1, 5.2, 6.0, 6.1, 6.2, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 7.1, 7.1.1, 7.2, 7.5

Operating system(s):

Platform Independent

Reference #:

1262022

Modified date:

2014-11-06

Translate my page

Machine Translation

Content navigation