1

JAVA API & Packages

Starring: Java Documentation

Co-Starring: BlueJ IDE

2

Purpose:In this lecture series we will learn the

following: Java API in more detail Java Package Access Java Documentation

3

Resources:Java API Big Java Appendix A5 p.1086 & A10 p.1159

Packages Deitel & Deitel “Java How to Program”

Chapter 8.13-14 p.379 Lambert Comprehensive Appendix G & H Java Methods p.102 Big Java Chapter 7.9 P.310 AP Student Reference Material --- posted

online BLUEJ IDE for Creating Java Documentation

--- bluejsetup-122

4

Intro:We will get more comfortable with the

Java API by examining with the required AP Subset of Java Classes

Then we will look at Java packages and we will see how Java’s file structure affects how we import classes into our programs.

Finally, we will discuss PACKAGE level access

5

Java API:

All of Java’s classes are represented in Java’s Documentation of its API.

We will have utilized many of the classes in Java’s vast library, but we will focus on only a few, especially the classes identified in the AP Subset.

Java API (Document)

Go through some classes (java lang, util, system)

6

Java API:java.lang.Objectjava.lang.Comparablejava.lang.Integerjava.lang.Doublejava.langStringjava.lang.Mathjava.util.Randomjava.util.Listjava.util.ArrayListjava.util.LinkedList

7

Java API:java.util.Setjava.util.HashSetjava.util.TreeSetjava.util.Mapjava.util.HashMapjava.util.TreeMapjava.util.Iteratorjava.util.ListIterator

We are required to be able to understand and implement ALL of these classes for the AP exam.

8

Packages: Students are expected to have a basic understanding of packages and a reading knowledge of import statements of the form

import packageName.subpackageName.ClassName;

9

A package is a set of related classesTo Include your class into a specific

package, you say:

package SpecificPackageName;

At the top of your class source code.

This must be the initial instruction.

CodeWarrior provides a default package for each program you create.

10

When placing a class into a package the class file itself MUST be in a specific location.

A Package is located in a subdirectory that matches the PACKAGENAME.

The DOT notation is used to list the directory tree of that package.

11

For example, if I create a package that contains classes used in our AP class, I can

Create a package Farrell.APJava.Samples

In this case I must have created a directory Farrell / APJava / Samples /

in which I place all of my classes.

12

Sun suggests that a consistent naming convention be used when creating package libraries. Use as the directory of your packages, the reverse name of your URL.

For example, development for our school would have the following package name:

com.highschool.millburn.apjava

You need to place your classes in an appropriately named directory.

13

The package name is now part of the class name, so if another program wished to use one of your classes, or the entire package they would need to import them as follows:

import com.highschool.millburn.apjava.*

import com.highschool.millburn.apjava.OurMathClass

14

Also, when writing a class that will belong to a specific package, you can use ANY other class in that package without having to IMPORT that class (or package).

java.lang is a package that contains the most common classes like Math, Object, System & String. This package is auto loaded into any program so the import is not required.

15

However, in order to use any other java package, you must import that package OR import a specific CLASS located in that package

16

import javax.swing.* // imports entire // package

import java.util.LinkedList // imports one // class in the package

The IMPORT statement tells the compiler where to find the classes and interfaces

You wish to use in your program. You can import an entire package or a specific class.

17

If you did not use import to bring in classes to your project, you would need to fully qualify the class path in your code.

For example, to use Swing’s JButon, you would code

javax.swing.JButton myButton = new javax.swing.JButton;

18

In cases where different packages contain classes that have the same class name, you still need to preface the class name, when referencing the class in your code, with it’s package name.

This obviates the ambiguity.

For example, the List class exists in java.util as well as java.awt so in code, you need to specify

java.util.List myList = new ArrayList( );

19

Common Classes:

java.lang

java.util

java.io

java.awt

java.applet

javax.swing

20

Package Access Control:

We have already discussed Public, private and protected access for classes but there is one more level of access to consider and that is Package access.

This level of access is NOT an AP topic, but it is interesting to consider.

21

Package Access Control:

If you DO NOT declare a class level attribute OR method in a class as public, private or protected then that attribute get PACKAGE level access.

With Package access, ALL classes in the same package can access a package level attribute. But NO other class in any other package can use it (Public provides for

such access).

22

For Example:

public class Account

{

double balance;

…

}

23

In this example, the balance class level attribute is not Private as it should be.

It has package level access SO ANY method in ANY class in the same package as the Account class can mutate this attribute.

This violates the principle of encapsulation.

24

In addition, PROTECTED access not only allows subclasses to access a given class attribute , it gives access to ALL classes in the same package.

SO, for this reason it is preferable to limit scope of class level attributes to PRIVATE and provide necessary accessor and mutator methods.

25

JavaDoc:

Just like the online Documentation for Java’s API and the Case Study (MBS) Documentation, you can create your own Java Doc.

You need to provide JAVA DOC style comments for your Classes, Methods and Class Level Attributes

/**

*/

Place each comment IMMEDIATELY above the item it documents.

26

Each document “set” contains information followed by tags

TAGS start with @

Examples: @author@param@return@throws@author@version

Keep the first part of the Java Doc short and make it a summary explanation of the class, method or attribute you are documenting. JavaDoc will extract these statements automatically.

27

Use one @param tag for each argument being passed Example of correctly commented code:import java.util.ArrayList;/** * Write a description of your class here. * * @author (your name) * @version (a version number or a date) */public class YOURCLASS{

CLASS Level Attributes Declared /** * Constructor. Sets the initial state of class level attributes */ public YOURCLASS ( ) { } /**

28

* Returns the Salary of the Person Given* @param SSN the social of the person to find* @param LN the Last Name of the person to find* @return the persons net salary* @throws IllegalArgumentException if the SSN

is not valid*/ public int getSalary (String SSN, String LN) { if(SSN.length() < 9)

throw new IllegalArgumentException( ); return salary;

}

29

Generating the Documentation:

RUN javadoc

GET MORE INFO ONLINE ON HOW TO DO THIS

java.sun.com/j2se/javadoc

30

Generating the Documentation:

Install and utilize BlueJ’s IDE to generate Documentation

Lets Illustrate using BlueJ

31

Project:

Create your own JavaDoc for your last class created

32

NO TEST FOR THIS LESSON !!!