Packages

A Java package is similar a C++ namespace. However, in Java, packages tend to be used more extensively and in a more fine-grained way than many C++ developments.

The main use of namespaces in C++ is to avoid name clashes between different libraries, eg form different vendors. For thsi reason it is common to see C++ developments which use a single namespace for the entire project, or maybe don't use namespaces at all.

Java developers use packages to avoid name clashes, but many developers also use multiple packages to indicate the logical structure of the code. It is rare to see a serious Java project which doesn't use a significant number of packages.

Syntax

Package names are usually hierarchical in nature, with the sub-packages separated by dot. For example java.util.zip is the package containing a standard Java library which implements ZIP compression. Here java is the top level package, java.util is a subpackage of java which holds various utility packages, and java.util.zip contains the ZIP classes.

The hierachical structure is useful for indicating the logical structure of a set of packages, but it is important to realise that there is no special relationship between, say java.util and java.util.zip. They are separate packages which happen to have similar names.

By convention, package names are usually all lower case.

You declare a class as being a member of a package by adding a package statement at the top of the file:

package simulator.graphics.transforms

Tells Java that the class belongs in the simulator.graphics.transforms package within your project. This also has implications on location of the Java file, see below.

If you do not include a package statement, the class will be placed in the unnamed package.

Packages and directory structure

For a project containing one or more packages, the source Java files must be stored in a folder structure which reflects the package structure. In the example above, if there is a package simulator.graphics.transforms, then there must be a folder simulator/graphics/transforms (beneath some project root folder) where the class files are stored. A class will not compile if it isn't in a folder which matches its package.

This works the other way around too. If you want to separate your Java files into different folders to make the project more organised, then you must place the classes in corresponding packages. That is one of the reasons packages are widely used in Java.

Package naming

Packages help to protect against name clashes between different libraries, but for this protection to be totally effective you want to make sure you have unique package names. An easy, effective way to do this is to base the start of your package name on a URL which you own. The recomendation is to use the TLD (ie com, org etc) followed by the domain name, followed by any subdomains in reverse order. No need to include the www part. So if our colleagues at www.cookiewiki.com ever wrote code (instead of eating pies the whole time) every package would start with com.cookiewikie, eg:

com.cookiewiki.simulator.graphics.transforms

There is an argument that some projects, maybe most projects, are very unlikely to encounter name clashes so don't need to bother with this. However, it is very easy to do, so why take the risk?

Package visibility

In most cases, visibility of class members (ie public, protected or private) works exactly the same regardless of which package a class is in.

There is a special case. If a class member is not declared as public, protected or private, it takes on default visibility (aka package visibility). Default visibility means that the member has public visibility for all classes within the same package, but private visibility for any classes in other packages.

Note that the member is only public within the same package, this does not extend to parent or child packages.

Compiling packages

As mentioned before, when a Java file is compiled it creates a .class file with the same name. When you compile a project containing a number of packages and classes, you will probably not be surprised to learn that the compiler creates a new folder tree corresponding to the package structure, and places the .class files at the correct locations in the tree.

Package members

Classes within a package are members of the package. Sub-packages are also members of the package. A package cannot contain a class and a sub-package which share the same name.

Summary

The main differences between Java packages and C++ namespaces are:

Packages are hierarchical.
There is a compiler enforced link between the file location of a Java file and the package it belongs to.
Classes within the same package have “friend” access to otherwise private members decalred with default visiility.