Oracle Stream Analytics supports Jetty as a Java web server to deploy HTTP servlets and static resources. You can configure Jetty features to use them with Oracle Stream Analytics. Features you can configure are network I/O, work managers, and configuring a Jetty server instance.
Oracle Stream Analytics Jetty support is based on Version 1.2 the OSGi HTTP Service. The OSGi HTTP Service API enables dynamically registering and unregistering objects with run time and static resources. This specification requires Java Servlet API 2.1 or higher. See http://java.sun.com/products/servlet/docs.html.
This chapter includes the following sections:
Oracle Stream Analytics supports these Jetty features.
Servlets: Oracle Stream Analytics supports synchronous and asynchronous Java servlets. An asynchronous servlet receives a request, gets a thread and performs some work, and finally releases the thread while waiting for those actions to complete before re-acquiring another thread and sending a response. See Application Development and Deployment.
Network I/O Integration: Oracle Stream Analytics uses network I/O (Net IO) to configure the port and listen address of Jetty services. Jetty has a built-in capability for multiplexed network I/O. However, it does not support multiple protocols on the same port.
Thread Pool Integration: Oracle Stream Analytics Jetty services use the Oracle Stream Analytics work manager for scalable thread pooling. See Example Jetty Configuration. Although, Jetty provides its own thread pooling capability, Oracle recommends that you use the Oracle Stream Analytics self-tuning thread pool to minimize footprint and configuration complexity.
Jetty Work Managers: Oracle Stream Analytics enables you to configure how your application prioritizes the execution of its work. You define rules and monitor run time performance to optimize application performance and maintain service-level agreements. You define a work manager to define the rules and constraints for your application. See Jetty Configuration Objects.
Oracle Stream Analytics uses a single thread pool to execute all types of work. Work is prioritized based on rules you define and run-time metrics that include the time it takes to execute a request, and the rate at which requests enter and leave the pool.
The common thread pool changes size to maximize throughput. The queue monitors throughput over time, and based on history, determines whether to adjust the thread count. For example, if historical throughput statistics indicate that a higher thread count increased throughput, Oracle Stream Analytics increases the thread count. Similarly, if statistics indicate that fewer threads did not reduce throughput, Oracle Stream Analytics decreases the thread count.
Oracle Stream Analytics prioritizes work and allocates threads based on an execution model that accounts for defined parameters, and run time performance and throughput. You can configure a set of scheduling guidelines and associate them with one or more applications or with particular application components.
For example, you can associate one set of scheduling guidelines for one application, and another set of guidelines for other applications. At run time, Oracle Stream Analytics uses the guidelines to assign pending work and enqueued requests to execution threads.
To manage work in your applications, define one or more of the following work manager components:
fairshare: The average thread-use time required to process requests.
For example, Oracle Stream Analytics runs two modules and the work manager for ModuleA specifies a fairshare of 80 and the work manager for ModuleB specifies a fairshare of 20. During a period of sufficient demand, with a steady stream of requests for each module such that the number requests exceed the number of threads, Oracle Stream Analytics allocates 80% and 20% of the thread-usage time to ModuleA and ModuleB, respectively.
Note:
You specify a fair share request class as a relative value, not a percentage. Therefore, in the above example, if the request classes are defined as 400 and 100, they still have the same relative values.
max-threads-constraint: Limits the number of concurrent threads executing requests from the constrained work set. The default is unlimited. For example, consider a constraint defined with maximum threads of 10 and shared by 3 entry points. The scheduling logic ensures that not more than 10 threads are executing requests from the three entry points combined.
A max-threads-constraint can be defined in terms of a the availability of resource that requests depend upon, such as a connection pool.
A max-threads-constraint might, but does not necessarily, prevent a request class from taking its fair share of threads or meeting its response time goal. Once the constraint is reached the Oracle Stream Analytics does not schedule requests of this type until the number of concurrent executions falls below the limit. The Oracle Stream Analytics then schedules work based on the fair share or response time goal.
min-threads-constraint: Guarantees a number of threads the server will allocate to affected requests to avoid deadlocks. The default is zero. A min-threads-constraint value of one is useful, for example, for a replication update request, which is called synchronously from a peer.
A min-threads-constraint might not increase a fair share. This type of constraint has an effect primarily when the Oracle Stream Analytics instance is close to a deadlock condition. In that case, the constraint causes Oracle Stream Analytics to schedule a request even when requests in the service class have gotten more than their fair share recently.
Oracle Stream Analytics supports servlet development for deployment to Jetty.
The developer creates a standard Java EE web application and configures it with the jetty-web-app configuration object in the config.xml file for the server where the servlet will run.
Oracle Stream Analytics supports servlet deployments packaged either as war files or as exploded war files, as described in version 2.4 of the Java Servlet Specification. You can deploy pre-configured web applications from an exploded directory or war file by including them in the server configuration.
Security constraints specified in the standard web.xml file are mapped to the Common Security Services security provider. The Servlet API specifies declarative role-based security, which means that particular URL patterns can be mapped to security roles.
This section presents an example Jetty configuration followed by a description of the Jetty configuration objects.
You configure a Jetty server instance in the config.xml file for the server you want to configure.For information about security configuration tasks that affect Jetty, see Configure Jetty Security.
The following snippet from a config.xml file provides an example Jetty configuration. Only Jetty-related configuration information is shown:
<config>
<netio>
<name>JettyNetIO</name>
<port>9002</port>
</netio>
<work-manager>
<name>WM</name>
<max-threads-constraint>64</max-threads-constraint>
<min-threads-constraint>3</min-threads-constraint>
</work-manager>
<jetty>
<name>TestJetty</name>
<work-manager-name>WM</work-manager-name>
<network-io-name>JettyNetIO</network-io-name>
<debug-enabled>false</debug-enabled>
<scratch-directory>JettyWork</scratch-directory>
</jetty>
<jetty-web-app>
<name>test</name>
<context-path>/test</context-path>
<path>testWebApp.war</path>
<jetty-name>TestJetty</jetty-nam>
</jetty-web-app>
</config>
This section explains how to use the following configuration objects to configure an instance of the Jetty HTTP server. You configure a Jetty HTTP server in the config.xml file that describes your Oracle Stream Analytics server.
jetty
Use the parameters described in the following table to define a jetty configuration object in your config.xml file.
Table 10-1 jetty Element Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
network-io-name |
String |
The name of the Net IO service used. The Net IO service defines the port the server listens on. See Jetty Configuration Objects for details. |
work-manager-name |
String |
The name of the Work Manager that should be used for thread pooling. If not specified, the default work manager is used. |
scratch-directory |
String |
The name of a directory where temporary files required for web applications, JSPs, and other types of web artifacts are kept. |
debug-enabled |
boolean |
Enable debugging in the Jetty code using the OSGi Log Service. |
name |
String |
The name of the jetty server instance. |
netio
Use the parameters described in the following table to define a netio configuration object in your config.xml file.
Table 10-2 netio Element Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
name |
String |
The name of the configuration object. |
port |
int |
The listening port number. |
listen-address |
String |
The address on which an instance of
The value of this parameter cannot be validated until the service has started. |
work-manager
Use the parameters described in the following table to define a work-manager configuration object in your config.xml file.
Table 10-3 work-manager Element Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
min-threads-constraint |
Integer |
The minimum threads this work manager uses. |
fairshare |
Integer |
The |
max-threads-constraint |
Integer |
The maximum threads constraint this work manager uses. |
name |
String |
The name of this work manager. |
jetty-web-app
Use the following configuration object to define a web application for use by Jetty.
Table 10-4 jetty-web-app Element Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
name |
String |
The name of this work manager. |
context-path |
String |
The context path where this web app is deployed in the web server's name space. If not set, it defaults to " |
scratch-directory |
String |
The location where Jetty stores temporary files for this web app. Overrides the |
path |
String |
A file name that points to the location of the web app on the server. It may be a directory or a war file. |
jetty-name |
String |
The name of the Jetty service where this web application is deployed. It must match the name of an existing Configure a Jetty Server Instance. |
name |
String |
The name of this configuration object. |