Working with a MongoDB Data Adapter

MongoDB is a big data architecture based on the NoSQL model that is neither relational nor SQL-based. Jaspersoft Studio includes data adapters that allow reports to use a native MongoDB data connection or a MongoDB JDBC data adapter. JasperReports Server also supports SSL and x509 authentication for MongoDB.

Creating a Native MongoDB Connection

To create a MongoDB data adapter with the native driver:

Follow these steps to create a MongoDB data source with the native MongoDB driver.

1. Create the connection globally or locally:
•      To create the connection globally, right-click Data Adapters in the Repository Explorer and choose Create Data Adapter.
•      To create the connection local to a project, click , enter a name and location for the data adapter in the DataAdapter File dialog box, and then click Next.

The Data Adapter wizard appears (see Data Adapter Wizard).

2. From the list, select MongoDB Connection to open the Data Adapter dialog.

Configuring a MongoDB Connection
3. Fill in the required fields:
•      Name: The name that will appear on the list of available data adapters when you create or run a report.
•      Mongo URI: The URI of your MongoDB data.
4. If you have configured your MongoDB source to be password protected, specify a valid username and password.
5. Click Test to check the values you entered. If everything's okay, you'll see a success message.
6. Click OK to exit the message.
7. Click Finish to create the connection.

If you get a ClassNotFoundError exception, the most likely cause is that the required driver is not present in the classpath. See ClassNotFoundError for more information.

The Jaspersoft MongoDB Query Language

MongoDB is designed to be accessed through API calls in an application or a command shell. As a consequence, it does not have a defined query language. In order to write queries for MongoDB data sources, we have developed a query language based on the JSON-like objects upon which MongoDB operates. JSON is the JavaScript Object Notation, a textual representation of data structures that is both human- and machine-readable.

The Jaspersoft MongoDB Query Language is a declarative language for specifying what data to retrieve from MongoDB. The connector converts this query into the appropriate API calls and uses the MongoDB Java connector to query the MongoDB instance. The following examples give an overview of the Jaspersoft MongoDB Query Language, with SQL-equivalent terms in parentheses:

• Retrieve all documents (rows) in the given collection (table): 
{ 'collectionName' : 'accounts' }
• From all documents in the given collection, select the named fields (columns) and sort the results: 
{
  'collectionName' : 'accounts',
  'findFields' : {'name':1,'phone_office':1,'billing_address_city':1,
                  'billing_address_street':1,'billing_address_country':1},
  'sort' : {'billing_address_country':-1,'billing_address_city':1}
}
• Retrieve only the documents (rows) in the given collection (table) that match the query (where clause). In this case, the date is greater-than-or-equal to the input parameter, and the name matches a string (starts with N): 
{
  'collectionName' : 'accounts',
  'findQuery' : {
    'status_date' : { '$gte' : $P{StartDate} },
    'name' : { '$regex' : '^N', '$options' : '' }
  }
}

The Jaspersoft MongoDB Query Language also supports advanced features of MongoDB such as map-reduce functions and aggregation that are beyond the scope of this document. For more information, see the language reference on the Community website.

When you create a report or subdatasource from a native MongoDB connection, Jaspersoft Studio automatically selects MongoDBQuery as the query language. You can explicitly view and set the query language using the Dataset and Query Dialog.

Example Dataset and Query Dialog for a MongoDB Data Adapter

Creating a MongoDB JDBC Data Source

If you want to wrap your MongoDB data source in a domain or virtual data source, create a MongoDB JDBC data source. The MongoDB JDBC driver can create a default normalized schema for your data or, if you prefer, you can load a schema from the repository or your server file system.

This section describes functionality that can be restricted by the software license for JasperReports Server. If you don’t see some of the options described in this section, your license may prohibit you from using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

To create a MongoDB JDBC data source:

1. Create the connection globally or locally:
•      To create the connection globally, right-click Data Adapters in the Repository Explorer and choose Create Data Adapter.
•      To create the connection local to a project, click , enter a name and location for the data adapter in the DataAdapter File dialog box, and then click Next.

The Data Adapter wizard appears (see Data Adapter Wizard).

2. From the list, select Database JDBC Connection to open the Data Adapter dialog.
3. In the JDBC Driver field, select MongoDB (TIBCO Jaspersoft).

MongoDB JDBC Data Adapter Dialog
4. Fill in the required fields:
•      Name: The name that will appear on the list of available data adapters when you create or run a report.
•      JDBC URL: The URL for your MongoDB instance. This is in the following format:

jdbc:tibcosoftware:mongodb://host:port;databaseName=db;SchemaDefinition=file

where:

• host:port is the host and port of your MongoDB instance
• db is the name of the database to use in your MongoDB instance
• file (optional) is a location on your local disk where you want to store the schema definition. When you first connect to a MongoDB server, the driver automatically creates a normalized schema of the data and generates a SchemaDefinition for housing and sharing the normalized schema. You can also specify the path of an existing schema on your local disk.
5. If you have configured your MongoDB source to be password protected, specify a valid username and password.
6. (Optional) Click Connection Properties to specify any additional properties for your connection. For example, if you're using MongoDB and you want to enable SSL, enter:

EncryptionMethod=SSL;ValidateServerCertificate=false

To enable both SSL encryption and self-signed CA, enter the TrustStore and KeyStore paths and the KeyStore password. For example:

EncryptionMethod=SSL;TrustStore=<path>;KeyStore=<path>;KeyStorePassword=<password>;

7. Click Test to check the values you entered. If everything's okay, you'll see this message:

Test Confirmation Dialog
8. Click OK to exit the message.
9. Click Finish to create the connection.

If you get a ClassNotFoundError exception, it may be due to one of the following:

• You are not licensed to use the TIBCO MongoDB JDBC driver. This driver is only available in commercial editions.
• The required driver is not present in the classpath. See ClassNotFoundError for more information.