Home

Purpose

JMX is the natural way to have access to technical management, e.g. for tuning, statistics, log levels, ... Unfortunately, it lacks a lightweight tool to expose mbeans and to browse them securely on any application and environment without heavy infrastructure setup. JMiniX provides such a feature.

Configuration

Requisites

• Java 1.5+

Maven Configuration

JMiniX is published in the official maven repository.

Add the following dependency to your pom.xml:

<dependency>
	<groupId>org.jminix</groupId>
	<artifactId>jminix</artifactId>
	<version>1.2.0</version>
</dependency>

NOTE: You may have to refer to the restlet repository since JMiniX relies on this excellent framework:

Declare the repository for your project or for a parent project by updating the pom.xml file and adding the following code to the <repositories> section:

<repository>  
    <id>maven-restlet</id>  
    <name>Public online Restlet repository</name>  
    <url>http://maven.restlet.org</url>  
</repository>  

Or you can put that in the settings.xml file. See http://www.restlet.org/downloads/maven.

Embed the Mini-Console in your Web Application

In web.xml :

<servlet>
    <servlet-name>JmxMiniConsoleServlet</servlet-name>
    <servlet-class>
        org.jminix.console.servlet.MiniConsoleServlet
    </servlet-class>
</servlet> 


<servlet-mapping>
    <servlet-name>JmxMiniConsoleServlet</servlet-name>
    <url-pattern>/jmx/*</url-pattern>
</servlet-mapping>	

By default, it finds the MbeanServerConnection by itself using the standard JMX discovery. You can add the serverConnectionProvider configuration parameter to provide your own implementation of the ServerConnectionProvider interface:

<servlet>
    <servlet-name>JmxMiniConsoleServlet</servlet-name>
    <servlet-class>
        org.jminix.console.servlet.MiniConsoleServlet
    </servlet-class>
    <init-param>
        <param-name>serverConnectionProvider</param-name>
        <param-value>org.myorg.myproject.MyOwnServerConnectionProvider</param-value>
    </init-param>
</servlet> 

Note: To open the Mini-Console, don't forget the trailing slash: http://localhost:8080/myapp/jmx/

Integration with Spring

If your web application uses a WebApplicationContext from Spring (using either the DispatcherServlet or the ContextLoaderListener in your web.xml), you can configure the MiniConsole to obtain the MBean server connection from it:

Using MBeanServer bean directly

<servlet>
    <servlet-name>JmxMiniConsoleServlet</servlet-name>
    <servlet-class>
        org.jminix.console.servlet.MiniConsoleServlet
    </servlet-class>
    <init-param>
        <param-name>serverConnectionProvider</param-name>
        <param-value>org.jminix.server.WebSpringServerConnectionProvider</param-value>
    </init-param>
</servlet> 

Note: You must have a bean named mbeanServer in your application context refering to a MBeanServer instance (usually created from a MBeanServerFactory). See Spring JMX documentation for more info:

<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"/>

Using a custom JminiX "application bean"

If you need to customize more, you can define the JMiniX application bean and connection provider yourself as Spring beans:

<bean id="miniConsoleApplication" class="org.jminix.console.application.MiniConsoleApplication">
  <property name="serverConnectionProvider" ref="myServerConnectionProvider"/>
</bean>

<bean id="myServerConnectionProvider" ...>

Then, you need to configure in web.xml the SpringMiniConsoleServlet.

<servlet>
    <servlet-name>JmxMiniConsoleServlet</servlet-name>
    <servlet-class>
        org.jminix.console.servlet.SpringMiniConsoleServlet
    </servlet-class>
</servlet> 

By convention, it uses the bean named miniConsoleApplication. If you want to name it differently, specify it in a servlet init-param named applicationBean.

Using the Mini-Console in Stand-Alone Mode

You can embed the miniconsole in any Java app or even in unit test with:

   new StandaloneMiniConsole(8088);

It can also be started as a stand-alone application, see Standalone.

Securing Access to the Mini-Console

The following web.xml example snippet restricts access to the MYAPPL_ADMIN role but let the access to the hello mbean open to everyone (The operation staff must have access to it!).

	<security-constraint>
		<web-resource-collection>
   			<web-resource-name>Resources-Protected</web-resource-name>
   			<url-pattern>/jmx/*</url-pattern>
		</web-resource-collection>		
		<auth-constraint>
			<role-name>MYAPPL_ADMIN </role-name>
		</auth-constraint>
	</security-constraint>	
	
	<security-constraint>
		<web-resource-collection>
   			<web-resource-name>Resources-Protected</web-resource-name>
   			<url-pattern>/jmx/servers/0/domains/mydomain/mbeans/type=Hello/attributes/Hello/</url-pattern>
		</web-resource-collection>
	</security-constraint>		

Using in a Clustered Application

See ClusterUsage

Use HTML content in attributes

JMiniX provides an extension to JMX. If you write your own MBeans, you can make attributes implement the marker interface org.jminix.type.HtmlContent.

The console will call toString() on these attributes and consider the result as an HTML snippet and render.

To avoid making your MBeans depend on JMinix API, you can use the filter feature below.

Extending attribute rendering using filters

You can register an AttributeFilter implementation to transform attributes before they are rendered. For example, you can make the filter generate a HtmlContent (see above) for some attribute types:

/**
  Attribute filter rendering String attributes in bold.
*/
public class Bolder implements AttributeFilter {
    public Object filter(final Object object) {
        if(object instanceof String) {
            return new HtmlContent() {
                public String toString() {
                    return "<b>"+object.toString()+"</b>";
                }                
            }; 
        } else {
            return object;
        }
    }
}

The filter is to be registered either:

• Programmatically using MiniConsoleApplication.setAttributeFilter()
• Or using the attributeFilter servlet parameter.

Example configuration for the latter:

  <servlet>
  	<servlet-name>jmx</servlet-name>
  	<servlet-class>org.jminix.console.servlet.MiniConsoleServlet</servlet-class>
  	<init-param>
  		<param-name>attributeFilter</param-name>
  		<param-value>Bolder</param-value>
  	</init-param>
  </servlet>

Using the Console

Skins for Embedding Attributes and Operations in Dashboards

Besides using the Ajax console which gives you full control but requires navigation in the tree, the RESTful nature of JMiniX allows you to embed the attributes and operation views in your application admin pages or even dashboards like iGoogle or Netvibes.

You have to use an HTML iframe pointing to the URL of the attribute/operation view.

In iGoogle or Netvibes, just search for "iframe" widgets.

For a better look, you can append a parameter to the URL:

• ?skin=embedded: Removes the margin around the title and content box.
• ?skin=raw: Removes the margin, the title and the content border.