Revision as of 11:40, 20 July 2010

Machine Setup

You need Sun JDK 6, Apache Ant 1.7.1 or later, and git. You'll probably want an IDE such as Eclipse.

At the time of writing, some ant targets occasionally fail because they cannot load classes from jsch-0.1.42.jar. A workaround on Mac OS X is to copy this JAR from virgo-build's /lib/ivy directory to /opt/local/share/java/apache-ant/lib.

On Mac OS X, increase the default number of concurrently open files by adding this to .profile:

       ulimit -n 10000

To run certain scripts, you'll need ruby, gems, and the 'choice' gem. On Mac OS you can get these by installing the XCode tools (from the Mac OS X disk) and MacPorts, then issuing:

       sudo port -v install ruby
       sudo port -v install rb-rubygems 
       sudo gem install --remote choice

Coding

Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "Code Complete". If you are already a proficient programmer and want to write really clean code, read "Clean Code". If you are not an expert in writing Java, read "Effective Java".

Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "Java Concurrency in Practice" for a good grounding in Java concurrency.

Code Style

Eclipse code templates, formatter, and clean up profile are available in the web server git repository in the doc/code-style/eclipse directory.

Concurrent Programming Guidelines

Levels of Concurrent Support

A class can either be thread safe or not. A class is thread safe if its invariants are protected when accessed simultaneously by multiple threads.

Required Level of Concurrent Support

• All classes that form part of the public API of their bundle, or serve as an externally accessible implementation of that public API are required to be thread safe.

• Public classes that are not intended to be shared by multiple threads may be coded as non thread safe, but this in discouraged since single-threaded usage cannot easily be enforced.

• Classes that are internal to a bundle are free to be non thread safe. However, if these classes are used as part of the implementation of the bundle API then the API classes must guarantee thread safe access to their delegate classes.

Alien Calls

An alien call is any call to a component outside of the control of the caller. Holding a lock while making an alien call is deadlock-prone and forbidden. The big question is what constitutes a component. Treating each class as a component from the perspective of alien calls is safe but can be too limiting at times. A package (within a bundle) is a more useful component in practice. In some situations, it may be necessary to code alien calls across packages within a bundle, but extreme care must be taken to avoid deadlocks. Alien calls between bundles are forbidden.

Use of Client Locking Protocols

A client locking protocol is a contract between a class and its consumers. This contract outlines how the calling class can cooperate in the locking of the callee class. An example of a client locking protocol in common usage can be found in Hashtable. When performing composite operations on a Hashtable it is possible to synchronize on the Hashtable instance and participate cooperatively in the locking inside the Hashtable.

In Virgo, the use of client locking protocols is forbidden because they can very easily lead to deadlocks. If a class in Virgo needs to allow composite operations on its internal data structures, it should support these operations in its API.

Use of synchronized Methods

The use of synchronized methods in Virgo is forbidden. A class with synchronized methods implicitly exposes its monitor object (itself) to the outside world.

In a multi-threaded environment this can easily lead to deadlocks. If class Foo synchronizes on an instance of Bar, and these instances of Bar synchronize on 'this', then access of Foo and Bar across different threads can easily deadlock.

Note also that explicit 'synchronized(this)' blocks are also forbidden.

A simple alternative for classes wishing to maintain some internal synchronization is to use an internal monitor field:

public class MyClass {

	private final Object monitor = new Object();
	
	public void doSomething() {
		synchronized(this.monitor) {
			// logic here
		}
	}
}

Important: The monitor field must be declared as final otherwise synchronizing on it is non-deterministic due to Java Memory Model visibility rules.

Testing

See Test.

IP Due Diligence

Raising "works with" CQs

"works with" CQs are required for test dependencies which are not distributed with Virgo or checked in to Eclipse version control (git, svn, cvs).

The initial set of test dependencies was determined, for repositories which are built with ant, as follows:

1. In the build-xxx directory run ant report

2. Extract a raw list of the test dependency jars

find <report directory> -name "*-test.xml" -exec grep -E \/.+\.jar  {} \; >test-jars.txt

3. Edit test-jars.txt using an editor with a regular expression global change facility and do the following global changes.

3.1 Replace regex .+\/(.+)\.jar\"> with $1.jar.

3.2 Replace regex .+\/(.+)\.jar\"\/> with $1.jar.

3.3 Replace -sources with the empty string

4. Sort test-jars.txt and remove duplicate lines.

5. Look through test-jars.txt and raise "works with" for any JARs which don't have a Virgo CQ for the correct version. Also, raise corresponding Virgo bugzillas and set the iplog flag to enter the bugzillas in the automated IP log.