Java Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

If you have a few years of experience in the Java ecosystem, and you're interested in sharing that experience with the community (and getting paid for your work of course), have a look at the "Write for Us" page. Cheers. Eugen

1. Introduction

In this quick tutorial, we’ll cover the basics of packages in Java. We’ll see how to create packages and access the types we place inside them.

We’ll also discuss naming conventions and how that relates to the underlying directory structure.

Finally, we’ll compile and run our packaged Java classes.

2. Overview of Java Packages

In Java, we use packages to group related classes, interfaces and sub-packages.

The main benefits of doing this are:

  • Making related types easier to find – packages usually contain types that are logically related
  • Avoiding naming conflicts – a package will help us to uniquely identify a class; for example, we could have a com.baeldung.Application, as well as com.example.Application classes
  • Controlling access – we can control visibility and access to types by combining packages and access modifiers

Next, let’s see how we can create and use Java packages.

3. Creating a Package

To create a package, we have to use the package statement by adding it as the very first line of code in a file.

Let’s place a type in a package named com.baeldung.packages:

package com.baeldung.packages;

It’s highly recommended to add each new type in a package. If we define types and don’t place them in a package, they will go in the default or unnamed package. In this, we lose the benefits of using the package structure, and will not be to access these types from other packages.

3.1. Naming Conventions

In order to avoid packages with the same name, we follow some naming conventions:

  • we define our package names in all lower case
  • package names are period-delimited
  • names are also determined by the company or organization that creates them

To determine the package name based on an organization, we’ll typically start by reversing the company URL. After that, the naming convention is defined by the company and may include division names and project names.

For example, to make a package out of www.baeldung.com, let’s reverse it:

com.baeldung

We can then further define sub-packages of this, like com.baeldung.packages or com.baeldung.packages.domain.

3.2. Directory Structure

Packages in Java correspond with a directory structure.

Each package and subpackage has its own directory. So, for the package com.baeldung.packages, we should have a directory structure of com -> baeldung -> packages.

Most IDE’s will help with creating this directory structure based on our package names, so we don’t have to create these by hand.

4. Using Package Members

Let’s start by defining a class TodoItem in a subpackage named domain:

package com.baeldung.packages.domain;

public class TodoItem {
    private Long id;
    private String description;
    
    // standard getters and setters
}

4.1. Imports

In order to use our TodoItem class from a class in another package, we need to import it. Once it’s imported, we can access it by name.

We can import a single type from a package or use an asterisk to import all of the types in a package.

Let’s import the entire domain subpackage:

import com.baeldung.packages.domain.*;

Now, let’s import only the TodoItem class:

import com.baeldung.packages.domain.TodoItem;

The JDK and other Java libraries also come with their own packages. We can import pre-existing classes that we want to use in our project in the same manner.

For example, let’s import the Java core List interface and ArrayList class:

import java.util.ArrayList;import java.util.List;

We can then use these types in our application by simply using their name:

public class TodoList {
    private List<TodoItem> todoItems;

    public void addTodoItem(TodoItem todoItem) {
        if (todoItems == null) {
            todoItems = new ArrayList<TodoItem>();
        }
        todoItems.add(todoItem);
    }
}

Here, we’ve used our new classes along with Java core classes, to create a List of ToDoItems.

4.2. Fully Qualified Name

Sometimes, we may be using two classes with the same name from different packages. For example, we might be using both java.sql.Date and java.util.Date. When we run into naming conflicts, we need to use a fully qualified class name for at least one of the classes.

Let’s use TodoItem with a fully qualified name:

public class TodoList {
    private List<com.baeldung.packages.domain.TodoItem> todoItems;

    public void addTodoItem(com.baeldung.packages.domain.TodoItem todoItem) {
        if (todoItems == null) {
            todoItems = new ArrayList<com.baeldung.packages.domain.TodoItem>();
        }todoItems.add(todoItem);
    }

    // standard getters and setters
}

5. Compiling with javac

When it’s time to compile our packaged classes, we need to remember our directory structure. Starting in the source folder, we need to tell javac where to find our files.

We need to compile our TodoItem class first because our TodoList class depends on it.

Let’s start by opening a command line or terminal and navigating to our source directory.

Now, let’s compile our com.baeldung.packages.domain.TodoItem class:

> javac com/baeldung/packages/domain/TodoItem.java

If our class compiles cleanly, we’ll see no error messages and a file TodoItem.class should appear in our com/baeldung/packages/domain directory.

For types that reference types in other packages, we should use the -classpath flag to tell the javac command where to find the other compiled classes.

Now that our TodoItem class is compiled, we can compile our TodoList and TodoApp classes:

>javac -classpath . com/baeldung/packages/*.java

Again, we should see no error messages and we should find two class files in our com/baeldung/packages directory.

Let’s run our application using the fully qualified name of our TodoApp class:

>java com.baeldung.packages.TodoApp

Our output should look like this:

6. Conclusion

In this short article, we learned what a package is and why we should use them.

We discussed naming conventions and how packages relate to the directory structure. We also saw how to create and use packages.

Finally, we went over how to compile and run an application with packages using the javac and java commands.

The full example code is available over on GitHub.

Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE