Skip to content

Latest commit

 

History

History
79 lines (60 loc) · 3.9 KB

mongo.md

File metadata and controls

79 lines (60 loc) · 3.9 KB
Raw

Binding MongoDB instances to Liberty applications

If you bind a MongoDB service instance to an application, the Liberty buildpack generates the following configuration elements in the server.xml file. The elements are required to access the database.

  • A mongo element with the default hostname and port subelements.
  • A mongoDB element.
  • A library element with an embedded fileset subelement. The library element is created for the MongoDB driver.
  • A featureManager element. The Liberty buildpack also adds the mongodb-2.0 feature to the featureManager element.
  • An application element. The Liberty buildpack adds the classloader for the Mongo library to the application element.

In addition, the Liberty buildpack provides the MongoDB driver that is required.

In the mongoDB element, the Liberty buildpack generates a JNDI name that is used by your application to access MongoDB. Because the Liberty buildpack does not have access to the JNDI name that is used by the application, the Liberty buildpack generates a JNDI name with a convention of mongo/service_name, where service_name is the name of the bound service. For example, if you bind a MongoDB service that is named mydb to the application, the Liberty buildpack generates a JNDI name of mongo/mydb. When you develop the application and create the MongoDB service instance, ensure that the JNDI name that is used by the application to access the database is the same as the JNDI name that is generated by the Liberty buildpack.

The following example shows the configuration that is generated when an application is pushed to the cloud and is bound to a MongoDB service instance that is named mydb:

    <application name="myapp" context-root="/" location="myapp" type="war">
        <classloader commonLibraryRef='mongo-library'/>
    </application>
    
    <mongo id='mongo-mydb' libraryRef='mongo-library'
           user='${cloud.services.mydb.connection.user}'
           password='${cloud.services.mydb.connection.password}'>
        <hostNames>${cloud.services.mydb.connection.hosts}</hostNames>
        <ports>${cloud.services.mydb.connection.ports}</ports>
    </mongo>
    
    <mongoDB id='mongo-mydb-db'
             databaseName='${cloud.services.mydb.connection.db}'
             jndiName='mongo/mydb' mongoRef='mongo-mydb'/>
             
    <library id='mongo-library'>
        <fileset id='mongo-fileset' dir='${server.config.dir}/lib'
                 includes='mongo-java-driver-2.12.3.jar'/>
    </library>

With this configuration, the mongoDB database should be accessible using Java code similar to the following:

import javax.annotation.Resource
import com.mongodb.DB

...

@Resource(name = "mongo/mydb")
private DB mydb;

The configuration elements in the server.xml file use the following IDs and ID formats:

  • The mongo element uses a configuration ID of mongo-service_name.
  • The mongoDB element uses a configuration ID of myongo-service_name-db.
  • The library element uses a configuration ID of mongo-library.
  • The fileset element uses a configuration ID of mongo-fileset.

If the Liberty buildpack finds existing configuration, it checks and updates the configuration if necessary. For example, the buildpack might update the following elements and attributes:

  • The user and password attributes in the mongo element. The hostNames and ports subelements of the mongo element might also be updated.
  • The databaseName attribute of the mongoDB element.
  • The dir and includes attributes of the fileset element.

The Liberty buildpack does not update the jndiName attribute.

You can provide your own client driver JAR files. The client driver JAR files must be placed in the usr/servers/<servername>/lib directory. If you do not provide client driver JAR files, the Liberty buildpack provides the files for you. The client driver JAR files that you provide must use the standard names that are established by the providing vendor. You cannot rename client JAR files.