B Deployer Command-Line Reference

This appendix provides a reference to the Oracle Stream Analytics Deployer utility, which you can use to deploy Oracle Stream Analytics applications.

This appendix includes the following sections:

B.1 Overview of Using the Deployer Utility

The Deployer utility is a Java-based deployment utility that provides administrators and developers command-line based operations for deploying Oracle Stream Analytics applications.

In the context of Oracle Stream Analytics deployment, an application is defined as an OSGi bundle at http://www.osgi.org/ 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.
One or more Oracle Stream Analytics 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.

See Developing Applications for Event Processing with Oracle Stream Analytics for information about creating this deployment bundle.

The Deployer utility uses HTTP to connect to Oracle Stream Analytics, which means that you must configure Jetty for the server instance to which you are deploying your application. See Administering Oracle Stream Analytics.

Oracle Stream Analytics uses the deployments.xml file to internally maintain its list of deployed application OSGi bundles. This file is located in the DOMAIN_DIR/servername directory, where DOMAIN_DIR refers to the main domain directory corresponding to the server instance to which you are deploying your application and servername refers to the server instance itself.

Caution:

The XSD for the deployments.xml file is provided for your information only. Oracle does not recommend updating the deployments.xml file manually.

B.2 Configure the Deployer Utility Environment

Before you can use the Deployer utility, you must configure your environment appropriately.

Configure the Deployer utility environment:

Perform the following steps to configure the deployer utility environment:

Install and configure the Oracle Stream Analytics software.
Update your CLASSPATH variable to include the wlevsdeploy.jar JAR file, located in the /Oracle/Middleware/my_oep/oep/bin directory.

B.3 Run the Deployer Utility Remotely

Sometimes it is useful to run the Deployer utility on a computer different from the computer on which Oracle Stream Analytics is installed and running.

Run the Deployer utility remotely:

Copy the following JAR files from the computer on which Oracle Stream Analytics 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/Middleware/my_oep/oep/bin/wlevsdeploy.jar
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.

B.4 Syntax to Invoke the Deployer Utility

This topic shows the syntax for using the Deployer utility.

java -jar wlevsdeploy.jar 
    [Connection Arguments]
    [User Credential Arguments] 
    [Deployment Commands]

The following sections describe the various arguments and commands you can use with the Deployer utility. See Deployer Utility Examples for specific examples of using the utility.

B.4.1 Connection Arguments

Table B-1 lists the connection arguments you can specify with the Deployer utility.

Table B-1 Connection Arguments

Argument Description

Argument	Description
-url url	Specifies the URL to the Deployer utility for the Oracle Stream Analytics 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 host name of the computer on which Oracle Stream Analytics is running. `port` refers to the port number to which Oracle Stream Analytics listens. Its value is `9002` by default. This port is specified in the `config.xml` file that describes your Oracle Stream Analytics domain. By default it is located in the `Oracle/Middleware/my_oep/user_projects/domains/<domainname>/ <servername>/config` directory. The port number is the value of the `<Port>` child element of the `<Netio>` element: <Netio> <Name>NetIO</Name> <Port>9002</Port> </Netio> If you configure the Oracle Stream Analytics server for SSL-only connections (HTTPS-Only Connections), use the value of the `<Port>` child element of the SSL `<Netio>` element: <Netio> <name>sslNetIo</name> <port>9003</port> <ssl-config-bean-name>sslConfig</ssl-config-bean-name> </Netio> For example, if Oracle Stream Analytics is running on host `ariel` at port `9002`, then the URL would be: http://ariel:9002/wlevsdeployer

-url url

Specifies the URL to the Deployer utility for the Oracle Stream Analytics 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 host name of the computer on which Oracle Stream Analytics is running.
port refers to the port number to which Oracle Stream Analytics listens. Its value is 9002 by default. This port is specified in the config.xml file that describes your Oracle Stream Analytics domain. By default it is located in the Oracle/Middleware/my_oep/user_projects/domains/<domainname>/ <servername>/config directory.

The port number is the value of the <Port> child element of the <Netio> element:
```
<Netio>
   <Name>NetIO</Name>
   <Port>9002</Port>
</Netio>
```
If you configure the Oracle Stream Analytics server for SSL-only connections (HTTPS-Only Connections), use the value of the <Port> child element of the SSL <Netio> element:
```
<Netio>
   <name>sslNetIo</name>
   <port>9003</port>
   <ssl-config-bean-name>sslConfig</ssl-config-bean-name>
</Netio>
```

For example, if Oracle Stream Analytics is running on host ariel at port 9002, then the URL would be:

http://ariel:9002/wlevsdeployer

B.4.2 User Credential Arguments

Table B-2 lists the user credential arguments you can specify with the Deployer utility.

Table B-2 User Credential Arguments

Argument Description

Argument	Description
-user username	User name of the Oracle Stream Analytics 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 Stream Analytics administrator. Note: This argument is deprecated and may be removed in a later release. Oracle recommends that you do not use this argument.

-user username

User name of the Oracle Stream Analytics 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 Stream Analytics administrator.

Note:

This argument is deprecated and may be removed in a later release. Oracle recommends that you do not use this argument.

B.4.3 Deployment Commands

Table B-3 lists the deployment commands you can specify with the Deployer utility.

Table B-3 Deployment Commands

Command	Description
-encrypt	Encrypts the user name and password and writes it to output file.
-encryptoutfile encryptoutfile	Specifies that encryptoutfile should be used to write encrypted the user and password.
-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 Note: You may only deploy to a group if the server is part of a multiserver domain (that is, if clustering is enabled). You may not deploy to a group if the server is part of a standalone-server domain (that is, if clustering is disabled). For more information, see About Multiserver Domains.
-help	Prints a message describe command syntax and arguments.
-install bundle	Installs the specified OSGi bundle to the specified Oracle Stream Analytics 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 Stream Analytics: 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.
-resume name	Resumes a previously suspended OSGI bundle on the specified Oracle Stream Analytics 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
-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
-suspend name	Suspends a currently running OSGI bundle which was previously installed to the specified Oracle Stream Analytics 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
-uninstall name	Removes the existing bundle from the specified Oracle Stream Analytics 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 Stream Analytics: Removes the specified OSGi bundle from the domain directory. Removes the bundles from the internal deployment registry.
-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 Stream Analytics: 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.
-userconfigfile userconfigfile	Specifies that userconfigfile (security-config.xml) should be used to retrieve encrypted user name and password from the file.
-userkeyfile userkeyfile	Specifies that userkeyfile (.msainternal.dat) should be used to get the encryption key used to encrypt the password in the user `config` file.

B.5 Deployer Utility Examples

These examples show how to use the Deployer utility.

In all the examples, Oracle Stream Analytics is running on host ariel, listening at port 9002, and the user name/password of the server administrator is oepadmin/welcome1, 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.

java -jar wlevsdeploy.jar 
     -url http://ariel:9002/wlevsdeployer -user wlevs -password wlevs
     -install /application/bundles/com.my.exampleApp_1.0.0.0.jar

The preceding example shows how to install an OSGi bundle called com.my.exampleApp_1.0.0.0.jar, located in the /application/bundles directory.

The next command shows how to resume this application after it has been suspended:

java com.bea.wlevs.deployment.Deployer 
     -url http://ariel:9002/wlevsdeployer -user wlevs -password wlevs
     -resume exampleApp

The next example shows how to uninstall the application, which removes all traces of it from the domain directory:

java com.bea.wlevs.deployment.Deployer 
     -url http://ariel:9002/wlevsdeployer -user wlevs -password wlevs
     -uninstall exampleApp

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:

java -jar wlevsdeploy.jar 
     -url http://ariel:9002/wlevsdeployer -install strategies_1.0.jar 
     -group strategygroup