Installation

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.5.0.jar or couchbase-manager-v4-0.5.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.5.jar. The spymemcached library to access memcached alike memory repositories.
• couchbase-client-1.3.2.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.
• org.apache.httpcomponents.httpcore_4.3.2.jar. Another dependency 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.5.0.jar if using glassfish v3 and couchbase-manager-v4-0.5.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.
• attrMaxSize: Attributes with a size greater than this property value will be tracked to calculate its usage ratio. It is specified in bytes. Default 10240 (10K).
• attrUsageCondition: This property defines when a big attribute (see previous property) its externalized or re-integrated. The attribute is a three integer number: {minimum-samples}-{low-limit}-{high-limit}. The first one (minimum samples) defines the minimum samples taken to start checking if an attribute is externalized. The second number (low limit) is the ratio low limit, when an attribute ratio is below this limit it is externalized. The last one (high limit) is the upper limit, an externalized attribute with a ratio above this limit will be re-integrated in the session object. The default value is 10-10-25 for sticky configuration and 10-30-45 for non-sticky (the sticky configuration has lower limits).
• attrTouchExtraTime: The number of seconds of extra expiration time for external attributes, the external attributes expiration in couchbase is the session expiration plus this number of seconds. It is specified in seconds, default value 600 (10 minutes).
• extraInactiveInterval: Since version 0.5.0 the session maximum inactivity interval is incremented by a extra amount of seconds in which the session remains in couchbase. This extra time is given to access session information before expiration in couchbase (JavaEE listeners mainly). Desfaul: 180 seconds.

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>