Programming WebLogic Management Services with JMX
When you instantiate a WebLogic Server MBean, the MBean Server subsystem registers the instance under a name that conforms to the weblogic.management.WebLogicObjectName
conventions. These naming conventions create a hierarchical JMX namespace that you use when looking up MBeans. (For more information about the MBean Server subsystem, see MBean Servers and the MBeanHome Interface.)
The following sections describe the WebLogic Server management namespace:
WebLogicObjectName
is a subclass of javax.management.ObjectName
. To provide unique names for MBeans, all JMX object names consist of two parts:
For WebLogic Server MBeans, the JMX domain name is the name of the WebLogic Server domain in which the MBean resides.
For example, in a WebLogic Server domain named mydomain, all WebLogic Server MBean names start with the mydomain:
string and therefore are in the mydomain
JMX domain. If you create custom MBeans for your applications, you can add them to the mydomain:
JMX domain or create your own JMX domain.
The MBean's WebLogicObjectName
uses the following conventions to provide a unique identification for a given MBean:
domain
:Name=name
,Type=type
[,Location=
serverName
]
[,TypeOfParentMBean
=NameOfParentMBean
][,TypeOfParentMBean1
=NameOfParentMBean1
]...
The order of the attribute
=value
pairs is not significant, but the name must begin with domain
:
.
The following table describes each name component.
The name of the JMX domain. By convention, the JMX domain name for all WebLogic Server MBeans corresponds to the name of the WebLogic Server administration domain. |
|
The string that you provided when you created the resource that the MBean represents. For example, when you create a JDBC connection pool, you must provide a name for that pool, such as The If you create an MBean, you must specify a value for this |
|
Refers to the interface class of which the MBean is an instance. All WebLogic Server MBeans are an instance of one of the interface classes defined in the To determine the value that you provide for the 1. Find the MBean's interface class and remove the 2. For a Local Configuration MBean, append |
|
All Runtime and Local Configuration MBeans include a For example, for a server instance named myserver, there are two instances of Server
For information about accessing these MBean instances, see Determining Which Interfaces to Use.
|
|
To create a hierarchical namespace, Runtime, Local Configuration, or Administration MBeans use one or more instances of this attribute in their object names. The levels of the hierarchy are used to indicate scope. For example, a By convention, WebLogic Server child MBeans use the same value for the
WebLogic Server cannot follow this convention when a parent MBean has multiple children of the same type. Some MBeans use multiple instances of this component to provide unique identification. For example, the following is the The |
While the MBeans that you use to manage security providers use JMX object names, they do not use names of type weblogic.management.WebLogicObjectName
. Instead, the security providers that are included with WebLogic Server use the following JMX-compliant naming conventions:
Security:Name=
realmNameProviderName
In this convention, Security:
is the name of the JMX domain, realmName
is the name of a security realm and ProviderName
is the name that you give to the security provider. For example, the name of the MBean for the authentication provider that WebLogic Server installs is Security:Name=myrealmDefaultAuthenticator
.
BEA recommends that you follow this convention for any additional security providers that you configure. If you use the Administration Console to add a security provider to the realm, your security-provider MBean names will follow the recommended naming convention.
For more information about security providers, see Developing Security Providers for WebLogic Server.
System administrators frequently use JMX APIs, the weblogic.Admin
utility, or the wlconfig
Ant task to automate the creation of resources within a WebLogic Server domain. To successfully configure these resources, you must create Administration MBeans and locate them within the namespace hierarchy.
Note: The management namespace for Local Configuration MBeans and Runtime MBeans is also hierarchical; however, because system administrators infrequently use APIs or other command-line utilities to access these types of MBeans, their namespace is not documented.
The following sections describe the namespace for the Administration MBeans that configure many WebLogic Server resources and server attributes:
Note: With the exception of DomainMBean
, all MBeans are direct or indirect children of the domain's DomainMBean
. Because this parent-child relationship applies to all MBeans, it is not expressed in MBean object names.
A WebLogic Server instance uses attributes from several MBeans to determine how it communicates with clients and other servers. Table 3-2 introduces the MBeans and Figure 3-1 illustrates the namespace in the sample MedRec domain.
Listen address, listen port, and enables protocols and tunneling. See |
|
See |
|
See |
|
See |
|
See |
|
Arguments that a Node Manager uses to start this server instance. See |
|
Additional network connections (network channel). See |
|
Host names to which the server responds. See |
Figure 3-1 MBean Namespace for Server Communication and Protocols
Within a WebLogic Server domain, several MBeans configure logging services. Table 3-3 introduces the MBeans and Figure 3-2 illustrates the namespace in the sample MedRec domain.
Log file names and rotation criteria. The Administration Server maintains an instance of See |
|
A domain log filter, which determines which messages a server instance sends to the domain-wide message log. Each domain log filter is represented by its own instance of See |
|
JDBC and JTA logging. Also determines which domain log filter the server instance uses. See |
|
See |
When you target and deploy J2EE modules (enterprise applications, Web applications, or EJBs), WebLogic Server creates MBeans for managing the module's configuration.
In addition, WebLogic Server creates MBeans for the startup classes and shutdowns classes that you configure and target. Table 3-4 introduces the MBeans and Figure 3-3 illustrates the namespace in the sample MedRec domain.
A startup class and the server instances to which the class is targeted. See |
|
A shutdown class and the server instances to which the class is targeted. See |
|
Deployment options for the Web applications and EJBs that it contains. Each application is managed by its own instance of See |
|
See |
|
Location and deployment information for all EJBs in an EJB JAR file. See |
Within a WebLogic Server domain, each security realm is managed by its own instance of RealmMBean
and several MBeans for the security providers that are configured for the realm.
Because each security realm can be customized, the weblogic.management.security.RealmMBean
and security-provider MBeans occupy a separate management namespace from all other WebLogic Server MBeans. In addition, while the RealmMBean
and security-provider MBean names are valid JMX object names, they do not follow WebLogicObjectName
conventions. Instead, BEA recommends the following naming convention for any security realm and security-provider MBeans you create:
Security:
realmnameProviderName
If you use the Administration Console to configure your realm and security providers, the MBean names follow the recommended convention.
In addition to realm and security-provider MBeans, a WebLogic Server domain uses the MBeans in Table 3-5 to configure security. These MBeans are in the same namespace as other WebLogic Server MBeans.
Domain-wide security configuration information. See |
|
The security realm, password policy, and connection filter that the domain uses. See |
|
This |
Figure 3-4 illustrates the security namespace in the sample MedRec domain. The security realm and providers in Figure 3-4 are those that WebLogic Server installs by default. In a domain that you create, your security namespace might look different depending on the realm and security providers that you configure.
WebLogic Server uses several MBeans to provide a management interface for JDBC services. The names of JDBC MBeans do not reflect a hierarchy because all JDBC MBeans are direct children of the DomainMBean
. Table 3-6 introduces the MBeans and Figure 3-5 illustrates the namespace in the sample MedRec domain. Figure 3-5 adds MBeans for the JDBC features that the MedRec domain does not use.
See |
|
A JDBC multipool, which is a pool of JDBC connection pools. See |
|
A non-transactional data source. See |
|
See |
WebLogic Server uses several MBeans to provide a management interface for its JMS services. Table 3-7 introduces the MBeans and Figure 3-6 illustrates the namespace in the sample MedRec domain.
See |
|
A JMS queue (Point-To-Point) destination for a JMS server. See |
|
A JMS topic (Pub/Sub) destination for a JMS server. See |
|
A server-managed pool of server sessions that enables an application to process messages concurrently. See |
|
A JMS connection consumer, which is a JMS destination (queue or topic) that retrieves server sessions and processes messages. See |
|
A JMS connection factory, which enables JMS clients to create JMS connections. See |
|
A JMS JDBC store for storing persistent messages and durable subscribers in a JDBC-accessible database. See |
|
A disk-based JMS file store that stores persistent messages and durable subscribers in a file-system directory. See |
|
A key value for a destination, which is used to define the sort order of messages as they arrive on a destination. See |
WebLogic Server uses several MBeans to provide a management interface for clusters and cluster-related resources. Table 3-8 introduces the MBeans and Figure 3-7 illustrates the namespace in the sample MedRec domain.
A representation of the WebLogic Server host on which a cluster member runs. Clusters use machines to determine default failover behavior. See |
|
Cluster address and multicast settings. See |
|
An individual server instance. See |
|
Host names to which the cluster responds. See |
If your domain consists of multiple server instances running on multiple WebLogic Server host computers, you can use machines and Node Manager to facilitate managing the life cycle of servers. WebLogic Server uses several MBeans to provide a management interface for machines and Node Managers. Table 3-9 introduces the MBeans and Figure 3-8 illustrates the namespace in the sample MedRec domain.
A representation of the WebLogic Server host on which a server instance runs. See |
|
Listen address, listen port, and security information that a server instance uses to communicate with a Node Manager running on a specific machine. See |
|
Information that a Node Manager uses to start a Managed Server instance. See |
Figure 3-8 Machines and Node Manager MBeans
If you are unsure which values to supply for an MBean's WebLogicObjectName
, you can use the weblogic.Admin
utility to find the WebLogicObjectName
. The utility can return information only for WebLogic Server MBeans that are on an active server instance.
For example, to find the WebLogicObjectName
for the Administration instance of the LogMBean
in the medrec
domain, enter the following command on the MedRecServer
Administration Server, where the Administration Server is listening on port 8001 and weblogic
is the name and password of a user who has permission to view MBean attributes:
java weblogic.Admin -url localhost:8001 -username weblogic -password weblogic GET -pretty -type Log
The command returns the output in Listing 3-1. Notice that the command returns two MBeans of type Log
on the Administration Server. The first MBean, medrec:Name=MedRecServer,Server=MedRecServer,Type=Log
, has a child relationship with the ServerMBean
of MedRecServer
; this relationship indicates that the MBean is the LogMBean
that configures the server-specific log file. The second MBean, medrec:Name=medrec,Type=Log
, has no child relationship, which indicates that it configures the domain-wide log file.
The -pretty
causes the weblogic.Admin
utility to place each MBean attribute and value on a separate line. Without this argument, the utility surrounds each attribute/value pair with curly braces {}
, but all output is on a single line.
Listing 3-1 Output from weblogic.Admin
---------------------------
MBeanName: "medrec:Name=MedRecServer,Server=MedRecServer,Type=Log"
CachingDisabled: true
FileCount: 7
FileMinSize: 500
FileName: MedRecServer\MedRecServer.log
FileTimeSpan: 24
Name: MedRecServer
Notes:
NumberOfFilesLimited: false
ObjectName: MedRecServer
Registered: false
RotationTime: 00:00
RotationType: none
Type: Log
---------------------------
MBeanName: "medrec:Name=medrec,Type=Log"
CachingDisabled: true
FileCount: 7
FileMinSize: 500
FileName: ./logs/wl-domain.log
FileTimeSpan: 24
Name: medrec
Notes:
NumberOfFilesLimited: false
ObjectName: medrec
Registered: false
RotationTime: 00:00
RotationType: none
Type: Log
To view the Local Configuration MBean instances of LogMBean
, append Config
to the value of the type
argument:
java weblogic.Admin -url localhost:8001 -username weblogic -password weblogic GET -pretty -type LogConfig
The command returns output in Listing 3-2. Notice that the WebLogicObjectName
of the Local Configuration MBeans includes a Location
component.
Listing 3-2 Local Configuration MBeans
---------------------------
MBeanName: "medrec:Location=MedRecServer,Name=MedRecServer,ServerConfig=MedRecServer,Type=LogConfig"
CachingDisabled: true
FileCount: 7
FileMinSize: 500
FileName: MedRecServer\MedRecServer.log
FileTimeSpan: 24
Name: MedRecServer
Notes:
NumberOfFilesLimited: false
ObjectName: MedRecServer
Registered: false
RotationTime: 00:00
RotationType: none
Type: LogConfig
---------------------------
MBeanName: "medrec:Location=MedRecServer,Name=medrec,Type=LogConfig"
CachingDisabled: true
FileCount: 7
FileMinSize: 500
FileName: ./logs/wl-domain.log
FileTimeSpan: 24
Name: medrec
Notes:
NumberOfFilesLimited: false
ObjectName: medrec
Registered: false
RotationTime: 00:00
RotationType: none
Type: LogConfig
If you are unsure which values to supply for a security MBean's object name, you can use the weblogic.Admin QUERY
command to retrieve the object name. The domain in which the security MBean exists must be active.
If you followed the recommended naming convention, or if you used the Administration Console to create the security MBean, you can use the following command to list all security MBeans in a domain:
java weblogic.Admin -url localhost:8001 -username weblogic -password weblogic QUERY -pretty -pattern Security:*
Otherwise, you can use other forms of the QUERY
command to find MBean names. See "QUERY" in WebLogic Server Command Reference.