X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

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

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


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

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


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.

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.  

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. 

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.


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)

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.