The Proxy Mechanism

Proxy objects simplify the interactions between an application and the MBeans it wants to manage. The purpose of a proxy is to invoke the methods that access the attributes and operations of an MBean, through its MBean server. These method calls can be rather tedious to construct at every invocation, so the proxy performs this task for the caller.

For example to invoke an operation on an MBean, an application must call the invoke method of the MBean server and provide the MBean's object name, the operation name string, an array of parameter objects, and a signature array. The proxy is a class which codes this whole sequence, meaning that the application can call the reset method directly on the proxy instance. And because the code of a proxy class is deterministic, it can be generated automatically using the proxygen tool.

Conceptually, a proxy instance makes the MBean server and a protocol connector completely transparent. Except for MBean registration and connector connection phases, all management requests on MBeans can be fully served through proxies, with identical results. However, all functionality of the Java Dynamic Management Kit is available without using proxies, so their usage is never mandatory.

By definition, a proxy object has the same interface as its MBean: the proxy can be manipulated as if it were the MBean instance, except that all requests are transmitted through the MBean server to the actual MBean instance for processing. A standard MBean proxy exposes getters, setters, and operation methods. It may also register listeners for all notifications broadcast by their corresponding MBean. A dynamic MBean proxy, also known as a generic proxy, exposes generic methods which are identical to those of the DynamicMBean interface.

In addition, standard proxies are commonly called proxy MBeans, because they are themselves MBeans. They are generated with an MBean interface, and can therefore be registered as standard MBeans in an MBean server. This feature allows one agent to expose resources whose MBeans are actually located in another agent. An equivalent functionality is covered in the topic of "Cascading Agents" in the lesson on "Agent Services".

Local and Remote Proxies

Proxies may also be bound to objects called handlers which necessarily implement the ProxyHandler interface. The methods of this interface are a subset of MBean server methods, as listed in Table 8-1 (see "The RemoteMBeanServer Interface"). These are the only methods that a proxy needs to in order to access its corresponding MBean and fulfill all management requests.

In the Java Dynamic Management Kit, the RemoteMBeanServer interface extends the ProxyHandler interface, meaning that proxy objects may be bound to any of the connector clients. These are called remote proxies, because they are instantiated in an application which is distant from the agent and its MBean instances.

As a new feature in version 4.2 of the product, the implementation of the MBeanServer interface also implements the ProxyHandler interface, so that proxy objects may be bound to the MBean server itself. These are called local proxies because they are located in the same application as their corresponding MBeans. Local proxies help preserve the management architecture by providing the simplicity of performing direct method calls on MBeans, while still routing all operations through the MBean server.

The symmetry of remote and local proxies complements the symmetry that allows management components to execute either in an agent or in a management application. Provided that all proxy classes are available, management components which use MBean proxies may be instantiated in an agent and rely on the MBean server or may be instantiated in a remote manager where they interact with a connector client. Except for communication delays, the results of all operations will be identical, and the same notifications will be received, whether obtained through a local proxy or a remote proxy (see "Adding a Listener Through the Connector").

The following diagram shows local proxies which are instantiated in an agent and bound to the MBean server, and the same classes instantiated as remote proxies in a management application and bound to the connector client. Management components located in either the agent or management application can interact with the local or remote proxies, respectively. Management components may also access the MBean server or the connector client directly, regardless of whether proxies are being used.

Figure 9-1 Interacting with Local and Remote Proxies

This diagram shows all possible relations between management components, proxies and their MBeans. Standard proxies can only represent a specific standard MBean, and generic proxies may represent any standard or dynamic MBean. In a typical management scenario, the management components will be located in only one application, and for simplicity, they will rarely instantiate more than one type of proxy.

Throughout the rest of this topic, we do not distinguish between local and remote proxies. A proxy object, either standard or generic, is used in exactly the same way regardless of whether it is instantiated locally or remotely.

The Proxy Interface

In addition to the methods for accessing the attributes and operations of its MBean, all proxies implement the methods of the Proxy interface. This interface contains the methods for binding the proxy instance to the proxy handler which can fulfill its requests. The setServer method binds the proxy to the handler object. Setting the server to null effectively unbinds the proxy object. The result of the getServer method can indicate whether or not a proxy is bound and if so, it will return a reference to the handler object.

Because of the new design of the proxy mechanism, many methods in the Proxy interface are deprecated as of version 4.2 of the product. The functionality of the deprecated methods is preserved in the three non-deprecated methods, listed in the following table. See the Javadoc API of the Proxy interface for details.

Table 9-1 Non-Deprecated Methods of the Proxy Interface

ObjectInstance	getMBeanObjectInstance()
ProxyHandler	getServer()
void	setServer(ProxyHandler server)

Standard proxies may also implement the NotificationBroadcasterProxy interface if their corresponding MBean is a notification proxy. This interface contains the same addNotificationListener and removeNotificationListener methods that the MBean implements from the NotificationBroadcaster interface.

Applications that use proxies therefore have two ways to detect notification broadcasters. The first way relies on the implementation of the NotificationBroadcasterProxy interface which can be detected in the proxy's class inheritance. The second and more standard way is to look at the notifications listed in the MBean's metadata obtained by the getMBeanInfo method either from the server or through the proxy.

Generic proxies do not implement the NotificationBroadcasterProxy interface, so callers must use the MBean metadata for detecting broadcasters. In addition, generic proxies cannot register notification listeners, callers must do this directly through the server.