WebLogic Event Server Administration and Configuration Guide

wlevs.Admin Command-Line Reference

The following sections describe the wlevs.Admin utility:

Overview of the wlevs.Admin Utility

The wlevs.Admin utility is a command-line interface to administer WebLogic Event Server and, in particular, dynamically configure the EPL rules for application processors. The utility internally uses JMX to query the configuration and runtime MBeans of both the server and deployed applications.

The WebLogic Event Server configuration framework allows concurrent changes to both the application and server configuration by multiple users. The framework does not use locking to manage this concurrency, but rather uses optimistic version-based concurrency. This means that two users can always view the configuration of the same object with the intention to update it, but only one user is allowed to commit their changes. The other user will then get an error if they try to update the same configuration object, and must refresh their session to view the updated configuration.

Each command of the wlevs.Admin utility runs in its own transaction, which means that there is an implicit commit after each execution of a command. If you want to batch multiple configuration changes in a single transaction, you must use JMX directly to make these changes rather than the wlevs.Admin utility.

Required Environment for the wlevs.Admin Utility

To set up your environment for the wlevs.Admin utility:

Running the wlevs.Admin Utility Remotely

Sometimes it is useful to run the wlevs.Admin utility on a computer different from the computer on which WebLogic Event Server is installed and running. To run the utility remotely, follow these steps:

Syntax for Invoking the wlevs.Admin Utility

The syntax for using the wlevs.Admin utility is as follows:

java wlevs.Admin 
      [ Connection Arguments ] 
      [ User Credentials Arguments ]
      [ Common Arguments ] 
      COMMAND-NAME command-arguments 

The command names and arguments are not case sensitive.

The following sections provide detailed syntax information about the arguments you can supply to the wlevs.Admin utility:

The following sections provide detailed syntax information about the supported commands of the wlevs.Admin utility:

Example Environment

In many of the examples throughout the sections that follow, it is assumed that a certain environment has been set up:

Exit Codes Returned by wlevs.Admin

All wlevs.Admin commands return an exit code of 0 if the command succeeds and an exit code of 1 if the command fails.

To view the exit code from a Windows command prompt, enter echo %ERRORLEVEL% after you run a wlevs.Admin command. To view the exit code in a bash shell, enter echo $?.

wlevs.Admin calls System.exit(1) if an exception is raised while processing a command, causing Ant and other Java client JVMs to exit.

Connection Arguments

java wlevs.Admin 
     [ {– url URL} ]
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     COMMAND-NAME command-arguments

When you invoke most wlevs.Admin commands, you specify the arguments in Table 5-1 to connect to a WebLogic Event Server instance.

User Credentials Arguments

java wlevs.Admin 
     [ Connection Arguments ] 
     [ -username username [-password password] ] 
     [ Common Arguments ] 
     COMMAND-NAME command-arguments 

When you invoke most wlevs.Admin commands, you specify the arguments in Table 5-2 to provide the user credentials of a WebLogic Event Server user who has permission to invoke the command.

If security has not been enabled for your WebLogic Event Server domain, then you do not have to provide user credentials.

Common Arguments

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ] 
     [ -verbose ] 
     COMMAND-NAME command-arguments 

All wlevs.Admin commands support the argument in Table 5-3 to get verbose output.

Command for Getting Usage Help

HELP

Provides syntax and usage information for all WebLogic Event Server commands (by default) or for a single command if a command value is specified on the HELP command line.

You can issue this command from any computer on which the WebLogic Event Server is installed. You do not need to start a server instance to invoke this command, nor do you need to supply user credentials, even if security is enabled for the server.

Syntax

java wlevs.Admin HELP [COMMAND]

The COMMAND argument can be:

Example

In the following example, information about using the UPLOAD command is requested:

prompt> java wlevs.Admin HELP ULOAD

The command returns the following:

Description:
Uploads rules to be configured in the EPL Processor.

Usage: 
java wlevs.Admin
   [-url | -listenAddress <host-name> -listenPort <port>] 
  -username <username> -password <password>
 UPLOAD -application <application name> -processor <eplprocessor name> -sourceURL "source url"

Where:
-application = Name of the application.
-processor = Name of the EPL Processor. 
-sourceURL = source URL containing the rules in an XML format.

java wlevs.Admin -url service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi -username wlevs -password wlevs UPLOAD -application myapplication -processor eplprocessor -sourceURL file:///d:/test/rules.xml

Commands for Managing the Server Life Cycle

Table 5-4 is an overview of commands that manage the life cycle of a server instance. Subsequent sections describe command syntax and arguments, and provide an example for each command.

SHUTDOWN

Gracefully shuts down the specified WebLogic Event Server instance.

A graceful shutdown gives WebLogic Event Server time to complete certain application processing currently in progress.

The -url connection argument specifies the particular WebLogic Event Server instance that you want to shut down, based on the host and jmxport values. See Connection Arguments for details.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     SHUTDOWN [-scheduleAt seconds] 

Example

The following example instructs the specified WebLogic Event Server instance to shut down in ten minutes:

prompt> java wlevs.Admin 
       -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
       -username wlevs -password wlevs 
        SHUTDOWN -scheduleAt 600

After you issue the command, the server instance prints messages to its log file and to its standard out. The messages indicate that the server state is changing and that the shutdown sequence is starting.

Commands for Managing the EPL Rules of an Application

Table 5-4 is an overview of commands that manage the EPL rules for a particular processor of a WebLogic Event Server application. Subsequent sections describe command syntax and arguments, and provide an example for each command.

ADDRULE

Adds a new EPL rule to the specified processor of a WebLogic Event Server application.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     ADDRULE -application application -processor processor -rule [rulename] rulestring 

Example

The following example shows how to add the EPL rule SELECT * FROM Withdrawal RETAIN 5 EVENTS, with name myrule, to the helloworldProcessor of the helloworld application deployed to the specified WebLogic Event Server application:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        ADDRULE – application helloworld – processor helloworldProcessor 
        – rule myrule "SELECT * FROM Withdrawal RETAIN 5 EVENTS"

DELETERULE

Deletes an existing EPL rule from the specified processor of a WebLogic Event Server application.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     DELETERULE -application application -processor processor -rule rulename

Example

The following example shows how to delete the EPL rule called myrule from the helloworldProcessor of the helloworld application deployed to the specified WebLogic Event Server application:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        DELETERULE – application helloworld – processor helloworldProcessor 
        – rule myrule

GETRULE

Returns the full text of an EPL rule from the specified processor of a WebLogic Event Server application.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     GETRULE -application application -processor processor -rule rulename

Example

The following example shows how to get the full text of the EPL rule called myrule from the helloworldProcessor of the helloworld application deployed to the specified WebLogic Event Server application:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        GETRULE – application helloworld – processor helloworldProcessor 
        – rule myrule

UPLOAD

Replaces the configured EPL rules for a specified processer with the EPL rules from an uploaded XML file.

The XML file that contains the list of EPL rules conforms to the processor configuration XSD Schema. This file contains one or more EPL rules that will replace those currently configured for the specified processor. An example of the XML file is as follows:

<?xml version="1.0" encoding="UTF-8" ?> 
<config >
  <processor>
    <name>helloworldProcessor</name> 
    <rules>
      <rule id="helloworldRule1">
        <![CDATA[  SELECT * FROM HelloWorldEvent RETAIN 2 EVENTS ]]> 
      </rule>
    </rules>
  </processor>
</config>

In the preceding example, the XML file configures a single rule, with name helloworldRule1, and its EPL query text is SELECT * FROM HelloWorldEvent RETAIN 2 EVENTS.

See Configuring the Complex Event Processor Rules for details and examples of creating the EPL rule XML file.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     UPLOAD -application application -processor processor -sourceURL sourcefileURL

Example

The following example shows how upload the EPL rules in the c:\processor\config\myrules.xml file to the helloworldProcessor of the helloworld application deployed to the specified WebLogic Event Server application:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        UPLOAD – application helloworld – processor helloworldProcessor 
        – sourceURL file:///c:/processor/config/myrules.xml

DOWNLOAD

Downloads the set of EPL rules associated with the specified processor of a WebLogic Event Server application to an XML file.

The XML file is of the same format as described in UPLOAD.

Syntax

java wlevs.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     DOWNLOAD -application application -processor processor 
     -file destinationfile [-overwrite overwrite]

Example

The following example shows how download the set of EPL rules currently attached to the helloworldProcessor of the helloworld application to the file c:\processor\config\myrules.xml; the utility overwrites any existing file:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        DOWNLOAD – application helloworld – processor helloworldProcessor 
        – file c:\processor\config\myrules.xml

Commands for Managing WebLogic Event Server MBeans

The following sections describe wlevs.Admin commands for managing WebLogic Event Server MBeans.

See the Javadoc for the full description of the WebLogic Event Server MBeans.

Specifying MBean Types

To specify which MBean or MBeans you want to access, view, or modify, all of the MBean management commands require either the -mbean argument or the -type argument.

Use the -mbean argument to operate on a single instance of an MBean.

Use the -type argument to operate on all MBeans that are an instance of a type that you specify. An MBean's type refers to the interface class of which the MBean is an instance. All WebLogic Event Server MBeans are an instance of one of the interface classes defined in the com.bea.wlevs.management.configuration, com.bea.wlevs.management.runtime, com.bea.wlevs.deployment.mbean and com.bea.wlevs.server.management.mbean packages. . For a complete list of all WebLogic Event Server MBean interface classes, see the Javadocs for the respective packages.

To determine the value that you provide for the -type argument, do the following: 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 com.bea.wlevs.management.configuration.EPLProcessorMBean, use EPLProcessor.

MBean Management Commands

Table 5-12 is an overview of the MBean management commands.

GET

Displays MBean properties (attributes) and JMX object names (in the javax.management.ObjectName format).

The output of the command is as follows:

{MBeanName object-name {property1 value} {property2 value}. . .} 
. . .

Note that the properties and values are expressed as name-value pairs, each of which is returned within curly brackets. This format facilitates parsing of the output by a script.

If -pretty is specified, each property-value pair is displayed on a new line and curly brackets are not used to separate the pairs:

MBeanName: object-name
property1: value
property2: value
.
.
.
MBeanName: object-name
property1: value
abbribute2: value

Syntax

java wlevs.Admin 
     [ Connection Arguments ]
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     GET [-pretty] {– type mbeanType|– mbean objectName} [– property property1] [– property property2]...

Example

The following example displays all properties of the EPLProcessorMBean that was registered for the Processor Stage when the application called helloworld was deployed in Weblogic Event Server.

prompt> java wlevs.Admin
         -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi
         -username wlevs -password wlevs
         GET -pretty
         -mbean com.bea.wlevs:Name=eplprocessor,Type=EPLProcessor,Application=helloworld

For more information about the environment in which this example runs, see Example Environment.

The following example displays all instances of all EPLProcessorMBean MBeans.

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        GET -pretty -type EPLProcessor

INVOKE

Invokes a management operation for one or more MBeans. For WebLogic Event Server MBeans, you usually use this command to invoke operations other than the getAttribute and setAttribute that most WebLogic Event Server MBeans provide.

Syntax

java wlevs.Admin 
     [ Connection Arguments ]
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     INVOKE {– type mbeanType|– mbean objectName} – method methodname [argument . . .]

Example

The following example invokes the addRule method of the com.bea.wlevs.configuration.application.DefaultProcessorConfig MBean:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        INVOKE -mbean com.bea.wlevs:Name=eplprocessor,Type=EPLProcessor,Application=helloworld 
        -method addRule "SELECT * FROM Withdrawal RETAIN ALL"

For more information about the environment in which this example runs, see Example Environment.

QUERY

Searches for WebLogic Event Server MBeans whose javax.management.ObjectName matches a pattern that you specify.

All MBeans that are created from a WebLogic Event Server MBean type are registered in the MBean Server under a name that conforms to the javax.management.ObjectName conventions. You must know an MBean’s ObjectName if you want to use wlevs.Admin commands to retrieve or modify specific MBean instances.

The output of the command is as follows:

{MBeanName object-name {property1 value} {property2 value}. . .} 
. . .

Note that the properties and values are expressed as name-value pairs, each of which is returned within curly brackets. This format facilitates parsing of the output by a script.

If -pretty is specified, each property-value pair is displayed on a new line and curly brackets are not used to separate the pairs:

MBeanName: object-name
property1: value
property2: value
.
.
.
MBeanName: object-name
property1: value
abbribute2: value

Syntax

java wlevs.Admin 
     [ Connection Arguments ]
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     QUERY -pretty – pattern object-name-pattern 

Example

The following example searches for all com.bea.wlevs.configuration.application.DefaultProcessorConfig MBeans:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
         QUERY -pattern *:Type=EPLProcessor,*

If the command succeeds, it returns the following:

Ok

For more information about the environment in which this example runs, see Example Environment.

Querying for Application and Processor Names

All the commands for managing the EPL rules of a WebLogic Event Server application require you know the name of the application, as well the particular processor to which you want to apply the rules. Typically you know these names, but if you do not, you can use the QUERY command to get the information from the MBean instances that represent applications and their attached processors.

In particular, use the following -pattern argument to get a list of all applications, processors, and rules for a given WebLogic Event Server instance:

  -pattern  com.bea.wlevs:*,Type=EPLProcessor 

For example:

prompt> java wlevs.Admin -url  
        service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        QUERY -pretty 
        -pattern com.bea.wlevs:*,Type=EPLProcessor

A sample output of this command is shown below:

Command Output
------------------------------------------------------
MBeanName: "com.bea.wlevs:Name=helloworldProcessor,Type=EPLProcessor,Application=helloworld,"
       AllRules:
       helloworldRule =  select * from HelloWorldEvent retain 1 event 
--end of command output -------- 

In the sample output above:

SET

Sets the specified property (attribute) values for an MBean.

If the command is successful, it returns OK and saves the new values to the server configuration.

Syntax

java wlevs.Admin 
     [ Connection Arguments ]
     [ User Credentials Arguments ]
     [ Common Arguments ] 
     SET {– type mbeanType|– mbean objectName}
     – property property1 property1_value 
     [-property property2 property2_value] . . .

Example

The following example shows how to set the MaxSize property of the stream named helloworldOutstream of the helloworld application:

prompt> java wlevs.Admin 
        -url service:jmx:rmi:///jndi/rmi://ariel:1099/jmxrmi 
        -username wlevs -password wlevs 
        SET -mbean com.bea.wlevs:Name=helloworldOutstream,Type=Stream,Application=helloworld
        -property  MaxSize 1024

For more information about the environment in which this example runs, see Example Environment.