[z/OS]

Java Management Extensions dynamic proxy concepts

A Java™ Management Extensions (JMX) dynamic proxy coordinates MBean requests among multiprocess servers. This section discusses the main terms associated with a JMX dynamic proxy.

Control process
Receives requests and distributes them to servant processes so that the application server can do work for the requests.
Servant process
Receives work from the control process and carries out the work.
Unicall option versus the multicall option
Use the unicall option on the proxyInvocationType method when a request invokes an arbitrary servant process or servant processes. Use the multicall option on the proxyInvocationType method when a request goes to multiple servant processes and the servant processes return different results.

The following example shows an MBean descriptor that was developed for a single process model (before) and modified for a multiprocess model (after).

Before
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MBean SYSTEM "MbeanDescriptor.dtd">
<MBean type="SampleStateMBean"
  version="6.0"
  description="Sample State MBean for the documentation example.">

  <attribute description="The name of the MBean."
    getMethod="getMBeanName" name="mbeanName" type="java.lang.String"/>
  <attribute description="The state of the MBean."name="state"
    getMethod="getState" setMethod="setState" type="java.lang.String"/>
  <operation
    description="Initialize the State MBean."
    impact="ACTION" name="initializeState" role="operation"
    targetObjectType="objectReference" type="void">
    <signature>
      <parameter description="The name of the MBean."
        name="mbeanName" type="java.lang.String"/>
      <parameter description="The initial state of the MBean."
        name="mbeanName" type="java.lang.String"/>
    </signature>
  </operation>
</MBean>
After
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MBean SYSTEM "MbeanDescriptor.dtd">
<MBean type="SampleStateMBean"
  version="6.0"
  platform="dynamicproxy"
  description="Sample State MBean for the documentation example.">

  <attribute description="The name of the MBean."
    getMethod="getMBeanName" name="mbeanName" type="java.lang.String"/>
  <attribute description="The state of the MBean."name="state"
    getMethod="getState" setMethod="setState" type="java.lang.String"/>
    proxyInvokeType="unicall" proxySetterInvokeType="multicall"/>
  <operation
    description="Initialize the State MBean."
    impact="ACTION" name="initializeState" role="operation"
    targetObjectType="objectReference" type="void" proxyInvokeType="multicall">
    <signature>
      <parameter description="The name of the MBean."
        name="mbeanName" type="java.lang.String"/>
      <parameter description="The initial state of the MBean."
        name="mbeanName" type="java.lang.String"/>
    </signature>
  </operation>
</MBean>
Make the user MBean run in dynamic proxy mode by specifying dynamicproxy on the platform attribute. If no platform attribute exists on the MBean descriptor, the user MBean deployed on WebSphere® Application Server for z/OS® automatically uses the dynamic proxy mode.
Update the attribute XML tag or the operation XML tag, as shown in the After example, to specify the unicall behavior or the multicall behavior in the multiprocess environment. If no proxyInvokeType option or proxySetterInvokeType option exists, the behavior defaults to one of the following values:
proxyInvokeType=unicall (for the getMethod)
proxyInvokeType=multicall (for the setMethod)

In the After example, the getMBeanName method and the getState method run with unicall behavior. The setState method and the initializeState method run with multicall behavior.

Single process model
The single process application server has one server run time. The MBean generally acts on one instance of each major run time component: one Enterprise JavaBeans (EJB) container, one web container, one Java 2 Platform, Enterprise Edition (J2EE) connection manager, and so on. This model assumes that each MBean invocation on the server runs in the same process and the same Java Virtual Machine (JVM).
Multiprocess model
The multiprocess model asserts that a single server instance is a federation of Java virtual machines (JVMs), that run in a separate operating process. The control process is responsible for such server functions as communication endpoints, authorization, resource recovery, and workload management. All other JVMs are worker JVMs, in which application requests run. These JVMs take direction from, and interact only with the control process.

All inbound and outbound requests go through the control process. Client requests arrive at the control process. The control process, with assistance from the MVS™ workload manager (WLM), dispatches the work to the servant processes.

The number of servant processes is managed by WLM and varies based on demand. The demand is measured against installation-specific performance goals, expressed as WLM policy. Each servant process is identical and hosts the necessary application server components to enable the J2EE application programming model. The servant processes rely on the control process for numerous services, such as communication, security, and transaction control.

The multiprocess model imposes additional demands on the Java Management Extension (JMX) infrastructure over the single process model. Administrative requests to a multiprocess server often require coordination among the processes that comprise the application server. The JMX infrastructure includes additional facilities to enable this coordination.

multiprocess server model
State object support for dynamic proxy MBean
com.ibm.websphere.management.dynamicproxy.StateObject class: The MBean provider extends the StateObject abstract class. Specify the subclass of the StateObject class so that the JMX run time can instantiate it before the dynamic proxy MBean completes its initialization. The JMX run time attaches StateObject class to the dynamic proxy Invocation Handler interface to keep track of the current state of the dynamic proxy before and after the MBean method runs. The JMX run time also attaches the StateObject class to the Result Aggregation interface class as well as the Event Handler interface class to support appropriate aggregation application.
Result aggregation handler support interface
com.ibm.websphere.management.dynamicproxy.AggregationHandler class: The result aggregation handler support interface defines the method that an MBean provider uses to handle result aggregation in a dynamic proxy-enabled WebSphere Application Server for z/OS MBean. Specify the aggregationHandlerClass attribute on the MBeanDescriptor MBean XML tag. Implement the interface for MBean methods that use the multicall proxyInvokeType option and that return a value. The interface determines the method for which this aggregation is processed. It then properly aggregates all servant MBean results that the servant processes pass back to the control process, and then compiles a single result to return to the caller.
Event aggregation handler support interface
com.ibm.websphere.management.dynamicproxy.EventHandler interface class: The event aggregation handler support interface defines the method that an MBean provider uses to handle event aggregation in a dynamic proxy-enabled WebSphere Application Server for z/OS MBean. Specify the eventHandlerClass attribute on the MBeanDescriptor MBean XML tag. The interface handles all incoming servant MBean events and aggregates them to filter out duplicate events from multiple servant MBeans. It sends one event back to the listener of the dynamic proxy MBean. The interface adjusts the current dynamic proxy MBean state according to the MBean provider requirements.
Invocation handler support interface
com.ibm.websphere.management.dynamicproxy.InvocationHandler class: The invocation handler support interface defines the preInvoke and postInvoke methods that a WebSphere Application Server for z/OS dynamic proxy MBean implements when it requires state management information. The MBean uses the information to coordinate with the servant MBeans in cases where the multicall invocation type is required. Specify the invocationHandlerClass attribute on the MBeanDescriptor MBean XML tag. Use the interface for dynamic proxy MBeans that require state management before and after invoking a method that changes its state.
User MBean
The user MBean resides in the servant process and handles requests through its dynamically created proxy MBean, which runs inside the control process. An MBean provider can package handlers with the user MBean so that the provider hooks in his own specialized processing for the following situations:
  • Result aggregation
  • Event aggregation
  • Invocation handling
  • State management of objects