Source Directory Structure

The source distribution of gridsam2 has the following directory structure

.
|-- target                          ; maven output directory of a build
|   |-- classes                     ; java classes compiled from source
|   |-- dist                        ; contain different version of the binary distribution
|   |   `-- gridsam-x.x             ;
|   |       `-- gridsam             ; the directory containing the binary distribution
|   |                               ; (see next section)
|   |-- javagen                     ; temporary directory for dynamically generated classes
|   |-- javagen-nc                  ; temporary directory for dynamically generated sources
|   `-- surefire-reports            ; containing junit test reports
|-- dist
|   |-- client                      ; client binary distribution created by "build-client"
|   |-- server                      ; server binary distribution created by "build-server"
|-- src                             ; source code
|   |-- doc                         ; root of the documentation directory
|-- modules                         ; GridSAM sub-modules
|   |-- service                     ; service sub-module
|   |-- core                        ; core sub-module
|   |-- client                      ; client sub-module
|   |-- schema                      ; XML-to-Java sub-module
|   |-- broker-plugin               ; simple, round-robin, GridSAM instances broker sub-module
|
|-- pom.xml                         ; Maven2 configuration file
|-- build.xml                       ; the main build file
`-- build.properties                ; the build configuration file

• Java Source Code: All java source code should be added to the src/java directory following the java package naming requirement
• Third Party Libraries (.jar files): should be added to the lib/third-party-name directory. A LICENCE file provided by the third-party must be added to that directory. Jar files in the lib/* directory will be added to the compilation classpath automatically.
• Generated Classes: source code that is generated dynamically and require no change from the developer's part should not be checked into SVN. The generation process should be executed in the build.xml Ant file, therefore included in the compilation. (read build.xml for example)
• Post Build: After all source-code is compiled and packaged, additional tasks can be put in the build.xml to perform post-build process (such as packaging .war file)
• All target/ directories contain the output of the build process. This directories SHOULD NEVER be checked into SVN. Some directories serve as places for staging file. The binary distributions for Service and Client can be found in dist/server and dist/client.

Binary Directory Structures

• Server Distribution (dist/server)

  |-- config                  ; configuration files
  |-- |-- ddl                 ; database SQL config scripts
  |-- docs                    ; this documentation
  |   |-- javadoc             ; the javadoc
  |   |-- ...                 ; other documentation
  |-- build.xml               ; server installation script
  `-- gridsam.war             ; deployable service archive

• Client Distribution (dist/client)

  |-- bin                     ; executable, shell scripts, etc..
  |-- conf                    ; configuration file
  |-- data
  |-- |-- examples            ; example JSDL files
  |-- docs                    ; documentation
  |   |-- javadoc             ; the javadoc
  |   |-- ...                 ; other documentation
  `-- build.xml               ; client installation script

Compile and Test

The <GRIDSAM_HOME>/build.xml is the primary 'make' file used by Ant to build the module and execute any junit tests. The build.xml file defines ant build targets. Read the build.xml file for more information. Here are some of the useful targets:

$> ant -projecthelp
Buildfile: build.xml

Main targets:

 build-all     build the server, client and documentation
 build-client  build the client
 build-doc     build the documentation
 build-server  build the server
 test          performs tests
 

• To build gridsam client

  $> cd <GRIDSAM_HOME>
  $> ant build-client

• To test gridsam server

  $> cd <GRIDSAM_HOME>
  $> ant test

• Test output can be found in the GRIDSAM_HOME/build/test/ directory

NOTE

• Build properties can be passed to the Ant system through the -D flag or in the build.propertiesfile.
• GridSAM uses Maven 2 for project's building, testing, reporting and documentation. The Ant tasks in the build.xml file rely on the functionality provided by Maven. If Maven is not found on the execution PATH its tar-ball is downloaded and Maven is installed in the GRIDSAM_HOME directory.

Logging

Developers are encouraged to use the org.apache.commons.logging API for fine-grained control of verbosity (e.g. severe, warning, debug), format (e.g. minimal, timestamped) and output (e.g. stdout, file, socket) of logging messages instead of the System.out.println() approach. It is the preferred practice to associate a org.apache.commons.logging.Log with each class you create.

package mypackage;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;


public class MyClass {

    // the class logger. The name of the logger is the same as the fully-qualified
    // class name
    private static final Log sLog = LogFactory.getLog(MyClass.class);

    public void myMethod(){
        sLog.debug("this is a debug message");
        sLog.info("this is a informational message");
        sLog.warn("this is a warning message");
        sLog.error("this is a warning message");

        try {
            // critical work here...
        } catch (SomeException e){
            sLog.error("we have encountered an error", e);
        }
    }

}
            
Unit Testing
JUnit is a regression testing framework. It is a powerful and simple tool to unit test a piece of functionality 
or a class against a set of requirement.

Developers are encouraged to write JUnit TestCase for each class they have created, or at least for any 
well-defined piece of functionality. The gridsam build system will automatically execute all junit.framework.
TestCase derived classes that has class name ending with *TestCase.java unless excluded in the build.xml file.
A sample test case class looks like the following

package mypackage;

import junit.framework.TestCase;

public class MyClassTestCase extends TestCase {

        public MyClassTestCase(String args){
                super(args);
        }

        public void testMethodAWithNullParameter(){
                MyClass c = new MyClass();
                assertTrue(c.methodA(null));
        }

        public void testMethodAWithStringParameter(){
                MyClass c = new MyClass();
                assertTrue(c.methodA("some string"));
        }

}

Each method in the TestCase that starts with testXYZ() defines a test case. junit.framework.TestCase provides a collection of assertXYZ() method to assert truth of expected behaviour of the class you are testing. If any of the assert statement is failed, the test will fail. Test output can be found in the build/test/TEST-name-of-test-class.

NOTE

• Coding Convention: The test method name is usually named after the functionality or method you are trying to test. It should also reflect the specific elements you are testing (e.g. handling of null parameter, etc.). The test case should also live in the test directory inside the package of the class you are trying to test.

Coding Guidelines

http://www.icenigrid.org/<year>/<month>/<context>/<sub-context>