Friday, October 7, 2011

[ Manual | Project ] Project's directory/package structure

Project's directory/package structure.

In first time, it is very unclear for developers, why they should create such directories as 'src/main/java' or 'src/main/resources'. Also, if you are new in developing, you will be probably confused in first time when you find such package names as 'com.makeappinc.calculator.context'.

In such moments you want to cry and ask - "Is it really more useful instead of using only 'src' directory as root path of project?".
I say, "Yes, it is very useful! Do such and you will be happy!".
Now I will explain why.

First, lets take a look at this path:

Awful? Don't panic!
There are four main parts in this path:
calculator/ - project root path
src/main/java/ - directory structure according to maven directory layout
com/makeappinc/calculator/ - root package for current application (e.g. calculator application)
context/ - inner application package

Let's look at them closer.

Project root path. [ calculator/ ]
This path is a root directory of you project. Actualy it will contains by default only these elements:
  • src/
  • target/ (it will be auto-generated by Maven during building of your project, if need to)
  • pom.xml
For Maven, src directory is a directory which contains all sources of current project. So, you should place inside all of them: code sources, resources, any meta-data or descriptions.
But target directory - is a directory where all build results and releases will be placed by Maven. So, if you build jar/war/ear, you will find it in target directory.

Maven Directory Layout. [ src/main/java/ ]
This part of path corresponds to Maven's conventions. You may find them here [ ]

So, if you want to place java code sources - you should put them inside this path:

If you have any property files, images or xmls, you should store them here:

In another case, when you have java test code sources, place them here:

It is very useful to store different sorts of data in different paths. You always know, where to search for properties, where to search for sources, no matter - know you all project structure or not. Also, there is no need to define such paths for Maven, It already knows it!

Root application package. [ com/makeappinc/calculator/ ]
This is like a unique application ID or like an application's passport. It gives some garanties, that there will be no any collisions with package names, classes or files between different jars and libraries. For example, if you have two jars, and both of them contains Main.class in root package, then there will be conflicts during loading of classes in JVM, cause two jars have two different implementations for one class name. So, when package names inside of your application depends of some parameters such as application name or your own name - it makes them more unique and resoulve such collisions.

It consist of:
  • com.makeappinc - reversed domen name of your company, brand, band or any other name which points to your organization or directly to yourself. For example, if your company named as 'appla' and it has domen name like '', then this part will be 'org.appla'. In another case, if you have nickname 'gadget' and even if you have no any web-resources, you may create such package: 'org.gadget'
  • calculator - just name of current application.

Inner application package. [ context/ ]
Of course, in simple application, such as "Hello world" application - there is no need to create packages. But it is absolutely useful when you develop large applications. So it's recommended to start use packages as soon as you start develop your application. I won't explain details about philosophy of package creating in your project. I can only say that you may create your own unique package instead of 'context' and create one more packages if you need to.

No comments: