Establish standard project directory layout
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://
[2] Guidelines, Patterns, and Code for End-to-End Java Applications, http://
[3] http://
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/
javascript source files
/src/main/
stylesheet source files
/src/main/webapp/
web content source files like JSP pages
/src/main/
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:
- None
- Definition:
- Review
- Series goal:
- Accepted for 1.8
- Implementation:
- Needs Code Review
- Milestone target:
- None
- Started by
- Ralf Claussnitzer
- Completed by
Related branches
Related bugs
Sprints
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.