Examples
Getting device information:
import com.raritan.idl.pdumodel.Pdu_2_0_0;
import com.raritan.json_rpc.Agent;
import com.raritan.json_rpc.pdumodel.Pdu_2_0_0_Proxy;
[...]
Agent agent = new Agent("https://my-px.raritan.com");
agent.setUsername("agent");
agent.setPassword("password");
Pdu_2_0_0 pdu = new Pdu_2_0_0_Proxy(agent, "/model/pdu/0");
Pdu_2_0_0.MetaData metadata = pdu.getMetaData()._ret_;
System.out.println("Firmware version: " + metadata.fwRevision);
Power-cycling an outlet:
import java.util.List;
import com.raritan.idl.pdumodel.Outlet;
import com.raritan.idl.pdumodel.Pdu_2_0_0;
import com.raritan.json_rpc.Agent;
import com.raritan.json_rpc.pdumodel.Pdu_2_0_0_Proxy;
[...]
Agent agent = new Agent("https://my-px.raritan.com");
agent.setUsername("agent");
agent.setPassword("password");
Pdu_2_0_0 pdu = new Pdu_2_0_0_Proxy(agent, "/model/pdu/0");
List<Outlet_1_3_3> outlets = pdu.getOutlets()._ret_;
outlets.get(0).cyclePowerState();
IDL-to-Java Mapping
Modules and Java Packages
The classes implementing Raritan JSON-RPC communication are contained in two separate Java package hierarchy: The namespace com.raritan.idl
contains Java interface declarations for all IDL interfaces, and Java equivalents for named IDL data types like structures or enumerations. The com.raritan.json_rpc
namespace contains proxy classes that implement those interfaces and relay any method calls to a remote device using JSON-RPC.
Interfaces and Methods
IDL interfaces are mapped to Java interfaces and implemented by proxy classes. Each method defined in IDL maps to three overloaded methods in the corresponding Java interface:
public class CreateAccountResult {
public int _ret_;
}
CreateAccountResult createAccount(String username, String password) throws Exception;
AsyncRequest createAccount(String username, String password,
AsyncRpcResponse<CreateAccountResult> rsp);
AsyncRequest createAccount(String username, String password,
AsyncRpcResponse<CreateAccountResult> rsp,
RpcCtrl rpcCtrl);
- A synchronous variant which takes the same arguments as the IDL method declaration. This method will block the calling thread until the JSON-RPC communication is finished and the result is available. If the method has a return value or out-parameters those will be included in the result object returned by the method.
This version of the method is the only one that may throw a Java exception in case of communication problems or an error response from the server.
- An asynchronous variant. This version of the method returns immediately without performing any network communication. Instead, the request is processed by a background thread. When it is finished, a method of the passed
rsp
response object is called: onSuccess
in case the JSON-RPC call was successful, or onFailure
when there was an error.
- An asynchronous variant with custom options. By default, the background thread can combine multiple method calls into a single HTTP request. If that's not desired it can be suppressed by setting an option in the passed
rpcCtrl
object.
Structures
IDL structures are mapped to Java classes with public members for each structure element. Those classes feature a default constructor and implement the Cloneable
interface.
Enumerations, Vectors and Maps
IDL enumerations are mapped to plain Java enums. Vectors are mapped to java.util.List, and maps are mapped to java.util.Map.
Exceptions
Exceptional error conditions may occur because of communication problems or because of system errors that occur on the server while processing a request. Those "unexpected" error conditions are not a part of the regular IDL signature, so they are handled by using one of the following exceptions:
raritan.rpc.json_rpc.RpcRequestException
This exception is raised in case of a communication failure. Typical examples for this include an unreachable server, an authentication problem or a wrong resource ID.
raritan.rpc.json_rpc.RpcErrorException
This exception is raised in case the server responded with a JSON-RPC error object instead of the expected method result. This can indicate either an internal problem in the server or a malformed request from the client.
raritan.rpc.json_rpc.RpcFormatException
This exception is raised in case the JSON-RPC response from the server cannot be decoded. This may indicate an interface version mismatch between client and server.
For synchronous method invocations the exceptions are thrown and can be intercepted with a try/catch block. For asynchronous method invocations the exception object is passed to the onFailure
method of the result object.
Interface Versions
The Java bindings contain interfaces and proxies for all IDL interface versions that have been released up to the firmware release the bindings were generated for. Using those classes client programs can be written to be compatible with any firmware version up until the most recent release.
IDL interface names like pdumodel.Pdu_3_1_0
contain three separate version numbers:
- A major version. This number is incremented when the interface has changed in an incompatible way. A client program that is written to support Pdu_2_* may or may not work with a device that implements the Pdu_3_* interface.
- The middle number is the sub-major version. This number is incremented in case a referenced interface is changed in an incompatible way. A client can safely ignore the middle version number as long as it uses only methods of the interface itself. However, it should verify the type and version of any objects returned from an interface with a different sub-major number before using them.
- The last number, the minor version, is incremented on backward- compatible interface changes, e.g. when a new method was introduced. A client that was written to support the
Pdu_3_1_0
interface is guaranteed to work with Pdu_3_1_1
or later without modification. Object references returned from an interface with compatible changes can be safely used without additional compatibility checks.
See the DumpPdu.java program distributed with this documentation for an example how to write a client program that supports multiple interface versions.