The example described here can be executed on a WebLogic domain created with the Domain Configuration Wizard in WebLogic version 7. The script assumes the name of the server is "myserver", but this can be changed in the script. Before starting the server, it is necessary to add the PointBase classes to the classpath. The lines to be added to file startWebLogic.cmd can be found in file pointbase.txt, included with the example files. In addition, the PointBase database has to be started before setting up the domain. The included script, startPB.cmd, will start PointBase. Just review these files to make changes if BEA home is installed on a different directory.

Once a WebLogic Server is running, start WLShell by typing wlsh (or wlsh.sh on Unix) on a different command window. WLShell will first read the commands in the initialization file .wlshrc. This file is used to customize WLShell environment startup. To set up the PetStore application and required WLS services, just type

read examples/petstore.wlsh

at WLShell prompt. This command will read and execute the commands in the specified file (the script file is under the examples directory). The script does the following tasks:

1. Connects to a WebLogic Server
2. Creates two JDBC Connection Pools
3. Creates three data sources
4. Creates a JMS JDBC data store
5. Creates a JMS server
6. Creates seven JMS Destinations (six queues and one topic)
7. Creates a JMS Connection Factory
8. Uploads and deploys two enterprise applications
9. Saves the domain configuration to file config.xml

Let's take a closer look at task 2, creation of JDBC Connection Pools. The script has the commands shown in Listing 1.

The first four lines will create the Administration MBean that will create the JDBC Connection Pool. Once the new pool is created, we set its properties by setting MBean attributes with the "set" command (lines 5 to 9). In these commands, values of types String and Integer are stored in MBean attributes. One attribute in particular, the "Properties" attribute, expects an object of class "java.util.Properties" that will specify the user to connect to the database (line 7). WLShell provides a mechanism to create an object of a particular class from a String object with a notation similar to Java casting. The command in line 9 will create the expected Properties object.

Finally, the "addTarget" MBean operation is invoked, providing the name of the server Administration MBean where the resource is going to be targeted.

At the end of the first part of the script we can read:

invoke $savedom $DOMAIN

This command invokes an MBean operation with one parameter to save the domain configuration just created. The fully qualified MBean operation name is in the $savedom variable, which was set up at WLShell start up in the ".wlshrc" file. The parameter is the name of the current active domain, which is stored automatically by the shell in the environment variable $DOMAIN when the user connects to a WebLogic server. The previous command would be equivalent to this one:

invoke weblogic:/Repository/Default/saveDomain petstoreDomain

An important point to remember is that in WLShell, all text is case sensitive, including MBean types, names, attributes and operations.

Deploying Applications
WebLogic version 7 introduces a new deployment model that's more robust and easier to use and provides a Deployer component to deploy J2EE applications. This component has an MBean interface that can be found in our example domain at:

petstoreDomain:/DeployerRuntime/DeployerRuntime

This MBean exposes several operations to activate and remove applications and WLShell provides scripting access to this MBean. In order to deploy an application, WebLogic must have access to the application file or directory (expanded format). WLShell supplies a command to upload a file to the server file system, very convenient when the administrator has no other access to the remote file system. With these commands we can deploy our application with just four lines (see Listing 2).

The first line creates an object of type DeploymentData with the name of the server where the application will be activated. The second line uploads the local enterprise application file to the server file system. The result of this invocation is the fully qualified name of the file uploaded to the server file system. That result is stored in the $LAST environment variable, as with any other WLShell command. We will need that file name for the activate operation, so we will store it on the $appfile environment variable (line 3). Line 4 is the command that invokes the Deployer MBean operation to activate the application with the required parameters. The application should be ready to use after that.

Runtime Monitoring
WebLogic Server provides another set of MBeans - Runtime MBeans - to monitor runtime attributes of the server, services, and applications. The naming convention for these MBeans consists of the MBean type name ending with "Runtime". As an example, in WLShell Runtime MBeans can be found under the following directories (this is a partial list):

/ApplicationRuntime
/ExecuteQueueRuntime
/JDBCConnectionPoolRuntime
/JVMRuntime
/ServerRuntime

The second script file in our example, monitor.wlsh, includes a set of commands to monitor some runtime attributes of the server we just set up. To execute those commands, at WLShell prompt type the following command:

read examples/monitor.wlsh

The script contains the following monitoring commands:
1.   A WLShell Explorer, to graphically explore the Domains and MBeans registered in the Administration Server
2.   Several WLShell Monitors to graphically display the following runtime values:
a. Throughput
b. Queue length
c. Free heap size
d. Sockets opened
e. JDBC runtime statistics
f. Servlet runtime statistics
g. EJB runtime statistics
3.   Text-based repetitive monitoring to correlate several runtime statistics

Figure 1 shows a screen shot of WLShell monitoring PetStore.

As seen on the script, a WLShell Monitor can be started with the "get -g attribute" command. This will graphically display the numeric value of an attribute over time. Any number of Monitors can be started to display any numeric attribute. This generic approach makes it possible to monitor any numeric MBean attribute in WebLogic, like a custom Execute Queue created in a Domain, runtime attributes of Web, EJB Components, etc.

An additional option to the "get -g attribute" command, the "-d" parameter, will tell the Monitor to display the difference between the current reading and the last one (delta) instead of the attribute value. This convenient flag allows you to graphically display things like throughput of the execute queue based on the number of requests serviced. Other interesting examples of this type of monitoring are the number of sockets opened on a server, the invocation count of a particular servlet, and the number of transactions committed by an EJB.

Server Life Cycle
Server life cycle can also be controlled through WLShell by invoking the corresponding MBean operations. For instance, a server can be shut down with the following command:

invoke /ServerRuntime/myserver/shutdown

To start a server with WLShell - the operation to invoke is in the corresponding Administration MBean - the command is:

invoke /Server/myserver/start

While this can be done with just one WLShell command, there are other components that have to be properly configured and running. WLShell invokes the operation of the Administration MBean on the Administration Server, the admin server connects to the node manager running on the machine where the server is located, and finally the node manager starts the server.

Other management operations include pinging the server for availability, suspending and resuming the server, etc. Examples of these operations can be found in WLShell script files under the "scripts" directory.

Moving Forward
A typical domain configuration with a few services and applications, like a WebLogic Portal Domain, can easily have over 1,300 MBeans registered. How can a WebLogic administrator know where to go to manage the domain? There are several suggestions that can be helpful. The first source of information is the WebLogic Administration guide, which provides information about MBeans and management tasks. In addition, the WebLogic Console offers help on every manageable attribute on the console, just click the question mark icon on the left of the attribute name and a help window will pop up providing the name of the MBean that contains the attribute and a short description.

WLShell will also display the description of MBean attributes through the command "get -v attribute" (v stands for verbose) and through the WLShell Explorer ("explore" command).

Summary
WLShell is a command-line shell for WebLogic administration, including domain configuration, monitoring, and server life-cycle control. It provides a generic access mechanism to any MBean in WebLogic, without requiring any Java programming. The simplified, yet complete, notation for MBeans can make a domain configuration and its documentation more concise and less error-prone. It is ideal for repetitive management tasks like setting up services, deploying applications on different servers, and monitoring. It is also convenient for interactive administration.