1. The Basics

In this chapter we quickly walk through the basics on contributing; future chapters go into more depth.

1.1. Prequisites

Java 7

Infinispan is baselined on Java 7 (we build with Oracle JDK, OpenJDK and IBM JDK)

Maven 3

The Infinispan build uses Maven, and we recommend using Maven 3.

Git

The Infinispan source code is stored in Git.

1.2. Issue Management

Infinispan uses JIRA for issue management, hosted on issues.jboss.org. You can log in using your jboss.org username and password.

1.2.1. Reporting Issues

If you need to create a new issue then follow these steps.

  1. Choose between

    • Feature Request if you want to request an enhancement or new feature for Infinispan

    • Bug if you have discovered an issue

    • Task if you wish to request a documentation, sample or process (e.g. build system) enhancement or issue

  2. Then enter a Summary , describing briefly the problem - please try to be descriptive!

  3. You should not set Priority.

  4. Now, enter the version you are reporting an issue against in the Affects Version field, and leave the Fix Version field blank.

  5. In the Environment text area, provide as much detail as possible about your environment (e.g. Java runtime and version, operating system, any network topology which is relevant).

  6. In the Description field enter a detailed description of your problem or request.

  7. If the issue has been discussed on the forums or the mailing list, enter a reference in the Forum Reference field

  8. Finally, hit Create

1.2.2. Versioning Guidelines

Only Infinispan contributors should set the _Fix Version_ field.

When setting the Fix Version field for bugs and issues in JIRA, the following guidelines apply: Version numbers are defined as ${major}.${minor}.${micro}.${modifier}. For example, 4.1.0.Beta1 would be:

major

4

minor

1

micro

0

modifier

Beta1

If the issue relates to a Task or Feature Request, please ensure that the .Final version is included in the Fixed In field. For example, a new feature should contain 4.1.0.Beta1, 4.1.0.Final if it is new for 4.1.0 and was first made public in beta1. For example, see ISPN-299 .

If the issue relates to a bug which affected a previous Final version, then the Fixed In field should also contain the Final version which contains the fix, in addition to any Alpha, Beta or CR release. For example, see ISPN-546. If the issue pertains to a bug in the current release, then the Final version should not be in the Fixed In field. For example, a bug found in 4.1.0.Alpha2 (but not in 4.1.0.Alpha1) should be marked as fixed in 4.1.0.Alpha3, but not in 4.1.0.Final. For example, see ISPN-416.

1.3. Version control

Infinispan uses git, hosted on GitHub, for version control. You can find the upstream git repository at https://github.com/infinispan. To clone the repository:

$ git clone git@github.com:infinispan/infinispan.git

or to clone your fork:

$ git clone git@github.com:YOUR_GITHB_USERNAME/infinispan.git

1.3.1. Setting up your IDE

Maven supports generating IDE configuration files for easy setup of a project. This is tested on Eclipse, IntelliJ IDEA and Netbeans.

Eclipse

Before we import the project, we need to clone the project as described above.

  1. Install the m2eclipse plugin if you have not already installed it. This is bundled with Eclipse from version "Indigo" 3.7. For older versions follow instructions on http://eclipse.org/m2e/.

  2. Import the Infinispan maven project. Select File → Import in your eclipse workbench. Select the Existing Maven Project importer.

    import maven1
  3. Select the root directory of your Infinispan checkout.

    import maven2
  4. Select Infinispan modules that you want to import.

  5. Finally, from Infinispan 5.0 onwards, annotation processing is used to allow log messages to be internationalized. This processing can be done directly from Eclipse as part of compilation but it requires some set up:

    1. Open the properties for infinispan-core and locate Annotation Processing

    2. Tick Enable project specific settings

    3. Enter target/generated-sources/annotations as the Generated source directory

      ann proc eclipse
  6. Code Formatting. From the menu Window → Preferences → Java → Code Style → Formatter. Import formatter.xml

  7. Code templates. From the menu Window → Preferences → Java → Code Style → Code Templates. Import codetemplates.xml

Some modules use Scala, if you plan contributing to one of these modules it’s worth installing the Scala IDE. After installing it you need to add "Scala Nature" to a few project of the projects (from the project context menu Configuration → Add Scala Nature), at the moment these projects are: . infinispan-server-core . infinispan-server-hotrod . infinispan-server-memcached . infinispan-server-rest

IntelliJ IDEA
Importing

When you start IntelliJ IDEA, you will be greeted by a screen as shown below:

idea 12 import

If you have already obtained a copy of the Infinispan sources via Github (see 'Source Control'), then follow: Import Project → /directory/to/downloaded/sources . IntelliJ will automatically make use of Maven to import the project since it will detect a pom.xml file in the base directory.

If you have not obtained the sources already, you can use the Git integration in IntelliJ IDEA 12. Click on Check out from Version Control → Github. After entering your Github credentials, you will then be prompted to enter the git repository URL along with the location that you want to check out the source code to.

idea 12 git
Compiler settings

From Infinispan 5.0 onwards, annotation processing is used to allow log messages to be internationalized. This processing can be done directly from IntelliJ as part of compilation but it requires some set up:

  1. Go to Preferences → Compiler → Annotation Processor" and click on Enable annotation processing

  2. Add an annotation processor with "Processor FQN Name" as org.jboss.logging.LoggingToolsProcessor

  3. In "Processed Modules", add all modules except the root and the parent modules.

idea 12 annotations
There can sometimes be issues with the generated logging classes on rebuild (particularly when you switch Git branches). If these issues do crop up then simply run mvn clean install -DskipTests on the command line to clear them out.
If you are running a multi-core environment (e.g. quad-core or above) then you can follow the instructions on making use of parallelized compilation in IntelliJ 12. Information on how to do this can be found here .
Scala Plugin

You will need to download the Scala plugin for IntelliJ as well. This can be done in Project Settings → Plugins → Browse Repositories. Then run a search for Scala. JetBrains themselves are the vendor for this plugin and more information on it can be found here .

idea 12 scala

You will then have to configure the Scala plugin to use the Scala compiler for Scala files and the Java compiler for Java files. You can do this by going into Settings → Compiler → Scala Compiler . Be sure to add the Scala compiler bundle as shown in the screenshot below.

idea 12 scala2
Code Style

Download the code style JAR file from here and import this into IntelliJ IDEA.

1.4. Builds

Infinispan uses Maven for builds. Make sure you have Maven 3 installed, and properly configured. For more information, read the Maven chapter.

1.4.1. Continuous Integration

Infinispan uses TeamCity for continuous integration. TeamCity polls GitHub for updates and runs whenever updates are available. You can check the status of the latest builds here .

1.5. Testing

Infinispan uses TestNG for unit and functional tests, and all Infinispan tests are run in parallel. For more information see the chapter on the test suite; this chapter gives advice on writing tests which can safely execute in parallel.

1.6. Communicating with other Infinispan contributors

Infinispan contributors use a mix of technologies to communicate. Visit this page to learn more.

1.7. Style Requirements

Infinispan uses the K&R code style for all Java source files, with two exceptions:

  1. use 3 spaces instead of a tab character for indentations.

  2. braces start on the same line for class, interface and method declarations as well as code blocks.

In addition, sure all new line characters used must be LF (UNIX style line feeds). Most good IDEs allow you to set this, regardless of operating system used.

All patches or code committed must adhere to this style. Code style settings which can be imported into IntelliJ IDEA and Eclipse are committed in the project sources, in ide-settings .

1.7.1. Spelling

Ensure correct spelling in code, comments, Javadocs, etc. (use American English spelling). It is recommended that you use a spellchecker plugin for your IDE.

1.7.2. Check-in comments

Please ensure any commit comments use this format if related to a task or issue in JIRA. This helps JIRA pick out these checkins and display them on the issue, making it very useful for back/forward porting fixes. If your comment does not follow this format, your commit may not be merged into upstream.

1.8. Logging

Infinispan follows the JBoss logging standards, which can be found here .

From Infinispan 5.0 onwards, Infinispan uses JBoss Logging to abstract over the logging backend. Infinispan supports localization of log message for categories of INFO or above as explained in the JBoss Logging guidelines . As a developer, this means that for each INFO, WARN, ERROR and FATAL message your code emits, you need to modify the Log class in your module and add an explicit method for it with the right annotations.

For example:


@LogMessage(level = INFO)
@Message(value = "An informative message: %s - %s", id = 600)
void fiveTransactionsHaveCompleted(String param1, String param2);

And then, instead of calling log.info(...), you call the method, for example log.fiveTransactionsHaveCompleted(param1, param2). If what you’re trying to log is an error or similar message and you want an exception to be logged as cause, simply use @Cause annotation:


@LogMessage(level = ERROR)
@Message(value = "An error message: %s", id = 600)
void anErrorMessage(String param1, @Cause IllegalStateException e);

The last thing to figure out is which id to give to the message. Each module that logs something in production code that could be internationalized has been given an id range, and so the messages should use an available id in the range for the module where the log call resides. Here are the id range assignments per module:

Module name Id range

core

1 - 1000

tree

2001 - 3000

bdbje cache store

2001 - 3000

cassandra cache store

3001 - 4000

hotrod client

4001 - 5000

server core

5001 - 6000

server hotrod

6001 - 7000

cloud cache store

7001 - 8000

jdbc cache store

8001 - 9000

jdbm cache store

9001 - 10000

remote cache store

10001 - 11000

server memcached

11001 - 12000

server rest

12001 - 13000

server websocket

13001 - 14000

query

14001 - 15000

lucene directory

15001 - 16000

rhq plugin

16001 - 17000

cdi integration

17001 - 18000

hbase cache store

18001 - 19000

cli interpreter

19001 - 20000

cli client

20001 - 21000

mongodb cache store

21001 - 22000

jpa cache store

22001 - 23000

leveldb cache store

23001 - 24000

couchbase cache store

24001 - 25000

When editing the above table, remember to update the README-i18n.txt file in the project sources!
You will need to enable annotation processing in order to be able to compile Infinispan and have the logger implementation generated.