IBM Support

Understanding the Maximo Implementation of Java Remote Method Invocation (RMI)

Troubleshooting


Problem

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 (Java) Remote Method Invocation. Java developers created this standard for calling Java objects located in a separate memory area (virtual machine) from the one calling the remote object. These separate memory areas can reside on the same physical system or on different systems connected by a network.

RMI uses Java Remote Method Protocol (JRMP ) 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. When running Maximo in clustered environments, 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 set mxe.registry.port property.


The RMI Server Name is set in the System Properties application mxe.name property.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.

Examples:

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. See Using -Dmxe.name to set the Server Name at runtime.


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 RMI Communication Port used by Maximo to bind RMI/JRMP communications in the System Properties application mxe.rmi.port property. By default, the mxe.rmi.port is set to zero (0) and Maximo will determine the random high port on its 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.

Port and Name References

System Properties application

MAXPROP and MAXPROPVALUE
tables
mxe.registry.port – The port where the RMI registry is stored
mxe.rmi.port – The port used by RMI communications
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..
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 or 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 or maximo.properties
If you add any of these parameters to maximo.properties, they will override the value in the database.
mxe.registry.port - see above.
mxe.rmi.port - see above.
mxe.rmi.enabled - see above.


Note: Connecting to Maximo with RMI is possible with third-party applications and Maximo internal applications such as CheckMXServer by supplying a username and password to authenticate the user against Maximo internal ("native") authentication. When Application Server Security is enabled, connecting with RMI by supplying a username and password is not supported, because authentication is done through the Application Server (WebSphere or WebLogic), not Maximo.

When running a tool that connects to Maximo natively with a a username and password, an error may be logged:

psdi.util.MXAccessException: access#mxauthenabled
While it is possible to use RMI to connect to Maximo when Application Server Security is enabled, IBM does not provide support for configuring this connection method. IBM recommends using the Maximo Integration Framework (MIF) to connect to Maximo. The MIF uses Maximo MBOs to authenticate incoming connections.

Instructions for deploying rmireg.war:

Deploying the RMI Registry (rmireg.war) in WebSphere 8.5.5 and 9.0

Deploying the RMI Registry (rmireg.war) in WebLogic 12c


Cross reference information
Product Component Platform Version Edition
Control Desk

Historical Number

M05006

Product Alias/Synonym

Maximo

Document information

More support for: Maximo Asset Management

Component: Not Applicable

Software version: All Versions

Operating system(s): Platform Independent

Reference #: 1262022

Modified date: 15 May 2019