Java project structure explained for newbies?

Question

I come from a .NET background and am completely new to Java and am trying to get my head around the Java project structure.

My typical .NET solution structure conta

Answer 1

Here are some notes about Java packages that should get you started:

The best practice with Java package names is to use the domain name of the organisation as the start of the package, but in reverse, e.g. if your company owns the domain "bobswidgets.com", you would start your package off with "com.bobswidgets".

The next level down will often be the application or library level, so if it's your ecommerce libraries, it could be something like "com.bobswidgets.ecommerce".

Further down than that often represents the architecture of your application. Classes and interfaces that are core to the project reside in the "root" e.g. com.bobswidgets.ecommerce.InvalidRequestException.

Using packages to subdivide functionality further is common. usually the pattern is to put interfaces and exceptions into whatever the root of the subdivision is and the implementation into sub packages e.g.

com.bobswidgets.ecommerce.payment.PaymentAuthoriser (interface)
com.bobswidgets.ecommerce.payment.PaymentException
com.bobswidgets.ecommerce.payment.paypal.PaypalPaymentAuthoriser (implementation)

This makes it pretty easy to pull the "payment" classes and packages into their own project.

Some other notes:

Java packages are tightly coupled to directory structure. So, within a project, a class with a Package of com.example.MyClass will invariably be in com/example/MyClass.java. This is because when it is packaged up into a Jar, the class file will definitely be in com/example/MyClass.class.

Java packages are loosely coupled to projects. It is quite common that projects will have their own distinct package names e.g. com.bobswidgets.ecommerce for ecommerce, com.bobswidgets.intranet for the intranet project.

Jar files will container the class files that are the result of compiling your .java code into bytecodes. They are just zip files with .jar extension. The root of the Jar file is the root of the namespace hierarchy e.g. com.bobswidgets.ecommerce will be /com/bobswidgets/ecommerce/ in the Jar file. Jar files can also container resources e.g. property files etc.

Answer 2

Do .JAR files contain compiled code? Or just compressed source code files?

They might contain both, or even totally different kinds of files like pictures. It's a zip archive first of all. Most often you would see JARs that contain class files, and those which contain source files (handy for debugging in your IDE if you use third party code) or those that contain javadoc (sourcecode documentatin), also handy if your IDE supports tooltipping the documentation when you access the lib's functions.

Is there a good reason why package names are all lower case?

Yes there is a good reason for package names to be written in lowercase letters: There is a guideline which says that only classnames are written with a capital letter in front.

Can Packages have 'circular dependencies'? In other words, can Package.A use Package.B and vice versa?

Packages do not use each other. Only classes do. And yes that might be possible but bad practice.

Can anyone just show the typical syntax for declaring a class as being in a package and declaring that you wish to reference another package in a class (a using statement maybe?)

Let's assume you want to use the ArrayList class from package java.util, either use

 import java.util.ArrayList;
 ArrayList myList = new ArrayList(); 

or use without import (say you use two different classes named ArrayList from different packages)

 java.util.ArrayList myList = new java.util.ArrayList();
 your.package.ArrayList mySecondList = new your.package.ArrayList();

Answer 3

A package in Java is very similar to a namespace in .Net. The name of the package essentially creates a path to the classes that live inside it. This path can be thought of as the class's namespace (in .Net terms) because it is the unique identifier for the specific class you want to use. For example if you have a package named:

org.myapp.myProject

And inside it you had a bunch of classes:

MyClass1
MyClass2

To specifically refer to those classes you would use:

org.myapp.myProject.MyClass1
org.myapp.myProject.MyClass2

The only real difference between this and .Net (that I know of) is that Java organizes its "namespaces" structurally (each package is a distinct folder) whereas .Net allows you to scope classes using the namespace keyword and ignores where the document actually lives.

A JAR file is roughly analogous to a DLL in most cases. It is a compressed file (you can open them with 7zip) that contains source code from other projects that can be added as dependencies in your application. Libraries are generally contained in JARs.

The thing to remember about Java is that is is very structural; WHERE files live is important. Of course there is more to the story then what I posted but I think this should get you started.

Answer 4

While it is not as easy to make circular dependent classes work, it may not be impossible. I did get it to work in one case. class A and class B depended on each other and wouldn't compile from scratch. but realizing that a part of class A didn't need class B, and that part was what class B needed to compile completely, I rem'd out that part of class A, not needed by class B, and the remaining part of class A was able to compile, then I was able to compile class B. I was then able to un-rem that section of class A that needed class B, and was able to compile the full class A. Both classes then functioned properly. While it is not typical, if the classes are tied together like this, it is kosher and at times possibly necessary. Just make sure you leave yourself special compile instructions for future updates.

Answer 5

To answer the example sub-question:

package com.smotricz.goodfornaught;

import java.util.HashMap;
import javax.swing.*;

public class MyFrame extends JFrame {

   private HashMap myMap = new HashMap();

   public MyFrame() {
      setTitle("My very own frame");
   }

}

Answer 6

From Wikipedia:

A Java package is a mechanism for organizing Java classes into namespaces

and

Java packages can be stored in compressed files called JAR files

So for package a.b.c, you could have Java classes in the a, a.b, and a.b.c packages. Generally you group classes inside the same package when they represent related functionality. Functionally, the only difference between classes in the same package and classes in different package is that the default access level for members in Java is "package-protected", which means that other classes in the same package have access.

For a class a.b.c.MyClass, if you want to use MyClass in your project you would import a.b.c.MyClass or, less recommended, import a.b.c.* Also, for MyClass to reside in package a.b.c in the first place, you would declare it in the first line of MyClass.java: package a.b.c;.

To do this you could JAR up the whole package (including packages b and c and class MyClass) and put this JAR into your $CLASSPATH; this would make it accessible for your other source code to use (via the aforementioned import statement).