MongoDB Connector

MongoDB Connector: Stellt eine Verbindung zu einer MongoDB her und führt ein oder mehrere Datenbank-Statements aus, die als Input-XML-Dokument mit adapterspezifischen Strukturen übergeben wurden.

Parameter

Adapter	Hauptklasse des Adapters (nicht verändern!) Mögliche Werte:  de.softproject.integration.adapter.mongodb.MongoAdapter: Hauptklasse (Standard)
ConnectionName	Alias/Referenzname für die Verbindung. Entspricht dem Connection name aus der Verbindungskonfiguration. Weitere Informationen hierzu finden Sie unter Verbindung konfigurieren. Mögliche Werte: Name der Verbindung (z. B. #default (Standard))
ReadPreference	Read-Preference-Modus. Dieser Parameter definiert, wie Reads bearbeitet werden. Mögliche Werte: PRIMARY: Alle Operationen lesen aus dem primary-Knoten des aktuellen Replica Sets. PRIMARY_PREFERRED: In den meisten Fällen lesen alle Operationen aus dem primary-Knoten. Wenn dieser Knoten nicht verfügbar ist, lesen die Operationen aus den secondary-Knoten (Standard). SECONDARY: Alle Operationen lesen aus den secondary-Knoten des aktuellen Replica Sets. SECONDARY_PREFERRED: In den meisten Fällen lesen alle Operationen aus den secondary-Knoten. Wenn kein secondary-Knoten verfügbar ist, lesen die Operationen aus dem primary-Knoten. NEAREST: Die Operationen lesen unabhängig vom Knotentyp aus dem Knoten des Replica Sets, der die niedrigste Netzwerk-Latenzzeit aufweist.  Zusätzliche Informationen zu den Read-Preference-Modi finden Sie unter:  http://docs.mongodb.org/manual/core/read-preference/ #read-preference-modes  http://api.mongodb.org/java/current/com/mongodb/ReadPreference.html #method_summary
WriteConcern	Gibt an, ob eine write-Operation erfolgreich ausgeführt wurde. Mit Write Concerns können Eingabefehler oder ungültige mongod-Instanzen ermittelt werden. Mögliche Werte: ERRORS_IGNORED: Es werden keine Exceptions ausgeworfen, auch nicht bei Netzwerkproblemen. Dieser Write Concern ist veraltet und verfügt über keinen Ersatz. Am ehesten vergleichbar ist der Write Concern UNACKNOWLEDGED. Dabei müssen jedoch alle Exceptions des Typs MongoSocketException über catch and ignore abgefangen werden. ACKNOWLEDGED: Die Operation wartet auf die Bestätigung des primären Servers, bevor sie ein Ergebnis ausgibt. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. UNACKNOWLEDGED: Die Operation gibt das Ergebnis aus, sobald die Nachricht in den Socket geschrieben wird. Exceptions werden lediglich bei Netzwerkproblemen, jedoch nicht bei Serverfehlern ausgeworfen. FSYNCED: Die Operation wartet, bis der Server sichergestellt hat, dass die Daten auf der Festplatte angekommen sind. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. JOURNALED: Die Operation wartet, bis der Server die Daten zu den Journal-Files committet. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. Beachten Sie: Das Journaling muss aktiviert sein, um diesen Write Concern zu verwenden. Bei diesem Write Concern müssen die Operationen bis zum nächsten Journal-Commit warten. Um die Wartezeit für diese Operationen zu verkürzen, erhöht MongoDB die Commit-Häufigkeit. Weitere Informationen hierzu finden Sie unter commitIntervalMs. REPLICA_ACKNOWLEDGED: Die Operation wartet auf mindestens zwei Server, bevor sie ausgeführt wird. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. NONE: Es werden keine Exceptions ausgeworfen, auch nicht bei Netzwerkproblemen. Dieser Write Concern wurde durch den Write Concern ERRORS_IGNORED und kann in kommenden Releases ggf. veraltet sein. NORMAL: Die Operation gibt das Ergebnis aus, sobald die Nachricht in den Socket geschrieben wird. Exceptions werden lediglich bei Netzwerkproblemen ausgeworfen, jedoch nicht bei Serverfehlern. Dieser Write Concern wurde durch den Write Concern UNACKNOWLEDGED ersetzt und kann in kommenden Releases ggf. veraltet sein .   SAFE: Die Operation wartet auf die Bestätigung des primären Servers, bevor sie ein Ergebnis ausgibt. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. Dieser Write Concern wurde durch den Write Concern ACKNOWLEDGED ersetzt und kann in kommenden Releases ggf. veraltet sein. MAJORITY: Die Operation wartet auf die Mehrheit der Server, bevor sie ausgeführt wird. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. FSYNC_SAFE: Die Operation wartet, bis der Server sichergestellt hat, dass die Daten auf der Festplatte angekommen sind. Exceptions werden sowohl bei Netzwerkpoblemen als auch bei Serverfehlern ausgeworfen. Dieser Write Concern wurde durch den Write Concern FSYNCED ersetzt und kann in kommenden Releases ggf. veraltet sein. JOURNAL_SAFE: Die Operation wartet, bis der Server die Daten zu den Journal-Files committet. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. Dieser Write Concern wurde durch den Write Concern JOURNALED ersetzt und kann in kommenden Releases ggf. veraltet sein. REPLICAS_SAFE: Die Operation wartet auf mindestens zwei Server, bevor sie ausgeführt wird. Exceptions werden sowohl bei Netzwerkproblemen als auch bei Serverfehlern ausgeworfen. Dieser Write Concern wurde durch den Write Concern REPLICA_ACKNOWLEDGED ersetzt und kann in kommenden Releases ggf. veraltet sein.  Zusätzliche Informationen zu den Write Concerns finden Sie unter: http://docs.mongodb.org/manual/core/write-concern/ #write-operations-write-concern http://docs.mongodb.org/ecosystem/drivers/java-replica-set-semantics/ http://api.mongodb.org/java/current/com/mongodb/WriteConcern.html #field_summary

Statuswerte

Verbindung konfigurieren

Die Verbindung zur MongoDB wird in der mongodb-connections.xml innerhalb des X4-Installationsordners konfiguriert, z. B. X4\Server\X4DB\0\mongodb-connections.xml.

<MongoDB>
    <!-- connects to localhost on the default port without authentication -->
    <Connection name="#default" db="test"/>
    
    <Connection name="localhost" db="test">
        <Server host="localhost" port="27017"/>
    </Connection>
</MongoDB>

Erläuterung:

• /MongoDB/Connection: Stellt eine benannte Verbindung dar. Kann mehrfach existieren.
• /MongoDB/Connection/@name: Alias/Referenzname für die Verbindung
• /MongoDB/Connection/@db: Name der Datenbank zu der die Verbindung hergestellt werden soll, d.h., Datenbanken müssen immer über externe Werkzeuge (z .B. MongoShell) angelegt werden.
• /MongoDB/Connection/Server: Stellt einen Servereintrag für eine Verbindung dar. Kann mehrfach pro Connection existieren, um einen Cluster zu adressieren.
• /MongoDB/Connection/Server/@host: IP/DNS-Name des Servers, zu dem eine Verbindung hergestellt werden soll (default: 127.0.0.1).
• /MongoDB/Connection/Server/@port: Port des Servers, zu dem eine Verbindung hergestellt werden soll (default: 27017).
• /MongoDB/Connection/Credential: Anmeldedaten für eine Verbindung. Kann mehrfach pro Verbindung existieren.
• /MongoDB/Connection/Credential/@user: Benutzername der Anmeldung
• /MongoDB/Connection/Credential/@password: Passwort der Anmeldung
• /MongoDB/Connection/Credential/@source: Ursprung der Anmeldedaten (Nutzung zZt. unklar)

Beachten Sie:

Wenn eine Verbindung keine Serverelemente besitzt, wird unabhängig davon, ob Credential-Elemente existieren, ohne Authentifizierungsdaten eine Verbindung mit localhost:27017 hergestellt.

Kodierung einer Dokumentenstruktur

Die JSON/Mongo-Dokumente werden nach einfachen Regeln in ihr XML-Äquivalent übersetzt:

• Dokumente und Objekte/Substrukturen werden durch <Object> dargestellt. Die Schlüssel-Wert-Einträge eines Objekts werden als Kindelemente des Object-Elements abgebildet.
• Arrays werden durch <Array> dargestellt. Die Array-Einträge werden als Kindelemente des Array-Elements abgebildet.
• Wenn es kein Array oder Object ist, wird es durch <Value> dargestellt.
• Der Datentyp eines Values wird in dem Attribut type auf dem Value-Element festgehalten (siehe Unterstützte Datentypen). Wenn kein Datentyp angegeben ist, wird String angenommen.
• Die Schlüssel-Wert-Einträge eines Objektes oder eine Substruktur bekommen den Schlüssel als name-Attribute auf das Element des Wert-Elements gesetzt.

Invarianten:

• Für jede { im JSON wird ein Object-Element im XML angelegt. (Ausnahme: Die Dokumentenwurzel wird in Kommandos durch andere Elemente abgebildet.)
• Für jede [ im JSON wird ein Array-Element im XML angelegt.
• Für jeden : im JSON (der nicht Bestandteil eines String-Literals ist) wird ein name-Attribut angelegt, das den Wert vor dem : als Inhalt enthält.
• Alle Kindelemente eines Object-Elements haben ein name-Attribut.
• Kindelemente eines Array-Elements haben kein name-Attribut.
• Value-Elemente haben kein Kindelement.
• Text-Knoten existieren nur als Kinder von Value-Elementen (Ausnahme: formatierender Whitespace).
• type-Attribute existieren nur auf Value-Elementen (aber nicht jedes Value-Element muss ein type-Attribute haben).

<Object>
	<Value name="some" type="String">thing</Value>
</Object>

Die Dokumenten-Wurzel kann auch durch andere Elemente ersetzt werden, um die Erzeugung eines Object-Elements zu vermeiden. In diesem Fall wäre dort immer ein Object-Element notwendig.

Unterstützte Datentypen

Der Adapter unterstützt folgende Datentypen:

• Null
• ObjectId
• Boolean
• Long
• Int
• Double
• String
• DateTime
• Integer: String wird als BigInteger gelesen und anschließend als Long gespeichert.
• Decimal: String wird als BigDecimal gelesen und anschließend als Double gespeichert.
• Numeric: Wenn der String einen . enthält, wird er als Decimal gelesen, sonst als Integer.

• RegEx: regulärer Ausdruck gemäß http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

  

  Dieses Value-Element kennt zudem das Attribut flags, welches einen String aus folgenden Zeichen ist und die entsprechende Option auf dem Muster setzt:

  • c: CANON_EQ
  • i: CASE_INSENSITIVE
  • m: MULTILINE
  • s: DOTALL
  • u: UNICODE_CASE
  • L: LITERAL
  • N: UNIX_LINES
  • U: UNICODE_CHARACTER_CLASS
  • Z: COMMENTS

Input

Der MongoDB Adapter erwartet spezifische Input-XML-Strukturen. Diese Input-XML-Strukturen enthalten eine Wurzel mit mehreren Kommandos darunter.  Ebenso wird auch das resulttag-Attribut unterstützt.

Input-Struktur

<!-- Ein Root-Element mit beliebigem Namen. -->
<root> 
	<insert collection="products" resulttag="insertOutput">
		<Value name="item" type="String">card</Value>
		<Value name="qty" type="Integer">15</Value>
	</insert>
	<find collection="products" resulttag="findOutput">
		<query>
			<Value name="item" type="String">card</Value>
		</query>
	</find>
	<!-- Hier können weitere Kommandos angegeben werden. -->
</root>

Dies ist ein vollständiges und ausführbares Beispiel. Alle nachfolgenden Beispiele sind lediglich Ausschnitte, die zur Ausführung in eine vollständige Input-Struktur mit einem umschließenden Root-Element eingefügt werden müssen.

Unterstützte Kommandos

• copy (kein MongoDB-Kommando)
• find
• insert
• remove
• save 
• update 

Kommando copy

Mit copy werden alle Kindelemente des copy-Kommandos in die Ausgabe kopiert.

Input

Das copy-Kommando hat folgende Syntax:

<copy resulttag="output">
 	<Child1/>
 	<Child2>
   		<Grandchild1/>
   		<Grandchild2/>
	</Child2>
</copy>

Output

Dieses Kommando gibt folgende XML-Struktur aus:

<output>
 	<Child1/>
 	<Child2>
   		<Grandchild1/>
   		<Grandchild2/>
 	</Child2>
</output>

Kommando  insert

Mit insert wird ein Dokument in die Collection eingefügt. Das insert-Element ist dabei gleichzeitig die Dokumentenwurzel.

• Bitte beachten Sie, dass Batchinsert mit insert nicht unterstützt wird.
• Weitere Informationen zu diesem Kommando finden Sie unter http://docs.mongodb.org/manual/reference/method/db.collection.insert/#db.collection.insert.

Input

Das  insert-Kommando hat folgende Syntax:

<insert collection="foo">
	<Value name="bar" type="String">baz</Value>
</insert>

Output

Dieses Kommando gibt ein WriteResult-Objekt aus, das den Status der Operation enthält.

Kommando  save

Mit save wird gemäß mitgegebenen Daten ein neues Dokument angelegt oder ein bestehendes Dokument aktualisiert. Das save-Element ist dabei gleichzeitig die Dokumentenwurzel.

Weitere Informationen zu diesem Kommando finden Sie unter http://docs.mongodb.org/manual/reference/method/db.collection.save/#db.collection.save.

Input

Das  save-Kommando hat folgende Syntax:

<save collection="foo">
	<Value name="bar" type="String">baz</Value>
</save>

Output

Dieses Kommando gibt ein WriteResult-Objekt aus, das den Status der Operation enthält. 

Kommando update

Mit update wird ein Dokument in einer Collection modifiziert. Je nach update-Parameter kann die Methode spezielle Felder eines bereits bestehenden Dokuments oder ein komplettes Dokument modifizieren.

Weitere Informationen zu diesem Kommando finden Sie unter http://docs.mongodb.org/manual/reference/method/db.collection.update/#db.collection.update.

Input

Das update-Kommando hat folgende Syntax:

<update collection="foo">
	<query/>
	<update upsert="false" multi="false"/>
</update>

Output

Dieses Kommando gibt ein WriteResult-Objekt aus, das den Status der Operation enthält. 

Kommando remove

Mit remove wird ein Dokument aus einer Collection entfernt.

Weitere Informationen zu diesem Kommando finden Sie unter http://docs.mongodb.org/manual/reference/method/db.collection.remove/#db.collection.remove.

Input

Das remove-Kommando hat folgende Syntax:

<remove collection="foo">
	<query/>
</remove>

• Das query-Element enthält den Abfrage/Selektionsteil des remove-Elements und ist auch Dokumentenwurzel für die Abfrage.

Beachten Sie, dass die Option justOne durch den Java-Treiber nicht unterstützt wird.

Output

Dieses Kommando gibt ein WriteResult-Objekt aus, das den Status der Operation enthält. 

Kommando find

Mit find wird ein Dokument aus einer Collection selektiert.

Weitere Informationen zu diesem Kommando finden Sie unter http://docs.mongodb.org/manual/reference/method/db.collection.find/#db.collection.find.

Input

Das find-Kommando hat folgende Syntax:

<find collection="foo">
<--! Optional elements -->
  <query/>
  <projection/>
  	<sort/>
 	<hint/>
  	<min/>
 	<max/>
  	<special/>
  	<cursor skip="0" limit="0" batchSize="0"/>
</find>

Dieses Kommando gibt einen  Cursor  aus, der auf die Dokumente zeigt, welche die query-Kriterien erfüllen.

Beispiele

Folgende Beispiele zeigen Mongo-Ausdrücke und ihre jeweiligen Entsprechungen in XML.

Beispiele für die Dokumentenstruktur:

{}

<Object/>

{ type: "snacks" }

<Object>
  	<Value name="type" type="String">snacks</Value>
</Object>

{ type: { $in: [ 'food', 'snacks' ] } }

<Object>
	<Object name="type">
		<Array name="type">
			<Value type="String">food</Value>
			<Value type="String">snacks</Value>
		</Array>
	</Object>
</Object>

{ type: 'food', price: { $lt: 9.95 } }

<Object>
 	<Value name="type" type="String">food</Value>
	<Object name="price">
 		<Value name="$lt" type="Double">9.95</Value>
	</Object>
</Object>

{ $or: [
 { qty: { $gt: 100 } },
 { price: { $lt: 9.95 } }
 ]
}

<Object>
  <Array name="$or">
 	<Object>
 		<Object name="qty">
 			<Value name="$gt" type="Integer">100</Value>
 		</Object>
 	</Object>
 	<Object>
 		<Object name="price">
 			<Value name="$lt" type="Double">9.95</Value>
 		</Object>
 	</Object>
  </Array>
</Object>

Beispiele für Aufrufe:

 db.products.insert( { item: "card", qty: 15 } )

<insert collection="products">
	 <Value name="item" type="String">card</Value>
	 <Value name="qty" type="Integer">15</Value>
</insert>

db.inventory.save( { type: "book", item: "notebook", qty: 40 } )

<save collection="inventory">
 	<Value name="type" type="String">book</Value>
 	<Value name="item" type="String">notebook</Value>
 	<Value name="qty" type="Integer">40</Value>
</save>

db.books.update(
 { item: "The Banquet" },
 { item: "The Banquet", price: 19 , stock: 3 }
)

<update collection="books">
 	<query>
 		<Value name="item" type="String">The Banquet</Value>
 	</query>
 	<update upsert="true">
		<Value name="item" type="String">The Banquet</Value>
 		<Value name="price" type="Double">19</Value>
 		<Value name="stock" type="Integer">3</Value>
	</update>
</update>

db.books.update(
 { item: "Divine Comedy" },
 {
 $set: { price: 18 },
 $inc: { stock: 5 }
 }
)

<update collection="books">
 	<query>
 		<Value name="item" type="String">Divine Comedy</Value>
 	</query>
 	<update upsert="true">
	 	<Object name="$set">
			<Value name="price" type="Double">19</Value>
 		</Object>
 		<Object name="$inc">
 			<Value name="stock" type="Integer">5</Value>
 		</Object>
 	</update>
</update>

db.inventory.update(
 { type: "book", item : "journal" },
 { $set : { qty: 10 } },
 { upsert : true }
 )

<update collection="inventory">
 	<query>
 		<Value name="type" type="String">book</Value>
 		<Value name="item" type="String">journal</Value>
 	</query>
 	<update upsert="true">
 		<Object name="$set">
 			<Value name="qty" type="Integer">10</Value>
 		</Object>
 	</update>
</update>

db.inventory.update(
 { type : "book" },
 { $inc : { qty : -1 } },
 { multi: true }
)

<update collection="inventory">
 	<query>
 		<Value name="type" type="String">book</Value>
 	</query>
	 <update multi="true">
 		<Object name="$inc">
 			<Value name="qty" type="Integer">-1</Value>
 		</Object>
 	</update>
</update>

db.inventory.find()

<find collection="inventory" />

db.inventory.find({})

<find collection="inventory">
	<query/>
</find>

db.inventory.find( { type: "snacks" } )

<find collection="inventory">
 	<query>
		<Value name="type" type="String">snacks</Value>
	</query>
</find>

db.inventory.find( { type: 'food' }, { _id: 0, item: 1, qty: 1 } )

<find collection="inventory">
 	<query>
 		<Value name="type" type="String">food</Value>
 	</query>
 	<projection>
 		<Value name="_id" type="Integer">0</Value>
 		<Value name="item" type="Integer">1</Value>
 		<Value name="qty" type="Integer">1</Value>
 	</projection>
</find>

<find collection="inventory">
 	<query>
 		<Value name="type" type="String">food</Value>
	</query>
 	<projection>
 		<exclude name="_id" />
 		<include name="item" />
 		<include name="qty" />
 		<!-- excludes und includes können mit Object, Array und Value im projection-Element gemischt werden -->
 	</projection>
</find>

db.stocks.find().sort( { ticker: 1, date: -1 } )

<find collection="stocks">
 	<sort>
 		<Value name="ticker" type="Integer">1</Value>
 		<Value name="date" type="Integer">-1</Value>
 	</sort>
</find>

<find collection="stocks">
 	<sort>
 		<ascending name="ticker" />
 		<descending name="date" />
 		<!-- ascending und descending können mit Object, Array und Value im sort-Element gemischt werden -->
 	</sort>
</find>

db.stocks.find().sort( { ticker: 1 } ).limit(100)

<find collection="stocks">
 	<sort>
 		<ascending name="ticker" />
 	</sort>
 	<cursor limit="100"/>
</find>

db.stocks.find().sort( { ticker: 1 } ).skip(200).limit(100)

<find collection="stocks">
 	<sort>
 		<ascending name="ticker" />
 	</sort>
 	<cursor skip="200" limit="100"/>
</find>