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, which must be unique in the current EventFlow module. 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: 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 with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this operator starts as part of the JVM engine that runs this EventFlow module. If this field is set to
No or to a module parameter that evaluates to false, the operator instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.
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 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 |
|---|---|
| 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 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.