XOP (MTOM)

This adapter generates XOP/MTOM packages from XML documents, dissolves XOP references from an XOP/MTOM package and outputs an XML document.

Properties

Operation

Defines the operation executed by the function adapter

Possible values:

CleanupXml: Removes <?xop-candidate?> instructions and normalizes their parent elements
MakeSimplepart: Removes <?xop-candidate?> instructions and normalizes their parent elements
MakeMultipart: Generate XOP/MTOM package from an XML document; The output structure is a MIME XML (see also MIME Multipart)
UnpackMultipart: Dissolve XOP references from a MIME XML, which represents an XOP/MTOM package; Output is an XML document (the actual payload)

Parameters

Adapter

Main adapter class (do not change!)

Possible values: de.softproject.integration.adapter.xop.Adapter: Main class (default)

RequiredMinimumPartSavings

Number of bytes that needs to be saved per element, in order for an element to be extracted via XOP/MTOM

any integer, e.g. 300
0 (default)
<0: Inefficiencies are accepted; That means, it is accepted that more bytes will be transferred, as if not extracted
<= -300: The extraction is performed regardless of the savings (extracting has an overhead of approx. 260–270 bytes per extraction)

RequiredMinimumTotalSavings

Specifies how many bytes need to be saved through extraction, in order for the extraction to be performed.

0 (default)
<0: The result MIME document may be bigger than a result document, for which no extraction was performed. With this parameter a high negative value in RequiredMinimumPartSavings can be relativized.

Status values

1	The operation was performed without problems
0	The operation was not executed or it was not executed completely
-1	An error occurred while processing; It is typically caused by invalid/incomplete input documents.

Operation CleanupXml

The adapter operation CleanupXml performs normalization works for the creation of an XOP package. Thereby, neither a candidate (identified by <?xop-candidate?>) will be outsourced, nor a Mime XML document will be created.

The mimetype of the resulting X4 document (see Document Properties Changer) is determines as follows.

Incoming mimetype	Incoming encoding	XML document is ...	Resulting mimetype	Resulting encoding
empty	any	no SOAP	`text/xml`	`UTF-8`
`some/type`	any	no SOAP	`some/type`	`UTF-8`
any	any	SOAP 1.1	`text/xml`	`UTF-8`
any	any	SOAP 1.2	`application/soap+xml`	`UTF-8`

Example

Input

XML

<SomeXml>
    <blob1>
        <?xop-candidate?>
            SGFs
            bG8=
    </blob1>
    <blob2>
        <?xop-candidate text/plain?>
            SGFs
            bG8g
            SGFs
            bG8=
    </blob2>
</SomeXml>

Output

XML

<SomeXml>
    <blob1>SGFsbG8=</blob1>
    <blob2>SGFsbG8gSGFsbG8=</blob2>
</SomeXml>

Operation MakeSimplepart

The adapter operation MakeSimplepart performs normalization works for the creation of an XOP package, whereby no candidate (identified by <?xop-candidate?>) will be outsourced. The result is a Mime XML document with only one part (no Multipart).

The Mime part has two headers:

content-transfer-encoding: binary
content-type: Wert siehe unten

Incoming mimetype	Incoming encoding	XML document is ...	Resulting `content-type` header
empty	any	no SOAP	`text/xml; charset=UTF-8`
`some/type`	any	no SOAP	`some/type; charset=UTF-8`
any	any	SOAP 1.1	`text/xml; charset=UTF-8`
any	any	SOAP 1.2	`application/soap+xml; charset=UTF-8`

Example

Input

XML

<SomeXml>
    <blob1>
        <?xop-candidate?>
            SGFs
            bG8=
    </blob1>
    <blob2>
        <?xop-candidate text/plain?>
            SGFs
            bG8g
            SGFs
            bG8=
    </blob2>
</SomeXml>

Output

XML

<Part>
    <Header>
        <Name>content-type</Name>
        <Value>text/xml; charset=UTF-8</Value>
        <Type>text/xml</Type>
        <Parameter>
            <Name>charset</Name>
            <Value>UTF-8</Value>
        </Parameter>
    </Header>
    <Header>
        <Name>content-transfer-encoding</Name>
        <Value>binary</Value>
    </Header>
    <Content encoding="base64">PD94bWwgdmVyc2lvb... more base64 ...g0K</Content>
</Part>

Operation MakeMultipart

The adapter operation MakeMultipart is used to optimize the transfer of XML documents with bigger binary (Base64) contents. Main application areas are SOAP web services, but also any other XML document.

Input: Example of an input XML for the operation MakeMultipart

XML

<SomeXml>
	<blob1>
		<?xop-candidate?>
			SGFsbG8=
	</blob1>
	<blob2>
		<?xop-candidate text/plain?>
			SGFsbG8gSGFsbG8=
	</blob2>
</SomeXml>

Explanation

The XML processing instruction <?xop-candidate?> specifies, which text node is to be extracted
If a media type is specified as parameter, e.g. <?xop-candidate text/plain?>, this media type will be used
If no media type is specified as parameter, application/octet-stream will always be assumed as media type
The adapter parameters RequiredMinimumPartSavings and RequiredMinimumTotalSavings specify how big the savings need to be in order to perform an extraction from the input XML.

Output: Example of a generated XML document with MakeMultipart

XML

<Multipart>
	<Header>
		<Name>content-transfer-encoding</Name>
		<Value>binary</Value>
	</Header>
	<Header>
		<Name>content-type</Name>
		<Value>multipart/related; type="application/xop+xml";
			start="&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;";
			start-info="application/xml";
			boundary=3f032702-07f2-46fa-8108-f2258033727e</Value>
		<Type>multipart/related</Type>
		<Parameter>
			<Name>type</Name>
			<Value>application/xop+xml</Value>
		</Parameter>
		<Parameter>
			<Name>start</Name>
			<Value>&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;</Value>
		</Parameter>
		<Parameter>
			<Name>start-info</Name>
			<Value>application/xml</Value>
		</Parameter>
		<Parameter>
			<Name>boundary</Name>
			<Value>3f032702-07f2-46fa-8108-f2258033727e</Value>
		</Parameter>
	</Header>
	<Prolog />
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>application/xop+xml; charset=UTF-8; type="application/xml"
			</Value>
			<Type>application/xop+xml</Type>
			<Parameter>
				<Name>charset</Name>
				<Value>UTF-8</Value>
			</Parameter>
			<Parameter>
				<Name>type</Name>
				<Value>application/xml</Value>
			</Parameter>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;</Value>
			<Id asUrl="cid:0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902">
				0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902
			</Id>
		</Header>
		<Content encoding="base64"> PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxTb21lWG1sPgoJPGJsb2IxPjx4b3A6SW5jbHVkZSBocmVmPSJjaWQ6MUAxOGE0ODI3ZC1lZWY3LTQ5NjUtYmY3OS1lN2YwZDBjYTI5OTQiIHhtbG5zOnhvcD0iaHR0cDovL3d3dy53My5vcmcvMjAwNC8wOC94b3AvaW5jbHVkZSIvPjwvYmxvYjE+Cgk8YmxvYjI+PHhvcDpJbmNsdWRlIGhyZWY9ImNpZDoyQDkyYzhlNjM5LTkwZjktNDJjNC1hMGNhLTNkOTdiODQzZTQ4YSIgeG1sbnM6eG9wPSJodHRwOi8vd3d3LnczLm9yZy8yMDA0LzA4L3hvcC9pbmNsdWRlIi8+PC9ibG9iMj4KPC9Tb21lWG1sPg0K</Content>
	</Part>
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>application/octet-stream</Value>
			<Type>application/octet-stream</Type>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;1@18a4827d-eef7-4965-bf79-e7f0d0ca2994&gt;</Value>
			<Id asUrl="cid:1@18a4827d-eef7-4965-bf79-e7f0d0ca2994">
				1@18a4827d-eef7-4965-bf79-e7f0d0ca2994
			</Id>
		</Header>
		<Content encoding="base64">SGFsbG8=</Content>
	</Part>
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>text/plain</Value>
			<Type>text/plain</Type>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;2@92c8e639-90f9-42c4-a0ca-3d97b843e48a&gt;</Value>
			<Id asUrl="cid:2@92c8e639-90f9-42c4-a0ca-3d97b843e48a">
				2@92c8e639-90f9-42c4-a0ca-3d97b843e48a
			</Id>
		</Header>
		<Content encoding="base64">SGFsbG8gSGFsbG8=</Content>
	</Part>
	<Epilog />
</Multipart>

This output XML corresponds to a MIME multipart document in which the the first Part corresponds to the input XML and all further Parts correspond to the extracted Base64 inclusions of the input XML.

Output: Entsprechendes MIME-Multipart-Dokument

TEXT

content-transfer-encoding: binary
content-type: multipart/related; type="application/xop+xml"; start="<0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902>"; start-info="application/xml"; boundary=3f032702-07f2-46fa-8108-f2258033727e

--3f032702-07f2-46fa-8108-f2258033727e
content-type: application/xop+xml; charset=UTF-8; type="application/xml"
content-transfer-encoding: binary
content-id: <0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902>

<SomeXml>
	<blob1><xop:Include href="cid:1@18a4827d-eef7-4965-bf79-e7f0d0ca2994" xmlns:xop="http://www.w3.org/2004/08/xop/include"/></blob1>
	<blob2><xop:Include href="cid:2@92c8e639-90f9-42c4-a0ca-3d97b843e48a" xmlns:xop="http://www.w3.org/2004/08/xop/include"/></blob2>
</SomeXml>

--3f032702-07f2-46fa-8108-f2258033727e
content-type: application/octet-stream
content-transfer-encoding: binary
content-id: <1@18a4827d-eef7-4965-bf79-e7f0d0ca2994>

Hallo
--3f032702-07f2-46fa-8108-f2258033727e
content-type: text/plain
content-transfer-encoding: binary
content-id: <2@92c8e639-90f9-42c4-a0ca-3d97b843e48a>

Hallo Hallo
--3f032702-07f2-46fa-8108-f2258033727e--

If no extractions were performed, e.g. because there were no markings or there were not enough savings, the adapter outputs the status 0 for this operation.

Operation UnpackMultipart

The adapter operation UnpackMultipart corresponds to the inverse operation to MakeMultipart. It dissolves the xop:Include elements from a MIME XML, which represents an XOP/MTOM package. The result is the payload XML of the XOP package (e.g. the SOAP envelope), whereby the xop:Include elements were replaced by the corresponding Base64 strings.

The operation also accepts a MIME XML, which is only a Part. In this case, the Part is only unpacked. However, in this case it is no guarantee that the result is an XML, e.g. if a Part corresponding to a PDF document is sent, the result will be the PDF.

In case of xop:Include references, only the URL protocol cid: is supported. The parts referenced have to be placed within the same multipart like the root part, that means they need to be sibling nodes of the root part.

Input: Example input for the operation UnpackMultipart

XML

<Multipart>
	<Header>
		<Name>content-transfer-encoding</Name>
		<Value>binary</Value>
	</Header>
	<Header>
		<Name>content-type</Name>
		<Value>multipart/related; type="application/xop+xml";
			start="&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;";
			start-info="application/xml";
			boundary=3f032702-07f2-46fa-8108-f2258033727e</Value>
		<Type>multipart/related</Type>
		<Parameter>
			<Name>type</Name>
			<Value>application/xop+xml</Value>
		</Parameter>
		<Parameter>
			<Name>start</Name>
			<Value>&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;</Value>
		</Parameter>
		<Parameter>
			<Name>start-info</Name>
			<Value>application/xml</Value>
		</Parameter>
		<Parameter>
			<Name>boundary</Name>
			<Value>3f032702-07f2-46fa-8108-f2258033727e</Value>
		</Parameter>
	</Header>
	<Prolog />
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>application/xop+xml; charset=UTF-8; type="application/xml"
			</Value>
			<Type>application/xop+xml</Type>
			<Parameter>
				<Name>charset</Name>
				<Value>UTF-8</Value>
			</Parameter>
			<Parameter>
				<Name>type</Name>
				<Value>application/xml</Value>
			</Parameter>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902&gt;</Value>
			<Id asUrl="cid:0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902">
				0@2eba3b7d-7eab-448d-be94-e5dd2bc6e902
			</Id>
		</Header>
		<Content encoding="base64">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxTb21lWG1sPgoJPGJsb2IxPjx4b3A6SW5jbHVkZSBocmVmPSJjaWQ6MUAxOGE0ODI3ZC1lZWY3LTQ5NjUtYmY3OS1lN2YwZDBjYTI5OTQiIHhtbG5zOnhvcD0iaHR0cDovL3d3dy53My5vcmcvMjAwNC8wOC94b3AvaW5jbHVkZSIvPjwvYmxvYjE+Cgk8YmxvYjI+PHhvcDpJbmNsdWRlIGhyZWY9ImNpZDoyQDkyYzhlNjM5LTkwZjktNDJjNC1hMGNhLTNkOTdiODQzZTQ4YSIgeG1sbnM6eG9wPSJodHRwOi8vd3d3LnczLm9yZy8yMDA0LzA4L3hvcC9pbmNsdWRlIi8+PC9ibG9iMj4KPC9Tb21lWG1sPg0K
		</Content>
	</Part>
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>application/octet-stream</Value>
			<Type>application/octet-stream</Type>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;1@18a4827d-eef7-4965-bf79-e7f0d0ca2994&gt;</Value>
			<Id asUrl="cid:1@18a4827d-eef7-4965-bf79-e7f0d0ca2994">
				1@18a4827d-eef7-4965-bf79-e7f0d0ca2994
			</Id>
		</Header>
		<Content encoding="base64">SGFsbG8=</Content>
	</Part>
	<Part>
		<Header>
			<Name>content-type</Name>
			<Value>text/plain</Value>
			<Type>text/plain</Type>
		</Header>
		<Header>
			<Name>content-transfer-encoding</Name>
			<Value>binary</Value>
		</Header>
		<Header>
			<Name>content-id</Name>
			<Value>&lt;2@92c8e639-90f9-42c4-a0ca-3d97b843e48a&gt;</Value>
			<Id asUrl="cid:2@92c8e639-90f9-42c4-a0ca-3d97b843e48a">
				2@92c8e639-90f9-42c4-a0ca-3d97b843e48a
			</Id>
		</Header>
		<Content encoding="base64">SGFsbG8gSGFsbG8=</Content>
	</Part>
	<Epilog />
</Multipart>

Output is an XML (or any document, if a MIME Part XML is sent)

Output: Example of an output XML

XML

<SomeXml>
	<blob1>SGFsbG8=</blob1>
	<blob2>SGFsbG8gSGFsbG8=</blob2>
</SomeXml>

If not all xop:Include elements were replaced, because the references could not be dissolved, the adapter outputs the status 0 and the output is the payload XML with all replacements that could be performed.

The status -1 is used to indicate different errors within the MIME XML.