MongoDB Connector

MongoDB Connector: Connects to a MongoDB and executes one or more database statements passed as an input XML document with adapter-specific structures.

Parameters

Adapter	Main class of the adapter (do not change!) Possible values:  de.softproject.integration.adapter.mongodb.MongoAdapter : Main class (default)
ConnectionName	Alias/reference name for the connection; Corresponds to the Connection name from the connection configuration, see Configure connection. Possible values: Name of the connection (e.g. #default (default)).
ReadPreference	Read-preference mode; this parameter defines how reads are processed Possible values: PRIMARY: All operations read from the primary node of the current replica set. PRIMARY_PREFERRED: In most cases all operations read from the primary node, but if it is not available, read from the secondary nodes (default). SECONDARY: All operations read from the secondary nodes of the current replica set. SECONDARY_PREFERRED: In most cases all operations read from the secondary nodes, but if these are not available, read from the primary node. NEAREST: The operations read from the node of the replica set with the lowest network latency, regardless of the node type.  Additional information on read-preference modes is also available at:  http://docs.mongodb.org/manual/core/read-preference/ #read-preference-modes  http://api.mongodb.org/java/current/com/mongodb/ReadPreference.html #method_summary
WriteConcern	Indicates whether a write operation was successfully executed. Write Concerns allow to detect input errors or invalid mongod instances. Possible values: ERRORS_IGNORED: No exceptions are thrown, not even in case of network problems. This write concern is and has no replacement. The write concern UNACKNOWLEDGED is the most comparable. However, all exceptions of the type MongoSocketException must be caught via catch and ignore. ACKNOWLEDGED: The operation waits for confirmation from the primary server before issuing a result; exceptions are thrown for both network problems and server errors. UNACKNOWLEDGED: The operation returns the result as soon as the message is written to the socket. Exceptions are thrown only for network problems, but not for server errors. FSYNCED: The operation waits until the server has ensured that the data has arrived on disk. Exceptions are thrown in the event of both network problems and server errors. JOURNALED: The operation waits until the server commits the data to the journal files. Exceptions are thrown in case of network problems as well as server errors. Notice: Journaling must be enabled to use this write concern. With this write concern, operations must wait until the next journal commit. To reduce the waiting time for these operations, MongoDB increases the commit frequency, see also commitIntervalMs. REPLICA_ACKNOWLEDGED: The operation waits for at least two servers before executing; exceptions are thrown for both network problems and server errors. NONE: No exceptions are thrown, not even in case of network problems. This write concern is obsolete and has been replaced by the write concern ERRORS_IGNORED and may be deprecated in future releases. NORMAL: The operation prints the result as soon as the message is written to the socket; exceptions are only thrown in case of network problems, but not in case of server errors. This write concern has been replaced by the write concern UNACKNOWLEDGED and may be deprecated in future releases . SAFE: The operation waits for confirmation from the primary server before issuing a result; exceptions are thrown for both network problems and server errors. This write concern has been replaced by the write concern ACKNOWLEDGED and may be deprecated in future releases. MAJORITY: The operation waits for the majority of servers before executing; exceptions are thrown for both network problems and server errors. FSYNC_SAFE: The operation waits until the server has ensured that the data has arrived on disk; exceptions are thrown in the event of both network problems and server errors. This write concern has been replaced by the write concern FSYNCED and may be deprecated in future releases. JOURNAL_SAFE: The operation waits until the server commits the data to the journal files; exceptions are thrown in case of network problems as well as server errors. This write concern has been replaced by the JOURNALED write concern and may be deprecated in future releases . REPLICAS_SAFE: The operation waits for at least two servers before it is executed; exceptions are thrown in case of network problems as well as server errors. This write concern has been replaced by the REPLICA_ACKNOWLEDGED write concern and may be deprecated in future releases.  Additional information on Write Concerns is also available at: 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

Status values

Configuring the connection

The connection to MongoDB is configured in mongodb-connections.xml  inside the X4 installation folder, e.g. 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>

Explanation:

• /MongoDB/Connection: Represents a named connection; May exist multiple times.
• /MongoDB/Connection/@name: Alias/reference name for the connection.
• /MongoDB/Connection/@db: Name of the database to which the connection should be made, i.e. databases must always be created via external tools (e.g. MongoShell).
• /MongoDB/Connection/Server: Represents a server entry for a connection; may exist multiple times per connection to address a cluster.
• /MongoDB/Connection/Server/@host: IP/DNS name of the server to connect to (default: 127.0.0.1)
• /MongoDB/Connection/Server/@port: Port of the server to connect to (default: 27017)
• /MongoDB/Connection/Credential: credentials for a connection; may exist multiple times per connection.
• /MongoDB/Connection/Credential/@user: User name of the login
• /MongoDB/Connection/Credential/@password: Login password
• /MongoDB/Connection/Credential/@source: Origin of credentials (usage currently unclear)

Notice:

If a connection has no server elements, it connects against localhost:27017 without authentication data, regardless of whether credential elements exist or not.

Coding of a document structure

The JSON/Mongo documents are translated into their XML equivalent according to simple rules:

• Documents and objects/substructures are represented by <Object>. The key-value entries of an object are mapped as child elements of the Object element.
• Arrays are represented by <Array>. The array entries are mapped as child elements of the Array element.
• If it is not an array or object, it is represented by <Value>.
• The data type of a Value is recorded in the type attribute on the Value element (see Supported data types). If no data type is specified, String is assumed.
• The key-value entries of an object or a substructure get the key set as name attributes on the element of the value element.

Invariants:

• For each { in the JSON, an Object element is created in the XML. (Exception: the document root is mapped by other elements in commands).
• For each [ in the JSON, an Array element is created in the XML.
• For each : in the JSON (which is not part of a string literal) a name attribute is created which contains the value before the : as content.
• All child elements of an Object element have a name attribute.
• Child elements of an Array element do not have a name attribute
• Value elements do not have a child element.
• Text nodes exist only as children of Value elements (exception: formatting whitespace).
• type attributes exist only on Value elements (but not every Value element must have a type attribute).

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

The document root can also be replaced by other elements to avoid the creation of an Object element. In this case, an Object element would always be necessary there.

Supported data types

The adapter supports the following data types:

• Null
• ObjectId
• Boolean
• Long
• Int
• Double
• String
• DateTime
• Integer: String is read as BigInteger and then stored as Long
• Decimal: String is read as BigDecimal and then stored as Double
• Numeric: If the string contains a . it will be read as Decimal, otherwise as Integer

• RegEx: Regular expression according to http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

  

  This Value element also knows the flags attribute, which is a string of the following characters and sets the corresponding option on the pattern:

  • 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

The MongoDB Adapter expects specific input XML structures. These input XML structures contain a root with several commands underneath. Likewise, the resulttag attribute is also supported.

Input structure

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

This is a complete and executable example. All subsequent examples are merely snippets that must be inserted into a complete input structure with an enclosing root element in order to execute.

Supported commands

• copy (no MongoDB command)
• find
• insert
• remove
• save 
• update 

Command copy

With copy all child elements of the copy command are copied to the output.

Input

The copy command has the following syntax:

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

Output

This command outputs the following XML structure:

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

Command  insert

With insert a document is inserted into the collection. The insert element is also the document root.

• Please note that Batchinsert with insert is not supported.
• More information about this command can also be found at http://docs.mongodb.org/manual/reference/method/db.collection.insert/#db.collection.insert.

Input

The insert command has the following syntax:

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

Output

This command outputs a WriteResult  object containing the status of the operation.

Command save

With save a new document is created or an existing document is updated according to the given data. The save element is also the document root.

More information about this command can also be found at http://docs.mongodb.org/manual/reference/method/db.collection.save/#db.collection.save.

Input

The save command has the following syntax:

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

Output

This command outputs a WriteResult  object containing the status of the operation.

Command update

With update a document in a collection is modified. Depending on the update  parameter, the method can modify specific fields of an existing document or a complete document.

More information about this command can also be found at http://docs.mongodb.org/manual/reference/method/db.collection.update/#db.collection.update.

Input

The update command has the following syntax:

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

Output

This command outputs a WriteResult object containing the status of the operation.

Command remove

With remove a document is removed from a collection.

More information about this command can also be found at http://docs.mongodb.org/manual/reference/method/db.collection.remove/#db.collection.remove.

Input

The remove command has the following syntax:

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

• The query element contains the query/selection part of the remove and is also the document root for the query.

Note that the justOne option is not supported by the Java driver.

Output

This command outputs a WriteResult object containing the status of the operation.

Command find

With find a document is selected from a collection.

More information about this command can also be found at http://docs.mongodb.org/manual/reference/method/db.collection.find/#db.collection.find.

Input

The find command has the following syntax:

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

This command outputs a Cursor pointing to the documents that meet the query criteria.

Samples

The following examples show Mongo expressions and their respective equivalents in XML.

Examples of document structure:

{}

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

Call examples:

 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>