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

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)

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>

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>

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.

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.

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.

Input

Das update-Kommando hat folgende Syntax:

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

Erläuterung:

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

• Das update-Element enthält den Veränderungsteil des Updates und ist auch Dokumentenwurzel für die Veränderung.

• Die Optionen upsert und multi werden auf dem inneren update-Element angegeben.

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.

Input

Das remove-Kommando hat folgende Syntax:

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

Erläuterung:

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

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.

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>

Erläuterung:

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

• Das projection-Element enthält die Feldauswahl des find-Elements und ist auch Dokumentenwurzel für die Auswahl.

Die weiteren optionalen Elemente steuern das Verhalten des Ergebnis-Cursors:

• sort (Dokumentenwurzel), siehe auch http://docs.mongodb.org/manual/reference/method/cursor.sort/#cursor.sort

• hint (Dokumentenwurzel), siehe auch http://docs.mongodb.org/manual/reference/method/cursor.hint/#cursor.hint

• min (Dokumentenwurzel), siehe auch http://docs.mongodb.org/manual/reference/method/cursor.min/#cursor.min

• max (Dokumentenwurzel), siehe auch http://docs.mongodb.org/manual/reference/method/cursor.max/#cursor.max

• special (quasi-Dokumentenwurzel), siehe auch http://api.mongodb.org/java/current/com/mongodb/DBCursor.html#addSpecial(java.lang.String,%20java.lang.Object)

  Für jeden Kindknoten in der Wurzel des special-Dokuments wird die addSpecial-Methode aufgerufen.

  
  

• cursor (no body) ist lediglich der Träger für folgende drei Attribute:skip, siehe auch http://docs.mongodb.org/manual/reference/method/cursor.skip/#cursor-skiplimit, siehe auch http://docs.mongodb.org/manual/reference/method/cursor.limit/#cursor.limitbatchSize, siehe auch http://docs.mongodb.org/manual/reference/method/cursor.batchSize/#cursor.batchSize

Output

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>