Quick-start guide to NetMX

Suppose you have an existing .NET application and you want to add some management and monitoring features requested by your app’s operations staff. This tutorial explains how to make such an app manageable through NetMX.

Configuration

First of all you have to add some configuration to the process you want to manage. It should be the process where your business logic is being executed because MBeans should by definition manage objects residing in same address space as they are.

First thing you have to configure is the actual NetMX/MBean server implementation. Because majority of NetMX is just an API and different implementations of this API are allowed, for each MBean server instance used in your application (yes, you can use more than one!) its implementing type must be specified.

In vast majority of cases you will simply use MBean server provided as part of NetMX distribution (the one from NetMX.Server assembly). The configuration should look like this:

<configSections>
	<section name="netMX" type="NetMX.Configuration.Provider.ProviderConfigurationSectionWithDefault, NetMX"/>
</configSections>
<netMX defaultProvider="default">
	<providers>
		<add name="default" type="NetMX.Server.MBeanServerBuilder, NetMX.Server"/>
	</providers>
</netMX>
Second and last thing that needs server-side config is remote access. You can register multiple so-called connectors (to read more about connectors see the architecture document) and bind them to URI “protocols” (for example: tcp for Remoting, HTTP for JSR-262).
Let’s say that we need Remoting access to the MBean server without any security checks. We should add the following section to the app.config:

<netMXConnectorServerFactory>
	<providers>
		<add name="tcp" type="NetMX.Remote.Remoting.RemotingServerProvider, NetMX.Remote.Remoting" securityProvider="null"/>
	</providers>
</netMXConnectorServerFactory>
<netMXSecurityService>
	<providers>			
		<add name="null" type="NetMX.Remote.NullSecurityProvider, NetMX.Remote"/>
	</providers>
</netMXSecurityService>

Starting up server

Next thing we have to do in order to get out MBean server up and running is include some code to create it’s instance and bind it to the connector we configured. This code is usually executed on application start. The address connector is listening could be configured using App Settings if there is such a need. We create a server using static factory class MBeanServerFactory:

IMBeanServer server = MBeanServerFactory.CreateMBeanServer();
INetMXConnectorServer connectorServer = NetMXConnectorServerFactory.NewNetMXConnectorServer(serviceUrl, server);
connectorServer.Start();

Creating MBeans

An MBean server without MBeans is completely useless. Let’s create one. Our first MBean would be a simple counter with following features:
  • Obtaining and setting counter value (integer)
  • Adding value to counter
  • Resetting to zero
  • Notifying when counter value changes
First, we have to define an interface which will define the contract of this MBean (attributes, operations and notifications which will be accessible remotely, via MBeanServer). It should look like this:

public interface CounterMBean
{
	int Value { get; set; }
	void Reset();
	void Add(int amount);
	[MBeanNotification("sample.counter")]
	event EventHandler<NotificationEventArgs> CounterChanged;
}
MBeanNotification attribute is required to set NetMX event type for published notification. Next, the actual implementation. It is really straightforward:
public class Counter : CounterMBean
{
	private int _counter;

	public int Value
	{
		get { return _counter; }
		set
		{
			_counter = value;
			OnCounterChanged();
		}
	}
	public void Reset()
	{
		_counter = 0;
		OnCounterChanged();
	}
	public void Add(int amount)
	{
		_counter += amount;
		OnCounterChanged();
	}
	public event EventHandler<NotificationEventArgs> CounterChanged;

	private void OnCounterChanged()
	{
		if (CounterChanged != null)
		{
			CounterChanged(this, new NotificationEventArgs("Counter changed", _counter));
		}
	}
}
Notice, that the implementation class of this standard MBean is a PONO – Plain Old .NET Object – so it can be tested in isolation, outside of NetMX runtime.

Registering MBeans

We have an MBean implemented so let’s register it in the server! Actually, it cannot be simpler. All you have to do is get an instance of IMBeanServer and call the RegisterMBean method. Now it is time to name our MBean -- every MBean in the server has a unique name which is used to access it. Bean name consists of two parts -- domain name and property list -- separated by a colon. Domain name consists of one or more alphanumeric strings separated by dots. Properties are key-value pairs separated by commas. Because this is quick-start and our bean represents a counter, let’s name it QuickStart:type=counter:

Counter o = new Counter();
ObjectName name = new ObjectName("QuickStart:type=counter");
server.RegisterMBean(o, name);


Last edited Jan 7, 2010 at 4:05 PM by SzymonPobiega, version 2

Comments

No comments yet.