The Rhino remote library contains a class that represents a connection to Rhino (RhinoConnection). Below are descriptions of various ways of getting and configuring an instance of this class, including:

RhinoConnectionFactory

Use the RhinoConnectionFactory class to create connections to Rhino. RhinoConnectionFactory has connect methods that let you specify connection parameters many ways. The RhinoConnectionFactory connect methods return objects that implement RhinoConnection. See the Rhino Remote API for details.

/**
 * Factory class to create connections to Rhino.
 * @author Open Cloud
 */
public class RhinoConnectionFactory {
  public static RhinoConnection connect(File propertiesFile)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(Properties properties)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(String host, int port, String username, String password)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(String serverList, String username, String password)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(String[] servers, String username, String password)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(String host, int port, String username, String password, Properties sslProps)
         throws ConnectionException { /* ... */ }

  public static RhinoConnection connect(String[] servers, String username, String password, Properties sslProps)
         throws ConnectionException { /* ... */ }
}

RhinoConnection

The RhinoConnection class represents a connection from an external OA&M tool to Rhino. RhinoConnection extends MBeanServerConnection so you can use it anywhere in the JMX Remote API that uses MBeanServerConnection. Other Rhino remote library classes can use MBeanServerConnection objects from other sources (such as a local MBeanServer) however such objects do not have the additional RhinoConnection features.

Tip You create a RhinoConnection with a list of servers. The OA&M client tries each server in the list — in order — as it connects to Rhino. A connection-failure exception is thrown if no connection can be made with any server in the list. If a connection fails whilst executing a command, the OA&M client tries the next server on the list and executes the pending command. 
/**
 * Rhino-specific connection interface.
 * @author Metaswitch
 */
public interface RhinoConnection extends MBeanServerConnection {
  /**
   * Try to connect this connection.
   * @throws ConnectionException if the connection attempt failed
   */
  void connect() throws ConnectionException;

  /**
   * Disconnect this connection.
   */
  void disconnect();

  /**
   * Disconnect then connect this connection.
   * @throws ConnectionException if the connection attempt failed
   */
  void reconnect() throws ConnectionException;

  /**
   * Test this connection by invoking a basic MBean operation.  If the test fails, an reconnect
   * attempt will betriggered automatically.
   * @throws ConnectionException if the test and the attempt to automatically reconnect failed
   */
  void testConnection() throws ConnectionException;

  /**
   * Get the JMXConnector associated with this MBeanServer connection.
   * @return a JMXConnector instance
   */
  JMXConnector getJmxConnector();

  /**
   * Whether or not this connection is connected.
   * @return state of the connection
   */
  boolean getConnectedState();

  /**
   * The host name of the current connection.  Useful if this connection is configured to try
   * multiple hosts.
   * @return host where this connection object is currently connected to Rhino
   */
  String getServerHost();

  /**
   * The port of the current connection.  Useful if this connection is configured to try
   * multiple hosts.
   * @return port where this connection object is currently connected to Rhino
   */
  int getServerPort();

  /**
   * The node ID of the server the current connection is to.  Useful if this connection is
   * configured to try multiple hosts.
   * @return node id of Rhino where this connection object is currently connected to
   */
  int getServerNodeId();

  /**
   * Tell this connection to only allow particular connection contexts.
   * See {@link com.opencloud.slee.remote.ExecutionContext} for more details.
   * @param ctx the context to allow
   */
  void setAllowedExecutionContext(ExecutionContext ctx);
}

ExecutionContext

Occasionally you may want control over whether or not a particular operation or set of operations can failover to another node. You can do this using the ExecutionContext mechanism. (See RhinoConnection.setAllowedExecutionContext(ExecutionContext) and ExecutionContext.)

/**
 * Defines execution contexts for MBean operations.  An execution context can be used to control the
 * behaviour during connection failover.
 * <p/>
 * The execution context can be set at any time on a {@link com.opencloud.slee.remote.RhinoConnection}
 * using {@link com.opencloud.slee.remote.RhinoConnection#setAllowedExecutionContext(ExecutionContext)}
 * and will remain in force until it is reset.
 * <p/>
 * The default value is CLUSTER.
 * @author Metaswitch
 */
public enum ExecutionContext {
  /**
   * Allow commands to execute only on the current connection.  If the connection fails, an exception
   * will be thrown.
   */
  CONNECTION,

  /**
   * Allow commands to executed on any connection, as long as a new connection is made to the same
   * node as the previous command was executed on.  <br/>
   * If a new connection is made to a different node, then an exception will be thrown.
   */
  NODE,

  /**
   * Allow commands to executed on any connection and on any node.  An exception will only be thrown
   * if the client cannot connect to any node.
   */
  CLUSTER
}

Configuring an SSL connection

If Rhino is configured to require SSL connections to the JMX Remote interface (the default setting), then the SSL connection factory that the JMX client uses will need a keystore, a trust store, and a password for each. You can provide these two ways:

  1. Getting system properties when starting the JVM that is running the JMX client:

  -Djavax.net.ssl.keyStore=$RHINO_CLIENT_HOME/rhino-public.keystore -Djavax.net.ssl.keyStorePassword=xxxxxxxx \
  -Djavax.net.ssl.trustStore=$RHINO_CLIENT_HOME/rhino-public.keystore -Djavax.net.ssl.trustStorePassword=xxxxxxxx

  1. Putting these settings into a properties file or properties object, and using one of the connection factory methods that takes such a parameter. For example, you could have a properties file containing the following lines:

javax.net.ssl.trustStore=rhino-public.keystore
javax.net.ssl.trustStorePassword=xxxxxxxx
javax.net.ssl.keyStore=rhino-public.keystore
javax.net.ssl.keyStorePassword=xxxxxxxx

and then create a connection as follows:

File propertiesFile = new File("remote.properties");
MBeanServerConnection connection = RhinoConnectionFactory.connect(propertiesFile);

Connection logging

Exceptions that the connection factory methods throw generally contain sufficient detail to determine the cause of any connection problems.

If you need more fine-grained tracing, you can provide a PrintWriter to the connection factory, so that all connection objects write trace messages to it while trying to connect.

Tip For examples of how to write connection trace messages to stdout or a Log4J logger, see RhinoConnectionFactory.setLogWriter(PrintWriter).

Platform MBean Server

Occasionally it may be necessary for a deployed application to access MBeans to obtain information usually used by management clients. For example, a rate limiting plugin may need to combine statistics from a resource adaptor and the JVM to determine if an incoming message should be rejected. Such applications can use the platform MBean server to access MBeans in Rhino. A component that accesses MBeans will typically be a library or resource adaptor. SBBs should rarely need to access the MBeans and profiles should never do so.

StatsManagementMBean statsMBean;
AccessController.doPriviliged(() -> {
    try {
        statsMBean = JMX.newMBeanProxy(ManagementFactory.getPlatformMBeanServer(), new ObjectName(StatsManagementMBean.OBJECT_NAME), StatsManagementMBean.class, true);
    }
    catch (MalformedObjectNameException e) {
        ...
    }
    try {
        long sessionId = 0;
        sessionId = statsMBean.createSession();
        statsMBean.subscribeCounter(sessionId, 101, "JVM.Thread", "threadCount", SubscriptionMode.SIMPLE_GAUGE);
        statsMBean.startCollecting(sessionId, 1000);
    }
    catch (ManagementException | ... e) {
        ...
    }
});

The library or resource adaptor will also need to be granted security permissions for the MBean operations that it will invoke.

grant {
    permission javax.management.MBeanPermission "com.opencloud.rhino.monitoring.stats.ext.StatsManagementMBean#*", "invoke";
}
Note Unless the operations are only possible via MBeans the SLEE Facility APIs should be used. MBean access is platform specific, more complex, and does not provide the normal transaction semantics that the Facility APIs offer.
Previous page Next page
Rhino Version 3.1