Best Practices¶

This page summarises the best practices for UML modelling and other (Java) coding guidelines

---

• Table of contents
• Best Practices
  • Documentation
    • Subversion
    • Bug Tracking, Feature Requests
  • UML
    • Namespaces
    • Documentation
    • Constraints
    • Naming Conventions
    • Associations
    • Attributes
    • Enterprise Architect
  • Java
    • Package Namespace
    • jar's, plugins etc
    • Coding Conventions
    • JUnit
    • Application Frameworks
    • Bidirectional Associations in Java
    • Generics
    • Eclipse
  • Webservices
    • REST
  • Ontologies
  • Licence scheme statement MPL1.1

• JavaCodingConventions

Documentation¶

Please use the RedmineWiki as the primary documentation outside your source code (which should have inline documentation of course). See DeveloperTools for more.

Subversion¶

You should always keep your code and plain text documents in EDIT'S subversion repository

Bug Tracking, Feature Requests¶

Please use the Redmine system for bug tracking and feature requests. See Redmine for more.

UML¶

A good introduction to agile UML2 class modelling:

http://www.agilemodeling.com/artifacts/classDiagram.htm

Namespaces¶

Please use the EDIT domain as much as possible for namespaces regardless whether this is for Java or UML packages, schema namespaces or anything else.
The proper EDIT domain is e-taxonomy.eu, but some languages including Java do not allow the hyphen inside package names. So please always use etaxonomy.eu instead!

Documentation¶

Structured documentation like constraints will not enter the final annotation in source code, xml schemas, sql scripts or anything else. So we strongly recommend to enter all documentation incl constraints into notes fields for classes or attributes. Constraints should still be entered using the {} notation, see below for common examples

Constraints¶

Constraints will not propagate from the PIM into the Java model, see UML Documentation for best documentation practice.

• http://www.sparxsystems.com.au/cgi-bin/yabb/YaBB.pl?board=Latest;action=display;num=1187704222

Common constraints that can be indicated are:

• {readOnly} - only get methods are created, no setters
• {frozen} - immutable attribute after it has been set once
• {unique} - unique constraint

Otherwise short natural language should be used.

Naming Conventions¶

In general, be expressive and do not abbreviate.

• Class names
  • UpperCamelCase. Use nouns
  • abstract class names end with "Base", e.g. TaxonBase
• Interface names
  • interface names start with "I", e.g. IAgentService
• Attribute names
  • lowerCamelCase. Use nouns
  • multivalued attributes, i.e. with cardinality > 1, use the plural form of the name
• Associations
  • only roles (source and target) need to be named, not the association itself.
  • multivalued roles, i.e. with cardinality > 1, use the plural form of the name
• Operation names
  • lowerCamelCase. Use verbs
• Accessor methods should be getXXX, addXXX and removeXXX in this case with get returning an unchangable list (e.g. clone)
• Enumeration entries, i.e. constants, are all caps with underscores: CONSTANT_VALUE

Associations¶

• never use aggregation, use association if in doubt
• use composition only if: any instance has exactly 1 owner only!

Attributes¶

• can be multivalued 0...* If no {ordered} constraint is given they become sets by default in java.
• optional attributes should have a cardinality of 0...1
• by default all attributes have the cardinality 1, i.e. they are mandatory!

Enterprise Architect¶

see EnterpriseArchitect for details. The page has grown too large to be included here.

Java¶

Package Namespace¶

All EDIT packages should use the namespace eu.etaxonomy. See UML namespaces above for more

jar's, plugins etc¶

problem with jar's is that they do not export library classpathes.

There is a workaround by creating fatjars" using the "fatjar plugin.

With the included tool One-jar you can even create executable jar's. Ant can be used but is still in the early stage of development.

• http://www.torsten-horn.de/techdocs/java-eclipse.htm#Export-als-jar

Coding Conventions¶

see JavaCodingConventions

JUnit¶

JUnit test classes should be placed in a separate parallel directory structure with package alignment.

For example:

src.main.java
           eu.etaxonomy.cmd
                          xyz
                            SomeClass.java
src.test.java
           eu.etaxonomy.cmd
                          xyz
                            SomeClass.java 

This approach allows the tests to access to all the public and package visible methods of the classes under test.

Some introduction to JUnit can be found here:

• http://junit.sourceforge.net/doc/cookstour/cookstour.htm

See also

• IntegrationTests
• maven

Application Frameworks¶

We decided to use the Eclipse Rich Client Platform based on SWT in favor over Swing. See JavaApplicationFrameworks for a detailed comparison

Bidirectional Associations in Java¶

• in order to keep the two instances connected by a bidirectional link in sync, setter methods need to take care of this. It is highly recommended that the single sided value side becomes the master and takes care of this. For example like this with a Taxon having a single Name (therefore the Taxon setters become "masters"), but a Name keeps track of all Taxa that use this name. Note that on the one side (Taxon) we first check in the setter method if the supplied name is the same as the existing one. This is due to a Hibernate weirdness which otherwise results in a java.util.ConcurrentModificationException. See http://opensource.atlassian.com/projects/hibernate/browse/HHH-1054 for details.

public class Name {
    protected ArrayList<Taxon> taxa;

    public Name() {
        this.taxa = new ArrayList<Taxon>();
    }

    public ArrayList<Taxon> getTaxa() {
        return (ArrayList<Taxon>) taxa.clone();
    }
    public void addTaxon(Taxon taxon) {
        taxon.setName(this);
    }
    public void removeTaxon(Taxon taxon) {
        taxon.setName(null);
    }
}

public class Taxon {
    private Name name;

    public Name getName() {
        return name;
    }
    public void setName(Name aName) {
        // Hibernate bidirectional cascade hack: 
        // http://opensource.atlassian.com/projects/hibernate/browse/HHH-1054
        if (name == aName) {return};
        if (name != null) { 
            this.name.taxa.remove(this);
        }
        if (aName!= null) { 
            aName.taxa.add(this);
        }
        this.name = aName;
    }
}

Generics¶

Please use java generics as much as possible. See the generics-tutorial for how to use generics best.

The useful book Java Generics and Collections is available online (partly) and in printing.

Eclipse¶

For developing in the eclipse IDE you should use the EclipseCodeTemplate

There are useful hints also at DeveloperEnvironmentSetup

Webservices¶

REST¶

• REST Mini Guide

Ontologies¶

see OntologyModelling

Licence scheme statement MPL1.1¶

EDIT uses the Mozilla Public License 1.1

In any source file place the following header that needs to be accompanied with a LICENSE.TXT file in the same or higher directory. Alternatively use the entire license text (see below) of that file as the header directly.

Source Code Header

Copyright (C) 2007 EDIT
European Distributed Institute of Taxonomy 
http://www.e-taxonomy.eu

The contents of this file are subject to the Mozilla Public License Version 1.1
See LICENSE.TXT at the top of this package for the full license terms.

LICENSE.TXT file content

The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in
compliance with the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
License for the specific language governing rights and limitations
under the License.