Sage-Code Laboratory

Java Packages

A package is group of related classes, interfaces, enumerations, and annotation types, providing access protection and name space management.

Java platform has several packages that are providing support for basic data structures, functions and algorithms that are built-in. You need to learn these packages because they are part of Java language.

You can organize a large system in small packages. A system can have one or many related applications. Packages can be distributed among multiple applications. In Java we use packages as components.

Advantages of packages

Creating packages is optional. However, is better to bundle related classes and interfaces in a packages for several reasons:

Note: If you do not use a package statement, your type ends up in an unnamed package. Generally speaking, an unnamed package is only for small or temporary applications or when you are just beginning the development process. Otherwise, classes and interfaces belong in named packages.

Package syntax

Packages are created with keyword "package" that is used at beginning of the source file. A package is identified by it's name. You must repeat the name in all files that belong to same package.

/* file description */
package package_name

/* define public members */
public interface my_interface { ... }

public class my_class { ... }

/* define private members */
private class clas1 { ... }

private class clas2 { ... }

/* footer notes or references */

Naming Conventions

To avoid overlaping identifier names from one package to another package you must be familiar with rules that can be used by every java developer arround the globe to create unique public names. This is necesary for imrpoving code reusability.

Package names must use lowercase letters and underscore. It can't contain special characters or spaces. Usually a package start with domain name inverted, then separated by dot, department or team name or project name then the feture name.

If domain mane contain hypen "-" this must be replaced with underscore "_" when you create package names. Sage-Code Laboratory has domain therefore a package created for a particlar project named "tor" would look like this:

/*  utopic package */
package net.sagecode.tor.utopic
Important: Java packages do not follow this convention. Java was invented bu Sun but it was purcessed by Oracle. So normally all Java packages should have been renamed. Sun domain no longer exist. Fortunately someone was smart and all Java system packages start with java or javax. So "java" is now a reserved package name.

Folder vs Packages

The best practice is to store source code in files organized in folders that have same structure as package name. Every package should be located in a different folder.

Source code:

// path example

// package file for class Utopic class

Symbol ~ is the home folder on Linux, but kan be any work folder. The "source" folder can be named anything for example: "github" or "mycode". Use your imagination.

Compiler output:

Compiler will create files with extension .class that should be stored outside of the source files, to improve delivery processes. So you must mirror the same structure using a different work folder for compiler target.

// class path example


// package file for class Utopic class

The "target" folder can be named anything for example: "classes" or "output" or "product" but do not name it: "java" or "javax". Use your imagination.

Finding the class

Compiler need to know the path to packages and source files in order to compile the application. Compiler can use .class files or source .java files.

Running application

Java JVM will execute your code when you call command: java with parameters. The parameters must include the main class of the application that you wish to run.


You can use a distribute architecture for your application. Some of the classes can be stored in a different folder. Java JVM can find classes using multiple parameters but also cam search in folders designated by the system variable called CLASSPATH.

CLASSPATH if set, contains a list of folders separated by semicolon. These folders can contain java classes that you use in your applications. The classpath folders can be subfolders in your project or in java lib folder $JAVA_HOME/lib or a subfolder of lib.

CLASSPATH is an environment variable that you can set differently in Windows vs Linux. You should know how to do this if you know your OS. Otherwise I advice you to follow Software Engineering class.


# In UNIX:     

Sometimes you need to clear the CLASSPATH for your session to run a test. To delete the current contents of the CLASSPATH variable, use these commands:

# On Windows:   

# On UNIX:      
% unset CLASSPATH; 
% export CLASSPATH

To set the CLASSPATH variable, you can use the user interface on Windows. There is a global CLSSPATH and a user specific CLASSPATH. On Linux you can edit environment variables in /etc/environment or .profile configuration files.


For temporary altering the CLASSPATH you can use these command line or Bash commands to set a temporary CLASSPATH that will be lost when you stop your session.

# On Windows:   
C:\> set CLASSPATH=C:\users\george\java\classes

# On UNIX:      
% CLASSPATH=/home/george/java/classes; export CLASSPATH

Importing packages

To use elements from packages you can import the package into the default package or in any other package. One package can be imported in many other packages. Java JVM is smart and will import the package only one time. There are several ways to use the "import" packages.

Methods of access

Given this package: /target/graphics/Rectancle.class" and /target in the CLASSPATH you can import this class and use it in you application.

//import one class
import graphics.Rectangle;

// import all graphic classes
import graphics.*;

//rarely used, import only members
import graphics.Rectangle.*;

// making an object
var rect = new graphics.Rectangle();

Note: If you do not import packages, you can still use a class from a package, but you need to use full qualifiers to find the class and also that class must be in the CLASSPATH.

Static import

When you use static keyword after import, you can supress the need to use a qualifier to search for public elements. All public elements are merged into local space. If the name overlap, local name is more powerful and the original will require a qualifier for access.

//import one class
import static graphics.Rectangle;

// making an object
var rect = new Rectangle();

Build-in Packages

The builtin packages are many and difficult to make a tutorial for all. You can study packages in reference documentation to learn all the features in every package that you want to use more often.

Package list: Java 18 packages

Read next: Collections