Summary: Configuration | Message Processors | Transformers

org.mule.modules

mule-module-mongo

2.0

Namespace	http://www.mulesoft.org/schema/mule/mongo
Schema Location	http://www.mulesoft.org/schema/mule/mongo/2.0/mule-mongo.xsd
Version	2.0
Minimum Mule Version	3.2

Module Overview

A Mongo Connector Facade

Summary

Configuration
<mongo:config> Configure an instance of this module

Message Processors
<mongo:count-objects> Counts the number of objects that match the given query.
<mongo:count-objects-using-query-map> Counts the number of objects that match the given query.
<mongo:create-collection> Creates a new collection.
<mongo:create-file-from-payload> Creates a new GridFSFile in the database, saving the given content, filename, contentType, and extraData, and answers it.
<mongo:create-index> Creates a new index
<mongo:drop-collection> Deletes a collection and all the objects it contains.
<mongo:drop-index> Drops an existing index
<mongo:exists-collection> Answers if a collection exists given its name
<mongo:find-files> Lists all the files that match the given query
<mongo:find-files-using-query-map> Lists all the files that match the given query
<mongo:find-objects> Finds all objects that match a given query.
<mongo:find-objects-using-query-map> Finds all objects that match a given query.
<mongo:find-one-file> Answers the first file that matches the given query.
<mongo:find-one-file-using-query-map> Answers the first file that matches the given query.
<mongo:find-one-object> Finds the first object that matches a given query.
<mongo:find-one-object-using-query-map> Finds the first object that matches a given query.
<mongo:get-file-content> Answers an inputstream to the contents of the first file that matches the given query.
<mongo:get-file-content-using-query-map> Answers an inputstream to the contents of the first file that matches the given queryAttributes.
<mongo:insert-object> Inserts an object in a collection, setting its id if necessary.
<mongo:insert-object-from-map> Inserts an object in a collection, setting its id if necessary.
<mongo:list-collections> Lists names of collections available at this database
<mongo:list-files> Lists all the files that match the given query, sorting them by filename.
<mongo:list-files-using-query-map> Lists all the files that match the given query, sorting them by filename.
<mongo:list-indices> List existent indices in a collection
<mongo:map-reduce-objects> Transforms a collection into a collection of aggregated groups, by applying a supplied element-mapping function to each element, that transforms each one into a key-value pair, grouping the resulting pairs by key, and finally reducing values in each group applying a suppling 'reduce' function.
<mongo:remove-files> Removes all the files that match the given query.
<mongo:remove-files-using-query-map> Removes all the files that match the given query.
<mongo:remove-objects> Removes all the objects that match the a given optional query.
<mongo:remove-using-query-map> Removes all the objects that match the a given optional query.
<mongo:save-object> Inserts or updates an object based on its object _id.
<mongo:save-object-from-map> Inserts or updates an object based on its object _id.
<mongo:update-objects> Updates objects that matches the given query.
<mongo:update-objects-using-map> Updates objects that matches the given query.

Transformers
<mongo:bson-list-to-json> Convert a BasicBSONList into Json.
<mongo:db-object-to-map> Convert a DBObject into Map.
<mongo:dbobject-to-json> Convert DBObject to Json.
<mongo:json-to-dbobject> Convert JSON to DBObject.
<mongo:mongo-collection-to-json> Convert a BasicBSONList into Json.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:mongo="http://www.mulesoft.org/schema/mule/mongo"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/mongo
               http://www.mulesoft.org/schema/mule/mongo/2.0/mule-mongo.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necesary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
Type	Name	Default Value	Description
xs:string	name		Optional. Give a name to this configuration so it can be later referenced.
xs:string	database	test	Optional. The database name of the Mongo server
xs:string	host	localhost	Optional. The host of the Mongo server
xs:int	port	27017	Optional. The port of the Mongo server

Connection Pool

This connector offers automatic connection management via the use of a connection pool. The pool will act a storage mechanism for all the connections that are in-use by the user of this connector.

Prior to execution of a processor, the connector will attempt to lookup an already established connection and if one doesn't exists it will create one. That lookup mechanism is done in the connection pool via the use of connection variables declared as keys.

The user of the connector can configure the pool by adding a connection-pooling-profile to the connector configuration like this:

    <mongo:connection-pooling-profile maxActive="10" maxIdle="10"
                             exhaustedAction="WHEN_EXHAUSTED_GROW" maxWait="120"/>

The following is a list of connection attributes, each connection attribute can be configured at the config element level or they can also be added to each processor. If they are used at the processor level they get the benefit of full expression resolution.

Connection Attributes
Name	Description
username	The username to use in case authentication is required
password	The password to use in case authentication is required, null if no authentication is desired

Also this connector offers automatic retry for certain operations. There are a couple of situations in which a retry may solve the problem at hand, like for example if the system is currently busy or if the session has expired. Those kind of situations are solvable by reacquiring a connection and retrying the operation.

By default, the connector will automatically attempt to retry the operation only once. You can at your choosing specify a greater ammount of retries by using the retryMax attribute on each operation.

    ... retryMax="3"/>

Message Processors

<mongo:count-objects>

Counts the number of objects that match the given query. If no query is passed, returns the number of elements in the collection

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
query		Optional. The optional DBObject query for counting objects. Only objects matching it will be counted. If unspecified, all objects are counted.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the amount of objects that matches the query

<mongo:count-objects-using-query-map>

Counts the number of objects that match the given query. If no query is passed, returns the number of elements in the collection

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
queryAttributes		Optional. The optional query for counting objects. Only objects matching it will be counted. If unspecified, all objects are counted.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the amount of objects that matches the query

<mongo:create-collection>

Creates a new collection. If the collection already exists, a MongoException will be thrown.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection to create
capped		Optional. If the collection will be capped
maxObjects		Optional. The maximum number of documents the new collection is able to contain
size		Optional. The maximum size of the new collection
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:create-file-from-payload>

Creates a new GridFSFile in the database, saving the given content, filename, contentType, and extraData, and answers it.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
payload		The mandatory content of the new gridfs file. It may be a java.io.File, a byte[] or an InputStream.
filename		The mandatory name of new file.
contentType		Optional. The optional content type of the new file
metadata		Optional. The optional DBObject metadata of the new content type
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the new GridFSFile
DBObject

Exception Payload

IOException

<mongo:create-index>

Creates a new index

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection where the index will be created
field		The name of the field which will be indexed
order		Optional. The indexing order
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:drop-collection>

Deletes a collection and all the objects it contains. If the collection does not exist, does nothing.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection to drop
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:drop-index>

Drops an existing index

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection where the index is
index		The name of the index to drop
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:exists-collection>

Answers if a collection exists given its name

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

if the collection exists

<mongo:find-files>

Lists all the files that match the given query

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
query		Optional. A DBObject query the optional query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a
DBObject files iterable

<mongo:find-files-using-query-map>

Lists all the files that match the given query

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
queryAttributes		Optional. The optional query attributes
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a
DBObject files iterable

<mongo:find-objects>

Finds all objects that match a given query. If no query is specified, all objects of the collection are retrieved. If no fields object is specified, all fields are retrieved.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
query		Optional. The optional DBObject query object. If unspecified, all documents are returned.
fields		Optional. Alternative way of passing fields as a literal List
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an iterable of
DBObject

<mongo:find-objects-using-query-map>

Finds all objects that match a given query. If no query is specified, all objects of the collection are retrieved. If no fields object is specified, all fields are retrieved.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
queryAttributes		Optional. The optional query object. If unspecified, all documents are returned.
fields		Optional. Alternative way of passing fields as a literal List
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an iterable of
DBObject

<mongo:find-one-file>

Answers the first file that matches the given query. If no object matches it, a MongoException is thrown.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
query		The DBObject mandatory query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a
DBObject

<mongo:find-one-file-using-query-map>

Answers the first file that matches the given query. If no object matches it, a MongoException is thrown.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
queryAttributes		The mandatory query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a
DBObject

<mongo:find-one-object>

Finds the first object that matches a given query. Throws a
MongoException if no one matches the given query

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
query		The mandatory DBObject query object that the returned object matches.
fields		Optional. Alternative way of passing fields as a literal List
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a non-null
DBObject that matches the query.

<mongo:find-one-object-using-query-map>

Finds the first object that matches a given query. Throws a
MongoException if no one matches the given query

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The target collection
queryAttributes		The mandatory query object that the returned object matches.
fields		Optional. Alternative way of passing fields as a literal List
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a non-null
DBObject that matches the query.

<mongo:get-file-content>

Answers an inputstream to the contents of the first file that matches the given query. If no object matches it, a MongoException is thrown.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
query		The DBObject mandatory query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an InputStream to the file contents

<mongo:get-file-content-using-query-map>

Answers an inputstream to the contents of the first file that matches the given queryAttributes. If no object matches it, a MongoException is thrown.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
queryAttributes		The mandatory query attributes
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an InputStream to the file contents

<mongo:insert-object>

Inserts an object in a collection, setting its id if necessary.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection where to insert the given object
dbObject		A DBObject instance.
writeConcern		Optional. The optional write concern of insertion
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the id that was just insterted

<mongo:insert-object-from-map>

Inserts an object in a collection, setting its id if necessary.

A shallow conversion into DBObject is performed - that is, no conversion is performed to its values.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection where to insert the given object
elementAttributes		Optional. Alternative way of specifying the element as a literal Map inside a Mule Flow
writeConcern		Optional. The optional write concern of insertion
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the id that was just insterted

<mongo:list-collections>

Lists names of collections available at this database

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

the list of names of collections available at this database

<mongo:list-files>

Lists all the files that match the given query, sorting them by filename. If no query is specified, all files are listed.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
query		Optional. The DBObject optional query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an iterable of
DBObject

<mongo:list-files-using-query-map>

Lists all the files that match the given query, sorting them by filename. If no query is specified, all files are listed.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
queryAttributes		Optional. The optional query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an iterable of
DBObject

<mongo:list-indices>

List existent indices in a collection

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

a collection of
DBObject with indices information

<mongo:map-reduce-objects>

Transforms a collection into a collection of aggregated groups, by applying a supplied element-mapping function to each element, that transforms each one into a key-value pair, grouping the resulting pairs by key, and finally reducing values in each group applying a suppling 'reduce' function.

Each supplied function is coded in JavaScript.

Note that the correct way of writing those functions may not be obvious; please consult MongoDB documentation for writing them.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection to map and reduce
mapFunction		A JavaScript encoded mapping function
reduceFunction		A JavaScript encoded reducing function
outputCollection		Optional. The name of the output collection to write the results, replacing previous collection if existed, mandatory when results may be larger than 16MB. If outputCollection is unspecified, the computation is performed in-memory and not persisted.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

Return Payload

an iterable that retrieves the resulting collection of
DBObject

<mongo:remove-files>

Removes all the files that match the given query. If no query is specified, all files are removed

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
query		Optional. The DBObject optional query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:remove-files-using-query-map>

Removes all the files that match the given query. If no query is specified, all files are removed

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
queryAttributes		Optional. The optional query
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:remove-objects>

Removes all the objects that match the a given optional query. If query is not specified, all objects are removed. However, please notice that this is normally less performant that dropping the collection and creating it and its indices again

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The collection whose elements will be removed
query		The optional DBObject query object. Objects that match it will be removed.
writeConcern		Optional. The write concern used to remove the object
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:remove-using-query-map>

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The collection whose elements will be removed
queryAttributes		The query object. Objects that match it will be removed.
writeConcern		Optional. The write concern used to remove the object
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:save-object>

Inserts or updates an object based on its object _id.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The collection where to insert the object
element		The mandatory DBObject object to insert.
writeConcern		Optional. The write concern used to persist the object
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:save-object-from-map>

Inserts or updates an object based on its object _id.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The collection where to insert the object
elementAttributes		The mandatory object to insert.
writeConcern		Optional. The write concern used to persist the object
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:update-objects>

Updates objects that matches the given query. If parameter multi is set to false, only the first document matching it will be updated. Otherwise, all the documents matching it will be updated.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection to update
query		The DBObject query object used to detect the element to update.
element		The DBObject mandatory object that will replace that one which matches the query.
upsert		Optional. If the database should create the element if it does not exist
multi		Optional. If all or just the first object matching the query will be updated
writeConcern		Optional. The write concern used to update
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired

Child Elements

<mongo:update-objects-using-map>

Updates objects that matches the given query. If parameter multi is set to false, only the first document matching it will be updated. Otherwise, all the documents matching it will be updated.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
collection		The name of the collection to update
queryAttributes		The query object used to detect the element to update.
elementAttributes		The mandatory object that will replace that one which matches the query.
upsert		Optional. If the database should create the element if it does not exist
multi		Optional. If all or just the first object matching the query will be updated
writeConcern		Optional. The write concern used to update
retryMax	1	Optional. Specify how many times this operation can be retried automatically
username		Optional. The username to use in case authentication is required
password		Optional. The password to use in case authentication is required, null if no authentication is desired