Programming WebLogic Management Services with JMX

Accessing and Changing Configuration Information

Configuration MBeans on the Administration Server (Administration MBeans) configure the managed resources on all WebLogic Server instances in a domain. To enhance performance, each server instance creates and uses local replicas of the Administration MBeans. These local replicas are called Local Configuration MBeans.

Note: While you can view the values of Local Configuration MBeans, BEA recommends that you do not change attribute values in Local Configuration MBeans. Instead, change only the values of Administration MBean attributes. When the Managed Server replicates the data of other Managed Servers, it uses the values that are stored in Administration MBeans. Communication problems can occur if the values in Administration MBeans and Local Configuration MBeans differ.

The following sections provide examples for programmatically viewing and modifying the configuration of WebLogic Server resources using the weblogic.Admin utility, the JMX MBeanServer APIs, and the WebLogic Server type-safe interface:

Example: Using weblogic.Admin to View the Message Level for Standard Out

This example uses the weblogic.Admin utility to connect directly to a Managed Server and look up the value of its StdoutSeverityLevel attribute. This attribute, which belongs to the server's ServerMBean, specifies a threshold for determining which severity-level of messages a server prints to its standard out.

While BEA recommends that you use only Administration MBeans to change values, there might be situations in which it is preferable to look up the values that are in Local Configuration MBeans. For example, the Administration Server might be down, making it impossible for you to access Administration MBeans.

The example command:

Uses the -url argument to connect to a Managed Server that runs on a host named myHost and that listens on port 8001.

Uses the -username and -password arguments to specify the credentials of a user who has permission to view MBean attributes. For information about permissions to view and modify MBeans, refer to "Security Roles" in the Securing WebLogic Resources guide.

Uses the GET command to retrieve a Local Configuration MBean.

To specify a Local Configuration MBean, it removes MBean and appends Config to the ServerMBean interface name. Note that the -type value for a Local Configuration instance of the ServerMBean is ServerConfig while the -type value for the corresponding Administration MBean instance is Server. For more information, refer to the description of Type in Table 3-1.

Listing 4-1 Configuring the Message Level

java weblogic.Admin -url myHost:8001 -username weblogic -password weblogic 
GET -pretty -type ServerConfig

---------------------------
MBeanName: "medrec:Location=MedRecServer,Name=MedRecServer,Type=ServerConfig"
        AcceptBacklog: 50
        AdministrationPort: 0
...

        StdoutDebugEnabled: false
        StdoutEnabled: true
        StdoutFormat: standard
        StdoutLogStack: true
        StdoutSeverityLevel: 16

Example: Configuring the Message Level for Standard Out

The class in this example changes the value of the StdoutSeverityLevel attribute in the weblogic.management.configuration.ServerMBean to change the level of messages that a server instance named MedRecServer sends to standard out.

Because the example is changing configuration values, it changes the value in the Administration MBean and relies on the WebLogic management services to propagate the change to the Managed Server.

The example class:

Uses JNDI to look up the Administration MBeanHome interface on the Administration Server.

Uses the MBeanHome.getMBean(String name, String type) API to retrieve the type-safe interface of the ServerMBean Administration MBean for a server instance named Server1.

Uses the type-safe interface to invoke the ServerMBean.setStdoutSeverityLevel method and set the severity level to 64.

In the example, weblogic is a user who has permission to view and modify MBean attributes. For information about permissions to view and modify MBeans, refer to "Security Roles" in the Securing WebLogic Resources guide.

Listing 4-2 Configuring Standard Out Severity Level

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.Context;
import javax.management.MBeanServer;
import javax.management.Attribute;
import java.lang.Object;

import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.configuration.ServerMBean;

public class ChangeStandardOut1 {

    public static void main(String[] args) {
        MBeanHome home = null;
        ServerMBean server = null;
        //domain variables
        String url = "t3://localhost:7001";
        String username = "weblogic";
        String password = "weblogic";
        String serverName = "Server1";

        //setting the initial context
        try {
            Environment env = new Environment();
            env.setProviderUrl(url);
            env.setSecurityPrincipal(username);
            env.setSecurityCredentials(password);
            Context ctx = env.getInitialContext();

            //getting the Administration MBeanHome
            home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);

            // Using MBeanHome.getMBean(name, type) to retrieve a type-safe
            // interface for a ServerMBean
            server = (ServerMBean)home.getMBean(serverName,"Server");

            // Using ServerMBean.setStdoutSeverityLevel
            server.setStdoutSeverityLevel(64);

            //  Providing feedback that operation succeeded.
            System.out.println("Changed standard out severity level to: " +
                                 server.getStdoutSeverityLevel());
        } catch (Exception e) { 
            System.out.println("Caught exception: " + e);
        }
    }
}

Setting and Getting Encrypted Values

To prevent unauthorized access to sensitive data such as passwords, some attributes in configuration MBeans are encrypted. The attributes persist their values in the domain's config.xml file as an encrypted string and represent the in-memory value in the form of an encrypted byte array. The names of encrypted attributes end with Encrypted. For example, the JDBCConnectionPoolMBean exposes the password that is used to access the database in an attribute named PasswordEncrypted.

The following sections describe how to work with encrypted attributes:

Set the Value of an Encrypted Attribute

To set the value of an encrypted attribute, encode a String object as a byte array and pass the output directly to the setter method as a parameter. Do not assign the byte array to a variable because this causes the unencrypted byte array to remain in memory until garbage collection removes it.

For example, if you use weblogic.management.MBeanHome:

ServerMBean.setCustomIdentityKeyStorePassPhraseEncrypted( (new String("myNewCustomIdentityKeyStorePassPhrase")).getBytes());

If you use weblogic.management.RemoteMBeanServer:

Attribute passphrase = new Attribute("CustomIdentityKeyStorePassPhrase", new String("myNewCustomIdentityKeyStorePassPhrase").getBytes());

String server = "examples:Name=examplesServer,Type=Server"; ObjectName serverOn = new ObjectName(server); RemoteMBeanServer.setAttribute(serverOn, passphrase);

Compare an Unencrypted Value with an Encrypted Value

A management application might need to compare a password or some other value that a user enters with a value that is in an MBean's encrypted attribute. Instead of decrypting the MBean attribute value and risk exposing the data to someone with unauthorized access, you encrypt the user-supplied value and compare the two encrypted values.

You must encrypt the user-supplied value on the same server that originally encrypted the MBean value. Each server uses its own salt file to encrypt data unless the server is sharing its root directory with another server. See "A Server's Root Directory" in Configuring and Managing WebLogic Server.

To compare a password or some other value that a user enters with a value that is in an encrypted attribute:

On the same server that set the encrypted value in the MBean, write the user-supplied value as a byte array and pass the byte array to the weblogic.management.EncryptionHelper.encrypt() method.

Use the getter method of the MBean's encrypted value to retrieve its encrypted byte array.

For example, invoke JDBCConnectionPoolMBean.getPasswordEncrypted, which returns an encrypted byte array.

Compare the two encrypted byte arrays.

Example: Setting and Getting an Encrypted Attribute

The class in Listing 4-3 retrieves and displays the encrypted pass phrase for a custom identity key store. Then it changes the pass phrase, retrieves and displays the newly encrypted phrase.

Because the example is changing configuration values, it changes the value in the Administration MBean.

The example class:

Uses JNDI to look up the Administration MBeanHome interface on the Administration Server.

Uses the MBeanHome.getMBean(String name, String type) API to retrieve the type-safe interface of the ServerMBean Administration MBean for a server instance named myserver.

Gets the encrypted pass phrase for the custom identity key store by invoking ServerMBean.getCustomIdentityKeyStorePassPhraseEncrypted().

The getCustomIdentityKeyStorePassPhraseEncrypted() method returns an encrypted byte array.

Displays the encrypted value by converting the encrypted byte array to a String object and printing the object to standard out.

Sets a new pass phrase for the custom identity key store by doing the following:

Creates a String object that contains the new pass phrase.

Uses String.getBytes() to create a byte array that contains the value of the String object.

Passes the byte array as input for the ServerMBean.setCustomIdentityKeyStorePassPhraseEncrypted method:

mbean.setCustomIdentityKeyStorePassPhraseEncrypted((new String("myCustomIdentityKeyStorePassPhrase")).getBytes())

Gets the encrypted pass phrase for the custom identity key store by invoking ServerMBean.getCustomIdentityKeyStorePassPhraseEncrypted().

Displays the unencrypted value by converting the unencrypted byte array to a String object and printing the object to standard out.

Listing 4-3 Getting and Setting Encrypted Values

import java.util.*;
import java.rmi.RemoteException;
import javax.naming.*;
import javax.management.MBeanServer;
import javax.management.Attribute;
import javax.management.InstanceNotFoundException;

import weblogic.jndi.Environment;
import weblogic.management.WebLogicMBean;
import weblogic.management.MBeanHome;
import weblogic.management.configuration.ServerMBean;

public class GetSetEncrypted {
    private static MBeanHome home = null;
    static MBeanHome getHome(String[] args) {
       Context ctx= null;
       Hashtable ht = new Hashtable();
       ht.put(Context.INITIAL_CONTEXT_FACTORY,
           "weblogic.jndi.WLInitialContextFactory");
       ht.put(Context.PROVIDER_URL, "t3://localhost:7001");
       ht.put(Context.SECURITY_PRINCIPAL, args[0]);
       ht.put(Context.SECURITY_CREDENTIALS, args[1]);
       try {
          System.out.println("Getting the initialContext ...");
          ctx = new InitialContext(ht);
          System.out.println("Got initialContext");
          home = (MBeanHome)ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
        } catch(Exception e) {
            e.printStackTrace();
       }
       return home;
    }

    static void getsetServerMBean() throws Exception {
       byte[] bytes = null;
       String serverName = "myserver";
       ServerMBean mbean=(ServerMBean)home.getMBean(serverName,"Server");
       System.out.println("Found admin mbean,name=" +
           ((WebLogicMBean)mbean).getObjectName());
       bytes = mbean.getCustomIdentityKeyStorePassPhraseEncrypted();
       if (bytes != null) {
          System.out.println("\n\ngetCustomIdentityKeyStorePassPhraseEncry
                  pted returned=\n" + (new String(bytes)));
       } else {
          System.out.println("\n\ngetEncrypted Attribute returned NULL");
       }
       System.out.println("\n\nInvoking
            setCustomIdentityKeyStorePassPhraseEncrypted() with
            myNewCustomIdentityKeyStorePassPhrase");
       mbean.setCustomIdentityKeyStorePassPhraseEncrypted((new
          String("myNewCustomIdentityKeyStorePassPhrase")).getBytes());
       bytes = mbean.getCustomIdentityKeyStorePassPhraseEncrypted();
       System.out.println("\n\nAfter
            setCustomIdentityKeyStorePassPhraseEncrypted(),
            getCustomIdentityKeyStorePassPhraseEncrypted returned=\n" +
            (new String(bytes)));
    }

    public static void main (String[] args) {
       getHome(args);
       try {
          getsetServerMBean();
       } catch (Exception e) {
          e.printStackTrace();
       }
    }
}