Child pages
  • Terracotta Integration Modules Manual

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Include Page
documentation-navbar
documentation-navbar
Section
Column
width250px
{div:style=} {include:
Wiki Markup
Div
stylemargin-top:20px
Include Page
documentation-index
documentation-index
} {div}
Column
{div9:id=documentationcolumn} h1. Terracotta Integration Modules Manual {toc:minLevel=2|maxLevel=3} h2. Before you start - Questions? Find answers, insights, and inspiration at the [Terracotta forums|http://forums.terracotta.org/forums/forums/list.page]. - Promote your integration project to an official Terracotta project at the [Terracotta Forge|http://forge.terracotta.org] and learn about becoming a [contributor|http://www.terracotta.org/confluence/display/devdocs/How+To+Become+A+Contributor]. - Share your integration project with a [community|http://www.terracotta.org/confluence/display/wiki/Home] of Terracotta DSO users. h2. Introduction Terracotta Integration Modules (TIMs) are sets of configuration elements and supporting Java classes packaged together as a single, includable module within the Terracotta configuration. A TIM allows you to integrate Terracotta DSO with the framework or platform that your application is based on. {tip} While a Terracotta configuration file resides with a Terracotta server instance, TIMs are never installed on Terracotta server instances. This is because applications are never integrated with Terracotta server instances, only with Terracotta clients. Terracotta clients get their TIM configurations when they fetch the Terracotta configuration file from a Terracotta server instance or by having their own Terracotta configuration files. {tip} The catalog of available TIMs continues to grow as new technologies are integrated with Terracotta DSO. Community-developed TIMs are also being added. For the complete list of currently supported modules, see the Terracotta Forge at
Wiki Markup
Div
iddocumentationcolumn

Terracotta Integration Modules Manual

Table of Contents
minLevel2
maxLevel3

Before you start

  • Share your integration project with a community of Terracotta DSO users.

Introduction

Terracotta Integration Modules (TIMs) are sets of configuration elements and supporting Java classes packaged together as a single, includable module within the Terracotta configuration. A TIM allows you to integrate Terracotta DSO with the framework or platform that your application is based on.

Tip

While a Terracotta configuration file resides with a Terracotta server instance, TIMs are never installed on Terracotta server instances. This is because applications are never integrated with Terracotta server instances, only with Terracotta clients. Terracotta clients get their TIM configurations when they fetch the Terracotta configuration file from a Terracotta server instance or by having their own Terracotta configuration files.

The catalog of available TIMs continues to grow as new technologies are integrated with Terracotta DSO. Community-developed TIMs are also being added. For the complete list of currently supported modules, see the Terracotta Forge at http://forge.terracotta.org.

If

a

TIM

isn't

available

for

your

environment,

this

document

shows

you

how

to

build

one.

Wiki Markup
{Note}
While there are many approaches and tools that could be used to design and build a TIM, we recommend Apache Maven. Except as noted below, this document focuses on using Maven2 for managing a TIM project.
{Note}
h2.

Integration

Module

Versioning

Versioning

a

TIM

to

fit

with

the

Terracotta

development

scheme

is

crucial

for

a

smooth

integration

path.

The

Terracotta

development

scheme

takes

the

Apache

Maven

approach

of

appending

"SNAPSHOT"

to

build

versions

still

in

flux.

A

typical

TIM

filename

looks

like

the

following:

{{

clustered-hibernate-3.2.5-2.6.0.jar

}}

where

a

descriptive

name

(clustered-hibernate)

is

followed

by

the

named

application's

version

(3.2.5),

and

finally

the

TIM

version

(2.6.0).

To

facilitate

a

consistent

and

functional

version-control

process,

an

official

management

policy

for

TIM

publishing

is

in

place.

If

you

pursue

creating

and

publishing

a

TIM,

follow

these

guidelines:

-

  • There
  • is
  • a
  • single
  • Maven2
  • repository
  • that
  • hosts
  • both
  • releases
  • and
  • snapshots
--
  • using
  • it
  • is
  • strongly
  • recommended.
-
  • Whenever
  • a
  • change
  • is
  • made
  • to
  • a
  • TIM,
  • the
  • version
  • number
  • must
  • be
  • incremented
  • as
  • appropriate,
  • in
_
  • both
_
  • the
{{
  • MANIFEST.MF
}}
  • file
  • for
  • the
  • module
  • and
  • the
  • module's
  • own
{{
  • pom.xml
}}
  • .
-
  • A
  • TIM
  • must
  • remain
  • a
{{
  • -SNAPSHOT
}}
  • version
  • until
  • it
  • becomes
  • an
  • official
  • release.
-
  • If
  • a
  • TIM
  • depends
  • on
{{
  • -SNAPSHOT
}}
  • versions
  • of
  • other
  • integration
  • modules,
  • then
  • the
  • dependencies
  • for
  • that
  • TIM
  • must
  • explicitly
  • declare
  • those
  • versions.
-
  • A
  • released
  • TIM
  • cannot
  • depend
  • on
{{
  • -SNAPSHOT
}}
  • versions
  • of
  • other
  • integration
  • modules.
-
  • At
  • product
  • release
  • time,
  • TIMs
  • are
  • blessed
  • as
  • release
  • versions
  • with
  • an
  • incremented
  • version
  • number.
-
  • Release
  • versions
  • of
  • all
  • current
  • TIMs
  • must
  • be
  • published
  • to
  • the
  • Terracotta
  • Maven
  • repository.
{anchor:create} h2. Create Your Own Terracotta Integration Module TIMs are very similar to [OSGi|http://www.osgi.org/] bundles or [Eclipse|http://www.eclipse.org/] plugins. Logically, a TIM is a specification loaded at runtime that tells the Terracotta software how to instrument certain Java objects. Structurally, a TIM is a {{jar}} file with special headers in the manifest. While a TIM can contain code that modifies bytecode directly, normally it's nothing more than an XML file containing a subtree of the {{tc-config.xml}} file. To meet Terracotta integration specification, the TIM requires at least one of the following: a) A {{terracotta.xml}} file (located in the root of the {{jar}}) b) An [OSGi|http://www.osgi.org/] {{BundleActivator}} Case b) supports a special use case where custom bytecode manipulation is required. Case b) is not likely to be encountered and is not covered here. {tip:title=Java code vs. terracotta.xml} If your project requires using a {{BundleActivator}} and you need help, post a question on the [developer mailing list|http://www.terracotta.org/confluence/display/wiki/Mailing+Lists]. {tip} You can build your TIM using Apache Maven and the Maven TIM archetype, or manually. The procedures for each of these methods are given below. {note} For either procedure, be sure you are familiar with Terracotta DSO and have a working {{tc-config.xml}} file. {note} h3. Procedure Using the Maven TIM Archetype This procedure assumes that you have Maven installed and are familiar with Maven projects. # Download and install the [Maven TIM archetype|http://forge.terracotta.org/releases/projects/tim-archetype/docs/installation.html]. # Generate a Maven TIM project archetype by following *these* instructions. Generating the project creates the necessary directory structure, a stub configuration file, a manifest file, and a Maven {{pom.xml}}. # that you can use to build the integration module jar. # Edit {{terracotta.xml}} to support the library or framework your TIM is intended for. See [terracotta.xml|#terracotta.xml] for details. # Add the appropriate headers to the {{MANIFEST.MF}} file. See [MANIFEST.MF|#manifest.mf] for details. h3. Manual Procedure # Create a {{terracotta.xml}}. # Edit {{terracotta.xml}} to support the library or framework your TIM is intended for. See [terracotta.xml|#terracotta.xml] for details. # Create a {{jar}} manifest file called {{MANIFEST.MF}}. # Add the appropriate headers to the {{MANIFEST.MF}} file. See [MANIFEST.MF|#manifest.mf] for details. # Package the {{terrracotta.xml}} and {{MANIFEST.MF}} files into a {{jar}} file. For example: {code}

Anchor
create
create

Create Your Own Terracotta Integration Module

TIMs are very similar to OSGi bundles or Eclipse plugins. Logically, a TIM is a specification loaded at runtime that tells the Terracotta software how to instrument certain Java objects. Structurally, a TIM is a jar file with special headers in the manifest. While a TIM can contain code that modifies bytecode directly, normally it's nothing more than an XML file containing a subtree of the tc-config.xml file.

To meet Terracotta integration specification, the TIM requires at least one of the following:

a) A terracotta.xml file (located in the root of the jar)
b) An OSGi BundleActivator

Case b) supports a special use case where custom bytecode manipulation is required. Case b) is not likely to be encountered and is not covered here.

Tip
titleJava code vs. terracotta.xml

If your project requires using a BundleActivator and you need help, post a question on the developer mailing list.

You can build your TIM using Apache Maven and the Maven TIM archetype, or manually. The procedures for each of these methods are given below.

Note

For either procedure, be sure you are familiar with Terracotta DSO and have a working tc-config.xml file.

Procedure Using the Maven TIM Archetype

This procedure assumes that you have Maven installed and are familiar with Maven projects.

  1. Download and install the Maven TIM archetype.
  2. Generate a Maven TIM project archetype by following these instructions.
    Generating the project creates the necessary directory structure, a stub configuration file, a manifest file, and a Maven pom.xml.
  3. that you can use to build the integration module jar.
  4. Edit terracotta.xml to support the library or framework your TIM is intended for.
    See terracotta.xml for details.
  5. Add the appropriate headers to the MANIFEST.MF file.
    See MANIFEST.MF for details.

Manual Procedure

  1. Create a terracotta.xml.
  2. Edit terracotta.xml to support the library or framework your TIM is intended for.
    See terracotta.xml for details.
  3. Create a jar manifest file called MANIFEST.MF.
  4. Add the appropriate headers to the MANIFEST.MF file.
    See MANIFEST.MF for details.
  5. Package the terrracotta.xml and MANIFEST.MF files into a jar file.
    For example:
    Code Block
    
    jar cvfm MyApp-cluster-config-1.0-1.0.0-SNAPSHOT.jar META-INF/MANIFEST.MF terracotta.xml
    
{code}
  1. Be
  1. sure
  1. to
  1. name
  1. your
{{
  1. jar
}}
  1. file
  1. using
  1. conventions
  1. that
  1. facilitate
  1. your
  1. integration
  1. project.
  1. See
  1. the
  1. versioning
  1. guidelines
  1. above
  1. and
  1. these
[
  1. usage
  1. guidelines
|docs:Configuration Guide and Reference#ConfigurationModules]
  1. for
  1. more
  1. information.
h3. {anchor:

Anchor
terracotta.xml
terracotta.xml

}

terracotta.xml

The

{{

terracotta.xml

}}

file

contains

a

subtree

of

the

{{

application/dso

}}

element

of

the

{{

<tc-config.xml>

}}

file,

wrapped

in

an

{{

<xml-fragment>

}}

element.

If

the

content

of

your

{{

tc-config.xml

}}

file

is

similar

to

the

following:

{code:xml}

Code Block
xml
xml

<tc:tc-config xmlns:tc="http://www.terracotta.org/config">
  <!-- ...stuff... -->
  <application>
    <dso>
      <instrumented-classes>
        <!-- ...other stuff... -->
      </instrumented-classes>
      <locks>
        <!-- ...yet more stuff... -->
      </locks>
    </dso>
  </application>
  <!-- ...trailing stuff... -->
</tc:tc-config>
{code}

then

the

content

of

your

{{

terracotta.xml

}}

file

should

be

similar

to

the

following:

{code:xml}

Code Block
xml
xml

<xml-fragment>
  <instrumented-classes>
    <!-- ...other stuff... -->
  </instrumented-classes>
  <locks>
    <!-- ...yet more stuff... -->
  </locks>
</xml-fragment>
{code} h3. {anchor:

Anchor
manifest.mf
manifest.mf

}

META-INF/MANIFEST.MF

The

manifest

file

has

one

required

[

OSGi

|http://www.osgi.org/]

header:

{{

Bundle-SymbolicName

}}

.

Optional

headers

can

be

added

to

make

the

manifest

file

more

useful.

{

Tip
:
title
=
Generate
TIM
Manifest
using
Terracotta
Maven
Plugin
}

If

Maven

is

used

to

build

the

TIM

project,

the

TIM

manifest

file

can

be

generated

using

the

[

Maven

Plugin

for

Terracotta

|http://forge.terracotta.org/releases/projects/tc-maven-plugin/manifest-mojo.html]. {tip} The following is an example of set of headers in a {{MANIFEST.MF}} file: {noformat}

.

The following is an example of set of headers in a MANIFEST.MF file:

No Format

Bundle-Description: MyApp/MyFramework Cluster Configuration
Bundle-DocURL: http://www.myorg.org/doc/terracotta-integration-module/
Bundle-Name: Terracotta integration module for MyApp/MyFramework
Bundle-SymbolicName: org.myorg.myapp.integration_module
Bundle-Vendor: MyOrg, Inc.
Bundle-Version: 1.0
{noformat}

See

the

[

OSGi

|http://www.osgi.org/]

R4

documentation

for

more

information

on

headers.

[

Eclipse

|http://www.eclipse.org/]

offers

a

manifest

editor

that

makes

it

easier

to

work

with

manifest

files.

h2.

Using

Your

TIM

To

use

your

TIM,

save

the

TIM

{{

jar

}}

file

to

a

module

repository

and

add

the

following

element

to

clients/modules

in

your

{{

tc-config.xml

}}

file:

{code:xml}

Code Block
xml
xml

<module name="MyApp-cluster-config" version="1.0"/>
{code}

Adding

this

element

effectively

embeds

the

{{

terracotta.xml

}}

in

{{

tc-config.xml

}}

.

{

Tip
:
title
=
Module
Versions
Are
Optional
}

Since

the

tim-get

script

finds

the

optimal

version

for

the

current

installation

of

the

Terracotta

kit,

module

versions

are

optional.

{tip} See these [usage guidelines|docs:Configuration Guide and Reference#ConfigurationModules] for a more detailed procedure. {anchor:replace tim} h2. Using a TIM to Replace a Shared Class Under certain circumstances, you may want to replace a class with your own version. This can be done using a TIM. The TIM's contents should be similar to the following: {code}

See these usage guidelines for a more detailed procedure.

Anchor
replace tim
replace tim

Using a TIM to Replace a Shared Class

Under certain circumstances, you may want to replace a class with your own version. This can be done using a TIM. The TIM's contents should be similar to the following:

Code Block

public class FooModule extends TerracottaConfiguratorModule {
     protected void addInstrumentation(BundleContext context) {
         super.addInstrumentation(context);
         Bundle bundle = getExportedBundle(context, "org.foo.tim-foo");
         addClassReplacement(bundle, "org.foo.Impl", "org.foo.ClusteredImpl");
     }
 }
{code}

where:

*

  • FooModule
  • is
  • the
  • class
  • name
  • of
  • the
  • TIM.
*
  • org.foo.Impl
  • is
  • the
  • class
  • to
  • replace.
*
  • org.foo.ClusteredImpl
  • is
  • the
  • new
  • class.
*
  • org.foo.tim-foo
  • is
  • the
  • value
  • of
  • the
  • TIM's
_
  • Bundle-SymbolicName
_
  • manifest
  • header.
  • For
  • example,
  • the
  • ehcache-1.3
  • TIM
  • has
  • the
_
  • Bundle-SymbolicName
_
  • manifest
  • header
_
  • org.terracotta.modules.clustered-ehcache-1.3
_
  • .
{comment}
comment

The above can be linked to from the c&a guide, and non-portable classes list.
{comment} h2. Additional Reading See [Juris

Additional Reading

See Juris Galang's

blog

entry

|http://www.jurisgalang.com/articles/read/tim_archetype]

on

using

the

TIM

archetype.

{div9}