Java Developer Guide

Contents 1 Becoming a new developer 2 Source Code Management 2.1 Accessing source code 2.2 SCM rules 3 Natural Language 4 Copyright 5 Developers mailing Lists 6 Java version 7 IDE 7.1 Eclipse configuration 7.2 Run configuration 8 Ant scripts 9 Code conventions 9.1 Eclipse formatter and templates 9.2 String externalization 9.3 Interfaces 9.4 XML 9.5 Comments / Javadoc 9.6 Dead code 9.7 Class headers 9.8 Code quality 9.9 Performances 9.10 Documentation 9.11 Code review/fixes 10 Development hits and available features 10.1 Using managers 10.2 Anonymizer 10.3 Utilities features 10.4 Files filters 10.5 Collection filters 10.6 Accessing to configuration files 10.7 Design patterns 10.7.1 Singleton [GOF] 10.7.2 Observer [GOF] 10.8 Developers Howto 11 See also

Becoming a new developer

• Please read the general member guide
• See also the Year 2008 planning as we use static release cycles
• In order to be registrated, a developer have to submit at least one significant patch and to accept the Team rules (see below). The project appreciates the code quality and makes the decision (an internal vote may be necessary). Of course, devs are available for help on the code.
• This code may be a unreserved feature implementation chosen from the task list or of him own choice.

Source Code Management

Jajuk uses the Subversion (SVN) source control system hosted by Sourceforge. We assume you know SVN. If you are not so familiar with it, please read this manual.

Accessing source code

The Connect String is :

https://jajuk.svn.sourceforge.net/svnroot/jajuk

Checkout last version from the trunk / Jajuk directory.

For details see Source Repository.

---

Note: With Eclipse 3.2 and 3.3, for unknown reason, the checkouted distribution may not compile (missing librairies errors, seen only under Windows). Refreshing or cleaning the project has no effect. To fix it : Select the project in Package Explorer view -> Properties -> Java build path -> Libraries. Remove a jar, apply, reopen this dialog and add it again. It worked for me

---

SCM rules

• Make sure the whole project yet compiles and keep it in an acceptable stability state before committing something.
• During a release process, please follow freeze periods (see release process part).
• Most of the work should be done in the trunk (main) branch.
• If you start to code a complex feature with many impacts on the project and potentially dangerous for current release, please create your own branch for this feature and merge your work into the trunk when you feel ready and when no release is planned for several weeks.
• Don't forget that issues on non-new features should be double-fixed into the maintenance branch and into the trunk. To make sure it is the case, please note explicitly in tickets which branch the fix has been applied against.

Natural Language

Jajuk team communication, code and comments have to be in English natural language only.

Copyright

• A single moral entity named "The Jajuk Team" owns the copyright on all sources, please do not set your name in the file headers (BTW, make sure to use the provided code generation template, see bellow).
• Note that your credits are still available from various members lists and from the SCM system anyway.

Developers mailing Lists

• Jajuk developer mailing list is the project main communication stream. Subscription form is here. Note that the Reply-to is directed to the original sender, not the list so please use the "Reply all" button from you e-mail client to reply to the list.
• jajuk-commits@lists.sourceforge.net is the SVN commits mailing-list that should be used in read-only (e-mails are generated by SVN at each commit). The reply-to of this list is directed towards the developer list in order to provide peer review. Please check diffs and provide review. Subscription form is here

Java version

• Jajuk has to run on every JVM >= 1.6
• Prefer using Java 5+ classes and features (like collection for instead of iterators or, autoboxing, enums). Using generics is mandatory.

IDE

We recommend the Eclipse platform. All following documentation (SVN...) deals with Eclipse only.

Eclipse configuration

• Templates: in Preferences / Java / Code Style / Code templates, please import this file. This is a template for new java sources
• Formatting (in Preferences / Java / Code Style / Formatting): We use generic Eclipse-built in formatter configuration with a column size of 100 instead of 80.
• Only use UTF-8 and Unix-flavor new file carriage return for your source. Check these setting by selecting the project in the Package explorer -> Properties.

Check your .properties file uses correct encoding (due to Eclipse known issue) by selecting file/properties/info. If the file is in ISO8859-1, set UTF-8 instead.

Run configuration

• See default configuration:

Program arguments are currently:

-ide -test

• -ide argument tells jajuk that it is executing inside an IDE (probably Eclipse) . This changes the resources path (images, doc...).
• -test argument tells jajuk to use the ~/.jajuk_debug repository and not the ~/.jajuk, reserved for stable releases (this way a jajuk developer can use a stable release of jajuk when working on a new release) .

VM arguments are currently:

-client -Xms20M -Xmx512M -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10

Ant scripts

You shouldn't have to use any provided ant script when under Eclipse environment. Two ant scripts are found in the tree:

• scripts/build.xml : this is the stored build file packaged with the distribution and used in command line to recompile Jajuk using a standard installation. It is also used by the packager to generate Jajuk distribution. Do not use it under Eclipse.

Code conventions

Eclipse formatter and templates

• Defaults templates are provided as Eclipse preference with the project. They are mainly Eclipse defaults templates with the Jajuk header for new files
• Defaults code formatter configuration is provided as well with the Eclipse project preferences. It is the Eclipse 3.3 default template except a 100 for line max length.
• Don't use one line statement without braces: use if (){..one line..}, not if (...) one line
• Note that the release packager applies source and import formatting over all the code at each release to make sure the formatting is always applied

String externalization

• All application labels have to be externalized (see Translator Guide) as <Class name>.<number from 0> .
• For common labels like OK, Cancel... we use generic externalized labels (see jajuk.properties). Please keep number of generic labels to minimum and when creating new generic labels, keep in mind that some language (French, German...) are genre-sensitive in opposition to English.
• Do not reuse existing label ids but always increment a new number for new strings because removed labels can still be present in out-of-date langpacks. For the same reason, leave a comment in the English langpack if your remove the last label of a class (to avoid another developer to use the same ID). For exemple if a class Foo contains 15 labels Foo.0, Foo.1... Foo.14 and if you have to remove Foo.14, leave a comment #Do not use Foo.14, continue to Foo.15.
• Make sure to cleanup useless labels to reduce translators work.

Interfaces

Begin interfaces with a upper ' I '. The 'i' is not taken into account for variables names:

IPerspectiveManager pm;

XML

• Avoid to use PCDATA values, use attributes instead : it's faster to parse and easier to code
• Use single quotes, not double quotes.

Comments / Javadoc

Please correctly comment attributes and methods with javadoc ( /** comments */ ).

Dead code

Please remove any dead code, SCM handles this for you anyway

Class headers

• Please use the standard Jajuk header (see Eclipse templates configuration). Please do not use your own copyright but keep "The Jajuk Team" as owner.
• Make sure to use the template provided as Eclipse project preference

Code quality

Please keep Eclipse standard level of warnings (imports, static context...) and make sure to cleanup imports (Control-Alt-o).

Performances

• Always use a thread or a SwingWorker invocation to launch long tasks in AWT-Dispatcher thread to avoid freezing UI

Documentation

• Please document your features at least in English into Java Help HTML pages (dist-files/doc/java-help/default).
• You may want to add new tips of the day in jajuk_properties file.

Code review/fixes

• Jajuk entire code can be updated by anyone if justified (in commit comments). We encourage the peer review and people to work on multiple software areas.
• An e-mail including diffs is sent automaticaly to the jajuk-commits mailing-list at each commit, please subscribe to this list.

---

Development hits and available features

Using managers

Managers are the only way to access (list or change) items (Track, File, Type, Directory, Playlist, PlaylistFile, Device, Author, album and Style). For example, listing devices is done this way:

DeviceManager.getInstance.getDevices()

Note that getXXXs() methods return copies that can be changed safely.

Anonymizer

• For any private data (track name, user info...), use {{ braces in logs. Example for Cover URL search: Log.debug("Search URL: {{"+sURL+"}}");

All strings between {{ and }} are replaced by *** in quality agent.

• Use this method to get a list of tracks for a given item like an author or an album : TrackManager.getAssociatedTracks()

Utilities features

• The org.jajuk.utils.Util class contains many useful methods. Please check it to avoid reinventing the wheel and don't hesitate to add new features by yourself.

Files filters

• Jajuk provides a powerful JajukFileFilter class to filter files. Example: to keep only audio files or directories:

new JajukFilter(false,JajukFileFilter.DirectoryFilter.getInstance(),
   JajukFileFilter.AudioFilter.getInstance());

• Jajuk provides several predefined filters: Audio, NotAudio, Playlist, Directory, KnownType, AnyFile than can be used in conjunction using a AND or an OR between them.

Collection filters

• Jajuk uses Jakarta Commons-Collections features to filter collections. Filtering is done by using decorated iterators using Predicates. Example:

Iterator it = new FilterIterator(tracks.iterator(),
  new JajukPredicates.AgePredicate(ConfigurationManager.getInt(CONF_OPTIONS_NOVELTIES_AGE)));

allows to iterate only on items of given age.

• New predicates should be centralized into the JajukPredicates class

Accessing to configuration files

• Since 1.4, the Jajuk workspace (the directory where Jajuk stores all configuration files and indexes) is variable (by default ~/.jajuk in production and ~/.jajuk_test_<version> in developement mode - ie using the -test option). This is why you have to access configuration files this way:

File fConfig = Util.getConfFileByPath(FILE_xxx);

and not trying to build the file path by your own

Design patterns

Singleton [GOF]

• Some Jajuk classes (mainly in org.jajuk.base) are singletons, most of the time for serious reasons.
• Please avoid making a class a singleton if you have no good reason for that

Observer [GOF]

• Jajuk provides a full featured observer pattern implementation (supports details, is fully asynchronous, has a cache etc..)
• To register to events, a view has to implement Observer interface and provide a list of observed events this way:

public Set<EventSubject> getRegistrationKeys() {
  HashSet<EventSubject> eventSubjectSet = new HashSet<EventSubject>();
  eventSubjectSet.add(EventSubject.EVENT_DEVICE_MOUNT);
  eventSubjectSet.add(EventSubject.EVENT_DEVICE_UNMOUNT);
  return eventSubjectSet;
}

• To handle events, look at this sample :

public void update(Event event) {
  EventSubject subject = event.getSubject();
  if (EventSubject.EVENT_DEVICE_MOUNT.equals(subject)) {
    SwingUtilities.invokeLater(new Runnable() {
      public void run() {
	Util.waiting();
	refreshDevices();
	Util.stopWaiting();
    }
  });
}

Developers Howto

• Read also the developers howto

See also

• Jajuk Members Guide