Package com.opencloud.slee.remote

Create remote management connections to Rhino and proxies for MBeans on the server.

See: Description

Package com.opencloud.slee.remote Description

Create remote management connections to Rhino and proxies for MBeans on the server.

Connecting to Rhino

Rhino Connection Factory

The RhinoConnectionFactory class is used to create connections to Rhino. The class has connect methods that allow connection parameters to be specified in several different ways (see the class documentation for more details).

Rhino Connections

The objects returned by the connection factory implement RhinoConnection, which is a subinterface of MBeanServerConnection. The connection objects can therefore be used directly in other JMX Remote API calls. Also, MBeanServerConnection objects obtained via other means (e.g., from a local MBeanServer) can be used by the rest of the Rhino Remote library classes (but will obviously not have the extra features described below).

If multiple servers are provided when creating a connection, they will be tried in the order given. Exceptions indicating a connection failure are only thrown when all servers are unreachable. If a previously active connection is found to have failed when attempting to execute a command, the other servers provided will be tried. The pending command will be executed if a connection can be made.

Execution Contexts

In some cases, it may be desirable to control whether or not a particular operation or set of operations is allowed to failover to another node. This control is available via the Execution Context mechanism. See RhinoConnection.setAllowedExecutionContext(ExecutionContext) and ExecutionContext.

SSL Configuration

If Rhino is configured to require SSL connections to the JMX-Remote interface (the default setting) then the SSL connection factory used by the JMX client must be provided with a keystore and a trust store, and a password for each. There are two ways of providing these settings. One is by setting 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
The other is to put these settings into a properties file or properties object, and use one of the connection factory methods that takes such a parameter. For example, in a properties file you could have 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 thrown by the connection factory methods generally will contain sufficient detail to determine the cause of any connection problems. If more fine-grained tracing is needed, then a PrintWriter can be provided to the connection factory, and all connection objects will write trace messages to it while trying to connect.

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

Retrieving JSLEE MBean Proxies

The SleeManagement class is used to create proxy instances for SLEE-standard MBeans with well-known Object Names. An MBeanServerConnection must be obtained first, then one of the methods on this class can be called. 

   MBeanServerConnection connection = RhinoConnectionFactory.connect( ... );
   SleeManagementMBean sleeManagement = SleeManagement.getSleeManagementMBean(connection);

Retrieving Rhino MBean Proxies

The RhinoManagement class is used to create proxy instances for Rhino-specific MBeans. An MBeanServerConnection must be obtained first, then one of the methods on this class can be called. 

   MBeanServerConnection connection = RhinoConnectionFactory.connect( ... );
   RhinoHousekeepingMBean rhinoHousekeeping = RhinoManagement.getRhinoHousekeepingMBean(connection);

Working with Profiles

The RemoteProfiles class contains a number of utility methods to greatly ease working with SLEE profile management operations. There are methods to: get proxies to ProfileMBeans; create and commit a new profile; create an uncommitted profile that can have its attributes set before it is committed; get attribute names, values and types. These methods are in addition to the standard management operations available on ProfileProvisioningMBean.

Creating a Profile Table

This can be done using the ProfileProvisioningMBean, but RemoteProfiles has a utility method to check if a profile table exists: 

    ProfileSpecificationID profileSpecificationID = new ProfileSpecificationID("AddressProfileSpec", "javax.slee", "1.0");
    if(RemoteProfiles.profileTableExists(connection, "TestProfileTable")) {
        profileProvisioning.removeProfileTable("TestProfileTable");
    }
    profileProvisioning.createProfileTable(profileSpecificationID, "TestProfileTable");

Creating a Profile

Option 1: Supply the attributes when creating the profile and have it committed. 

    AttributeList list = new AttributeList();
    list.add(new Attribute("Addresses", new Address[] { new Address(AddressPlan.IP, "127.0.0.1") }));
    RemoteProfiles.createCommittedProfile(connection, "TestProfileTable", "TestProfile1", list);

Option 2: Create the profile in the uncommitted state, and use a proxy to the Profile Management interface to set the attributes, then call commitProfile. 

    RemoteProfiles.UncommittedProfile<AddressProfileManagement> uncommittedProfile1;

    uncommittedProfile1 = RemoteProfiles.createUncommittedProfile(connection, "TestProfileTable", "TestProfile2",
                                                                           AddressProfileManagement.class);

    AddressProfileManagement addressProfile = uncommittedProfile1.getProfileProxy();
    addressProfile.setAddresses(new Address[] { new Address(AddressPlan.IP, "127.0.0.2") });
    uncommittedProfile1.getProfileMBean().commitProfile();

Option 3: Create the profile in the uncommitted state, and use the setAttribute method on the connection, then call commitProfile. 

    RemoteProfiles.UncommittedProfile uncommittedProfile2;

    uncommittedProfile2 = RemoteProfiles.createUncommittedProfile(connection, "TestProfileTable", "TestProfile3");

    connection.setAttribute(uncommittedProfile2.getObjectName(), new Attribute("Addresses", new Address[] { new Address(AddressPlan.IP, "127.0.0.3") }));
    uncommittedProfile2.getProfileMBean().commitProfile();

Editing a Profile

Using the profile management interface as a proxy to the profile object allows set methods to be invoked directly: 

    ProfileMBean profileMBean = RemoteProfiles.getProfileMBean(connection, "TestProfileTable", profileName);

    profileMBean.editProfile();

    AddressProfileManagement addressProfileManagement = RemoteProfiles.getProfile(connection, "TestProfileTable", profileName, AddressProfileManagement.class);
    addressProfileManagement.setAddresses(new Address[] { new Address(AddressPlan.IP, "127.0.1.1") });

    profileMBean.commitProfile();

Inspecting Profile Tables

Using RemoteProfiles methods to get the attribute names and types for a given profile table: 

    String[] names = RemoteProfiles.getAttributeNames(connection, "TestProfileTable");
    System.out.println("Profile attributes:");
    for (String name : names) {
        String type = RemoteProfiles.getAttributeType(connection, "TestProfileTable", name);
        System.out.println("    " + name + " (" + type + ")");
    }

Working with Usage

The RemoteUsage class contains a number of utility methods to assist working with MBeans related to SLEE Usage.

Rhino Housekeeping

The RemoteHousekeeping class methods to get a Rhino housekeeping MBean for a cluster or for a particular node.