• Bug
  • Status: Closed
  • 1 Critical
  • Resolution: Fixed
  • Documentation,ehcache
  • Reporter:
  • July 05, 2011
  • 0
  • Watchers: 4
  • July 27, 2012
  • February 14, 2012

Description

Since the introduction of the Terracotta toolkit the README.html in the distribution has been incorrect.

To get integration with Terracotta going you actually need to follow these new instructions:

Maven Based Development =======================

     Most Ehcache modules are placed in the central Maven repository.

     The Maven snippet for ehcache is:

     <dependency>
        <groupid>net.sf.ehcache</groupid>
        <artifactid>ehcache</artifactid>
        <version>[current-version]</version>
        <type>pom</type>
     </dependency>

    To deploy to a Terracotta server you also need to add the following:


    <dependency>
        <groupId>org.terracotta</groupId>
        <artifactId>terracotta-toolkit-1.2-runtime</artifactId>
        <version>3.1.0</version>
    </dependency>


    <repositories>
        <repository>
            <id>terracotta-repository</id>
            <url>http://www.terracotta.org/download/reflector/releases</url>
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
    </repositories>

Then create an ehcache.xml configuration from the one supplied in the distribution and place it in the root of your classpath.

We used to be able to specify just ehcache and it would suck everything else in. Users would need to specify ehcache-core to avoid that.

Not any more. Now you get: “Please verify that terracotta-toolkit is in your classpath”

The terracotta-toolkit is not sucked in.

I then googled to try to find what the snippet for it was. I found one that did not work over in the terracotta.org docs. Then I googled again and found out how to do it from this forum post: http://forums.terracotta.org/forums/posts/list/5382.page where someone else was having the same problem.

What exacerbates this is that our Maven repo is not browsable. So it is impossible to discover the maven coordinates from the Maven repo. Nice! I have found a way to fix this and have created a separate JIRA for it.

So we have a very difficult situation. I almost gave up trying to get this going yesterday afternoon. I think this is hurting us a lot.

Preferred Fix

Move the terracotta-toolkit into oss.sonatype and thence Maven central. It is TPL so there should be no more of a licensing problem than we had with ehcache-terracotta before it. The add terracotta-toolkit as an ehcache dependency.

That way it just works.

Workaround

Fix the README.HTML ( I have already done this in trunk) so at least it works. Fix http://www.terracotta.org/documentation/toolkit-intro.html

Comments

Hung Huynh 2011-07-06

Are we sure terracotta-toolkit runtime license would allow it to be on Maven central?

[GL] Yes, we have ehcache-terracotta there which is under the same TPL. Check with Tim McIntyre though.

Also, if we add terracotta-toolkit to ehcache’s pom, if a fix was introduced into toolkit but not ehcache, will the version of ehcache’s pom change to pick up the new toolkit?

[GL] If we use an open ended range it will get picked up.

ehcache pom includes: ehcache-core, ehcache-terracotta, and now terracotta-toolkit runtime.

Does the terracotta-toolkit really need to live in Maven central repo? The ehcache’s pom has reference to TC repo already. http://svn.terracotta.org/svn/forge/projects/terracotta-ehcache/trunk/ehcache-express-kit/pom.xml

[GL] The Maven Central Rules are here: http://maven.apache.org/guides/mini/guide-central-repository-upload.html

[GL] They will allow us to specify our own repo for a dependency. If we do that then that will only require a change to the ehcache pom right?

Tim Eck 2011-07-06

to make things a little more confusing. I think part of the (current) reason for not declaring a dependency on terracotta-toolkit-runtime is that they are bound to core terracotta versions (ie. L2 version).

[GL] Yep - aware of that.

For example the mentioned artifact:

org.terracotta terracotta-toolkit-1.2-runtime 3.1.0

Only works with a 3.5.0 server (not 3.5.1, not 3.6.0, etc). We could leave the version range open on the upper side but the fact that we encode the toolkit API version in the artifactId means people might think they have to use a 1.2 runtime (whereas they can really use anything 1.2+)

[GL] Yep the two versions are very confusing.

There is plenty of good argument for potentially re-jiggering the versioning and coordinates of the toolkit given all this, just not sure we’re attacking the right problem by adding a toolkit dependency in the pom here.

[GL] The problem is that it is too difficult to get the software working out of the box. This is focused at new users trying to get Ehcache and Terracotta running.

Tim Eck 2011-07-07

I annotated Greg’s comments to the comments above since I can’t understand them without them.

Fiona OShea 2011-07-12

Need input from PM on priority of this. Thanks everyone for commenting.

Gautam Jayaprakash 2011-08-02

Meeting scheduled for 5pm today.

gluck 2011-08-02

Mike, Hung and I agreed to:

1) Add a dependency on the toolkit in ehcache.pom. 2) For versions before Ulloa, we cannot update the README.html because the kits are already shipped. So:

a) Update http://ehcache-org/documentation/user-guide/getting-started to add a section linking to dependencies b) Update dependencies to add a snippet like:

    To deploy to a Terracotta server you also need to add the following:


    <dependency>
        <groupId>org.terracotta</groupId>
        <artifactId>terracotta-toolkit-1.2-runtime</artifactId>
        <version>3.1.0</version>
    </dependency>


    <repositories>
        <repository>
            <id>terracotta-repository</id>
            <url>http://www.terracotta.org/download/reflector/releases</url>
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
    </repositories>

Although we need to pair up the right versions of the toolkit with the server.

3) Add documentation on how to use exclude with ehcache to override the toolkit version. This will come up in maintenance situations.

Hung Huynh 2011-08-02

Toolkit version for Ulloa:

org.terracotta terracotta-toolkit-1.4-runtime 4.0.0

gluck 2011-08-02

Also resolved to:

1) push ehcache-terracotta and terracotta-toolkit to sonatype and maven central 2) move Terracotta repo to a public nexus instance.

Steve Harris 2011-08-04

I don’t remember discussing number 2 on here. What does that mean?

Hung Huynh 2011-08-09

starting from ehcache 2.4.4, ehcache-terracotta pom depends terracotta-toolkit-runtime

Hung Huynh 2011-08-09

the pom dependency change is done. There’s still documentation involved per Greg’s comment.

Fiona OShea 2011-08-09

I don’t think we can make changes to the site during this time as the websites are being updated. I’m not sure that Igal has bandwidth to update this week. Greg can you take care of this, as you have immediate knowledge of what needs to be done? thanks

Gautam Jayaprakash 2011-08-11

Adding 2.4.4 since the POM changes are in that release.

Fiona OShea 2011-10-27

Can you follow up on the doc part of this.

ilevy 2011-10-27

looks like the only issue with http://www.terracotta.org/documentation/toolkit-intro.html is that org.terracotta.toolkit needs to lose the ".toolkit" part.

next i’ll look into the getting-started doc.

ilevy 2012-02-14

updated in source: http://www.ehcache.dev/documentation/get-started/building#deploying-maven-artifacts

Note: kit readmes etc. have not been updated by me. please open a separate jira for anything in the kit that requires a fix.