Object-Oriented Programming with Java Lecture Notes

5 February 2008 • Classes, Part 2

Outline

• Scope.

• Packages

• Comments and Javadoc.

Source Program Structure

• Java source comprises one or more source files.

  • A source file is your basic text file.

  • The filename should have a .java extension.

• Each source file contains one or more class defintions (among other things).

• Each class in a source file compiles in to a separate .class file.

Executable Structure

• The JVM builds an executible from .class files.

  • .class files are loaded at runtime as needed.

  • This is known as lazy link and load.

• This is an amazingly powerful and dangerous feature.

  • Unfortunately, we won't be persuing it in this class.

Compilation

• The javac compiler also deals with .class files.

  • It needs them for type checking, for example.

• The compiler manages source-.class file consistency automatically.

  • Newer source files are compiled to update older (or nonexistent) .class files.

Development Structure

• What kind of development structure works well with Java?

  • The trick here is there are two set of files: the source and the .class files.

• One possibility is a monolithic structure: all files in one place.

Monolithic Problems

• Monoliths are not well structured, and so don't scale well and are difficult to deal with.

• Break monoliths up into interacting pieces.

  • Functional division is usually the best, but there are other ways.

• The result is a set of mini-monoliths.

  • But each new monolith is smaller and functionally consistent.

Packages

• A package is a named group of .class files.

  • Every .class file is a member of exactly one package.

• A source file declares package membership with a package statement:

  package package-name;
  

  • Every .class file created from the source file belongs to the declared package.

Accessing Classes

• Given a class access via its name

  TetrisBoard board;
  

  the compiler and JVM need access to the associated .class file.

  • Searching all packages could be expensive.

  • There could be several classes with the same name in different classes.

Class Access

• Package qualification indicates class package membership.

  board.TetrisBoard board;
  

  • The TetrisBoard .class file in the board package.

  • You tell the compiler (and the JVM) the package holding the class.

• Every access to a class in a different package has to be qualified.

Scope

• Can a class access any other class in any other package?

• Scope refers to the extent over which a feature exists and can be accessed.

  • An existant and accessable feature is called in-scope.

  • A non-existant or inaccessable feature is called out-of-scope.

Scopes So Far

• Pacakges, classes, and methods are the scopes seen so far.

  • There are others to come.

• The features introduced so far are packages, classes, methods, and instance variables.

  • There are others to come.

The General Questions

• Can feature X in scope Y be accessed from scope Z?

  • If so, how?

• How can scope Z be prohibited from accessing feature X in scope Y?

  • This is an important question.

• The combinatorics of these questions are complex.

Package Scope and Classes

• By default, each class in package X can access any class in package X.

  • Accessed by using just the class name.

  • The compiler defaults to searching the containing package for other classes.

• By default, classes not in package X cannot access any class in package X.

• This is the default package scope for classes.

Package Scope Example.

Package Scope Example..

Package Scope Example...

$ javac B/C2.java
B/C2.java:8: A.C1 is not public in A; 
cannot be accessed from outside package
  A.C1 c1;
   ^
1 error

$ 

Package Scope Example....

Widening Package Scope

• Default package scope is too restrictive.

  • Cross-package accesses are essential.

• The public scope for a class (or just public class) allows access to the class from any package.

• A public class starts with the public keyword.

  • Public scope is a per-class scope, not per-package.

Public Class Naming

• The name of the source file containing a public class must be the same as the public-class name.

  $ cat t.java
  public class T { }
  
  $ javac t.java
  t.java:1: class T is public, 
  should be declared in a file named T.java
  public class T { }
         ^
  1 error
  
  $ 

• Only one public class per source file.

Public Scope Example.

Public Scope Example..

Public Scope Example...

$ javac B/C2.java

$ 

Observations

• A class has either public or package scope.

  • All or nothing access is clumsy.

• Package scope is global within the package.

  • Every class in the package can access every other class in the package.

  • Problems with this suggest design errors.

    • In particular, the package's too big.

The Default Package

• Every .class file is a member of some package.

  $ cat A/C1.java
  class C1 { }
  
  $ 

• package statements are optional. What package is C1 in?

• Classes not explicitly placed in a package fall into the nameless default package.

Abbreviating Package Qualification

• Every non-local class access has to be package qualified, which is a pain.

• The import statement explicitly locates a class.

  import package-qualified-class;

• Imported classes don't need package qualification.

  • Identically named classes from different packages still need package qualification.

Import Example

Global Imports

• Import statements of the form

  import package.*;

  import every public class from the given package.

• There's some documentation value to importing individual classes.

  • With a good IDE it doesn't much matter.

• * imports could lead to unnecessary name clashes.

Mapping Packages

• What is a package in the real world?

• A package maps naturally to directory in a file system.

  • Mapping to directories is not required, but is the most conventional and convenient.

• Package tetris maps to the directory tetris.

  • This mapping is most natural, but not required.

!! Warning !! Warning !!

• As the general semanticists remind: the map is not the territory.

• Do not confuse directories and packages.

  • They are different but related things.

• In particular, not every class in a directory is part of the same package.

• javac does not check to see that a source file in a package is being compiled in the proper directory for the package.

Package Mapping Example.

Package Mapping Example..

Package Mapping Example...

$ javac A/C2.java
A/C2.java:1: cannot find symbol
symbol  : class C1
location: class C2
class C2 { C1 c1; }
           ^
1 error

$ 

• Even though they share the A directory, both packages are separate.

Hierarchical Packages

• Packages nest to form a tree structure.

  • Package levels are separated by a dot.

    package tetris;
    package tetris.player.computer;
    

• Package hierarchies map naturally to file-system hierarchies.

  • The package tetris.player.computer corresponds tetris/player/computer (on Unixoid systems).

Imports and Nesting

• Import statements deal with .class files, not nested packages.

  

No Really, Where are the Packages?

• Knowing that package X is in directory X isn't too helpful.

  • Because where's directory X?

• The classpath describes locations where package directories may be found.

  • It lists parent directories that may contain package directories.

The -classpath Option

• javac and java have the -classpath command-line option (also -cp for java) to set the classpath.

  • The default classpath is the current directory (.).

  • javac always searches .; java only by default.

• The classpath is a colon separated list of directories.

  • On Unix; check for other systems.

Classpath Example.

Classpath Example..

$ javac Cb.java
Cb.java:1: package A does not exist
class Cb { A.Ca ca; }
            ^
1 error

$ 

• Huh? Why doesn't package A exist?

Classpath Example...

• Classpath defaults to .

• The search for packages starts in directory B.

• Classpath needs to point to B's parent to find A.

  

Classpath Example....

$ javac -classpath .. Cb.java

$ 

• Whew.

The CLASSPATH Environment

• Typing “-classpath blah” all the time is a pain.

  • Unless maybe if you use make or ant.

• You can set the CLASSPATH environment variable instead.

  • javac and java use the contents of CLASSPATH if -classpath isn't given.

  • Don't forget . for java if you need it.

Method Scope

• Method scope is independent of class scope.

• By default, methods have package scope.

  • Any class in the same package can access the method.

• Methods with public scope can be accessed from any class in any package.

  • Public-scope methods have the public modifier.

Method Scope Example..

$ cat A/Ca.java
package A;
public class Ca { 
  public void yes() { }
  void no() { }
  }

$ cat B/Cb.java
import A.Ca;
class Cb { 
  void blue() {
    Ca ca = new Ca();
    ca.yes();
    ca.no();
    }
  }

$ 

Method Scope Example.

$ javac B/Cb.java
B/Cb.java:7: no() is not public in A.Ca; 
cannot be accessed from outside package
    ca.no();
      ^
1 error

$ 

Private Method Scope

• A method m with private scope can only be accessed by features in the same class as m.

  • Right now, the only sensible features are other methods.

  • No access from other classes in the same package.

• Private-scope methods have the private modifier.

Instance-Variable Scope

• An instance variable can have public, package, or private scope.

  • By default, instance variables have package scope.

    • This is a bad default; instance variables should almost always be private.

  • Public or private scope is indicated by the public or private modifier.

• Access rules are the same as for methods.

Class and Instance Methods

• By default, methods are called on class instances.

  classInstance.method(args...)

  • A method manipulates the instance's state, among other things.

• If there's no class instance, there's no method.

• But what about constructors? Where's the instance there?

Class Methods

• A constructor is an example of a class method, a method called without reference to an instance.

  • There's no this inside a class method.

• A method becomes a class method by using the static modifier.

  static double sin(double x) { ... }
  

• Static and scope are independent.

Class Method Access

• Class methods are accessed using the name of the containing class:

  ClassName.staticMethod(args...)

• Static imports let you drop the class-name prefix.

  import static class.staticMethod;

  import static class.*;

Class vs. Instance Methods

• Class methods can directly access only other class methods.

  • A class method can access instance methods via a class instance.

• Instance methods can directly access class methods.

  • Going through the class name is fine too.

Method-Access Example

class blob {

  static void m1() { }

  void m2() { }

  static void m3() {
    m1();
    blob.m1();

    m2();

    blob b = new blob();
    b.m2();
    }
  }

Java Programs

• Java programs (as opposed to applets) start executing in the main method of the form

  public static void main(String args[]) { ... }
  

Class and Instance Variables

• As with methods, so with variables.

• A variable becomes a class method by using the static modifier.

  static double pi = 3.1415;
  

• Static and scope are independent.

• Class and instance methods can access class variables.

Comments

• Comments can either be single line or multi-line.

  // Ignore to end of line.
  /* 
    Ignore until next star-slash.
  */

  • Multi-line comments do not nest.

• Javadoc comments are multi-line comments of the form

  /**
    blah blah blah
  */

Javadoc

javadoc is a JDK documentation tool. It extracts javadoc comments from Java source and formats them as HTML pages.

Javadoc Comments

• Javadoc comments is text with HTML tags and @-keywords.

  • javadoc parses @-keywords, passes along HTML.

  • Be careful mixing HTML and @-keywords.

• A feature's javadoc comment immediately precedes the feature.

• Javadoc can document packages, classes, methods, and variables.

Class Comments

• A class comment should immediately precede the related class.

• Useful @-keywords for classes include @author, @version, and @deprecated.

  • Always document a deprecated feature's replacement.

• By default, only public classes are documented.

Method Comments

• A method comment immediately precede the related method.

• Useful @-keywords for methods include @param, @returns, and @throws.

  • javadoc performs sanity checks on these keywords.

• By default, only public and protected methods are documented.

Instance-Variable Comments

• An instance-variable comment immediately precedes the related variable.

• By default, only public and protected instance variables are documented.

Other Comment Types

• Javadoc also provides package and overview (framework, subsystem) documentation.

• These comments require separate HTML files.

  • package.html and overview.html

• File placement depends on directory structure.

  • package.html goes in the package directory.

  • overview.html goes in some ancestor directory.

Running Javadoc

• javadoc's a complicated program, but simple invocations usually do.

• Make sure you have a separate documentation directory.

  • javadoc generates a lot of files.

  • Use the -d command-line option, or run javadoc in the documentation directory.

Javadoc Quirks

• javadoc is a chatty program.

  • javadoc warnings are useful but hard to see.

  • Use the -quiet command-line option to cut the chatter.

• By default, javadoc documents only public or protected features.

  • Use the -private or -package command-line options to document more features.

Generalizing Javadoc

• Doclet generalizes javadoc.

  • Create new document components and document formats.

• The trick: generate documentation that's Java code.

  • Boilerplate-code generation.

  • Used a lot in J2EE systems.