1 Introduction to Server Administration

Oracle Stream Analytics server administration tasks involve creating domains and administering domains, servers, and applications. This guide describes the server administration tools you run from the command line to accomplish these tasks.

You can also use Oracle Stream Analytics Visualizer. Visualizer is a browser-based tool that enables you to administer Oracle Stream Analytics servers and domains, and to view, develop, configure and monitor aspects of Oracle Stream Analytics applications and security. See Getting Started with Oracle Stream Analytics Visualizer in Using Visualizer for Oracle Stream Analytics.

This chapter includes the following sections:

See also Java API Reference for Oracle Stream Analytics for information about the Oracle Stream Analytics APIs described in this guide.

1.1 Server-Provided Services

An Oracle Stream Analytics server consists of logically related resources and services to which you deploy Oracle Stream Analytics applications.

Services include:

Network I/O: Server and client Internet Protocol (IP) port access, IPv4 and IPv6 support, and a variety of blocking and non-blocking network I/O providers.
Security: Security services such as SSL, password stores, and authentication and authorization providers.
Jetty HTTP publish-subscribe server: Enables web clients to subscribe to channels and publish asynchronous messages to these channels over HTTP.
Java Management Extensions (JMX): Programmatic access to Oracle Stream Analytics server and application behavior.
JDBC data sources: Enables access to relational databases to store events for event record and playback, and to access a table as an event source for Oracle CQL queries.
HTTP publish-subscribe server: Pushes event messages to subscribed clients such as the Oracle Stream Analytics Visualizer and your own Web 2.0 applications.
Logging: Monitors and troubleshoots server and application operation.

1.2 Server Domains

An Oracle Stream Analytics domain is the management unit of a set of one or more servers.

There are two types of domains:

Standalone-server domain: A domain that contains a single server. This is default type of domain created by the Configuration Wizard and is the starting point for a multiserver domain. See Standalone-Server Domains.
Multiserver domain: A domain that contains two or more servers that share the same unicast address, unicast port, multicast address, multicast port, domain, and security provider. The multicast address, multicast port, and domain are configured in the config.xml file for each server in the domain. You can create server groups within a multiserver domain and deploy applications to each server in the specified server group. The servers within a multiserver domain can be located on the same computer or on separate computers.

1.3 Server Life Cycle

The states in the life cycle of an Oracle Stream Analytics server are specific to itself. They are not OSGi bundle states.

Figure 1-1 shows a state diagram for the Oracle Stream Analytics server life cycle. In this diagram, the state names (STARTING, RUNNING, and SHUTTING_DOWN) correspond to the ServerRuntimeMBean.getState method return values. These states are specific to Oracle Stream Analytics.

Figure 1-1 Server Life Cycle State Diagram

Description of "Figure 1-1 Server Life Cycle State Diagram"

1.3.1 Server Startup Actions

After you start the Oracle Stream Analytics server, it performs the following actions:

Starts core engine bundles.
Starts Oracle Stream Analytics bundles and extension libraries.
Registers MBeans.
Oracle Stream Analytics server state is now STARTING.
Starts application libraries and then application bundles.
Oracle Stream Analytics server state is now RUNNING.

1.3.2 Server Shutdown Actions

After you shut down the Oracle Stream Analytics server, it performs the following actions:

Oracle Stream Analytics server state is SHUTTING_DOWN.
Unregister ServerRuntimeMBean.

Oracle Stream Analytics server ceases to have a state.
Shuts down Oracle Stream Analytics bundles.
Shuts down application bundles.
Shuts down core engine bundles.

1.4 Server Configuration

You can configure the server and configure applications deployed to the server and perform the asks statically or dynamically. Static configuration involves editing XML files. Dynamic configuration involves manipulating management beans (MBeans).

You can use Oracle Stream Analytics Visualizer, the wlevs.Admin command-line tool, or JMX APIs to do it programmatically.

Static Configuration

There are some server configuration tasks that you can only perform statically, such as configuring Jetty.

To configure the server statically:

Stop the Oracle Stream Analytics server.
Edit the Oracle Stream Analytics server config.xml file located in the server's domain directory
Start the Oracle Stream Analytics server.

Dynamic Configuration

There are some server configuration tasks that you can perform dynamically using JMX and MBeans. In this case, you do not have to manually stop and start the server for the changes to take effect.

After you deploy an application, you can dynamically change its configuration and the configuration of its individual components by manipulating the MBeans that the Oracle Stream Analytics server automatically creates for the application and its components. A typical task is to dynamically configure the Oracle CQL rules for the processors of a deployed application, using the Oracle Stream Analytics Visualizer, wlevs.Admin command-line utility, or JMX.

Related Information

For more information, see:

1.4.1 Server Configuration Files

All server files are contained in a single server directory. The main server configuration file is config.xml, which is where you configure the server services and specify the domain to which the server belongs.

By default, the Configuration Wizard creates server domains in the /Oracle/Middleware/my_oep/user_projects/domains directory. The following list describes the important server files and directories that are in each domain:

deployments.xml: An XML file that contains the list of applications, packaged as OSGi bundles, that are currently deployed to the Oracle Stream Analytics instance of this domain. You never update this file manually to deploy applications. Use the Deployer tool instead.
startwlevs.cmd: A command file which starts an instance of an Oracle Stream Analytics server. The UNIX equivalent is startwlevs.sh.
stopwlevs.cmd: A command file which stops an instance of an Oracle Stream Analytics server. The UNIX equivalent is stopwlevs.sh.
config/config.xml: An XML file which describes the configured services for the Oracle Stream Analytics server instance. Services include logging, debugging, Jetty Web Service, and JDBC data sources.
config/security*: Files that configure security for the domain.
config/atnstore.txt: A file which lists the configured users and user groups for the domain.

1.4.2 Edit the config.xml File

The most efficient way to configure an Oracle Stream Analytics server is to use one or more of the Oracle Stream Analytics administration tools described in Server Administration Tools. You can also perform Oracle Stream Analytics server configuration by editing the Oracle Stream Analytics server config.xml file.

Caution:

If you update the config.xml file manually to change the configuration of an Oracle Stream Analytics server, you must restart the server for the change to take effect.

You can configure the following server objects and features using the config.xml file. The referenced sections describe the exact elements you must add or update:

How the servers in a multiserver domain are configured together. This includes the multicast address and multicast port, the server groups, and so on. See:
Network I/O. See Network I/O.
Security. See Security.
Jetty, an open-source, standards-based, full-featured Java Web Server. See Jetty.
JMX, required to use the Oracle Stream Analytics Visualizer, wlevs.Admin utility, and Deployer utility See JMX .
JDBC data source, used to connect to a relational database. See JDBC.
HTTP publish-subscribe server. See HTTP Publish-Subscribe Server.
Logging and debugging properties of the server. By default, the log level is set to NOTICE. See Logging and Debugging.

The following example shows a sample config.xml that contains configurations for some of these services.

<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2007 sp2 (http://www.altova.com)-->
<n1:config
  xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/server wlevs_server_config.xsd"
  xmlns:n1="http://www.bea.com/ns/wlevs/config/server"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <netio>
     <name>NetIO</name>
     <port>9002</port>
   </netio>
   <netio>
     <name>sslNetIo</name>
     <ssl-config-bean-name>sslConfig</ssl-config-bean-name>
     <port>9003</port>
   </netio>
   <work-manager>
     <name>JettyWorkManager</name>
     <min-threads-constraint>5</min-threads-constraint>
     <max-threads-constraint>10</max-threads-constraint>
   </work-manager>
   <jetty>
     <name>JettyServer</name>
     <network-io-name>NetIO</network-io-name>
     <work-manager-name>JettyWorkManager</work-manager-name>
     <secure-network-io-name>sslNetIo</secure-network-io-name>
   </jetty>
   <rmi>
     <name>RMI</name>
     <http-service-name>JettyServer</http-service-name>
   </rmi>
   <jndi-context>
     <name>JNDI</name>
   </jndi-context>
   <exported-jndi-context>
     <name>exportedJndi</name>
     <rmi-service-name>RMI</rmi-service-name>
   </exported-jndi-context>
   <jmx>
     <rmi-service-name>RMI</rmi-service-name>
     <jndi-service-name>JNDI</jndi-service-name>
   </jmx>
   <ssl>
     <name>sslConfig</name>
     <key-store>./ssl/evsidentity.jks</key-store>
     <key-store-pass>
        <password>{Salted-3DES}j4XEtuXmmvEl4M/NInwq0A==</password>
     </key-store-pass>
     <key-store-alias>evsidentity</key-store-alias>
     <key-manager-algorithm>SunX509</key-manager-algorithm>
     <ssl-protocol>TLS</ssl-protocol>
     <enforce-fips>false</enforce-fips>
     <need-client-auth>false</need-client-auth>
   </ssl>
   <http-pubsub>
     <name>pubsub</name>
     <path>/pubsub</path>
     <pub-sub-bean>
        <server-config>
          <name>/pubsub</name>
          <supported-transport>
             <types>
                <element>long-polling</element>
             </types>
          </supported-transport>
          <publish-without-connect-allowed>true</publish-without-connect-allowed>
        </server-config>
        <channels>
           <element>
              <channel-pattern>/evsmonitor</channel-pattern>
           </element>
           <element>
              <channel-pattern>/evsalert</channel-pattern>
           </element>
           <element>
              <channel-pattern>/evsdomainchange</channel-pattern>
          </element>
        </channels>
     </pub-sub-bean>
   </http-pubsub>
   <cluster>
     <server-name>productionServer</server-name>
   </cluster>
   <domain>
     <name>oep_domain</name>
   </domain>

1.4.3 Manage Configuration History

When you deploy an application to a server, the server creates a configuration history for the application. Any configuration changes you make to the application are recorded in this history. You can view and roll back (undo) these changes with Oracle Stream Analytics Visualizer or the wlevs.Admin tool.

1.4.4 Configure the Server bootclasspath

Use the -Xbootclasspath command to set the search path for bootstrap classes and resources. For example, you can use this command to satisfy server dependencies beyond those set by the server configuration file (config.xml). You can also use this command to satisfy application and application library dependencies beyond those set by application import statements and found in the library and library extensions directories.

Configure the bootclasspath:

Change directories to the server directory of the domain for which you want to configure the bootclasspath.

The location is:

/Oracle/Middleware/my_oep/user_projects/domains/<domainname>/ <server_name>
In the server directory, open the start script (startwlevs.sh or startwlevs.cmd, depending on your operating system) in an editor.

Locate the following line:

"$JAVA_HOME/bin/java" $JVM_ARGS $JVM_D64 $DEBUG_ARGS -Dwlevs.home="$USER_INSTALL_DIR" -jar "${USER_INSTALL_DIR}/bin/wlevs.jar" $ARGS
/wlevs.jar

Set the -Xbootclasspath/a option to the full path name of the native library you are going to use.
For example, if you want to use the native library mynativelib located in Oracle Stream Analytics server directory %USER_INSTALL_DIR%\bin, update the java command in the start script as follows.

The example is broken for readability. Put the full command on one line.
```
%JAVA_HOME%\bin\java -Dwlevs.home=%USER_INSTALL_DIR% -Dbea.home=%BEA_HOME%  
-Xbootclasspath/a:\Oracle\Middlware\my_oep\oep\bin\mynativelib.jar 
-jar "%USER_INSTALL_DIR%\bin\wlevs.jar" 
-disablesecurity %1 %2 %3 %4 %5 %6 
```
If Oracle Stream Analytics is running, restart it so it reads the new java option and data source information. See Start and Stop Servers.

1.5 Server Administration Tools

This section describes the server administration tools that you can use to administer Oracle Stream Analytics servers, domains, and applications.

Configuration Wizard. A Java application that you can invoke graphically to create and update Oracle Stream Analytics servers and domains. For the 12.1.3 release, the Configuration Wizard can generate an Oracle database configuration only. See Standalone-Server Domains.
wlevs.Admin command-line utility. A Java application that you can invoke locally or remotely to perform a wide variety of Oracle Stream Analytics server, domain, and application administration tasks. See About the wlevs.Admin Command-Line Reference.
Deployer command-line utility. A Java application that you can invoke locally or remotely to perform application deployment and application administration tasks. See Deployer Command-Line Reference.
Security administration utilities. See Security Utilities Command-Line Reference.
JMX. A set of standards-based interfaces that enable you to perform server, domain, and application administration tasks using JMX and management beans (MBeans). See JMX.

1.6 Server Administration Tasks

Server administration tasks include creating and updating servers and domains; configuring, starting, and stopping servers; and deploying and managing applications.

Create Servers and Domains

The primary administrative task in setting up an Oracle Stream Analytics platform is creating and configuring the server domains. Oracle Stream Analytics supports standalone-server domains and multiserver domains.

For more information, see:

Update Servers and Domains

Once you create an Oracle Stream Analytics server and domain, you can update it to change its configuration or server group membership. See:

Configure Servers

Once you create an Oracle Stream Analytics server and domain, you must configure the various services they provide. See:

Start and Stop Servers

After you have created an Oracle Stream Analytics domain along with at least one server, you start a server instance so you can then deploy applications and begin running them. During upgrades and after some configuration changes, you must stop and start the Oracle Stream Analytics server. See:

Start and Stop a Server in a Standalone-Server Domain
Oracle Coherence: Start and Stop a Server in a Multiserver Domain
Oracle Stream Analytics Native Clustering: Start and Stop a Server in a Multiserver Domain

Note:

On a Windows Operating System, do not stop the Oracle Stream Analytics server by clicking the Close button in the command prompt in which you started it. Always stop the Oracle Stream Analytics server using the stopwlevs.cmd script or Ctrl-C.

Deploy Applications to Servers

Once you have created and configured an Oracle Stream Analytics server and domain, you can deploy Oracle Stream Analytics applications. See:

Manage Applications, Servers, and Domains

Once you have deployed applications to an Oracle Stream Analytics server and domain, you must manage the applications to perform tasks such as monitor the performance and perform upgrades. See: