Using the Tuple to XML Operator

Contents

Introduction
Properties View Settings
Operator Ports
Typechecking and Error Handling
Related Topics

Introduction

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.

Properties View Settings

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.

General Tab

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 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 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 Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

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.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming 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.

Concurrency 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.

Operator Ports

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.

Typechecking and Error Handling

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 TupleIn port schema does not contain exactly one field of type tuple.

  • The TupleIn port schema contains a field of type list<list<?>> (which is not allowed).

  • The TupleIn port schema contains an Element Value Field (default name _VALUE) of type tuple or list (which is also not allowed).

  • The TupleIn port schema contains an Attribute Values Field (default name _ATTRIBUTES) that is not of type list<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 TupleIn port 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.

Related Topics

Back to Top ^