|
|
|
|
| |
Programming WebLogic Server MBeans
Using the J2EE Java Management Extensions (JMX) specification with the WebLogic Server Management API, developers can create and deploy Management Beans (or MBeans) to extend and customize WebLogic Server.
Configuration is done using MBeans, which retrieve their values from the domain configuration and state. MBeans provide developers with a way to programmatically access all configuration and monitoring information about WebLogic Server via the JMX standard API. Using this JMX specification with the WebLogic Server Management API, developers can create and deploy MBeans to extend and customize WebLogic Server. WebLogic Server MBeans also provide management access to domain resources.
WebLogic Server MBeans are based on JMX extensions for server configuration and server runtime data. For the MBean interfaces that are exposed by JMX, see the WebLogic Server Management API.
The following sections describe how to program WebLogic Server MBeans:
For documentation describing the WebLogic Server architecture and management services, see the WebLogic Server Administration Guide. The Administration Server must be running in order to perform any kind of management operation. For details on how to start and stop the server, see the WebLogic Server Administration Guide section, "Starting and Stopping WebLogic Servers."
For additional information, see the WebLogic Server Programming Guides.
Programming Client Access to WebLogic MBeans
Two interfaces are used to provide client access to MBeans:
MBeanServer and MBeanHome provide access to the same set of MBeans in a given server. Each server in a domain contains an MBeanHome (and a corresponding MBeanServer), which hosts configuration and run-time MBeans on that server. In addition, the Administration server has an administration MBeanHome that provides access to all MBeans in the entire domain The Administration MBeans reside only in the Administration Server, and are only available through the Administration MBeanHome. For example, a query for server run-time MBeans on the Admiinistration MBeanHome returns one server MBean for each running server in the domain. The same query on the MBeanHome of a managed server (or the regular MBeanHome of the Administration Server) returns only the server run-time MBean for that managed server.
Getting MBeanServer and MBeanHome
The MBeanHome of any server is available from the relevant server's JNDI tree at:
weblogic.management.MBeanHome.JNDI_NAME.relevantserverName
An Administration server publishes an MBeanHome for each server in the domain on its JNDI tree. The administration MBeanHome is available only from the JNDI tree of the Administration server at:
weblogic.management.MBeanHome.ADMIN_JNDI_NAME
The underlying MBeanServer for any MBeanHome can be obtained by invoking the getMBeanServer() method on that MBeanHome.
The following is an example of a JNDI lookup for an Administration server MBeanHome:
import javax.naming.Context;
import javax.naming.NamingException;
import javax.naming.AuthenticationException;
import javax.naming.CommunicationException;
import weblogic.jndi.Environment; ...
import weblogic.management.MBeanHome;
...
String url = "t3://localhost:7001"; //URL of the Administration server
String username = "guest"; //Only works if guest logins are enabled
String password = "guest";
MbeanHome home = null;
try {
Environment env = new Environment();
env.setProviderUrl(URL);
env.setSecurityPrincipal(username);
env.setSecurityCredentials(password);
ctx = env.getInitialContext();
home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
}
catch (AuthenticationException e) {
... //Error handling
} catch (CommunicationException e) {
... //Error handling
} catch (NamingException e) {
... //Error handling
}
The WebLogic Server Management API distinguishes between three types of MBeans:
All MBeans have a name, a type and a domain. These attributes are reflected in the MBean's JMX Object Name. The Object Name is the unique identifier for a given MBean across all domains, and has the following structure:
domain name:Name=name,Type=type[,attr=value]...
Name is a name that is unique for a given domain and a given type. Examples of type include Server, WebComponent or JDBCConnectionPoolRuntime. Type is used to distinguish between the various types of MBeans; for example, the value of Type for a Server MBean is:
Note that the "MBean" suffix is removed from the MBean interface name to get the base type of an MBean. Therefore, Config or Runtime suffices are added to the base name (Server) to distinguish configuration and run-time MBeans from administration MBeans.
Specific MBean types have additional components. All run-time and configuration MBeans have a Location component that uses the name of the server on which that MBean is located as its value. For example:
mydomain:Name=myServlet,Type=ServletRuntime,Location=myserver
Any MBean which has a child relationship with another parent MBean, has an extra attribute in its object name in the following format: TypeOfParentMBean=NameOfParentMBean. In the following example, Server is the type of Parent MBean, and myserver is the name of the Parent MBean:
mydomain:Name=mylog,Type=Log,Server=myserver
All interface types for administration or configuration MBeans are located in the weblogic.management.configuration API.
All interfaces types for run-time MBeans are located in the weblogic.management.runtime API.
A WebLogic client can set up monitors to monitor MBean properties. The various monitors are defined in the JMX documentation for the package javax.management.monitor, and are as follows: CounterMonitor, GaugeMonitor, StringMonitor. Without repeating the details available in the JMX documentation, the following is an example of how to set up a counter monitor for receiving JMX Notifications.
The following code example is a simple implementation of CounterListener:
public class CounterListener implements RemoteNotificationListener {
public void handleNotification(Notification p1,java.lang.Object p2){
System.out.println(">>><<<<<<---->GotNotified!!" + p1.toString());
}
}
(CounterListener), and create a Monitor object (CounterMonitor).
RemoteMBeanServer rmbs = mbHome.getMBeanServer();
CounterMonitor monitor = new CounterMonitor();
CounterListener listener = new CounterListener();
. . .
Then set up the Listener on the Monitor. A simple implementation example follows:
ObjectName monitorObjectName = new WebLogicObjectName("mydomain:Type=CounterMonitor,Name=MyCounter");
rmbs.registerMBean((Object)monitor, monitorObjectName);
ObjectName securityRtObjectName = new WebLogicObjectName("mydomain:Name=myserver,Location=myserver,
Type=ServerSecurityRuntime");
rmbs.setAttribute(monitorObjectName, new Attribute("Threshold",
new Integer(5)));
rmbs.setAttribute(monitorObjectName, new Attribute("Offset", new Integer(0)));
rmbs.setAttribute(monitorObjectName, new Attribute("GranularityPeriod",
new Long(5000)));
rmbs.setAttribute(monitorObjectName, new Attribute("ObservedObject",
securityRtObjectName));
rmbs.setAttribute(monitorObjectName, new Attribute("ObservedAttribute",
"InvalidLoginAttemptsTotalCount"));
rmbs.addNotificationListener(monitorObjectName,listener, null, null);
java -classpath $CLASSPATH\;. weblogic.rmic -keepgenerated
-compiler sj -d $WL_HOME/classes -classpath $CLASSPATH\;.
-d $CLASSOUTDIR -keepgenerated
-nomanglednames CounterListener
See also Programming WebLogic RMI.
Note: For an overview of JMX notifications and how they work, see the Sun Microsystems J2EE JMX specification.
A WebLogic client can set up notification listeners to listen for WebLogic Server events. These notifications are generated when you attempt to add or remove a collection attribute. For example, you would get the appropriate notification if addSomeCollection or removeSomeCollection were called for an MBean.
The following notification methods are generated from the server:
MBeans are notification broadcasters, which makes it possible for a client to set up a notification listener on any WebLogic Server MBean using the following API:
javax.management.NotificationBroadcaster.AddNotificationListener()
An example implementation of a notification listener follows:
import javax.management.NotificationLister;
import javax.management.Notification;
import javax.management.Notification.AttributeChangeNotification;
import weblogic.management.RemoteNotificationListener;
class FooListener implements RemoteNotificationListener {
public void handleNotification(Notification n, Object hb) {
if (notification instanceof AttributeChangeNotification) {
AttributeChangeNotification acn = (AttributeChangeNotification)n;
if ("Bar".equals(acn.getAttributeName())) {
BarMBean oldValue = (BarMBean)acn.getOldValue();
BarMBean newValue = (BarMBean)acn.getNewValue();
// do my thing
}
}
}
}
Writing Custom Notifications for WebLogic Server Error Messages
Note: For an overview of JMX notifications and how they work, see the Sun Microsystems J2EE JMX specification.
WebLogic Server can send JMX notifications for log messages. Users code can create NotificationListeners that can receive selective log messages as a notification based on a user-defined NotificationFilter; for example, certain log messages might need to be written or sent to an additional destination such as an RDBMS or an enterprise management console, or paged to an administrator.
Registering a Notification Listener for Log Notifications
You use published JMX interfaces to register a notification listener to the JMX notification broadcaster (LogBroadcasterRuntimeMBean) provided by the WebLogic Server logging system. LogBroadcasterRuntimeMBean is only responsible for generating notifications for log messages generated by the server. All notifications generated are of the type WebLogicLogNotification. There is only one LogBroadcasterRuntimeMBean per server, named TheLogBroadcaster, of the type LogBroadcasterRuntime. As defined in the JMX specification, the user can also provide a customized filter at the time of registration.
The LogBroadcasterRuntimeMBean can be fetched using the mechanisms described in " Writing Custom Notifications for WebLogic Server Error Messages." The following example shows a simple implementation of the registration of a notification listener.
...
WebLogicObjectName oname = new WebLogicObjectName("mydomain:Name=TheLogBroadcaster,
Type=LogBroadcasterRuntime,Location=myserver");
logBroadcaster = (LogBroadcasterRuntimeMBean) mbeanhome.getMBean(oname);
ANotificationFIlter filter = new ANotificationFIlter();
logBroadcaster.addNotificationListener(this, filter, null);
...
Contents of a Log Notification
A JMX notification contains the following fields:
'weblogic.logMessage.subSystem.messageID'
All log notifications are of the type WebLogicLogNotification. The class interface provides getters for all individual fields of a message. This eases the filtering of log notifications when filtering messages based on their severity, user ID, subystem, and other fields. The following NotificationFilter example implementation only selects messages of a specific message ID (111000) to be sent as notifications.
import weblogic.management.logging.WebLogicLogNotification;
import javax.management.NotificationFilter;
....
class ALogNotificationFilter
implements NotificationFilter, java.io.Serializable {
public boolean isNotificationEnabled(Notification notif) {
WebLogicLogNotification wln = (WebLogicLogNotification) notif;
return(wln.getMessageId() == 111000);
}
}
The WebLogic Server Management API is fully documented online in JavaDocs. For additional information, see the WebLogic Server Programming Guides.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|