XOP (MTOM)

Dieser Adapter erzeugt XOP/MTOM-Pakete aus XML-Dokumenten, löst XOP-Referenzen aus einem XOP/MTOM-Paket auf und gibt ein XML-Dokument aus.

Eigenschaften (Properties)

Operation

Bestimmt, welche Operation der Funktions-Adapter durchführt

Mögliche Werte:

CleanupXml: Entfernt <?xop-candidate?>-Anweisungen und normalisiert deren Elternelement
MakeSimplepart: Entfernt <?xop-candidate?>-Anweisungen und normalisiert deren Elternelement
MakeMultipart: aus einem XML-Dokument ein XOP/MTOM-Paket erzeugen; Die Ausgabestruktur ist ein MIME-XML (siehe auch MIME Multipart)
UnpackMultipart: XOP-Referenzen aus einem MIME-XML, welches ein XOP/MTOM-Paket darstellt, auflösen; Ausgabe ist ein XML-Dokument (die effektive Nutzlast)

Parameter

Adapter

Hauptklasse des Adapters (nicht verändern!)

Mögliche Werte:
de.softproject.integration.adapter.xop.Adapter: Hauptklasse (Standard)

RequiredMinimumPartSavings

Anzahl der Bytes, die pro Element eingespart werden müssen, damit ein Element via XOP/MTOM ausgelagert wird

Beliebige ganze Zahl, z.B. 300
0 (Standard)
<0: Ineffizienzen werden akzeptiert, d.h. es wird akzeptiert, dass mehr Bytes übertragen werden, als wenn nicht ausgelagert wird
<= -300: Die Auslagerung soll unabhängig von den Ersparnissen stattfinden (Auslagern hat einen Overhead von ca. 260–270 Bytes pro Auslagerung)

RequiredMinimumTotalSavings

Legt fest wie viele Bytes insgesamt durch Auslagerungen eingespart werden müssen, damit die Auslagerungen durchgeführt werden.

0 (Standard)
<0: Das Ergebnis-MIME-Dokument darf größer sein als ein Ergebnisdokument, für welches keine Auslagerungen durchgeführt wurden. Mit diesem Parameter kann ein hoher negativer Wert in RequiredMinimumPartSavings relativiert werden.

Statuswerte

`1`	Die Operation wurde ohne Probleme ausgeführt
`0`	Die Operation wurde nicht oder nicht vollständig ausgeführt
`-1`	Fehler bei der Verarbeitung; Wird typischerweise durch ungültige/unvollständige Input-Dokumente ausgelöst.

Operation CleanupXml

Die Adapter-Operation CleanupXml führt die Normalisierungsarbeiten für die Erstellung eines XOP-Pakets durch. Dabei wird weder ein Kandidat (identifiziert durch <?xop-candidate?>) ausgelagert noch wird ein Mime-XML-Dokument erzeugt.

Der mimetype des resultierenden X4-Dokuments (siehe Document Properties Changer) wird wie folgt ermittelt.

Eingehender mimetype	Eingehendes encoding	XML-Dokument ist ...	resultierender mimetype	resultierendes encoding
leer	beliebig	kein SOAP	`text/xml`	`UTF-8`
`some/type`	beliebig	kein SOAP	`some/type`	`UTF-8`
beliebig	beliebig	SOAP 1.1	`text/xml`	`UTF-8`
beliebig	beliebig	SOAP 1.2	`application/soap+xml`	`UTF-8`

Beispiel

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

Die Adapter-Operation MakeSimplepart führt die Normalisierungsarbeiten für die Erstellung eines XOP-Pakets durch, wobei kein Kandidat (identifiziert durch <?xop-candidate?>) ausgelagert wird. Das Ergebnis ist ein Mime-XML-Dokument mit nur einem Part (kein Multipart).

Der Mime-Part hat zwei Header:

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

Eingehender mimetype	Eingehendes encoding	XML-Dokument ist ...	resultierender `content-type` Header
leer	beliebig	kein SOAP	`text/xml; charset=UTF-8`
`some/type`	beliebig	kein SOAP	`some/type; charset=UTF-8`
beliebig	beliebig	SOAP 1.1	`text/xml; charset=UTF-8`
beliebig	beliebig	SOAP 1.2	`application/soap+xml; charset=UTF-8`

Beispiel

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

Die Adapter-Operation MakeMultipart wird verwendet, um die Übertragung von XML-Dokumenten mit größeren Binär(Base64)-Inhalten zu optimieren. Haupteinsatzgebiet sind SOAP-Webservices, aber auch jede andere XML.

Input: Beispiel einer Input-XML für die Operation MakeMultipart

XML

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

Erläuterung

Mit der XML-Verarbeitungsanweisung <?xop-candidate?> wird angegeben, welcher Textknoten ausgelagert werden soll
Wird ein Medien-Typ als Parameter angegeben, z.B. <?xop-candidate text/plain?>, so wird dieser Medien-Typ verwendet
Wird kein Medien-Typ als Parameter angegeben, so wird immer application/octet-stream als Medien-Typ angenommen
Über die Adapter-Parameter RequiredMinimumPartSavings und RequiredMinimumTotalSavings kann gesteuert werden, wie groß die Ersparnisse sein müssen, damit eine Auslagerung aus dem Input-XML stattfindet.

Output: Beispiel eines erzeugten XML-Dokuments mit 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>

Dieses Output-XML entspricht einem MIME-Multipart-Dokument in dem sich als erster Part das modifizierte Eingangs-XML befindet, und alle weiteren Parts die extrahierten Base64-Einschlüsse des Input-XMLs sind.

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

Wenn keine Auslagerungen stattgefunden haben, weil z.B. keine Markierungen existieren, oder nicht genug Ersparnisse zusammen gekommen sind, liefert der Adapter den Status 0 für diese Operation.

Operation UnpackMultipart

Die Adapter-Operation UnpackMultipart entspricht der inversen Operation zu MakeMultipart. Sie löst aus einem MIME-XML, das ein XOP/MTOM-Paket darstellt, die xop:Include Elemente auf. Als Ergebnis kommt das Nutzlast-XML des XOP-Pakets (z.B. der SOAP-Envelope) heraus, wobei die xop:Include Elemente durch die entsprechenden Base64-Strings ersetzt wurden.

Die Operation akzeptiert auch ein MIME-XML, welches nur ein Part ist. In diesem Fall wird das Part einfach nur ausgepackt. Dann wird jedoch nicht garantiert, dass das Ergebnis ein XML ist, z.B. wird ein Part reinschicken das ein PDF darstellt, ist das Ergebnis das PDF.

Bei den xop:Include-Referenzen wird nur das URL-Protokoll cid:unterstützt. Die so referenzierten Teile müssen sich im selben Multipart befinden wie das Root-Part, d.h. sie müssen Geschwister-Knoten des Root-Parts sein.

Input: Beispiel Input für die 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 ist ein XML (oder ein beliebiges Dokument, wenn ein MIME-Part-XML hineingeschickt wird)

Output: Beispiel einer Output-XML

XML

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

Wenn nicht alle xop:Include-Element ersetzt werden konnten, weil die Referenzen nicht aufgelöst werden konnten, gibt der Adapter den Status 0 zurück und die Ausgabe ist das Nutzlast-XML mit allen Ersetzungen, die durchgeführt werden konnten.

Ein Status von -1 wird verwendet, um verschiedene Fehler in dem MIME-XML anzuzeigen.