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 "DerbyJMX" by JohnHEmbretsen
Date Thu, 10 Apr 2008 09:29:21 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:
http://wiki.apache.org/db-derby/DerbyJMX

The comment on the change is:
Example Java code using JMX remote (client)

------------------------------------------------------------------------------
  
  == Accessing Derby's MBeans using custom Java code ==
  
- Add quick start info here...
+ 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. Most examples include code which throws exceptions
that would have to be caught or re-thrown when appropriate (not shown).
+ 
+ === 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:'''
+ {{{#!java
+     JMXServiceURL url = new JMXServiceURL(
+             "service:jmx:rmi:///jndi/rmi://derby.apache.org:9999/jmxrmi");
+     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):'''
+ {{{#!java
+     JMXServiceURL url = new JMXServiceURL(
+             "service:jmx:rmi:///jndi/rmi://derby.apache.org:9999/jmxrmi");
+     // 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:'''
+ {{{#!java
+     ObjectName mgmtObjName = new ObjectName("com.somecompany.app", "type", "DerbyManagement");
+     try {
+         ObjectInstance mgmtObj = mbeanServerConn.createMBean("org.apache.derby.mbeans.Management",
mgmtObjName);
+     } 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:'''
+ {{{#!java
+     // 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 pattern.)
+ 
+ '''The following example shows how to obtain the system identifier by accessing the `ManagementMBean`:'''
+ {{{#!java
+     // assuming we already have a reference to the ManagementMBean's object name
+     String sysID = (String) mbeanServerConn.getAttribute(mgmtObjName, "SystemIdentifier");
+ }}}
+ 
+ '''The following example shows how to obtain the system identifier from a Derby MBean's
object name:'''
+ {{{#!java
+     // assuming we already have a reference to the ObjectName of an MBean registered by
Derby, 
+     // for example the Derby-registered ManagementMBean
+     // TODO
+ }}}
+ 
+ 
+ In the above examples you have already seen how to read a single MBean attribute, and how
to invoke an MBean operation...
  ----
  
  [[AttachInfo]]

Mime
View raw message