Java RMI clients

A Java Remote Invocation (RMI) client can call the methods of the SA API from a server that has network access to the SA core. The server running the client does not have to be an SA core or managed server. When it connects to the core, the client specifies an SA user name and password, much like an end user logging on with the SA Client. The group that the user belongs to determines which SA resources and tasks are available to the client.

This topic is intended for software developers who are familiar with SA fundamentals and the Java programming language.

Setup for Java RMI clients

Before developing Java RMI clients for the SA API, perform the following steps:

1. Install an SA core in a development environment. Do not use a production core.
2. Obtain a development server where you will build and run the Java RMI client.
3. On the development server, install the Java SE 7 SDK.
4. Verify that the development server has a network connection to the SA core server that runs the OCC component.
5. Download the opswclient.jar file from the SA core server to your development server. The opswclient.jar file contains the Java RMI stubs for the SA API. You include the opswclient.jar in the classpath option when compiling and running Java RMI clients.
6. To download opswclient.jar do one of the following:
   1. Specify the following URL, where occ_host is the core server running the OCC component:
      
      https://occ_host/twister/opswclient.jar
   2. Go to the following directory: /opt/opsware/twist/extlib/client.

You also need the spinclient-latest.jar and the opsware_common-latest.jar files. These files can be obtained from a running SA Core in:

/opt/opsware/twist/lib/

You must also add these .jar files to the classpath parameter when compiling and running these examples.

Sample Java RMI

This section describes a simple Java RMI client named GetServerInfo.

The GetServerInfo client searches for managed servers by full or partial host name, which you specify as a command-line argument. For each managed server found, the client prints out the server’s name, management IP address, and OS version.

The GetServerInfo client performs the following steps:

1. Connects to SA:
   // Set the JNDI provider
client.setJNDIProvider( "https" , host , ( short ) 1032 , null, newString[] { OPSWARE_CA_CRT_PATH } , null ) ;
// Force a reconnection
client.getContext( true ) ;
// Set and authenticate the user
client.setAPIUser( new APIUserImpl(username , password)) ;
2. Gets a reference to the ServerService interface:
   serverSvc = (ServerService)OpswareClient.getService
(ServerService.class);
3. Invokes methods on ServerService:
   ServerRef[] serverRefs = serverSvc.findServerRefs(filter);
. . .
ServerVO[] serverVOs = serverSvc.getServerVOs(serverRefs);
. . .
System.out.println(serverVOs[i].getName());

Compiling and running the GetServerInfo example

Before compiling and running the example, perform the following tasks:

1. Obtain the opsware_common-latest.jar, spinclient-latest.jar andopswclient.jar files, as described in Setup for Java RMI clients.
2. Download the ZIP file that contains the demo program GetServerInfo.java file. For information about downloading the demo file, see Platform Developer Guide examples.
3. To compile the client, specify the opsware_common-latest.jar, spinclient-latest.jar and opswclient.jar files for the classpath parameter:
   
   javac -classpath :path/opswclient.jar:path/opsware_common-latest.jar:path/spinclient-latest.jar GetServerInfo.java
4. To run the client, enter the following command, where target is the full or partial name of a server managed by SA. Note: the Java classpath separator for windows is ";".
   java -classpath .:path/opswclient.jar:path/opsware_common-latest.jar:path/spinclient-latest.jar \GetServerInfo [options]    target

   In the following example, GetServerInfo connects to SA on host c44 (where the OCC core component runs) and port 443. The program displays information for managed servers with hostnames that contain the string opsw.
   
   java -classpath .:/home/jdoe/opswclient.jar:/home/jdoe/opsware_common-latest.jar:/home/jdoe/spinclient-latest.jar \GetServerInfo --host c44.dev.example.com --port 443 opsw
5. Respond to the prompts for the SA user name and password. The SA user must have read permissions for the servers that match the target  specified on the command line.

Possible issue on Windows

The SA Java RMI Client, opswclient.jar, might not work on Windows if your SA certificates are using an SHA-224 signature algorithm. This is caused by the following JDK change: Remove SHA224 from the default support list if SunMSCAPI enabled.
Workaround: Disable the SunMSCAPI security provider. This restores support for SHA-224 in the JDK. To disable the SunMSCAPI provider either:

• edit <JRE_HOME>/lib/security/java.security and comment out the line that defines the SunMSCAPI provider OR
• disable the SunMSCAPI provider programatically by using the java.security.Security.removeProvider() method.