User Guide

The eMongo project provides an OSGi service model for MongoDB. Thin wrappers are created on top of the MongoDB driver and registered as OSGi services complete with metatype. If you combine this with the Apache Fexlx Web Console, building and configuring servers using this environment is greatly simplified.

Mongo Provider Service

The MongoProvider OSGi service provides access to a configured MongoDB driver. The implementation of the client provider service MongoProviderComponent requires a configuration through the ConfigurationAdmin service. Metatype is provided for configuration by a UI. Most of the configuration properties correspond to the attributes of MongoClientOptions in the MongoDB driver.

eMongo Specific Service Properties

• uri - the URI of the MongoDB database in the form: mongodb://host[:port] - use a CSV of URIs for a replica set
• databaseName - the database to connect to

MongoClientOptions Service Properties

• alwaysUseMBeans
• connectionsPerHost
• connectTimeout
• cursorFinalizerEnabled
• description
• heartbeatConnectTimeout
• heartbeatFrequency
• heartbeatSocketTimeout
• localThreshold
• maxConnectionIdleTime
• maxConnectionLifeTime
• maxWaitTime
• minConnectionsPerHost
• minHeartbeatFrequency
• readPreferenceType
• readPreferenceTags
• requiredReplicaSetName
• serverSelectionTimeout
• socketKeepAlive
• socketTimeout
• sslEnabled
• sslInvalidHostNameAllowed
• threadsAllowedToBlockForConnectionMultiplier
• w
• wtimeout
• fsync
• j

Mongo ID Factory Service

The MongoIdFactory OSGi service provides access to a configured ID factory service. The ID factory is used to generate a sequential ID for records in a collection. The factory stores the latest ID value as a special record in the collection to maintain consistency across reboots. This type of ID can be useful when you need to display the ID of a record to users. The ID factory service requires a configuration through the ConfigurationAdmin service. Metatype is provided for configuration by a UI.

Configuration Properties

• MongoDatabaseProvider.target - the target filter used to bind to the database service in the form: (alias=alias_of_database_service)
• collection - the database collection name

MongoLogListener Component

The MongoLogListener is an OSGi component that persists OSGi log entries into a MongoDB collection. Since this is a component and not a service, there is no public API. To use this component, simply include the org.eclipselabs.emongo.log bundle in your runtime. The component requires a configuration through the ConfigurationAdmin service. Metatype is provided for configuration by a UI.

Configuration Properties

• MongoDatabaseProvider.target - the target filter used to bind to the database service in the form: (alias=alias_of_database_service)
• collection - the database collection name
• maxLevel - the maximum log level to persist - defaults to LogService.LOG_ERROR

Here is an example log entry:

{ 
  "_id" : ObjectId("528ac950ef86a96274a8ca41"), 
  "level" : 3, 
  "bsn" : "net.springfieldusa.ems.app.email.component", 
  "time" : ISODate("2013-11-19T02:13:36.628Z"), 
  "message" : "ServiceEvent REGISTERED", 
  "pid" : "net.springfieldusa.ems.app.email.component.EmailComponent" 
}

Configuration

Configuration of the service can be done either programmatically through the ConfigurationAdmin service or by a UI that uses the metatype data like the Apache Felix Web Console.

Here is an example configuration of a client service for a MongoDB server running on localhost:

Here is an example configuration of a database service for the client above:

Here is an example configuration of an ID factory service for the database above:

Example Client

@Component
public class MyComponent
{
  private volatile MongoDatabaseProvider mongoDatabaseProvider;

  @Activate
  public void activate()
  {
    DB database = mongoDatabaseProvider.getDB();
    DBCollection collection = database.getCollection("items");
    ...
  }

  @Reference(unbind = "-", target = "(alias=primary)")
  public void bindMongoDatabaseProvider(MongoDatabaseProvider mongoDatabaseProvider)
  {
    this.mongoDatabaseProvider = mongoDatabaseProvider;
  }
}

MongoDB JUnit Testing

A JUnit MongoDatabase @Rule is available to assist with unit testing. The MongoDatabase rule will clean out the database after each test. The rule has several constructors for flexibility, but also attempts to provide a reasonable set of defaults. Here is an example unit test:

public class MyTest
{
  @Rule
  public MongoDatabase database = new MongoDatabase();

  @Test
  public void testMyFunction()
  {
    DB db = database.getMongoDB();
    ...
  }
}