Overview of Using the Deployer Command-Line Utility
The Deployer is a Java-based deployment utility that provides administrators and developers command-line based operations for deploying Oracle CEP applications. In the context of Oracle CEP deployment, an application is defined as an OSGi bundle JAR file that contains the following artifacts:
The compiled Java class files that implement some of the components of the application, such as the adapters, adapter factory, and POJO that contains the business logic. T
One or more Oracle CEP configuration XML files that configure the components of the application, such as the processor, adapter, or streams.
The configuration files must be located in the META-INF/wlevs directory of the OSGi bundle JAR file.
An EPN assembly file that describes all the components of the application and how they are connected to each other. The EPN assembly file extends the standard Spring context file.
The EPN assembly file must be located in the META-INF/spring directory of the OSGi bundle JAR file.
A MANIFEST.MF file that describes the contents of the JAR.
The Deployer utility uses HTTP to connect to Oracle CEP, which means that you must configure Jetty for the server instance to which you are deploying your application. For details, see Configuring Oracle CEP.
Oracle CEP uses the deployments.xml file to internally maintain its list of deployed application OSGi bundles. This file is located in in the DOMAIN_DIR/servername directory, where DOMAIN_DIR refers to the main domain directory correspoding to the server instance to which you are deploying your application and servername refers to the server instance itself. See Deployment XSD Schema for information about this file.
WARNING:
The XSD for the deployments.xml file is provided for your information only; Oracle does not recommend updating the deployments.xml file manually.
Required Environment for the Deployer Utility
To set up your environment to use the Deployer utility:
Install and configure the Oracle CEP software, as described in Installing Oracle CEP.
Update your CLASSPATH variable to include the wlevsdeploy.jar JAR file, located in the ORACLE_CEP_HOME/ocep_10.3/bin directory where, ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as /oracle_cep.
Running the Deployer Utility Remotely
Sometimes it is useful to run the Deployer utility on a computer different from the computer on which Oracle CEP is installed and running. To run the utility remotely, follow these steps:
Copy the following JAR files from the computer on which Oracle CEP is installed to the computer on which you want to run the deployer utility; you can copy the JAR files to the directory name of your choice:
ORACLE_CEP_HOME/ocep_10.3/bin/wlevsdeploy.jar
where ORACLE_CEP_HOME refers to the main directory into which you installed Oracle CEP.
Set your CLASSPATH in one of the following ways:
Implicitly set your CLASSPATH by using the -jar argument when you run the utility; set the argument to the NEW_DIRECTORY/wlevsdeploy.jar file, where NEW_DIRECTORY refers to the directory on the remote computer into which you copied the required JAR file. When you use the -jar argument, you do not specify the Deployer utility name at the command line.
Explicitly update your CLASSPATH by adding the JAR file you copied to the remote computer to your CLASSPATH environment variable:
Invoke the Deployer utility as described in the next section.
Syntax for Invoking the Deployer Utility
The syntax for using the Deployer utility is as follows:
The following sections describe the various arguments and commands you can use with the Deployer utility. See Examples of Using the Deployer Utility for specific examples of using the utility.
Connection Arguments
The following table describes the connection arguments you can specify with the Deployer utility.
Table 3-1 Connection Arguments
Argument
Description
-url url
Specifies the URL of the deployer of the Oracle CEP instance to which you want to deploy the OSGI bundle.
The URL takes the following form:
http://host:port/wlevsdeployer
where:
host refers to the hostname of the computer on which Oracle CEP is running.
port refers to the port number to which Oracle CEP listens; its value is 9002 by default. This port is specified in the config.xml file that describes your Oracle CEP domain, located in the DOMAIN_DIR/config directory, where DOMAIN_DIR refers to your domain directory. The port number is the value of the <Port> child element of the <Netio> element:
For example, if Oracle CEP is running on host ariel at port 9002, then the URL would be:
http://ariel:9002/wlevsdeployer
User Credential Arguments
The following table describes the user credential arguments you can specify with the Deployer utility.
Table 3-2 User Credential Arguments
Argument
Description
-user username
Username of the Oracle CEP administrator.
If you supply the -user option but you do not supply a corresponding -password option, the Deployer utility prompts you for the password.
-password password
Password of the Oracle CEP administrator.
Deployment Commands
The following table describes the deployment commands you can specify with the Deployer utility.
Table 3-3 Deployment Commands
Command
Description
-install bundle
Installs the specified OSGi bundle to the specified Oracle CEP instance.
The bundle parameter refers to a filename that is local to the computer from which you execute the Deployer utility.
Be sure to specify the full pathname of the bundle if it is not located relative to the directory from which you are running the Deployer utility.
In particular, Oracle CEP:
Copies the specified bundle to the domain directory.
Searches the META-INF/wlevs directory in the bundle for the component configuration files and extracts them to the domain directory.
Updates the internal deployment registry.
Starts the application. The incoming adapters immediately start receiving data.
-update bundle
Updates the existing OSGi bundle with new application code.
The bundle parameter refers to a filename that is local to the computer from which you execute the Deployer utility.
Be sure to specify the full pathname of the bundle if it is not located relative to the directory from which you are running the Deployer utility.
In particular, Oracle CEP:
Copies the updated bundles to the domain directory.
Searches the META-INF/wlevs directory in the updated bundle for the updated component configuration files and extracts them to the domain directory.
Updates the internal deployment registry with the updated information.
-uninstall name
Removes the existing bundle from the specified Oracle CEP instance.
The name parameter refers to the symbolic name of the OSGi bundle that you want to remove. The symbolic name is the value of the Bundle-SymbolicName header in the bundle’s MANIFEST.MF file:
Bundle-SymbolicName: myApp
In particular, Oracle CEP:
Removes the specified OSGi bundle from the domain directory.
Removes the bundles from the internal deployment registry .
-suspend name
Suspends a currently running OSGI bundle which was previously installed to the specified Oracle CEP instance.
The name parameter refers to the symbolic name of the OSGi bundle that you want to start. The symbolic name is the value of the Bundle-SymbolicName header in the bundle’s MANIFEST.MF file:
Bundle-SymbolicName: myApp
-resume name
Resumes a previously suspended OSGI bundle on the specified Oracle CEP instance; the configured adapters once again start immediately receiving incoming data.
The name parameter refers to the symbolic name of the OSGi bundle that you want to stop. The symbolic name is the value of the Bundle-SymbolicName header in the bundle’s MANIFEST.MF file:
Bundle-SymbolicName: myApp
-group groupname
Specifies that the deploy command (install, uninstall, update, suspend, or resume) applies to a target group, or more specifically, to the set of running servers within that group.
To specify the domain group, use the keyword all, such as:
-group all
To specify a custom group, simply specify the name of the group:
-group my_group
-status name
Returns status information about a currently installed OSGi bundle.
The name parameter refers to the symbolic name of the OSGi bundle for which you want status information. The symbolic name is the value of the Bundle-SymbolicName header in the bundle’s MANIFEST.MF file:
Bundle-SymbolicName: myApp
-startLevel startLevel
Specifies the level at which the OSGi bundle is started. Bundles with smaller numbers are started first.
System bundles have start levels of under 7.
Examples of Using the Deployer Utility
The following examples show how to use the Deployer utility. In all the examples, Oracle CEP is running on host ariel, listening at port 9002, and the username/password of the server administrator is wlevs/wlevs, respectively. For clarity, the examples are shown on multiple lines; however, when you run the command, enter all arguments and commands on a single line.
The following example shows how to install an application called strategies_1.0.jar to the strategygroup; this example also shows how to use the -jar command of the java utility:
