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 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|
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.
|RMI Server Name||RMI Communication Port|
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.
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:
The error access#mxauthenabled means Application Server Security ("LDAP") is enabled.
Instructions for deploying rmireg.war:
06 May 2022