Installation v0.3

The couchbase manager is a session manager for glassfish. The installation process consists in two phases: adding the libraries to application server and changing the file descriptors in the application to begin using the module. Since version 0.3.0 the manager can be used in glassfish v3 (3.1.2.2) and v4 (4.0).

Adding the modules

Glassfish uses an OSGi framework in order to activate different services (different JavaEE specifications like EJBs or CDI are integrated as OSGi modules but also non-standard modules like Spring are available). This way the couchbase manager should be integrated as another module. The couchbase manager manages at this moment the following libraries:

• couchbase-manager-v3-0.3.0.jar or couchbase-manager-v4-0.3.0.jar. The couchbase manager itself for the two different glassfish versions. Select only one depending the version of glassfish you are using.
• spymemcached-2.10.1.jar. The spymemcached library to access memcached alike memory repositories.
• couchbase-client-1.2.1.jar. The specialized couchbase library that adds to the spymemcached client some specific features (like locking).
• commons-codec-1.6.jar. Library dependency from couchbase client to add Base64 encoding provided by the Apache Foundation.
• netty-3.5.5.Final.jar. Library dependency from couchbase client to add non-io features.
• httpcore-4.1.1.jar and httpcore-nio-4.1.1.jar. Another dependencies from couchbase to deal with HTTP conections.
• jettison.jar. Another dependency from couchbase client.

Glassfish already uses jettison (version 1.1) to deal with JSON so this library is distributed with v3 and v4 bundles by default. The other libraries should be copied inside the following directory:

<GLASSFISH3_DIR>/glassfish/modules/

Remember that since 0.3 there are two versions of the couchbase manager. You have to download couchbase-manager-v3-0.3.0.jar if using glassfish v3 and couchbase-manager-v4-0.3.0.jar if running v4. The rest of dependencies are exactly the same for both versions.

As it was previously commented all of them must be OSGi modules (that requires some special MANIFEST.MF tags). And, although Netty, commems-codec and httpcore are distributed as an OSGi module, the other two (couchbase-client and spymemcached) are not. For that reason those libraries were re-packaged (OSGi enabled) and all of them can be downloaded from here.

Copy all the libraries in the commented directory and restart glassfish.

Configuring the manager in your application

Once the libraries are available for glassfish your application should specify that it is going to use the manager. In order to do that web.xml and glassfish-web.xml are going to be used:

---

In the web.xml the distributable tag needs to be added:

  <distributable/>

---

Inside the glassfish-web.xml custom file the session-config section is configured. There coherence-web must be specified as the persistence type and the following properties are currently managed by the manager:

• repositoryUrl: The list of URIs of the couchbase servers, it is a comma separated list. For example http://server1:8091/pools,http://server2:8091/pools. Default: http://localhost:8091/pools.
• repositoryBucket: Repository bucket to use in couchbase. Default: default.
• repositoryUsername: Repository admin username to use in the bucket. Default no user.
• repositoryPassword: Repository admin password. Default no password.
• sticky: Change the manager to be sticky. Sticky works very different, session is not locked in couchbase and it is not reload every request. Default false.
• lockTime: The amount of time in seconds that a key will be locked inside couchbase manager without being released. In current couchbase implementation the maximum locktime is 30 seconds. Default 30.
• operationTimeout: The time in milliseconds to wait for any operation against couchbase to timeout. Default 30000ms (30s).
• persistTo: the amount of nodes the item should be persisted to before returning. This is a couchbase parameter to all write/modification operation, the value should be the String representation of the net.spy.memcached.PersistTo enumeration. Default ZERO.
• replicateTo: the amount of nodes the item should be replicated to before returning. This is a couchbase parameter to all write/modification operation, the value should be the String representation of the net.spy.memcached.ReplicateTo enumeration. Default ZERO.

The following example shows how to add the couchbase manager in this file:

<session-config>
  <session-manager persistence-type="coherence-web">
    <manager-properties>
      <property name="repositoryUrl" value="http://localhost:8091/pools"/>
      <property name="repositoryBucket" value="default"/>
      <property name="sticky" value="true"/>
      <property name="lockTime" value="30"/>
      <property name="persistTo" value="ONE"/>
    </manager-properties>
  </session-manager>
</session-config>

---

The application session is serialized in order to be saved in the couchbase repository. So, all the objects that are stored into the session should implement the Serializable interface.

---

Finally deploy your application inside the glassfish target:

asadmin deploy --availabilityenabled=true --target=<GLASSFISH_TARGET> <APP.WAR>