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 required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.
Operator: A read-only field that shows the formal name of the operator.
Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.
Enable Error Output Port: Select this checkbox 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 to learn about Error Ports.
Description: Optionally, enter text to briefly describe the purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
| Property | Description |
|---|---|
| XSLT File | The name of the file used to transform the complete XML after the tuple to XML conversion is complete. If this entry is empty no XSLT transform will occur. NOTE: The intermediate XML is displayed in the console when the adapters log level is set to debug. |
| 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 Oracle 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. |
| Namespace Variable Name | The variable name associated with the namespace, if this value is empty and a namespace is supplied then the namespace it is assumed to be the default namespace |
| Namespace URI | The URI of the namespace to apply to the XML |
| 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. |
Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.
Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.
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.