Contents
The Tuple to XML Java operator converts StreamBase tuples to XML-encoded messages. Each field in the operator's input port schema populates an element or attribute in the resulting XML message. Each tuple enqueued to the operator results in a single XML message emitted on its output port.
The operator's input schema determines the set of fields that appear in the generated
XML messages. The hierarchy of the fields in the schema matches that of the elements
in the XML message. Fields containing null are discarded
and do not appear in the XML message. Each tuple field serves one of three purposes:
-
Adds a non-leaf element to the XML message.
-
Provides an XML element's value.
-
Provides an XML element's attributes.
Support for XML attributes is controlled through an operator property. When
attributes are disabled, the tag of an XML leaf element typically matches the name of
the tuple field that supplies its value. For example, a tuple field named
MyInt of type int
containing a value of 123 results in the following XML
fragment: <MyInt>123</MyInt>.
When attributes are enabled, an XML element's value and attributes are supplied
through subtuples of the tuple whose name matches the XML element's tag. For example,
to generate the XML <MyInt
myattr="myattrvalue">123</MyInt>, specify a tuple field named
MyInt of type tuple
containing two subfields named _VALUE and _ATTRIBUTES. The _VALUE subfield is of
type int and contains 123,
while the _ATTRIBUTES subfield is of type list<tuple<string Name, string Value>> and contains a
list with a single tuple whose Name and Value fields contain myattr and
myattrvalue, respectively.
Note
When attributes are enabled, a _VALUE subfield must be
used to populate an XML element's value if no attributes are to be written to that
specific element.
This section describes the properties you can set for a Tuple to XML operator, using the various tabs of the Properties view in StreamBase Studio.
Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Operator: A read-only field that shows the formal name of the operator.
Class: A field that shows the fully qualified class name that implements the functionality of this operator. Use this class name when loading the operator in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this operator starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the operator does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
| Property | Description |
|---|---|
| Element Value Field Name |
The name of the tuple subfield that contains an XML element's value; the
default is _VALUE. This field must be used
when attributes are being written to an XML element. When attributes are
disabled, or no attributes are being written to a particular XML element, a
tuple field with a name matching the XML element's tag may be used.
|
| Attribute Values Supported | If enabled (the default), attributes can be written to XML elements, and a valid value must be specified for the Attribute Values Field Name property. |
| Attribute Values Field Name |
The name of the tuple subfield that contains an XML element's attributes;
the default is_ATTRIBUTES. The schema of
attribute value fields must be list<tuple<string Name, string Value>>.
|
| Attribute Fields | A comma-delimited list of fully-qualified tuple field names that should generate attributes rather than elements in the XML. |
| Date/Time Format |
The format to use in converting StreamBase timestamps to strings in
generated XML messages. The format of the format string is described in the
java.text.SimpleDateFormat
class described in the Sun Java Platform SE
reference documentation. Typical format string values include
yyyyMMdd and yyyyMMdd
HH:mm:ss.
|
| Assume Local Time Zone | If enabled, date-time strings containing no timezone specifier are assumed to represent local time. If disabled (the default), date-time strings are assumed to represent GMT. |
| Include Null List Values | If enabled (the default), Include list values containing nulls in the generated XML. |
| Null List Value Representation |
Representation of null list values in XML. The default is null.
|
| Enable Status Port | If enabled (the default), status tuples are sent to port 2. If disabled, No status is reported. If disabled after previously being enabled, the arc connected to port 2 is deleted. |
| Pass Through Fields | When enabled, the incoming fields are passed through (not processed) during conversion, except for the field specified by the XML Input Field Name property, which alone will be converted. Default is disabled. |
| XML Input Field Name | The field name in the incoming tuple which contains the data to convert to XML. Only used when Pass Through Fields is selected. |
| XML Output Field Name | The name of a field of type string in the outgoing tuple which contains the converted XML data, named XML by default. Only used when Pass Through Fields is selected. |
| Log Level | Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. |
Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.
Caution
Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.
As shown in the diagram below (depicting one of the operator's sample applications), the operator has one input port and two output ports to communicate with the surrounding application.
The Tuple to XML operator's ports are used as follows:
-
TupleIn: The tuple to be converted to an XML message. The TupleIn port has the following schema:
-
<Top-level XML tag>, tuple: The field representing the top-level XML element. The field's name determines the name of the top-level XML element. Subfields of this top-level field result in subelements of the top-level XML element.
-
-
XMLOut: This output port contains a single field containing the contents of the generated XML message:
-
XML, string: The contents of the generated XML message
-
-
Status: A tuple is emitted on this port when an attempt to convert a tuple to an XML message fails. The Status port has the following schema:
-
type, string: Contains the following value describing the type of event that occurred:
-
Convert
-
-
action, string: Contains the following value indicating the conversion failed:
-
Failed
-
-
object, string: Contains a string representation of the input tuple.
-
message, string: Contains a human-readable description of the conversion failure.
-
time, timestamp: Contains the time of the conversion failure.
-
inputTuple, tuple: Contains a copy of the input tuple.
-
The Tuple to XML operator uses typecheck messages to help you configure the operator in your StreamBase application. In particular, the operator generates typecheck messages when:
-
The
TupleInport schema does not contain exactly one field of typetuple. -
The
TupleInport schema contains a field of typelist<list<?>>(which is not allowed). -
The
TupleInport schema contains an Element Value Field (default name_VALUE) of typetupleorlist(which is also not allowed). -
The
TupleInport schema contains an Attribute Values Field (default name_ATTRIBUTES) that is not of typelist<tuple<string Name, string Value>>. -
The Attribute Values Supported property is enabled and No Attribute Values Field Name is specified.
-
The Element Value Field Name and Attribute Values Field Name properties contain the same non-empty value.
-
The
TupleInport schema contains at least one timestamp field and no Date/Time Format string is specified. -
An invalid Date/Time Format string is specified.
The operator generates messages on the status port when an attempt to convert a tuple to an XML message fails.