JPPF, java, parallel computing, distributed computing, grid computing, parallel, distributed, cluster, grid, cloud, open source, android, .net
JPPF, java, parallel computing, distributed computing, grid computing, parallel, distributed, cluster, grid, cloud, open source, android, .net
JPPF

The open source
grid computing
solution

 Home   About   Features   Download   Documentation   Forums 

Working from the source code

From JPPF 5.2 Documentation

Jump to: navigation, search

Contents

Main Page > Working from the source code

1 Source code repository

We use the SourceForge.net infrastructure for our SVN repository. The repository follows a very common layout with /trunk, /branches and /tags (i.e. versions) under the repository root.

The SVN repository root is: http://svn.code.sf.net/p/jppf-project/code/

2 Versioning policy

  • there is normally a version tag for each released version (like v_2_1 for version 2.1, etc.)
  • any version that includes new features will be numbered in x.y form for minor versions, and x.0 for major versions. We're not exactly clear on the distinction between minor vs. major, however the rule of thumb is that if a major refactoring was involved, especially to enable new major features, then it is a major version
  • a version that only includes bug fixes is numbered in the form x.y.z. We call these technical releases, as they contain no new feature
  • if we can provide a patch to our users and they are satisfied with it then that's what we do. It's much simpler and faster than releasing a new version

3 Branching policy

  • the fewer branches, the better!
  • branches are created when working on major new features in the trunk, and new minor features have been requested by the users. We keep working on the major stuff on the trunk, and create a new branch for the minor modifications and enhancements
  • branches are created from tagged versions, based on the latest release. For instance, the latest version was v2.4 (tag v_2_4), if we were to create a new branch now, we would create b_2_4. Then depending on major vs. minor work on the trunk, the next version based on this branch would be v_2_5 (new features that cannot wait the next major version) or v_2_4_1 (bug fixes only).
  • we only work on the trunk and the latest branch. Bug fixes are committed to both branches, as are minor new features. Major new features are committed to the trunk only.

4 Patches

We have a section of the web site dedicated to patches. These allow us to release bug fixes quickly in a formal way, and avoid a full release cycle once a bug has been fixed. It's proved quite effective so far.

5 Setting up a development and build environment

Development is done with the Eclipse IDE. Here we are not discussing the merits of Eclipse versus other IDEs. This is just what we use. Two additional plugins are required: Subclipse to integrate with SVN, and Checkstyle, to enforce the consistency of the code metrics and documentation.

5.1 Prerequisites

  • to be able to build the Android node project properly, you need to define the ANDROID_HOME environment variable and make it point to the Android SDK installation root. For instance: export ANDROID_HOME=/home/me/android-sdk
  • you must also make sure that you have installed (with the Android sdk manager) the "Android 4.4.2 (API 19) SDK Platform" and the "Android SDK Build-tools" version 23.0.1
  • make sure that you have the Subclipse and Checkstyle plugins installed in Eclipse. You can get them from the Eclipse market place

5.2 Importing the code from SVN

  • create a new Eclipse workspace and open it
  • define a classpath variable "JDK_HOME" that points to the root installation folder of your JDK (make sure it's a JDK and not a JRE): "Window > Preferences > Java > Build Path > Classpath Variables" then click on "New ...". This is needed because JPPF uses a custom doclet for the javadoc, whose source is in JPPF/src, and the JDK's tools.jar is needed as a dependency
  • open the "SVN Repository Exploring" perspective and create a new SVN repository location: right-click in the "SVN Repositories" view and select "New > Repository Location"
  • enter "http://svn.code.sf.net/p/jppf-project/code/" as the url: this is the root of the JPPF SVN repository
  • depending on which version you want to build:
    • if you want the latest and greatest, expand the "trunk" subfolder
    • if you want the code from another branch, expand "branches" and select the one you want. For example branches/b_5_1 contains the latest code for the 5.1.x branch
    • if you want the code from a specific version, expand "tags" and select the one you want. For example tags/v_5_1_4 contains the code for JPPF 5.1.4
  • select all the modules under the branch or version you chose, then right-click and select "Checkout"
  • in the next dialog, just click "finish" and the projects are checked out into your workspace
  • everything should be imported and there should be no build error when you get back to the Java perspective

5.3 Importing the code from the source distribution

  • download the source distribution JPPF-x.y.z-full-src.zip and unzip it
  • open the resulting JPPF-x.y.z-full-src folder as a workspace with Eclipse
  • define a classpath variable "JDK_HOME" that points to the root installation folder of your JDK (make sure it's a JDK and not a JRE): "Window > Preferences > Java > Build Path > Classpath Variables" then click on "New ..."
  • import the projects: "File > Import > General > Existing projects into Workspace"
  • browse to the "JPPF-x.y.z-full-src" workspace folder and click "OK"
  • make sure all the projects in the list are checked and click "Finish"
  • everything should be imported and there should be no build error when you get back to the Java perspective

5.4 Building the Android node

  • the Android node is not an Eclipse project, rather it is an Android Studio project. To edit/modify the code, the best is to open it with Android Studio, however it is not necessary if you just want to build it
  • JPPF uses Ant as its build system, and it uses a specific Ant target to invoke the build of the Android node
  • in Eclipse, open the Ant view: "Window > Show View > Ant"
  • add this build file: JPPF/bin/build.xml
  • in this build file, run the target "build.android" by double-clicking it (you can also do it in the command line by running "ant build.android" in JPPF/bin)

5.5 Building everything

Simply run one of the "deploy[.xxx]" targets All the build artifacts (zip, jar apk) are created under JPPF/build.

5.6 tests

Provides a framework and a set of automated tests based on JUnit to ensure that JPPF features are working as expected and that no regression were introduced in the latest code. These tests start actual drivers and nodes, and manage the corresponding processes. So they're more than unit tests. They do, however, ensure that a large set of the features are convered.

To run the tests, open a command prompt in JPPF_WORKSPACE/JPPF/bin and type: "ant tests.run". This will generate a number of related artifacts:

  • an HTML JUnit tests report in JPPF_WORKSPACE/tests/report
  • a zip of the client, driver(s) and node(s) logs for each test class in JPPF_WORKSPACE/tests/logs.
    For example, for the test class test.org.jppf.client.TestJPPFClient you will have the logs in JPPF_WORKSPACE/tests/logs/test.org.jppf.client.TestJPPFClient.zip
  • the tests all log to the same client log file JPPF_WORKSPACE/tests/jppf-client.log


A number of JUnit launch configuration are also provided in test/launches, so the tests can be run from within the IDE, as any other JUnit test.

5.7 stress-tests

Provides a sophisticated framework for testing the resilience and stability of a JPPF grid under load and stress conditions. It makes it really easy to define sophisticated topologies via a very few configuration properties. See its Readme.txt for an overview of what it can do.

6 Code metrics and documentation constraints

Via Checkstyle, we attempt to enforce the following:

  • A header, with the copyright disclaimer and license terms, must be present at the start of each file (Java, configuration, XML files, etc.). Using Eclipse code and documentation templates for this is quite handy and painless.
  • there must be a Javadoc for each and all Java artifacts, no matter their visibility level: classes, instance and static variables, methods. {@inheritDoc} tags are accepted for overridden methods, when there is no significant implementation details to document.
  • Java files can be 600 hundred lines long at most. If it gets longer, split it. It may seem unduly constraining, however it forces the developers to really think about how they write their code, and as far as we know, results in a clearer code and class design. It also leads to more frequent refactorings and provides a better survivability of the design. This has worked great during all the years of JPPF development.
  • Methods can be no more than 80 lines long. If a method goes over this limit, split it.

There are few exceptions to these rules, essentially in Java files that we imported directly from other sources with a compatible license or from the public domain. We are still working on that.

You can find actual code metrics on the Open HUB page for JPPF.

7 API deprecation and removal policy

In principle, any deprecated API is removed from the next major version. For example if method a() of class A is deprecated in version 4.1, then it will be removed in version 5.0.

When the deprecation occurs, it must be clearly documented, and the deprecated API must still work as it used to. This ensures that no existing code using this API is broken and that users have time to prepare and adjust for when it will be removed.

Here is an example of how this can be documented:

/**
 * Get the listener that receives notifications of completed tasks.
 * @return a {@code TaskCompletionListener} instance.</span>
 * @deprecated {@code TaskResultListener} and its implementations are no longer exposed
 * as public APIs. {@link JobListener} should be used instead, with the
 * {@link #addJobListener(JobListener)} and {@link #removeJobListener(JobListener)}
 * methods.
 */
@Deprecated
public TaskResultListener getResultListener() {
  ...
}

8 JPPF Maven artifacts

Starting from JPPF 3.3, we are now publishing the main JPPF artifacts to Maven Central:
http://search.maven.org/#search|ga|1|jppf

You can also find the public snapshots and releases on Sonatype's public repository:
https://oss.sonatype.org/content/groups/public/org/jppf/

Main Page > Working from the source code

JPPF Copyright © 2005-2017 JPPF.org Powered by MediaWiki