db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "DerbyJMXQuickStart" by JohnHEmbretsen
Date Thu, 10 Apr 2008 11:36:18 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by JohnHEmbretsen:

The comment on the change is:
Moved quick start info to this new page

New page:
~-Parent: ["DerbyJMX"]-~

This page is intended to provide examples and information that may help you get started using
Derby's JMX (Monitoring and Management) features.

For more information about Derby's JMX features, see ["DerbyJMX"].



Derby's JMX features are automatically available when Derby is started in a Java Virtual Machine
(JVM) supporting the [http://java.sun.com/j2se/1.5.0/docs/guide/management/overview.html#mxbeans
platform MBean Server]. This includes JVMs supporting J2SE 5.0, Java SE 6, or newer. Derby's
JMX features are not available when using J2SE 1.4.2 or Java ME (as per March 2008).

You start Derby by loading Derby's embedded driver. If you are using Derby's Network Server,
the embedded driver is automatically loaded in the server JVM when the server is started.

In short, Derby's JMX features consist of a set of MBeans (Managed Beans) and their attributes
and operations. MBean implementations instrument one or more parts of a running Derby system,
potentially giving you real-time access to Derby-specific information from a host of your
choice. The word ''potentially'' here indicates that JMX access may depend on how you configure
your JVM and (for example) Derby's security features.

Note that if you are unfamiliar with JMX technology, it may be a good idea to take a look
at some of the references provided [:DerbyJMX#Resources:here] before you continue. 

You may access Derby's MBeans using for example an existing JMX client utility, such as JConsole,
or programmatically by writing your own Java code utilizing JMX.

== Enabling JMX ==

'''Note:''' In the following, ''local'' basically means ''on the same host (machine)'' and
''running as the same user''. For example, this means that local JMX access is possible only
if the JVM you want to access is running on the same host and as the same user as the user
running JConsole (or a different user with sufficient file system permissions). In order to
allow other users to access the JVM, or to allow access from other hosts, remote JMX must
be enabled.

=== Local JMX access ===

If you are using a Java SE 6 JVM, local JMX management and monitoring is most likely enabled
by default. 

Some JVMs, for example J2SE 5.0 JVMs, do not enable local JMX management by default. Refer
to the documentation for your JVM for details. It seems that the de-facto standard way to
enable (local) JMX access is to include `-Dcom.sun.management.jmxremote` on the command line
when starting the JVM.

=== Remote JMX access ===

Remote JMX management and monitoring is a powerful Java feature, letting you monitor a specific
JVM from a remote location. Enabling remote JMX requires explicit actions by the JVM administrator
(you), since it may involve exposing sensitive information about your JVM or application.

The most common way to enable remote JMX access to your JVM is to specify a TCP/IP port number
and some basic security (authentication, SSL  (Secure Sockets Layer)) settings when starting
the JVM. For a list of (seemingly de-facto standard) command line options (system properties)
and their meaning, refer to the [http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#gdeum
Java SE Monitoring and Management Guide], the [http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html
Platform Monitoring and Management guide for J2SE 5.0], or your JVM's documentation.

The following example starts the Derby Network Server on the command line with (insecure)
remote JMX management and Monitoring enabled, using the JVM from Sun's JDK 6. Password authentication
over SSL is enabled by default, but in this example these security features are disabled,
to keep the example simple. '''It is not recommended to disable authentication or SSL in production

java -Dcom.sun.management.jmxremote.port=9999
-jar lib/derbyrun.jar server start

Refer to the above mentioned documentation for information about enabling JMX security features.

=== Security policy ===

When starting the Derby Network Server from the command line, it installs a basic security
policy by default. This policy includes the required permissions to allow authenticated JMX
users to access Derby's MBeans. 

If you are using a custom security policy, refer to the [http://db.apache.org/derby/javadoc/publishedapi/
public API] of Derby's MBeans and Derby's template security policy file ($DERBY_HOME/demo/templates/server-policy)
for details about the permissions you may need to set to allow or restrict specific JMX access.
See also ["JMXSecurityExpectations"].

== Using JConsole to access Derby's MBeans ==

JConsole is a graphical JMX-compliant tool originally developed by Sun Microsystems, and is
available in recent versions of Sun's Java Development Kits (JDKs). JConsole enables you to
monitor and manage Java applications and virtual machines on a local or remote machine.

Note that you may use JConsole from JDK 6 even if you are running Derby using JDK 5.0 (or
just the JRE), or vice versa. It is recommended that you use the newest version possible.
More information about JConsole is available [http://www.openjdk.org/tools/svc/jconsole/index.html
in the Java SE Monitoring and Management Guide] and [http://openjdk.java.net/tools/svc/jconsole/
in the OpenJDK project].

=== Starting JConsole and connecting to Derby ===

In Sun's JDK 5.0 and JDK 6, the JConsole binary is available in the `bin` directory of `JDK_HOME`,
where `JDK_HOME` is the directory in which the JDK is installed. You can simply start JConsole
by running the `jconsole` executable, for example (Unix):

A graphical user interface (GUI) should appear. For additional startup options, refer to the
references mentioned above.
Once the GUI starts, you will be presented with a list of JVMs that are accessible on the
local host. Locate the JVM running Derby in that list and connect to it.
 * If you want to connect to a JVM on a remote host, you will need to supply the host name
and port number, or a JMX service URL, instead.
 * If you cannot find the Derby JVM running on the local host, make sure you are running JConsole
as the same user as the Derby JVM, or a different user with sufficient file system permissions.
Also make sure you have enabled JMX if using J2SE 5.0. When using Java SE 6, local JMX access
is enabled by default.

=== Accessing MBeans ===

Once connected to a JVM via JConsole, the JVM's MBeans should be available on a separate tab
in the internal JConsole window. Under the domain "org.apache.derby" you should see a list
of MBeans. Browse the MBeans and their attributes and operations by navigating the hierarchy

Below is a screenshot showing how JConsole (from JDK 6, monitoring the network server of Derby
10.4.1 beta) presents the attributes of the NetworkServerMBean.


Another useful JConsole feature is that you can view dynamic data represented as JMX attributes
as graphs. You may view these graphs by double clicking an attribute value that is a number
(in '''bold''' in the screenshot above). The partial screenshot below shows some of the attribute
values of the NetworkServerMBean as graphs, after the Network Server has been running with
some load.


== Accessing Derby's MBeans using custom Java code ==

Besides using generic tools as described above, it is also possible to access Derby's MBeans
programmatically, that is from a Java application. How to do this may depend on how you configure
the JVM running Derby, for example how you configure user authentication and authorization,
or from which host(s) you want to access the MBeans. 

Below is some example code which should help you get started. It is assumed that the client
JVM will be supporting J2SE 5.0 or newer (you will find the JMX classes you need in the packages
`javax.management` and `javax.management.remote`). Most examples include code which throws
exceptions that would have to be caught or re-thrown when appropriate (not shown).

''Note that you do '''not''' need any Derby libraries in the JMX client application's classpath
(unless MBean proxies are used)''.

=== Connecting to the MBean Server ===

Derby will attempt to register its MBeans with the Platform MBean Server of the JVM running
the Derby system (embedded or Network Server). The following examples assume that you have
configured the Derby JVM to enable remote JMX, which means that you have set a port number
(`com.sun.management.jmxremote.port`) to be used by the JMX Server Connector.

For local management, there may be alternative ways to access the MBean server; however this
outside the scope of this document.

The examples below assume that the port configured for remote JMX is `9999`, and that the
host name of the host running Derby is `derby.apache.org` and that this host is reachable
from the client host. (This host name is fictitious, and is used for example purposes only.)

'''The following example code shows how to connect to the MBean Server when JMX security has
been disabled:'''
    JMXServiceURL url = new JMXServiceURL(
    JMXConnector jmxc = JMXConnectorFactory.connect(url, null);
    MBeanServerConnection mbeanServerConn = jmxc.getMBeanServerConnection();

'''The following code shows how to connect to the MBean server when JMX password authentication
is enabled (default):'''
    JMXServiceURL url = new JMXServiceURL(
    // Assuming the following JMX credentials: username=controlRole, password=derby
    String[] credentials = new String[] { "controlRole" , "derby" };
    HashMap<String,Object> env = new HashMap<String,Object>();
    // Set credentials (jmx.remote.credentials, see JMX Remote API 1.0 spec section 3.4)
    env.put(JMXConnector.CREDENTIALS, credentials); 
    JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
    MBeanServerConnection mbeanServerConn = jmxc.getMBeanServerConnection();

=== Creating a ManagementMBean ===

The only Derby MBean that can be created by a JMX client is the `ManagementMBean`. This MBean
is useful for controlling Derby management (for example enabling and disabling management/MBeans),
and to obtain information such as the system identifier (may be needed to specify MBeans later).

If you create such an MBean from your application, and Derby has already registered a `ManagementMBean`
instance, the new MBean cannot have the same object name as the `ManagementMBean` already
registered with the server. It is therefore recommended to use different object name domain
(i.e. different from `org.apache.derby`) and/or a different `type` key property value (different
from `Management`).

'''The following example code shows how to create and register a new `ManagementMBean`with
the MBean server:'''
    ObjectName mgmtObjName = new ObjectName("com.somecompany.app", "type", "DerbyManagement");
    try {
        ObjectInstance mgmtObj = mbeanServerConn.createMBean("org.apache.derby.mbeans.Management",
    } catch (InstanceAlreadyExistsException e) {
        // A management MBean with this object name already exists!

=== Activating Derby management ===

Derby attempts to activate its JMX management service by default, so it will usually be active
unless you explicitly deactivate it, providing that Derby has permissions to do so. If Derby
management is not active, you will not be able to access any other MBeans but the `ManagementMBean`.

By accessing the attribute '''!ManagementActive''' of the `ManagementMBean`, you can check
whether Derby's JMX management service is active or not. 

'''The following example code checks if Derby's management service is active, and activates
it if it isn't:'''
    // assuming we already have a reference to the ManagementMBean's object name
    Boolean active = (Boolean) mbeanServerConn.getAttribute(mgmtObjName, "ManagementActive");
    if (!active.booleanValue()) {
        // start management
        mbeanServerConn.invoke(mgmtObjName, "startManagement", new Object[0], new String[0]);

=== Obtaining the system identifier ===

The system identifier is a unique String distinguishing one running Derby system from another.
All MBeans that are instantiated by Derby include the system identifier in their object names.

One way to access an MBean is to fully specify its object name when contacting the MBean server.
For this, you need to know the current system identifier. (Alternative ways to access MBeans
include querying the MBean server for all MBeans, or MBeans which object names match a specific

'''The following example shows how to obtain the system identifier by accessing a `ManagementMBean`:'''
    // assuming we already have a reference to the ManagementMBean's object name
    String systemID = (String) mbeanServerConn.getAttribute(mgmtObjName, "SystemIdentifier");

'''The following example shows how to obtain the system identifier from a Derby MBean's object
    // assuming we already have a reference to the ObjectName of an MBean registered by Derby,

    // for example the Derby-registered ManagementMBean
    String systemID = derbyMgmtObjectName.getKeyProperty("system");

=== Accessing a specific Derby-registered MBean ===

In the above examples you have already seen how to read a single MBean attribute, and how
to invoke an MBean operation. In order to do this, you usually need a reference to the MBean's

If you have access to the (Javadoc) [http://db.apache.org/derby/javadoc/publishedapi/jdbc4/
API of Derby's MBeans] as well as the [#SysID system identifier] of the Derby system you are
accessing through JMX, you have all the information you need to be able to instantiate an
`javax.management.ObjectName` object directly, by fully specifying its String representation
(see the `ObjectName API` for details).

'''This example code shows how to obtain a reference to the VersionMBean for derby.jar:'''
    // Assuming we already know the system idenfifier (see examples above), systemID.
    // A list of key properties is available is each MBean's Javadoc API.
    Hashtable<String, String> keyProps = new Hashtable<String, String>();
    keyProps.put("type", "Version");
    keyProps.put("jar", "derby.jar");
    keyProps.put("system", systemID);
    // MBeans registered by Derby always belong to the "org.apache.derby" domain
    ObjectName versionObjectName = new ObjectName("org.apache.derby", keyProps);

    // we can now use the object name to read an attribute
    String versionString = (String) mbeanServerConn.getAttribute(versionObjectName, "VersionString");
    System.out.println("VersionString: " + versionString);

Example output:
VersionString: - (645238)



View raw message