Legrand / Raritan / Server Technology Xerus™ PDU JSON-RPC API
|
The classes implementing Xerus™ 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.
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:
rsp
response object is called: onSuccess
in case the JSON-RPC call was successful, or onFailure
when there was an error.rpcCtrl
object.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.
IDL enumerations are mapped to plain Java enums. Vectors are mapped to java.util.List, and maps are mapped to java.util.Map.
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.
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:
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.
The Bulk RPC interface allows combining multiple JSON-RPC method calls into a single bulk request that can be sent to the server and processed in a single HTTP request. When using the asynchronous API the Java client library automatically adds all submitted requests into a bulk request queue. A background thread combines pending requests into a bulk request and sends it to the device. As a result, submitted requests can be delayed by up to 250 Milliseconds while the bulk RPC thread waits for more requests to be queued.
To bypass the bulk request queue, add an rpcCtrl
parameter to the asynchronous method call. The following call will be immediately sent to the device as a dedicated JSON-RPC request:
Creates a new agent.
Parameters:
It is necessary to call setUsername()/setPassword() or setToken() before the first request.
This method sets the username for HTTP basic authentication.
Parameters:
This method sets the password for HTTP basic authentication.
Parameters:
This method enables and disables HTTP authentication using a session token. A session token can be obtained by calling the newSession method of the session.SessionManager interface.
Calling setToken(token) with a string variable which contains the token will enable token-based authentication.
When calling setToken(null), token-based authentication is disabled.
Parameters: