10 DM_MIB MBean Interface

TSAM Plus wraps configurations DM_MIB classes to MBean operations.

10.1 Creating the TuxedoDomainGatewayTargetMBean Object

JMXConnectorFactory.connect (JMXServiceURL serviceURL, Map<String,?> environment) is used to create a connection to the tlisten JMX server. The "serviceURL" format is “service:jmx:rmi:///jndi/rmi://%s:%s/server", host, port, where "host" is the host name tlisten runs, and port is the tlisten -j port value. The environment key is jmx.remote.credentials. The environment value is a String array.

The following table lists its elements:

Table 10-1 Environment Value Elements

Index Value Description
0 Tuxedo user name Its value may be null when the Tuxedo resource "SECURITY" value is not USER_AUTH, ACL, or MANDATORY_ACL.
1 Tuxedo user password Its value may be null when the Tuxedo resource "SECURITY" value is not USER_AUTH, ACL, or MANDATORY_ACL.
2 Tuxedo application password Its value may be null when the Tuxedo resource SECURITY value is not APP_PW.
3 Tuxedo DOMAINID -
4 Tuxedo IPCKEY -

ObjectName domainId + "_" + ipckey + ":type=tuxedo_domain_gateway,group_name=" + groupName + ",SRVID=" + SVRID is used to create the TuxedoDomainGatewayTargetMBean object, where domainId is the Tuxedo domain DOMAINID, ipckey is the Tuxedo domain IPCKEY, groupName is the server GWTDOMAIN SRVGRP, and SVRID is the server GWTDOMAIN SVRID.

Parent topic: DM_MIB MBean Interface

10.1.1 get Operations

get operations are used to get the existing TM MIB entities.

Name

get+MIB class name (in camel naming format)+s (if the return type is TabularData)

Parameters

All parameters are input ones. The format is [keyType keyValue]*, CompositeData filter).

  • keyValue: the key fields that are required when calling the DM_MIB get interface
  • filter: includes all optional fields.

Return Type

The return type is CompositeData if only one recode is returned; otherwise the return type is TabularData.

Exception

It is always the MBeanException type.

Parent topic: Creating the TuxedoDomainGatewayTargetMBean Object

10.1.2 add Operations

add operations are used to add a new TM MIB entity.

Name

add+MIB class name (in camel naming format)

Parameters

All parameters are input ones. The format is CompositeData parameters , where parameters includes all fields.

Return Type

void

Exception

It is always the MBeanException type.

Parent topic: Creating the TuxedoDomainGatewayTargetMBean Object

10.1.3 delete Operations

delete operations are used to delete an existing TM MIB entity.

Name

delete+MIB class name (in camel naming format)

Parameters

All parameters are input ones. The format is [keyType keyValue]+),where keyValue is the key fields that are required when calling the DM_MIB set interface.

Return Type

void

Exception

It is always the MBeanException type.

update Operations

update operations are used to update an existing TM MIB entity.

Name

update+MIB class name (in camel naming format)

Parameters

All parameters are input ones. The format is [keyType keyValue]+, CompositeData parameters)

  • keyValue: the key fields that are required when calling the DM_MIB set interface.
  • parameters: includes all fields to be updated.

    Note:

    Key fields must not be in the "CompositeData parameters", otherwise an exception will be thrown.

Return Type

void

Exception

It is always the MBeanException type.

Parent topic: Creating the TuxedoDomainGatewayTargetMBean Object

10.2 Application Programming Interfaces

All MBean DM_MIB operations are in the class "oracle.tuxedo.jmx.tux.emmodel.TuxedoDomainGatewayTarget", which extends "javax.management.modelmbean.RequiredModelMBean".

Here is the list of them:

Table 10-2 Tdomain and Command Interfaces

MBeanOperation Name Class Name TA_OPERATION Description
TabularData getACLs(CompositeData filter) T_DM_ACL get Get an ACL list
void addACL(CompositeData parameters) T_DM_ACL set Add a new ACL
void deleteACL(String ACLName) T_DM_ACL set Delete an ACL
void updateACL(String ACLName, CompositeData parameters) T_DM_ACL set Update an existing ACL
TabularData getEventIns(CompositeData filter) T_DM_EVT_IN get Get events, which can be received from remote domains
void addEventIn(CompositeData parameters) T_DM_EVT_IN set Add an event, which can be received from remote domains
void deleteEventIn(String eventName, String lAccessPoint) T_DM_EVT_IN set Delete an event, which can be received from remote domains
TabularData getEventOuts(CompositeData filter) T_DM_EVT_OUT get Get events, which can be sent to remote domains
void addEventOut(CompositeData parameters) T_DM_EVT_OUT set Add an event, which can be sent to remote domains
void deleteEventOut(String eventName, String lAccessPoint, String rAccessPointList) T_DM_EVT_OUT set Delete an event, which can be sent to remote domains
TabularData getExports(CompositeData filter) T_DM_EXPORT get Get local resources that are exported to one or more remote domains through a local access point
void addExport(CompositeData parameters) T_DM_EXPORT set Add a local resource that is exported to one or more remote domains through a local access point
void deleteExport(String resourceName, String lAccessPoint) T_DM_EXPORT set Delete a local resource that is exported to one or more remote domains through a local access point
void updateExport(String resourceName, String lAccessPoint, CompositeData parameters) T_DM_EXPORT set Update a local resource that is exported to one or more remote domains through a local access point
TabularData getImports(CompositeData filter) T_DM_IMPORT get Get remote resources that are imported through one or more remote domain access points
void addImport(CompositeData parameters) T_DM_IMPORT set Add a remote resource that is imported through one or more remote domain access points
void deleteImport(String resourceName, String lAccessPoint, String rAccessPointList) T_DM_IMPORT set Delete a remote resource that is imported through one or more remote domain access points
void updateImport(String resourceName, String lAccessPoint, String rAccessPointList, CompositeData parameters) T_DM_IMPORT set Update a remote resource that is imported through one or more remote domain access points
TabularData getLocals(CompositeData filter) T_DM_LOCAL get Get local domain access points
void addLocal(CompositeData parameters) T_DM_LOCAL set Add a local domain access point
void deleteLocal(String accessPoint) T_DM_LOCAL set Delete a local domain access point
void updateLocal(String accessPoint, CompositeData parameters) T_DM_LOCAL set Update a local domain access point
TabularData getPasswords(CompositeData filter) T_DM_PASSWORD get Get passwords for interdomain authentication through access points of type
oid addPassword(CompositeData parameters) T_DM_PASSWORD set Add a password for interdomain authentication through access points of type
void deletePassword(String lAccessPoint, String rAccessPoint) T_DM_PASSWORD set Delete a password for interdomain authentication through access points of type
void reCryptPasswords(String lAccessPoint,String rAccessPoint) T_DM_PASSWORD set Re-encrypt all passwords using a new encryption key. Applies to all password instances in the classes
TabularData getRemotes(CompositeData filter) T_DM_REMOTE get Get remote domain access points
void addRemote(CompositeData parameters) T_DM_REMOTE set Add a remote domain access point
void deleteRemote(String accessPoint, String type) T_DM_REMOTE set Delete a remote domain access point
void updateRemote(String accessPoint, String type, CompositeData parameters) T_DM_REMOTE set Update a remote domain access point
TabularData getResources(CompositeData filter) T_DM_RESOURCES get Get resources
void setResources(CompositeData parameters) T_DM_RESOURCES set Set resources
TabularData getRoutings(CompositeData filter) T_DM_ROUTING get Get all routing list to a domain
void addRouting(CompositeData parameters) T_DM_ROUTING set Add a routing to a domain through a remote domain access point
void deleteRouting(String routingName, String bufType) T_DM_ROUTING set Delete a routing to a domain through a remote domain access point
void updateRouting(String routingName, String bufType, CompositeData parameters) T_DM_ROUTING set Update a routing to a domain through a remote domain access point
TabularData getTDomain(CompositeData filter) T_DM_TDOMAIN get Get the TDomain specific configuration for a local or remote domain access point
void addTDomain(CompositeData parameters) T_DM_TDOMAIN set Add the TDomain specific configuration for a local or remote domain access point
void deleteTDomain(String accessPoint, String nwaddr, String lAccessPoint) T_DM_TDOMAIN set Delete the TDomain specific configuration for a local or remote domain access point
void setTDomain(String accessPoint, String nwaddr, String lAccessPoint, CompositeData parameters) T_DM_TDOMAIN set Update the TDomain specific configuration for a local or remote domain access point

Parent topic: DM_MIB MBean Interface

10.3 Security Requirement

The security level is controlled by Oracle Tuxedo. The corresponding credentials are required when the configuration item SECURITY value in the Tuxedo UBBCONFIG is not NONE.

$TUXDIR/jmx/tmjmx_tux.jar is reuqired to add the JAVA classpath, in which oracle.tuxedo.jmx.tux.utility.Encryption.getInstance().encrypt() is used to encrypt the APP password and user passwords.

When the security level USER_AUTH or above is enabled, the client of the user used to login is required to be set to tpsysadm when calling tpusradd.

Parent topic: DM_MIB MBean Interface

10.4 User Cases

Parent topic: DM_MIB MBean Interface

10.4.1 User Case 1 - Specify the network address associated with a access point

  1. Intall TSAM Plus Agent in Oracle Tuxedo 12c
  2. Start tlisten with the -j option using the following command:

    tlisten -j rmi://<host>:<rmiport> -l //<host>:<tlistenport>

  3. Boot up the tuxedo domain.
  4. Compile and run the following source file:

User Case 1 - Specify the network address associated with a access point 

import java.io.Closeable;
import java.io.IOException;
import java.net.MalformedURLException;
import java.util.HashMap;
import java.util.Map;

import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.openmbean.CompositeData;
import javax.management.openmbean.CompositeDataSupport;
import javax.management.openmbean.CompositeType;
import javax.management.openmbean.SimpleType;
import javax.management.openmbean.TabularData;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
public class TuxedoDomainGatewayTargetTestCustom implements Closeable {

   private JMXConnector jmxc = null;
   private MBeanServerConnection mbsc = null;
   private ObjectName tuxedoDomainGatewayTargetMBean = null;

   private String host = "rno05038.us.oracle.com";

   private String port = "5039";

   private String userName = "";

   private String password = "";

   private String appPassword = "";

   private String domainId = "DOMAIN1";

   private String ipckey = "123468";

   private String groupName = "SYSGRP1";

   private String SVRID = "3";

   TuxedoDomainGatewayTargetTestCustom() throws Exception {

      String[] credentials = new String[] {
         userName,
         password,
         appPassword,
         domainId,
         ipckey
      };

      jmxc = createJMXConnector(credentials);
      mbsc = jmxc.getMBeanServerConnection();
      tuxedoDomainGatewayTargetMBean = new ObjectName(domainId + "_" + ipckey +
         ":type=tuxedo_domain_gateway,group_name=" + groupName +
         ",SRVID=" + SVRID);
   }

   @Override
   public void close() throws IOException {
      jmxc.close();
   }

   /*get all Tdomain items with the filter "TA_DMACCESSPOINT=accessPoint"*/
   public void getTDomain(String accessPoint) throws Exception {
      String[] itemNames = {
         "TA_DMACCESSPOINT"
      };
      Object[] itemValues = new Object[] {
         accessPoint
      };
      javax.management.openmbean.OpenType < ? > [] itemTypes = new javax.management.openmbean.OpenType < ? > [] {
         SimpleType.STRING
      };

      CompositeType compositeType = new CompositeType(
         "tuxedo_domain_gateway", "tuxedo_domain_gateway", itemNames,
         itemNames, itemTypes);
      CompositeDataSupport filter = new CompositeDataSupport(compositeType,
         itemNames, itemValues);

      TabularData result = (TabularData) mbsc.invoke(
         tuxedoDomainGatewayTargetMBean, "getTDomain",
         new Object[] {
            filter
         },
         new String[] {
            CompositeData.class.getName()
         });

      if (result != null)
         System.out.println(result.toString());
   }

   /*add a TDomain item*/
   public void addTDomain(String accessPoint, String nwaddr,
      String lAccessPoint) throws Exception {
      String[] itemNames = {
         "TA_DMACCESSPOINT",
         "TA_DMNWADDR",
         "TA_DMLACCESSPOINT"
      };
      Object[] itemValues = new Object[] {
         accessPoint,
         nwaddr,
         lAccessPoint
      };
      javax.management.openmbean.OpenType < ? > [] itemTypes = new javax.management.openmbean.OpenType < ? > [] {
         SimpleType.STRING, SimpleType.STRING, SimpleType.STRING
      };

      CompositeType compositeType = new CompositeType(
         "tuxedo_domain_gateway", "tuxedo_domain_gateway", itemNames,
         itemNames, itemTypes);
      CompositeDataSupport compositeDataSupport = new CompositeDataSupport(
         compositeType, itemNames, itemValues);

      mbsc.invoke(tuxedoDomainGatewayTargetMBean, "addTDomain",
         new Object[] {
            compositeDataSupport
         },
         new String[] {
            CompositeData.class.getName()
         });

   }

   /*delete a TDomain item*/
   public void deleteTDomain(String accessPoint, String nwaddr,
      String lAccessPoint) throws Exception {
      mbsc.invoke(tuxedoDomainGatewayTargetMBean, "deleteTDomain",
         new Object[] {
            accessPoint,
            nwaddr,
            lAccessPoint
         },
         new String[] {
            String.class.getName(), String.class.getName(),
               String.class.getName()
         });
   }

   private JMXConnector createJMXConnector(String[] credentials)
   throws MalformedURLException, IOException {
      Map < String, Object > env = new HashMap < String, Object > ();
      env.put("jmx.remote.credentials", credentials);

      // Create an RMI connector client and
      // connect it to the RMI connector server

      JMXServiceURL url = new JMXServiceURL(String.format(
         "service:jmx:rmi:///jndi/rmi://%s:%s/server", host, port));

      System.out.print("try to connect " + url + " with the credentials=" +
         env + "...");
      JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
      System.out.println("OK");

      return jmxc;
   }

   /*change the nwaddr of "DOMAIN2_3" from "//localhost:11003"
    * to "//localhost:11004"*/
   public static void main(String[] args) throws Exception {
      String accessPoint = "DOMAIN2_3";
      String oldNwaddr = "//localhost:11003";
      String newNwaddr = "//localhost:11004";
      String lAccessPoint = "DOMAIN1_1";

      TuxedoDomainGatewayTargetTestCustom tuxedoDomainGatewayTargetTestCustom = new TuxedoDomainGatewayTargetTestCustom();

      tuxedoDomainGatewayTargetTestCustom.deleteTDomain(accessPoint,
         oldNwaddr, lAccessPoint);
      tuxedoDomainGatewayTargetTestCustom.addTDomain(accessPoint, newNwaddr,
         lAccessPoint);
   }

Note:

$TUXDIR/udataobj/jmx/tmjmx_exceptions.jar should be added to the classpath when running it.

Parent topic: User Cases

10.4.2 User Case 2 - When Tuxedo Security Level is "USER_AUTH"

  1. Install TSAM Plus Agent in Oracle Tuxedo 12c
  2. Add the Tuxedo user "user1" with the group name "group1" and password "user123456":

    tpusradd -g group1 -c tpsysadm user1

    Enter password for user1:user123456

    Re-enter password for user1:user123456: The client name must be "tpsysadm".

  3. Specify the app password "app123456" when running tmloadcf:

    tpusradd -g group1 -c tpsysadm user1

    Enter password for user1:app123456

    Re-enter password for user1:app123456

  4. Start tlisten with the "-j" option using the following command:

    tlisten -j rmi://<host>:<rmiport> -l //<host>:<tlistenport>

  5. Boot up the tuxedo domain.
  6. Compile and run the following source file:

User Case 2 - When Tuxedo Security Level is "USER_AUTH"

import java.io.Closeable;
import java.io.IOException;
import java.net.MalformedURLException;
import java.util.HashMap;
import java.util.Map;

import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.openmbean.CompositeData;
import javax.management.openmbean.CompositeDataSupport;
import javax.management.openmbean.CompositeType;
import javax.management.openmbean.SimpleType;
import javax.management.openmbean.TabularData;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
public class TuxedoDomainGatewayTargetTestCustom implements Closeable {

   private JMXConnector jmxc = null;
   private MBeanServerConnection mbsc = null;
   private ObjectName tuxedoDomainGatewayTargetMBean = null;

   private String host = "rno05038.us.oracle.com";

   private String port = "5039";

   private String userName = "user1";

   private String password = oracle.tuxedo.jmx.tux.utility.Encryption
      .getInstance().encrypt("user123456");

   private String appPassword = oracle.tuxedo.jmx.tux.utility.Encryption
      .getInstance().encrypt("app123456");

   private String domainId = "DOMAIN1";

   private String ipckey = "123468";

   private String groupName = "SYSGRP1";

   private String SVRID = "3";

   TuxedoDomainGatewayTargetTestCustom() throws Exception {

      String[] credentials = new String[] {
         userName,
         password,
         appPassword,
         domainId,
         ipckey
      };

      jmxc = createJMXConnector(credentials);
      mbsc = jmxc.getMBeanServerConnection();
      tuxedoDomainGatewayTargetMBean = new ObjectName(domainId + "_" + ipckey +
         ":type=tuxedo_domain_gateway,group_name=" + groupName +
         ",SRVID=" + SVRID);
   }

   @Override
   public void close() throws IOException {
      jmxc.close();
   }

   /*get all Tdomain items with the filter "TA_DMACCESSPOINT=accessPoint"*/
   public void getTDomain(String accessPoint) throws Exception {
      String[] itemNames = {
         "TA_DMACCESSPOINT"
      };
      Object[] itemValues = new Object[] {
         accessPoint
      };
      javax.management.openmbean.OpenType < ? > [] itemTypes = new javax.management.openmbean.OpenType < ? > [] {
         SimpleType.STRING
      };

      CompositeType compositeType = new CompositeType(
         "tuxedo_domain_gateway", "tuxedo_domain_gateway", itemNames,
         itemNames, itemTypes);
      CompositeDataSupport filter = new CompositeDataSupport(compositeType,
         itemNames, itemValues);

      TabularData result = (TabularData) mbsc.invoke(
         tuxedoDomainGatewayTargetMBean, "getTDomain",
         new Object[] {
            filter
         },
         new String[] {
            CompositeData.class.getName()
         });

      if (result != null)
         System.out.println(result.toString());
   }

   /*add a TDomain item*/
   public void addTDomain(String accessPoint, String nwaddr,
      String lAccessPoint) throws Exception {
      String[] itemNames = {
         "TA_DMACCESSPOINT",
         "TA_DMNWADDR",
         "TA_DMLACCESSPOINT"
      };
      Object[] itemValues = new Object[] {
         accessPoint,
         nwaddr,
         lAccessPoint
      };
      javax.management.openmbean.OpenType < ? > [] itemTypes = new javax.management.openmbean.OpenType < ? > [] {
         SimpleType.STRING, SimpleType.STRING, SimpleType.STRING
      };

      CompositeType compositeType = new CompositeType(
         "tuxedo_domain_gateway", "tuxedo_domain_gateway", itemNames,
         itemNames, itemTypes);
      CompositeDataSupport compositeDataSupport = new CompositeDataSupport(
         compositeType, itemNames, itemValues);

      mbsc.invoke(tuxedoDomainGatewayTargetMBean, "addTDomain",
         new Object[] {
            compositeDataSupport
         },
         new String[] {
            CompositeData.class.getName()
         });

   }

   /*delete a TDomain item*/
   public void deleteTDomain(String accessPoint, String nwaddr,
      String lAccessPoint) throws Exception {
      mbsc.invoke(tuxedoDomainGatewayTargetMBean, "deleteTDomain",
         new Object[] {
            accessPoint,
            nwaddr,
            lAccessPoint
         },
         new String[] {
            String.class.getName(), String.class.getName(),
               String.class.getName()
         });
   }

   private JMXConnector createJMXConnector(String[] credentials)
   throws MalformedURLException, IOException {
      Map < String, Object > env = new HashMap < String, Object > ();
      env.put("jmx.remote.credentials", credentials);

      // Create an RMI connector client and
      // connect it to the RMI connector server

      JMXServiceURL url = new JMXServiceURL(String.format(
         "service:jmx:rmi:///jndi/rmi://%s:%s/server", host, port));

      System.out.print("try to connect " + url + " with the credentials=" +
         env + "...");
      JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
      System.out.println("OK");

      return jmxc;
   }

   /*change the nwaddr of "DOMAIN2_3" from "//localhost:11003"
    * to "//localhost:11004"*/
   public static void main(String[] args) throws Exception {
      String accessPoint = "DOMAIN2_3";
      String oldNwaddr = "//localhost:11003";
      String newNwaddr = "//localhost:11004";
      String lAccessPoint = "DOMAIN1_1";

      TuxedoDomainGatewayTargetTestCustom tuxedoDomainGatewayTargetTestCustom = new TuxedoDomainGatewayTargetTestCustom();

      tuxedoDomainGatewayTargetTestCustom.deleteTDomain(accessPoint,
         oldNwaddr, lAccessPoint);
      tuxedoDomainGatewayTargetTestCustom.addTDomain(accessPoint, newNwaddr,
         lAccessPoint);
   }

Note:

$TUXDIR/udataobj/jmx/tmjmx_tux.jar should be added to the classpath when compiling and running it.

Parent topic: User Cases