[jboss-user] [JBoss Cache] Document updated/added: "JBossCacheDevelopment"

Manik Surtani do-not-reply at jboss.com
Mon Feb 22 10:30:27 EST 2010 

User development,

The document "JBossCacheDevelopment", was updated Feb 22, 2010
by Manik Surtani.

To view the document, visit:
http://community.jboss.org/docs/DOC-10259#cf

Document:
--------------------------------------------------------------
h2.  Developing with JBoss Cache
 
This page is intended as a developer's guide to the JBoss Cache source tree, and in addition to information on the code repositories and tags and branches, also contains details on how to set up and use your IDE's debugger with JBoss Cache.
 
h2.  Development resources
 
h3.  Mailing lists
 
JBoss Cache developer's mailing list: https://lists.jboss.org/mailman/listinfo/jbosscache-dev
JBoss Cache Subversion commits list: https://lists.jboss.org/mailman/listinfo/jbosscache-commits
 
h3.  Discussion forums
 
JBoss Cache user forum: http://jboss.org/index.html?module=bb&op=viewforum&f=157
 
JBoss Cache design forum: http://jboss.org/index.html?module=bb&op=viewforum&f=207
 
h3.  IRC
 
jbosscache on irc.freenode.net
 
 
h2.  Version control information
 
h3.  Subversion (2.1.0 and beyond)
 
h4.  Access
 
* Committer access - https://svn.jboss.org/repos/jbosscache
 
* Anonymous access - http://anonsvn.jboss.org/repos/jbosscache
 
* FishEye access - http://fisheye.jboss.org/browse/JBossCache
 
* ViewVC access - http://viewvc.jboss.org/cgi-bin/viewvc.cgi/jbosscache
 
 
Please read http://community.jboss.org/docs/DOC-11991 for more information on connecting to the JBoss.ORG repositories.
 
Tags and branches have been migrated across from CVS, and the new directory structure is shown below.
 
h4.  Core cache
 
/jbosscache/core - +core cache+
 
/jbosscache/core/branches - +branches for core cache+
 
/jbosscache/core/support-branches - +branches for core cache, for Red Hat internal support engineers+
 
/jbosscache/core/tags - +tags for core cache+
 
/jbosscache/core/trunk - +HEAD for core cache+
 
/jbosscache/core/trunk/src/main/java
/jbosscache/core/trunk/src/test/java
/jbosscache/core/trunk/src/test-perf/java
/jbosscache/core/trunk/src/test-stress/java
/jbosscache/core/trunk/src/main/docbook
 
 
 
h4.  Pojo cache
 
/jbosscache/pojo - +pojo cache+
 
/jbosscache/pojo/branches - +branches for pojo cache+
 
/jbosscache/pojo/support-branches - +branches for pojo cache, for Red Hat internal support engineers+
 
/jbosscache/pojo/tags - +tags for pojo cache+
 
/jbosscache/pojo/trunk - +HEAD for pojo cache+
 
/jbosscache/pojo/trunk/src/main/java
/jbosscache/pojo/trunk/src/test/java
/jbosscache/pojo/trunk/src/test-perf/java
/jbosscache/pojo/trunk/src/test-stress/java
/jbosscache/pojo/trunk/src/main/docbook
 
 
 
 
h4.  Branches and tags
 
Tags are simply named after the version, using a point notation (see http://docs.jboss.org/process-guide/en/html/release-procedure.html).  E.g., *2.1.0.ALPHA1* or *2.2.0.GA*
 
Branches are named after the versions that would be tagged off the branch, using a *X* in place of the variable version.
 
E.g., a branch off which *2.0.0.GA*, *2.0.0.SP1*, *2.0.0.SP2*, etc. but +not+ *2.0.1.GA* would come off would be called *2.0.0.X*.
 
E.g., a branch off which *2.0.0.GA*, *2.0.0.SP1*, *2.0.1.GA*, etc. but +not+ *2.1.0.GA* would come off would be called *2.0.X*.
 
E.g., a branch off which *2.0.0.GA*, *2.0.0.SP1*, *2.0.1.GA*, *2.1.0.GA*, etc. but +not+ *3.0.0.GA* would come off would be called *2.X*.
 
See *1.4.X* and *1.3.X* as live examples of this.
 
h4.  Legacy tags and branches
 
Old tags and branches have been imported from CVS, and have been renamed to ensure consistency.  Note that all old tags and branches reside under the *core* module.
 
E.g., the old *Branch_JBossCache_1_4_0* is now https://svn.jboss.org/repos/jbosscache/core/branches/1.4.X
 
h4.  Branches for Red Hat support engineers
 
Occasionally Red Hat support engineers may create branches on released versions.  These will live separate from project branches, but follow a similar naming pattern.  E.g.,
 
https://svn.jboss.org/repos/jbosscache/core/support-branches/1.4.1.SP3_CP01
 
h4.  Snapshots
 
Snapshots will be released to the JBoss Maven2 snapshot repository.  Note that snapshots do not have a release qualifier (*.GA*, etc.) but instead have the *-SNAPSHOT* qualifier.  E.g., *2.1.0-SNAPSHOT*
 
h4.  Maven for builds
 
We have moved to Maven2 to handle building of JBoss Cache and Pojo Cache.  pom.xml will exist in /jbosscache/core/trunk/ and /jbosscache/pojo/trunk/ to manage library dependencies and documentation.  See http://fisheye.jboss.com/browse/~raw,r=4259/JBossCache/core/trunk/README-Maven.txt in the source tree for usage information.
 
 
 
h3.  older CVS repository (up to and including 2.0.0.GA)
 
Older versions of JBoss Cache used JBoss.org's CVS repository.
 
*NOTE that this CVS repository is now FROZEN and READ-ONLY.  All active work should happen in the Subversion repository (see above)*
 
*Note* that the CVS module name is *JBossCache* (case sensitive)
 
In the examples below, XXX is the tag or branch name.  Beginning with 1.2.4 a source-only distribution is also available from the download site.  For 1.2.2 and earlier, the source for JBossCache was integrated with the JBoss AS code base, so you need to check out JBoss AS code.
 
h4.  Committer CVS Access
 
You would need to make sure your SSH keys are set up on the CVS server.  Your first step should be to http://docs.jboss.org/process-guide/en/html/cvsaccess.html.
 
     export CVS_RSH=SSH
     cvs -d:ext:USERNAME at cvs.forge.jboss.com:/cvsroot/jboss co -r XXX JBossCache
 
 
h3.  Anonymous CVS Access
 
cvs -d:pserver:mailto:anonymous at anoncvs.forge.jboss.com:/cvsroot/jboss co -r XXX JBossCache
 
h4.  Web based access
 
Web-based access to JBoss Cache CVS repository is either via:
* http://fisheye.jboss.com/browse/JBoss/JBossCache
* http://viewvc.jboss.org/cgi-bin/viewvc.cgi/jboss/JBossCache.
 
h4.  CVS tags for released versions
 
|| Version || Label or branch name in CVS || Location in SVN ||  ||
| 2.0.0.GA +"Habanero"+ | JBossCache_2_0_0_GA | http://anonsvn.jboss.org/repos/jbosscache/core/tags/2.0.0.GA |
| 1.4.1.SP4 +"Cayenne"+ | JBossCache_1_4_1_SP4 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.1.SP4 |  |
| 1.4.1.SP3 +"Cayenne"+ | JBossCache_1_4_1_SP3 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.1.SP3 |  |
| 1.4.1.SP2 +"Cayenne"+ | JBossCache_1_4_1_SP2 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.1.SP2 |  |
| 1.4.1.SP1 +"Cayenne"+ | JBossCache_1_4_1_SP1 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.1.SP1 |  |
| 1.4.1.GA +"Cayenne"+ | JBossCache_1_4_1_GA | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.1.GA |  |
| 1.4.0.SP1 +"Jalapeno"+ | JBossCache_1_4_0_SP1 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.0.SP1 |  |
| 1.4.0.GA +"Jalapeno"+ | JBossCache_1_4_0_GA | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.4.0.GA |  |
| 1.3.0.SP4 +"Wasabi"+ | JBossCache_1_3_0_SP4 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.3.0.SP4 |  |
| 1.3.0.SP3 +"Wasabi"+ | JBossCache_1_3_0_SP3 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.3.0.SP3 |  |
| 1.3.0.SP2 +"Wasabi"+ | JBossCache_1_3_0_SP2 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.3.0.SP2 |  |
| 1.3.0.SP1 +"Wasabi"+ | JBossCache_1_3_0_SP1 | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.3.0.SP1 |  |
| 1.3.0.GA +"Wasabi"+ | JBossCache_1_3_0_GA | http://anonsvn.jboss.org/repos/jbosscache/core/tags/1.3.0.GA |  |
 
 
h4.  CVS branches for development streams
 
|| Version || Branch name || Location in SVN || Description ||  ||
| 2.0.x branch | +branch not created as yet+ | Ongoing development on the 2.0.x stream |  |  |
| 1.4.x branch | Branch_JBossCache_1_4_0 | http://anonsvn.jboss.org/repos/jbosscache/core/branches/1.4.X | Ongoing development on the 1.4.x stream |  |
| 1.3.x branch | Branch_JBossCache_1_3_0 | http://anonsvn.jboss.org/repos/jbosscache/core/branches/1.3.X | Unused (except for backports and releasing service packs) on the 1.3.x stream. |  |
 
 
h3.  Using Maven
 
Maven2 is the preferred approach when developing software with JBoss Cache.  Point your project's pom.xml to http://repository.jboss.org/maven2 to get the latest JBoss Cache releases.  From 2.1.0, JBoss Cache uses the groupId org.jboss.cache and the artifactId jbosscache-core or jbosscache-pojo.
 
h4.  Snapshots
 
Point your project's pom.xml to http://shapshots.jboss.org/maven2 to be able to use snapshots of JBoss Cache.
 
h5. Parent POMs
 
Seehttp://community.jboss.org/docs/DOC-13392 for a discussion on parent POMs and how to release them.
 
h4.  Classpaths with IDEs
 
Use the mvn idea:idea or mvn eclipse:eclipse commands to build project files for IDEA or Eclipse.  This sets up your project dependencies, etc. as per the maven2 pom.
 
h2.  IDEs and debugging
 
h3.  IntelliJ IDEA
 
1.  Set up the project as you would in IntelliJ, by checking out the source tree from CVS.
2.  Make sure your source directories include src and src-50, and your test-source directories include tests/functional, tests/stress, tests/perf and tests-50/functional
 
http://community.jboss.org/servlet/JiveServlet/download/10259-50-4665/idea-srcs.png
 
3.  Make sure your library dependencies include all the jars in lib as well as the etc/ directory and the tests/functional directory (some tests have additional resources there that are looked up using a context class loader)
 
http://community.jboss.org/servlet/JiveServlet/download/10259-50-4662/idea-libs.png
 
4.  Running JUnit tests.  Certain Linux kernels default to IPv6 which screws up a few things with some JDK implementations.  Make sure you force IPv4 by passing in a few VM parameters to IntelliJ's JUnit plugin.  The parameters you'd want are -Dbind.address=127.0.0.1 -Djava.net.preferIPv4Stack=true
 
http://community.jboss.org/servlet/JiveServlet/download/10259-50-4664/idea-junit.png
 
5.  If you wish to test PojoCache tests and want load-time aspectisation of objects, add the following VM params as well. For JBoss Cache release 1.4.x (using JDK5):
 
-javaagent:$\lib-50\jboss-aop-jdk50.jar  -Djboss.aop.path=$\etc\jboss-aop.xml -Dlog4j.configuration=file:$\etc\log4j.xml
 
For release 2.x (only supported in JDK5):
 
-javaagent:$\lib\jboss-aop-jdk50.jar  -Djboss.aop.path=$\src-50\resources\pojocache-aop.xml -Dlog4j.configuration=file:$\etc\log4j.xml
 
h2.  Code style
 
h3.  IntelliJ IDEA
 
Download /settings.jar and import it into IDEA using *File | Import Settings*.  This will only reset the code formatting, and leave everything else - including inspections, JDKs, etc - untouched.  Thanks to Mircea Markus for this tip.
 
h3.  Eclipse
 
Download and unzip /eclipse-settings.xml.zip, and import into Eclipse using *Preferences | Java | Code Style | Formatter | Import*.
 
h2.  Continuous Integration
 
JBoss Cache uses Hudson for continuous integration. See
http://hudson.jboss.org/hudson/job/jboss-cache-1.4.X-jdk1.5/
 
h3.  Trunk
 
http://dev45.qa.atl.jboss.com:8585/hudson/job/jboss-cache-core-jdk1.5/
http://dev45.qa.atl.jboss.com:8585/hudson/job/jboss-cache-core-jdk1.6/
http://dev45.qa.atl.jboss.com:8585/hudson/job/jboss-cache-pojo-jdk1.5/
http://dev45.qa.atl.jboss.com:8585/hudson/job/jboss-cache-pojo-jdk1.6/
 
h3.  Branch 1.4.x
 
http://hudson.jboss.org/hudson/job/jboss-cache-1.4.X-jdk1.5
 
h2.  Docs
 
h3.  Prerequesites
 
You need the docbook-support module from the JBoss AS subversion repository (NOT the old, outdated, frozen CVS repo)
 

  svn co https://svn.jboss.org/repos/jbossas/trunk/docbook-support

 
This should be checked out in the same directory you checked out the JBossCache CVS module.  E.g.:,
 

FatBastard:~/Code manik$ pwd
/Users/manik/Code
FatBastard:~/Code manik$ ls -l
total 0
drwxr-xr-x   29 manik  manik  986 Mar  2 17:10 JBossCache
drwxr-xr-x    9 manik  manik  306 Feb 28 12:09 docbook-support
 
h3.  Building docs
 
JBoss Cache docs can be built from their docbook sources using:
 

FatBastard:~/Code/JBossCache manik$ ./build.sh docs

 
from the JBoss Cache root directory.
 
h3.  Output
 
HTML and PDF output will be in the docs/BOOK_TITLE/build directory.
 
h2. Unit tests
 
In order be able to execute the test suite before committing a modification, JBoss Cache runs its test suite in parallel. This requires following some rules and best practices for writing test as well. Please read this for a detailed description: https://www.jboss.org/community/docs/DOC-13315

--------------------------------------------------------------

More information about the jboss-user mailing list