Establish standard project directory layout

Registered by Ralf Claussnitzer on 2011-07-08

SUMMARY
======

Discover and implement a standard Java project file structure to help developers gain understanding for the project quicker and to enable the use of common build and dependency management tools and IDEs.

Therefore:
* Adopt to standard Maven project layout as much as possible.
* Handle third party library distributions with a dependency management system. Only libraries not hosted in any of the public library repositories shall be distributed via the source code branch.

RATIONALE
======

In general, a project directory structure should not be given by any kind of IDE or build tool. Beside some exceptions, there are common patterns and well-understood best-practices for the structure of Java projects [1,2]. The placement of any artifact should be made as clear and consistent as possible.

Although, I don't think Maven is the right tool to for Goobi by the time, it's clear and concise project layout has a lot of value [3]. It has a good point in separating build results from sources and resources. Sub-projects and multiple programming language sources are also covered by this structure. Java developers quickly recognize the project structure and Tool vendors usually handle Maven project layouts very well.

Default directory layout allow for better tooling to be applied. Project structures for specific IDEs can be generated and updated automatically for project members working with Eclipse, IDEA or any IDE.

[1] Java EE 6 Tutorials, http://download.oracle.com/javaee/6/tutorial/doc/docinfo.html
[2] Guidelines, Patterns, and Code for End-to-End Java Applications, http://java.sun.com/blueprints/code/projectconventions.html
[3] http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html

DESIGN
=====

Goals:
* Separation of build artifacts, libraries and source code
* Build and test runs don't change any source code files
* Project can be cleaned to the state of initial checkout/branch
* Build results can be recognized and utilized by IDEs (e.g. in-place deployment)

The structure for build artifacts is different as might be imposed by build tool specifics and are not described by the specification.

Source code
--------------------

Principal source code structure is 1) one directory per application module and 2) maven source code layout within the module directory. Project information or specific build files might be given to enable separate module builds.

src/
├── main
│   ├── config
│   ├── java
│   │   ├── de
│   │   ├── dubious
│   │   ├── messages
│   │   └── org
│   └── webapp
│   ├── css
│   ├── js
│   ├── newpages
│   ├── pages
│   └── WEB-INF
└── test
    ├── java
    │   ├── de
    │   ├── dubious
    │   └── org
    └── resources

/src
 source code of web application module
/src/main
 main module source code (web gui)
/src/main/config
 standard application configuration files
/src/main/java
  java source files
/src/main/resources/js
    javascript source files
/src/main/resources/css
    stylesheet source files
/src/main/webapp/
    web content source files like JSP pages
/src/main/webapp/WEB-INF
 static web content
 deployment descriptor,
 faces configuration
 dynamic web page source code

/src/test
 test source code
/src/test/java
 JUnit and functional test sources
/src/test/resources
 static test data

(other modules will end up in separate directories like /src/cli or /src/server respectivly)

Auxiliary files
--------------------

/docs
    project documentation, installation instructions
/lib
    libraries needed for compilation or execution but not provided by dependency
    management (sub-folder per build task)
/lib/runtime
    special runtime libraries
/lib/deploy
    special deployment libraries
/lib/build
    special build tool libraries
/scripts
    command line scripts needed to operate the application
/setup
    install tools, database import files

Blueprint information

Status:
Started
Approver:
Henning Gerhardt
Priority:
Undefined
Drafter:
Ralf Claussnitzer
Direction:
Needs approval
Assignee:
Ralf Claussnitzer
Definition:
Review
Series goal:
Accepted for 1.8
Implementation:
Needs Code Review
Milestone target:
None
Started by
Ralf Claussnitzer on 2012-04-23

Whiteboard

- project can be loaded into Idea IntelliJ without problems. Web facets get detected. The web sub project is not shown as explicit sub project.
- Eclipse recognizes the web module but fails to configure project facets

It seems that structuring the source code the maven way already has positive impact on usability wit IDEs.

- lp:~zeutschel/goobi-production/standard-project-structure contains Eclipse configuration necessary to load the project within Eclipse JEE Edition. All project facets are detected and the application runs inside the IDE if Apache Tomcat Connector is configured.

(?)

Work Items

Work items:
restructure sources: DONE
check with IntelliJ: DONE
check with Eclipse: DONE
check with Netbeans: TODO

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.