JAVA API & Packages

slimwhimperSoftware and s/w Development

Nov 3, 2013 (3 years and 9 months ago)

119 views

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.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 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 !!!