Exposing the MongoDB as an OData service

This tutorial will guide you on how to expose data from a MongoDB datasource as an OData service using the ESB profile of WSO2 Enterprise Integrator (WSO2 EI).

Follow the steps given below. Also, see the samples in /wiki/spaces/EI6xx/pages/49616348.

Install and start MongoDB 

A MongoDB server v2.4.x or v2.2.x should be already running in the default port.

Create a collection as below in the command shell.

Creating a data service

Now, let's start creating the data service from scratch:

1. Download the product installer from here, and run the installer.
   Let's call the installation location of your product the <EI_HOME> directory. This is located in a place specific to your OS as shown below:

   OS	Home directory
   Mac OS	/Library/WSO2/EnterpriseIntegrator/6.6.0
   Windows	C:\Program Files\WSO2\EnterpriseIntegrator\6.6.0\
   Ubuntu	/usr/lib/wso2/EnterpriseIntegrator/6.6.0
   CentOS	/usr/lib64/EnterpriseIntegrator/6.6.0

2. Start the ESB profile:
3. Log in to the management console of ESB profile of WSO2 EI using the following URL on your browser:  "https://localhost:9443/carbon/".
4. Click Create under the Data Service menu to open the Create Data Service window.

5. Enter the following data service name.

   Data Service Name	MongoDB

6. Leave the default values for the other fields.
7. Click Next to go to the Datasources screen

Connecting to the datasource

When you get to the Add New Data Source screen, click Add New Datasource to open the corresponding screen.

1. Start by entering the following values:

   Datasource ID	MongoDB
   Datasource Type	MongoDB

2. You can then specify the connection details to the MongoDB database you set up previously. The fields available for the MongoDB datasource type are as follows:

   Servers	Enter localhost. This can be a comma separated list of server hosts and ports where the database is running. E.g.: "localhost" - "125.10.5.3, 125.10.5.4" - "192.168.3.1:27017, 192.168.3.2:27017".
   Database Name	Enter mydb. The name of the database to which you want to connect.
   Write Concern	Select NONE from the list. The write concern value to control the write behavior as well as exception raising on error conditions:   Descriptions of Write Concern options Option Description FSYNC_SAFE Exceptions are raised for network issues, and server errors. The write operation waits for the server to flush the data to disk. NONE No exceptions are raised, even for network issues. NORMAL Exceptions are raised for network issues, but not server errors. REPLICAS_SAFE Exceptions are raised for network issues, and server errors; waits for at least 2 servers for the write operation. SAFE Exceptions are raised for network issues, and server errors; waits on a server for the write operation.
   Read Preference	Select PRIMARY from the list. The read preference value, which describes how MongoDB clients route read operations to members of a replica set. It has the following options.  Descriptions of Read Preference options Option Description PRIMARY Default mode. All operations read from the current replica set primary. SECONDARY All operations read from the secondary members of the replica set.
   Auto Connect Retry	Controls whether or not to connect. That is, the system retries to connect automatically.
   Connection Timeout	Connection timeout in milliseconds. 0 is default and infinite.
   Max. Wait	Max wait time of a blocking thread for a connection.
   Socket Timeout	Socket timeout value. 0 is default and infinite.
   Connections per Host	If the number of connections allowed per host is exceeded, further connections will be blocked.
   Threads Allowed to Block For Connection Multiplier	The value in this field, multiplied by the connections per host, gives the maximum number of threads that may be waiting for a connection to become available from the pool. All further threads will get an exception. For example, if connections per host are 10 and the 'threads allowed to block for connection multiplier' is 5, up to 50 threads can wait for a connection.

Creating a query to POST data

Follow the steps given below.

1. Click Add New Query and enter the following details:

   Query ID	Enter mongo_insert as the query ID.
   Datasource	Select the datasource for which you are going to write a query. Select the mongo datasource that you created previously.
   Expression	In this field, enter the SPARQL query describing the data that should be retrieved from the RDF datasource. We will use the following query:  things.insert("{id:#, name:#}")

2. Now let's specify input mappings for the data in the MongoDB database. We will create output mappings for the id and name fields.
   

   1. Click Add New Input Mapping to start creating the input mapping. We want to add data into the database using the id and name fields. First, create the input mapping for id.
      
   2. Click Add to save the input mapping.
   3. Create the input mapping for the name field.
      
      
3. Save the query.

Creating a query to GET data

Now, let's start writing a query for getting data from the MongoDB datasource. The query will specify the data that should be fetched by this query, and the format that should be used to display data when the query is invoked.

1. Click Add New Query, and enter the following data:

   Query ID	Enter mongo_find as the query ID.
   Datasource	Select the datasource for which you are going to write a query. Select the mongo datasource that you created previously.
   SPARQL	In this field, enter the SPARQL query describing the data that should be retrieved from the MongoDB datasource. We will use the following query:  things.find()

2. Define Output Mapping: Now, let's specify how the data fetched from the datasource should be displayed in the output. We will create output mappings for the Data field.
   

1. Start by giving the following information:
   

   Output type	Specify the format in which the query results should be presented. You can select XML, JSON or RDF. We will use XML for this tutorial.
   Grouped by element	Specify a grouping for all the output mappings. This will be the XML element that will group the query result. Enter Documents in this field.
   Row Name	Specify the XML element that should group each individual result. Enter Document in this field.

2. Click Add New Output Mapping to start creating the output mapping. Enter the following values:
   

3. Click Main Configuration to return to the Query screen.
   

3. Save the query, and click Next to go to the Operations screen.

Creating SOAP operations to invoke the queries

To invoke the query, you need to define an operation.

1. Click Add New Operation and enter the following information.
   

   Operation Name	mongo_insert_op
   Query ID	mongo_insert

2. Save the operation.

3. Click Add New Operation and enter the following information.
   

   Operation Name	mongo_find_op
   Query ID	mongo_find

4. Save the operation.
   

You can now invoke the data service query using SOAP.

Creating REST resources to invoke the queries

Now, let's create REST resources to invoke the query created above. Alternatively, you can create SOAP operations to invoke the queries. See the previous section for instructions.

1. Click Add New Resource and enter the following information.
   

   Resource Path	insert/{id}
   Resource Method	POST
   Query ID	mongo_insert

2. Save the resource.

3. Click Add New Resource and enter the following information.
   

   Resource Path	find
   Resource Method	GET
   Query ID	mongo_find

4. Save the resource.
   

You can now invoke the data service query using REST.

Finish creating the data service

Once you have defined the operation, click Finish to complete the data service creation process. You will now be taken to the Deployed Services screen, which shows all the data services deployed on the server.

Access the data service using CRUD operations

Open a REST client and execute the following commands using CRUD operations. Note that you should have privileges to perform CRUD operations on the database. If not, the OData service will not work properly.

https://localhost:8243/odata/{data_service_name}/{data_source_id}

GET https://localhost:8243/odata/MongoODataSampleService/MongoID 

Accept : application/json

To get the metadata of the service:

https://localhost:8243/odata/{data_service_name}/{data_source_id}/$metadata

GET https://localhost:8243/odata/MongoODataSampleService/MongoID/metadata

Accept : application/xml

To read details from the project table:

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}

GEThttps://localhost:8243/odata/MongoODataSampleService/MongoID/project

Accept : application/json

To read an individual record:

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}(‘_id’)

GEThttps://localhost:8243/odata/MongoODataSampleService/MongoID/project(‘5c2edc2e70df5656835ae19e’)

Accept : application/json

To add a new record to project table, send the HTTP request as shown below. In this example we will be creating a record with name : “Project2” and id : "2".

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}

POST https://localhost:8243/odata/MongoODataSampleService/MongoID/project

Accept: application/json

Content-Type: application/json

Prefer : return=representation

{ "name" : “Project2” ,"id" : “2” }

To delete an existing record, send the HTTP request as shown below. In this example, we will be deleting the document Project2 with the corresponding ObjectId of the particular document. (note : Since MongoDB is schemaless, you cannot have a separate primary key field for the collections and therefore MongoDB driver generates a unique ObjectId(i.e. _id) for every document that you enter.  Hence ObjectId should be used as the primary key in MongoDB.)

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}('_id')


DELETE https://localhost:8243/odata/MongoODataSampleService/MongoID/PROJECT('5c29b6f577ec332a94d8fecc')

Accept: application/json

Content-Type: application/json

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}('_id')

DELETE https://localhost:8243/odata/MongoODataSampleService/MongoID/PROJECT('5c29b6f577ec332a94d8fecc')

Accept: application/json

Content-Type: application/json

{ "location" : ”Kandy” }

To invoke a particular query, send the HTTP request as shown below. In this example, we are going to retrieve the id and name of all the projects.

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}?$select={attribute_name_1, attribute_name_2}


GET https://localhost:8243/odata/MongoODataSampleService/MongoID/project?$select=name,id

Accept: application/json

To filter information based on a query, send the HTTP request as shown below. In this example, we will receive the project details with location 'Colombo'.

https://localhost:8243/odata/{data_service_name}/{data_source_id}/{table_name}?$filter={attribute_name} eq {attribute_value}

GET https://localhost:8243/odata/MongoODataSampleService/MongoID/project?$filter=location eq 'Colombo'

Accept: application/json