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 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.Object java.lang.Comparable java.lang.Integer java.lang.Double java.langString java.lang.Math java.util.Random java.util.List java.util.ArrayList java.util.LinkedList

7 Java API: java.util.Set java.util.HashSet java.util.TreeSet java.util.Map java.util.HashMap java.util.TreeMap java.util.Iterator java.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 classes To 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. Netbeans 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 PACKAGE NAME. 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.OurMath Class

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 JButton, 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 gets 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 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 tag for each argument being passed Example of correctly commented code: import java.util.ArrayList; /** * Write a description of your class here. * (your name) (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 SSN the social of the person to find LN the Last Name of the person to find the persons net salary 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 !!!