Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Management Services with JMX

# WebLogic Server Management Namespace

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:

- Conventions for WebLogicObjectName
- Conventions for Security-Provider MBean Names
- Locating Administration MBeans Within the Namespace
- Using weblogic.Admin to Find the WebLogicObjectName
- Using weblogic.Admin to Find the Name of a Security Provider MBean

# Conventions for WebLogicObjectName

`WebLogicObjectName` is a subclass of `javax.management.ObjectName`. To provide unique names for MBeans, all JMX object names consist of two parts:

- A JMX domain name, which is a case-sensitive string that defines a top level within the JMX namespace.

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.

- An unordered set of one or more name-value pairs (key properties).

The key properties create unique object names within a given JMX domain. They do not need to reflect attributes within the MBean that they name.

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.

Table 3-1 WebLogic Server MBean Naming Conventions

This Component | Specifies
--- | ---
`domain``:` | 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.
`Name`=`name` | 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 `MyPool1`. The `JDBCConnectionPoolMBean` that represents `MyPool1` uses Name=`MyPool1` in its JMX object name. The `WebLogicObjectName.getName` method returns this value for any given MBean. If you create an MBean, you must specify a value for this `Name` component that is unique amongst all other MBeans in a domain.
`Type=``type` | 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 `weblogic.management.configuration` or `weblogic.management.runtime` packages. For Configuration MBeans, `Type` also refers to whether an instance is an Administration MBean or a Local Configuration MBean. For a complete list of all WebLogic Server MBean interface classes, refer to the WebLogic Server Javadoc for the `weblogic.management.configuration` or `weblogic.management.runtime` packages. To determine the value that you provide for the `Type` component: 1. Find the MBean's interface class and remove the `MBean` suffix from the class name. For example, for an MBean that is an instance of the `weblogic.management.runtime.JDBCConnectionPoolRuntime MBean`, use `JDBCConnectionPoolRuntime`. 2. For a Local Configuration MBean, append `Config` to the name. For example, for a Local Configuration MBean that is an instance of the `weblogic.management.configuration.JDBCConnectionPool MBean` interface class, use `JDBCConnectionPoolConfig`. For the corresponding Administration MBean instance, use `JDBCConnectionPool`.
> `Location=``servername` | All Runtime and Local Configuration MBeans include a `Location` component that specifies the name of the server on which that MBean is located. Administration MBeans do not include this component. For example, for a server instance named myserver, there are two instances of Server`MBean`: The Administration MBean, whose object name is `mydomain:Name=myserver,Type=Server` The Local Configuration MBean, whose object name is: `mydomain:Name=myserver,Type=Server,Location=myserver` For information about accessing these MBean instances, see Determining Which Interfaces to Use.
>     The WebLogicObjectName.getLocation method returns this value for any given MBean.
`TypeOfParentMBean`= `NameOfParentMBean` | 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 `LogMBean` at the domain level of the hierarchy manages the domain-wide message log, while a `LogMBean` at a server level manages a server-specific message log. By convention, WebLogic Server child MBeans use the same value for the `Name` component as the parent MBean. For example, the `LogMBean` that is a child of the `MedRecServer` `Server` MBean uses `Name=MedRecServer` in its `WebLogicObjectName`: `medrec:Name=MedRecServer,Type=Log` 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 `WebLogicObjectName` for an `EJBComponentRuntime` MBean for in the MedRec sample application: `medrec:ApplicationRuntime=MedRecServer_MedRecEAR, Location=MedRecServer,Name=MedRecServer_MedRecEAR_Session EJB,ServerRuntime=MedRecServer,Type=EJBComponentRuntime` The `ApplicationRuntime=MedRecServer_MedRecEAR` attribute/value pair indicates that the EJB instance is a module within the MedRec enterprise application and a child of the `MedRecServer_MedRecEAR` ApplicationRuntimeMBean. The `ServerRuntime=MedRecServer` attribute/value pair indicates that the EJB instance is currently deployed on a server named MedRecServer and a child of the `MedRecServer` ServerRuntimeMBean. See: Locating Administration MBeans Within the Namespace Using weblogic.Admin to Find the WebLogicObjectName

# Conventions for Security-Provider MBean Names

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.

# Locating Administration MBeans Within the Namespace

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:

- Server Communication and Protocols Configuration Namespace
- Domain and Server Logging Configuration Namespace
- Applications Configuration Namespace
- Security Configuration Namespace
- JDBC Configuration Namespace
- JMS Configuration Namespace
- Clusters Configuration Namespace
- Machines and Node Manager Configuration Namespace

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.

## Server Communication and Protocols Configuration Namespace

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.

Table 3-2 MBeans for Server Communication and Protocols

This MBean... | Configures...
--- | ---
`ServerMBean` | Listen address, listen port, and enables protocols and tunneling. See `ServerMBean` Javadoc.
`SSLMBean` | The SSL protocol. See `SSLMBean` Javadoc.
`IIOPMBean` | The IIOP protocol. See `IIOPMBean` Javadoc.
`COMMBean` | The COM protocol. See `COMMBean` Javadoc.
`WebServerMBean` | The HTTP and HTTPS protocols. See `WebServerMBean` Javadoc.
`ServerStartMBean` | Arguments that a Node Manager uses to start this server instance. See `ServerStartMBean` Javadoc.
`NetworkAccessPointMBean` | Additional network connections (network channel). See `NetworkAccessPointMBean` Javadoc.
`VirtualHostMBean` | Host names to which the server responds. See `VirtualHostMBean` Javadoc.

Figure 3-1 MBean Namespace for Server Communication and Protocols

## Domain and Server Logging Configuration Namespace

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.

Table 3-3 MBeans for Domain and Server Logging

This MBean... | Configures...
--- | ---
`LogMBean` | Log file names and rotation criteria. The Administration Server maintains an instance of `LogMBean` for the domain-wide message log, and each server instance maintains its own instance for its local server log. See `LogMBean` Javadoc.
`DomainLogFilterMBean` | 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 `DomainLogFilterMBean`. See `DomainLogFilterMBean` Javadoc.
`ServerMBean` | JDBC and JTA logging. Also determines which domain log filter the server instance uses. See `ServerMBean` Javadoc.
`WebServerMBean` | Logging HTTP requests. See `WebServerMBean` Javadoc.

Figure 3-2 Logging MBeans

## Applications Configuration Namespace

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.

Table 3-4 MBeans for Applications

This MBean... | Configures...
--- | ---
`StartupClassMBean` | A startup class and the server instances to which the class is targeted. See `StartupClassMBean` Javadoc.
`ShutdownClassMBean` | A shutdown class and the server instances to which the class is targeted. See `ShutdownClassMBean` Javadoc.
`ApplicationMBean` | Deployment options for the Web applications and EJBs that it contains. Each application is managed by its own instance of `ApplicationMBean`. See `ApplicationMBean` Javadoc.
`WebAppComponentMBean` | A Web application. See `WebAppComponentMBean` Javadoc.
`EJBComponentMBean` | Location and deployment information for all EJBs in an EJB JAR file. See `EJBComponentMBean` Javadoc.

Figure 3-3 Application MBeans

## Security Configuration Namespace

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.

Table 3-5 MBeans for Security

This MBean... | Configures...
--- | ---
`SecurityMBean` | Domain-wide security configuration information. See `SecurityMBean` Javadoc.
`SecurityConfigurationMBean` | The security realm, password policy, and connection filter that the domain uses. See `SecurityConfigurationMBean` Javadoc.
`weblogic.management.configuration.RealmMBean` | This `RealmMBean`, which is in a different package from the `weblogic.management.security.RealmMBean` described above, is deprecated and used to configure realms that use compatibility security.

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.

Figure 3-4 Security MBeans

## JDBC Configuration Namespace

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.

Table 3-6 MBeans for JDBC

This MBean... | Configures...
--- | ---
`JDBCConnectionPoolMBean` | A JDBC connection pool. See `JDBCConnectionPoolMBean` Javadoc.
`JDBCMultiPool` | A JDBC multipool, which is a pool of JDBC connection pools. See `JDBCMultiPool` Javadoc.
`JDBCDataSource` | A non-transactional data source. See `JDBCDataSource` Javadoc.
`JDBCTxDataSource` | A transactional data source. See `JDBCTxDataSource` Javadoc.

Figure 3-5 JDBC MBeans

## JMS Configuration Namespace

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.

Table 3-7 MBeans for JMS

This MBean... | Configures...
--- | ---
`JMSServerMBean` | A JMS server. See `JMSMBean` Javadoc.
`JMSQueueMBean` | A JMS queue (Point-To-Point) destination for a JMS server. See `JMSQueueMBean` Javadoc.
`JMSTopicMBean` | A JMS topic (Pub/Sub) destination for a JMS server. See `JMSTopicMBean` Javadoc.
`JMSSessionPoolMBean` | A server-managed pool of server sessions that enables an application to process messages concurrently. See `JMSSessionPoolMBean` Javadoc.
`JMSConnectionConsumerMBean` | A JMS connection consumer, which is a JMS destination (queue or topic) that retrieves server sessions and processes messages. See `JMSConnectionConsumerMBean` Javadoc.
`JMSConnectionFactoryMBean` | A JMS connection factory, which enables JMS clients to create JMS connections. See `JMSConnectionFactoryMBean` Javadoc.
`JMSJDBCStoreMBean` | A JMS JDBC store for storing persistent messages and durable subscribers in a JDBC-accessible database. See `JMSJDBCStoreMBean` Javadoc.
`JMSFileStoreMBean` | A disk-based JMS file store that stores persistent messages and durable subscribers in a file-system directory. See `JMSFileStoreMBean` Javadoc.
`JMSDestinationKeyMBean` | A key value for a destination, which is used to define the sort order of messages as they arrive on a destination. See `JMSDestinationKeyMBean` Javadoc.

Figure 3-6 JMS MBeans

## Clusters Configuration Namespace

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.

Table 3-8 MBeans for Clusters

This MBean... | Configures...
--- | ---
`MachineMBean` | A representation of the WebLogic Server host on which a cluster member runs. Clusters use machines to determine default failover behavior. See `MachineMBean` Javadoc.
`ClusterMBean` | Cluster address and multicast settings. See `ClusterMBean` Javadoc.
`ServerMBean` | An individual server instance. See `ServerMBean` Javadoc.
`VirtualHostMBean` | Host names to which the cluster responds. See `VirtualHostMBean` Javadoc.

Figure 3-7 Cluster MBeans

## Machines and Node Manager Configuration Namespace

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.

Table 3-9 MBeans for Machines and Node Manager

This MBean... | Configures...
--- | ---
`MachineMBean` | A representation of the WebLogic Server host on which a server instance runs. See `MachineMBean` Javadoc.
`NodeManagerMBean` | Listen address, listen port, and security information that a server instance uses to communicate with a Node Manager running on a specific machine. See `NodeManagerMBean` Javadoc.
`ServerStartMBean` | Information that a Node Manager uses to start a Managed Server instance. See `ServerStartMBean` Javadoc.

Figure 3-8 Machines and Node Manager MBeans

# Using weblogic.Admin to Find the WebLogicObjectName

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

# Using weblogic.Admin to Find the Name of a Security Provider MBean

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.