Operator HTTPTupleView

IBMStreams streamsx.inetserver Toolkit > com.ibm.streamsx.inetserver 4.3.4 > com.ibm.streamsx.inet.rest > HTTPTupleView

REST HTTP or HTTPS API to view tuples from windowed input ports. Embeds a Jetty web server to provide HTTP REST access to the collection of tuples in the input port window at the time of the last eviction for tumbling windows, or last trigger for sliding windows. The URLs defined by this operator are:
  • prefix/ports/input/port index/tuples - Returns the set of tuples as a array of the tuples in JSON format (content type application/json).
  • prefix/ports/input/port index/info - Output port meta-data including the stream attribute names and types (content type application/json).
The prefix for the URLs is:
  • context path/base operator name - When the context parameter is set.
  • full operator name - When the context parameter is not set.
The /tuples URL accepts optional query parameters. The parameter namedPartitionQuery determines how query parameters work. If parameter namedPartitionQuery is false (the default), the following query parameters are accepted :
  • partition – When the window is partitioned defines the partition to be extracted from the window. When partitionKey contains multiple attributes, partition must contain the same number of values as attributes and in the same order, e.g. ?partition=John&partition=Smith. would match the SPL partitionKey setting of: partitionKey: “firstName”, “lastName”;. When a window is partitioned and no partition query parameter is provided the data for all partitions is returned.
  • attribute – Restricts the returned data to the named attributes. Data is returned in the order the attribute names are provided. When not provided, all attributes in the input tuples are returned. E.g. ?format=json&attribute=lastName&attribute=city will return only the lastName and city attributes in that order with lastName first.
  • suppress – Suppresses the named attributes from the output. When not provided, no attributes are suppressed. suppress is applied after applying the query parameter attribute. E.g. ?suppress=firstName&suppress=lastName will not include lastName or firstName in the returned data.
  • callback – Wrappers the returned JSON in a call to callbackvalue(...json...); to enable JSONP processing.
If namedPartitionQuery is true, the query parameters are accepted as follows:
  • name=value- where name is the name of the partition/attribute* attribute - if none of the partitions have the name attribute, it works like in the default case, otherwise it addresses the partition attributes.
  • suppress - if none of the partitions have the name suppress, it works like in the default case, otherwise it addresses the partition suppress.
  • callback - if none of the partitions have the name callback, it works like in the default case, otherwise it addresses the partition callback.
Query parameters are ignored if the input port's schema is tuple<rstring jsonString>.

The fixed URL /ports/info returns meta-data (using JSON) about all of the Streams ports that have associated URLs.

Tuples are converted to JSON using the JSONEncoding support from the Streams Java Operator API, except for:
  • If the input port's schema is tuple<rstring jsonString> then value is taken as is serialized JSON and the resultant JSON is returned as the tuple's JSON value.
  • Within a tuple any attribute that is rstring jsonString, then the value is taken as serialized JSON and it is placed into the tuple's JSON object as its deserialized JSON with key jsonString.
Limitations:
  • Error handling is limited, incorrect URLs can crash the application, e.g. providing the wrong number of partition values.
  • By default no security access is provided to the data, HTTPS must be explicitly configured.

HTTPS Support and Sharing the Jetty Server

see also namespace:com.ibm.streamsx.inet

Summary

Ports
This operator has 1 or more input ports and 0 output ports.
Windowing
This operator requires a windowing configuration.
Parameters
This operator supports 16 parameters.

Optional: certificateAlias, context, contextResourceBase, forceEmpty, headers, host, keyPassword, keyStore, keyStorePassword, namedPartitionQuery, partitionBy, partitionKey, port, sslAppConfigName, trustStore, trustStorePassword

Metrics
This operator reports 2 metrics.

Properties

Implementation
Java

Input Ports

Ports (0)

Windowed input port whose tuples will be available using a HTTP GET request with a URL using port index 0.

Properties
Ports (1...)

Optional windowed input ports whose tuples will be available using a HTTP GET request a URL with the corresponding port index.

Properties

Parameters

This operator supports 16 parameters.

Optional: certificateAlias, context, contextResourceBase, forceEmpty, headers, host, keyPassword, keyStore, keyStorePassword, namedPartitionQuery, partitionBy, partitionKey, port, sslAppConfigName, trustStore, trustStorePassword

certificateAlias

Alias of the certificate to use in the key store. When this parameter is set all connections use HTTPS and parameters keyStore and keyPassword are required.

Properties
context

Define a URL context path that maps to the resources defined by contextResourceBase. This allows a composite that invokes this operator in a toolkit to provide resources regardless of the value of the application's data directory. For example setting it to maps would result in the URL /maps/index.html mapping to the file index.html in the directory defined by contextResourceBase. Requires the parameter contextResourceBase to be set. If when the operator is initialized the context already exists then no action is taken. This allows multiple independent composites in the same toolkit to have common context and contextResourceBase settings, typically to point to a single set of HTML and Javascript resources for the toolkit.

If the operator provides URLs for its input or output ports then they are placed in the this context when this parameter is set. This then provides fixed locations for the URLs regardless of the depth of the operator invocation in the main composite.

Only a single context per invocation is supported.

Properties
contextResourceBase

Directory location of resources that will be available through the the URL context defined by the parameter context. Typically used to allow a toolkit to provide a set of resources in a fixed location. The set of resources is recommended to be stored in the application_dir/opt directory, which is automatically included in the bundle by default. Path of this directory can be absolute or relative, if relative path is specified then it is relative to the application directory. A set of default resources is included in the toolkit directory under ToolkitDir/opt/resources and will be loaded by the operator. This default resources can be viewed at http://hostname:8080/streamsx.inet.resources. A path within the application is obtained using the SPL function getThisToolkitDir(). Thus a composite in the file maps.spl in the namespace directory com.acme.streams.apps.map might have the following setting to map http://127.0.0.1:8080/maps to opt/resources/mapinfo in the application. 

param
  context: “maps”
  contextResourceBase: getThisToolkitDir() + “/opt/resources/mapinfo”

If this parameter is applied parameter contextResourceBase is required too.

Properties
forceEmpty

If true, the operator returns an empty result if input port is partitioned but the request does not specify a partition query. The parameter is meaningless for ports without partition. Default: false

Properties
headers

List of headers to insert into the http reply. Formatted as header:value

Properties
host

You can configure a host either as a host name or IP address to identify a specific network interface on which to listen. If not set, or set to the value of 0.0.0.0, the integrated jetty server listens on all local interfaces.

Properties
keyPassword

Password to the private key.

Properties
keyStore

URL to the key store containing the certificate. If a relative file path then it is taken as relative to the application directory.

Properties
keyStorePassword

Password to the key store.

Properties
namedPartitionQuery

Determines how the queries of the /tuples URL work. If false, the partition values must be entered in the order of the partition definition in parameter partitionKey or partitionBy. If true, the queries must be entered in the form 'name=value', where name is name of the partition and not the 'partition' word. Default: false

Properties
partitionBy

Names of attributes to partition the window by. The cardinality of this parameter must be equal the number of input ports. Each value must contain one a comma separated list of the partition attributes of the corresponding input port. If an input port is not partitioned, the corresponding value must be the empty string. Thus the input ports may have different port schemata. This parameter must not be used with parameter partitionKey.

Properties
partitionKey

Names of attributes to partition the window by. If the cardinality of this parameter is > 1, then every value represents one attribute name. If the cadinality equals to 1, the value may contain one attribute name or a comma separated list of attribute names. The values of this parameter list are applied to the window partitions of all input ports. Thus the input ports must have equal port schemata. If different partition lists are necessary use parameter partitionBy. Empty values are omitted. This parameter must not be used with parameter partitionBy.

Properties
port

Port number for the embedded Jetty HTTP server, default: "8080". If the port is set to 0, the jetty server uses a free tcp port, and the metric serverPort delivers the actual value.

Properties
sslAppConfigName
The operator can get the SSL server key/certificate and the client trust material from Streams application configuration with this name. If this parameter is present, certificateAlias, keyStore, keyPassword, trustStore and trustStorePassword are not allowed. The application configuration must contain the folowing properties:
  • server.jks - Base 64 encoded representation of the Java key store with one key-certificate pair to be used as server key and certitficate.
  • server.pass -Password for server.jks (and its key) and cacerts.jks.
The app configuration may contain property:
  • cacerts.jks - Base 64 encoded representation of the Java trust store with the client trust material.
If the property cacerts.jks is present, the operator requests client certificates. To create the Streams application configuration you may use a comand like: 
streamtool mkappconfig --description 'server cert and trust store' --property "server.jks=$(base64 --wrap=0 etc/keystore.jks)" --property "server.pass=password" --property "cacerts.jks=$(base64 --wrap=0 etc/cacerts.jks)" streams-certs
Properties
trustStore

URL to the trust store containing client certificates. If a relative file path then it is taken as relative to the application directory. When this parameter is set, client authentication is required.

Properties
trustStorePassword

Password to the trust store.

Properties

Metrics

https - Gauge

Jetty SSL/TLS status: 0=HTTP, 1=HTTPS.

serverPort - Gauge

Jetty (HTTP/HTTPS) server port if the operator hosts the server, 0 otherwise

Libraries

Operator class library
Library Path: ../../impl/lib/com.ibm.streamsx.inetserver.jar