Java in Notes/Domino Explained: Creating your own packages

The purpose of a package is to create a namespace for the classes to make similarly named classes from different packages distinguishable to the compiler and the JVM. Using packages you can have a class called MyClass in two packages but have the compiler know the difference between them. This really comes in handy when starting to work with third-party libraries since all libraries tend to have a Context or Document class.

Looking at the core Java API you’ll find two classes called Document. The Notes/Domino Java API also has a class called Document. The compiler and JVM are however able to distinguish between these three classes since they are in different packages:

• javax.swing.text.Document
• org.w3c.dom.Document
• lotus.domino.Document

Creating packages

You create a package by using the package directive at the top of your class. The below class is in the mypackage package:

package mypackage;

public class Echo {
  public String echo(String s) {
    return "Echo: " + s;
  }
}

To use this class you have to import the package using the import directive (first example below) or specify the fully qualified name of the class (second example below).

import mypackage;

public class SomeClass {
  public void run() {
    Echo e = new Echo();
    System.out.println(e.echo("HelloWorld"));
  }
}

public class SomeOtherClass {
  public void run() {
    mypackage.Echo e = new mypackage.Echo();
    System.out.println(e.echo("HelloWorld"));
  }
}

Classes automatically have access to the classes in the same package so there’s no need to import the package into itself.

Package naming

Packages are normally named using a hierarchical naming scheme sort of like domain names. Domain names are in fact very often used to make sure that packages from a certain company are uniquely named. At my company we always start our package names with dk.it-inspiration for example.

When discussing package naming two points of confusion are common:

1. Package name doesn’t have to unique in the World but simply within the scope of the code you write. You are free to think up any package name you like. You can even choose to start your packages with “com.ibm” if you are so inclined.
2. Although package names are hierarchical they will not be imported in a hierarchical manner.

Point number 2 is often confusing to programmers new to Java so let me explain it in a little more detail. If you look inside the notes.jar file you’ll see that it contains a lot of packages as shown on the left. However even though you import lotus.domino.* in your code the classes from lotus.domino.cso, lotus.domino.local and lotus.domino.util will not be imported. You have to import these packages explicitly (although there is no need to do so).

If you come to Java from LotusScript I guess packages will be a welcome addition. Since LotusScript has no concept of namespaces for functions, you often run into issues with function and sub naming. For example you cannot write a function called Split since LotusScript already has a function of that name. In fact this was a major pain upon upgrading to Notes/Domino 6 where the function was introduced since I had already written a Split function in our Notes/Domino 5 applications. As part of the upgrade all our LotusScript code using this custom Split function had to be rewritten.

This wouldn’t have happened if LotusScript had had the concept of namespaces.