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 IBM Maximo Asset Management and IBM Control Desk. This document explains the Maximo implementation for RMI.

Resolving The Problem

Remote Method Invocation is deprecated for the Maximo Application Suite Manage component versions 8.0 and higher.
This document applies only to Maximo and Control Desk versions 7.1.x, 7.5.x, 7.6.x, and 7.6.1.x.



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 by modifying the mxe.registry.port System Property. In over simplified terms, the RMI registry can be viewed as a two-column table as shown here:

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. Maximo attempts to register itself (under RMI Server Name) in 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 attempts to create the RMI registry on port 1099, but the port number may be changed. When running Maximo in clustered environments, deploy the rmireg.war file. The RMI Registry is a separate server, and creates the registry independent of any Maximo running servers. Installing and using the RMI Registry application prevents loss of RMI communications.


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 that uses the same EAR file is automatically assigned 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 are used. Example: If the external Application refers to MXServer and port 1099, in the above example, only port 10345 is available because other cluster members have a different names than MXServer. See Using -Dmxe.name to set the Server Name at run time.


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 unique name and associated port registered in the RMI Registry. Calls from remote systems must specify the specific name and the registry port in order to look up the RMI communications port. In the example, if the server MXServer does not exist in the registry (stopped or failed), the look-up fails. Once the Maximo server is restarted, it registers itself again and RMI communications can resume.


Once the RMI registry exists, Maximo registers itself in the registry. By default, Maximo binds 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 0, and Maximo selects the random high port on its own. If a specific port is required for RMI/JRMP communications, administrators can change the mxe.rmi.port System Property to reflect the correct port number. This may be valuable if specific external applications must always use the same port to invoke RMI, and also 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. Installing Maximo and automatically configuring WebSphere Application Server, the installer uses this value tp 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 override the value in the database.
mxe.registry.port
mxe.rmi.port
mxe.rmi.enabled


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.

Under certain circumstances. using a tool that connects to Maximo natively with a username and password may throw an error:

psdi.util.MXAccessException: access#mxauthenabled

The error access#mxauthenabled means Application Server Security ("LDAP") is enabled.
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 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

[{"Type":"MASTER","Line of Business":{"code":"LOB59","label":"Sustainability Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSLKT6","label":"IBM Maximo Asset Management"},"ARM Category":[{"code":"a8m50000000CbJpAAK","label":"Mobility->System Related"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.6.0;7.6.1"},{"Type":"MASTER","Line of Business":{"code":"LOB59","label":"Sustainability Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSWT9A","label":"IBM Control Desk"},"ARM Category":[{"code":"a8m500000008b3TAAQ","label":"Miscellaneous Category (Portal, UI, Maximo, Install)"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.6.0;7.6.1"}]

Historical Number

M05006

Product Synonym

Maximo

Document Information

Modified date:
17 June 2022

UID

swg21262022