Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Transformers Configuration Reference

This page provides details on configuring the standard transformers. Note that many transports and modules provide their own transformers as well.

Transformer

A reference to a transformer defined elsewhere.

Attributes of <transformer…​>

Name Type Required Default Description

ref

string

yes

The name of the transformer to use.

Child Elements of <transformer…​>

Name Cardinality Description

Auto transformer

A transformer that uses the transform discovery mechanism to convert the message payload. This transformer works much better when transforming custom object types rather than Java types, because there is less chance for ambiguity.

Attributes of <auto-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <auto-transformer…​>

Name Cardinality Description

Custom transformer

A user-implemented transformer.

Attributes of <custom-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

class

class name

yes

An implementation of the Transformer interface.

Child Elements of <custom-transformer…​>

Name Cardinality Description

spring:property

0..*

Spring-style property element for custom configuration.

Message properties transformer

A transformer that can add, delete or rename message properties.

Attributes of <message-properties-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

overwrite

boolean

no

true

If false, a property is not added if the message already contains a property with that name.

scope

enumeration

no

outbound

Property scope to/from which properties are added/removed. The scope determines the lifespan of the properties. Default scope is outbound.

Child Elements of <message-properties-transformer…​>

Name Cardinality Description

delete-message-property

0..*

Delete message properties matching a regular expression or wildcard.

add-message-property

0..*

Add a message property.

rename-message-property

0..*

Rename a message property.

add-message-properties

0..1

Add a set of message properties.

Base64 encoder transformer

A transformer that base64 encodes a string or byte array message.

Attributes of <base64-encoder-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <base64-encoder-transformer…​>

Name Cardinality Description

Base64 decoder transformer

A transformer that base64 decodes a message to give an array of bytes.

Attributes of <base64-decoder-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <base64-decoder-transformer…​>

Name Cardinality Description

Xml entity decoder transformer

A transformer that decodes a string containing XML entities.

Attributes of <xml-entity-decoder-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <xml-entity-decoder-transformer…​>

Name Cardinality Description

Gzip compress transformer

A transformer that compresses a byte array using gzip.

Attributes of <gzip-compress-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <gzip-compress-transformer…​>

Name Cardinality Description

Gzip uncompress transformer

A transformer that uncompresses a byte array using gzip.

Attributes of <gzip-uncompress-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <gzip-uncompress-transformer…​>

Name Cardinality Description

Byte array to hex string transformer

A transformer that converts a byte array to a string of hexadecimal digits.

Attributes of <byte-array-to-hex-string-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <byte-array-to-hex-string-transformer…​>

Name Cardinality Description

Hex string to byte array transformer

A transformer that converts a string of hexadecimal digits to a byte array.

Attributes of <hex-string-to-byte-array-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <hex-string-to-byte-array-transformer…​>

Name Cardinality Description

Byte array to object transformer

A transformer that converts a byte array to an object (either deserializing or converting to a string).

Attributes of <byte-array-to-object-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <byte-array-to-object-transformer…​>

Name Cardinality Description

Object to byte array transformer

A transformer that serializes all objects except strings (which are converted using getBytes()).

Attributes of <object-to-byte-array-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <object-to-byte-array-transformer…​>

Name Cardinality Description

Object to string transformer

A transformer that gives a human-readable description of various types (useful for debugging).

Attributes of <object-to-string-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <object-to-string-transformer…​>

Name Cardinality Description

Byte array to serializable transformer

A transformer that converts a byte array to an object (deserializing the object).

Attributes of <byte-array-to-serializable-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <byte-array-to-serializable-transformer…​>

Name Cardinality Description

Serializable to byte array transformer

A transformer that converts an object to a byte array (serializing the object).

Attributes of <serializable-to-byte-array-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <serializable-to-byte-array-transformer…​>

Name Cardinality Description

Byte array to string transformer

A transformer that converts a byte array to a string.

Attributes of <byte-array-to-string-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <byte-array-to-string-transformer…​>

Name Cardinality Description

String to byte array transformer

A transformer that converts a string to a byte array.

Attributes of <string-to-byte-array-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

Child Elements of <string-to-byte-array-transformer…​>

Name Cardinality Description

Append string transformer

A transformer that appends a string to a string payload.

Attributes of <append-string-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

message

string

yes

The string to append.

Child Elements of <append-string-transformer…​>

Name Cardinality Description

Encrypt transformer

A transformer that encrypts a message.

Attributes of <encrypt-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

strategy-ref

string

no

The name of the encryption strategy to use. This should be configured using the password-encryption-strategy element, inside a security-manager element at the top level.

Child Elements of <encrypt-transformer…​>

Name Cardinality Description

Decrypt transformer

A transformer that decrypts a message.

Attributes of <decrypt-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

strategy-ref

string

no

The name of the encryption strategy to use. This should be configured using the password-encryption-strategy element, inside a security-manager element at the top level.

Child Elements of <decrypt-transformer…​>

Name Cardinality Description

Expression transformer

A transformer that evaluates one or more expressions on the current message. Each expression equates to a parameter in the return message. The return message for two or more expressions will be an Object[].

Attributes of <expression-transformer…​>

Name Type Required Default Description

name

name (no spaces)

no

Identifies the transformer so that other elements can reference it. Required if the transformer is defined at the global level.

returnClass

string

no

The class of the message generated by the transformer. This is used if transformers are auto-selected and to validate that the transformer returns the correct type. Note that if you need to specify an array type you need postfix the class name with '[]'. For example, if you want return a an Orange[], you set the return class to 'org.mule.tck.testmodels.fruit.Orange[]'.

ignoreBadInput

boolean

no

Many transformers only accept certain classes. Such transformers are never called with inappropriate input (whatever the value of this attribute). If a transformer forms part of a chain and cannot accept the current message class, this flag controls whether the remaining part of the chain is evaluated. If true, the next transformer is called. If false the chain ends, keeping the result generated up to that point.

encoding

string

no

String encoding used for transformer output.

mimeType

string

no

The mime type, e.g. text/plain or application/json

returnSourceIfNull

boolean

no

If all expressions return null on this transformer, this flag will cause the source payload to be returned without modification.

evaluator

standardExpressionEvaluators

no

The expression evaluator to use. Expression evaluators must be registered with the ExpressionEvaluatorManager before they can be used. Using the custom evaluator allows you to define your own evaluator with the 'custom-evaluator' attribute. Note that some evaluators such as xpath, groovy, and bean are loaded from other Mule modules (XML and Scripting, respectively). These modules must be on your classpath before the evaluator can be used.

expression

string

no

The expression to evaluate. The syntax of this attribute changes depending on the evaluator being used.

custom-evaluator

name (no spaces)

no

The name of the custom evaluator to use. This attribute is only used when the 'evaluator' attribute is set to "custom". You can plug in your own expression evaluators by registering them with the ExpressionEvaluatorManager.

Child Elements of <expression-transformer…​>

Name Cardinality Description

return-argument

0..1

If all expressions return null or NullPayload on this transformer, this flag will cause the source payload to be returned without modification.