Programming for API’s

[next] [prev] [prev-tail] [tail] [up] [toc]

Chapter 5
Programming for API’s

   5.1 Background
   5.2 javadoc
   5.3 Classes
   5.4 Fields
   5.5 Constructors
   5.6 Methods
   5.7 Packages
   5.8 Inheritance
   5.9 Implementation
   5.10 API’s Comments
   5.11 Assignment #5: Reverse Engineering APIs
   5.12 Assignment #6: Reverse Engineering APIs

5.1 Background

Programming in java consists of
- Introducing code which states the functionality of features
- Providing code which realizes the functionality of the features.
- Writing code which uses the features
We are concerned here with the first issue.
- This issue asks for abstractions in programs
- Abstractions are a vital approach of programming, helping to cope with the complexity of systems.
- Interfaces offer a way to program abstractions.

5.2 javadoc

API’s are abstractions of the static structure code. They are the skeletons on top of which the code in discourse is built. They show the contract of the code.
The Java system is offered with a utility for extracting API’s, named javadoc.
We use the command ‘javadoc -package filename.java’ to compile a file for its interfaces.
The output is sent to ‘filename.html’.

5.3 Classes

The simplest complete code program consists of an empty class.
The file should be named the same way as the class.
Possible syntax:
<optional modifiers> class <name> { <body> }

Classdoc.java, javadoc -package Classdoc.java
public class Classdoc{ }

Class Classdoc

java.lang.Object
|
+--Classdoc

public class Classdoc

extends java.lang.Object

Constructor Summary

Classdoc()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

5.4 Fields

Syntax:
<optional modifiers> <type> <name> ;
That is, the field interface followed by semicolon.

Fielddoc.java, javadoc -package Fielddoc.java
public class Fielddoc {
   public int a;
   public Fielddoc b;
   static public double c;
   public double d;
  }

Class Fielddoc

java.lang.Object
|
+--Fielddoc

public class Fielddoc

extends java.lang.Object

Field Summary

(package private) int a

(package private) Fielddoc b

(package private) static double c

double d

Constructor Summary

Fielddoc()

5.5 Constructors

If none mentioned, an empty-arguments variant is supplied by the system.
If some is mentioned, an empty-arguments variant must also be supplied.
All the constructors must carry the class name.
Possible syntax
<optional modifiers> <name> ( <parameters> ) { }
That is, the constructor interface followed by braces.

Constructordoc.java, javadoc -package Constructordoc.java
public class Constructordoc{
public Constructordoc () {}
public Constructordoc (int x) {}
}

Class Constructordoc

java.lang.Object
|
+--Constructordoc

public class Constructordoc

extends java.lang.Object

Constructor Summary

(package private) Constructordoc()

(package private) Constructordoc(int x)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

5.6 Methods

Possible syntax (for compilation under javadoc):

<optional modifiers> <return type> <name> ( <parameters> ) { }

That is, the method interface followed by braces.

Methoddoc.java, javadoc -package Methoddoc.java
public class Methoddoc{
public int a () {}
public static double b (int x) {}
}

Class Methoddoc

java.lang.Object
|
+--Methoddoc

public class Methoddoc

extends java.lang.Object

Constructor Summary

Methoddoc()

Method Summary
(package private) int	a()
static double	b(int x)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

5.7 Packages

Choose a name for the package (lower case letters)
Create a subdirectory with that name
Prepare a separate file for each class, with the following command at the start.
package <package name>
Insert the files to the subdirectory
Compile the files
javadoc <subdirectory name>/*.java

package mypackage;
public class Cdoc1{ }

package mypackage;
public class Cdoc2{ }

javadoc -package mypackage/*.java

Hierarchy For All Packages

Class Hierarchy

     * class java.lang.Object
          + class mypackage.Cdoc1
          + class mypackage.Cdoc2

mypackage

Class Cdoc1

java.lang.Object
|
+--mypackage.Cdoc1

public class Cdoc1

extends java.lang.Object

Constructor Summary

Cdoc1()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

5.8 Inheritance

Default inheritance from the Object class.
Possible syntax:
<optional modifiers> class <name>
extends <name> {
<body>
}

inherdoc.java, javadoc -package inherdoc.java
public class inherdoc extends java.lang.Math{
}

Class inherdoc

inherdoc

public class inherdoc

Constructor Summary

inherdoc()

Constructor Detail

inherdoc

public inherdoc()

5.9 Implementation

Abstract classes are introduced for enforcing designs in concrete classes.
Possible syntax:
<optional modifiers> class <name>
implements <interfaces> {
<body>
}

public class foo implements goo, hoo {
...
}

5.10 API’s Comments

Associate reference documentation to code.
They should included immediately before declarations to which they apply.
They are typically designed to provide fairly terse reference documentation.
They are introduced through block comments of the form ‘/** ... */’.
Different features of javadoc are described in its manual

/**  prose for our class
*/
class Foo {
  /**  prose for the `xx' method */
  public static void xx (String yy)  {
  }
}

5.11 Assignment #5: Reverse Engineering APIs

Due: Fr, Apr 11, midnight

Prepare a file ‘Counter.java’ that results in the following documentation, when compiled with a command of the form ‘javadoc -package Counter.java’.

Class Counter

java.lang.Object
|
+--Counter

public class Counter

extends java.lang.Object

A simple class

Constructor Summary

Counter()
sets the counter to 0

Method Summary
int	count() informs the value of the counter
void	reset() sets the counter to 0
void	step() increases the counter by 1
void	step(int i) increases the counter by i
java.lang.String	toString() sets a print representation for the counter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Counter

public Counter()

sets the counter to 0

Method Detail

step

public void step()

increases the counter by 1

step

public void step(int i)

increases the counter by i

reset

public void reset()

sets the counter to 0

count

public int count()

informs the value of the counter

toString

public java.lang.String toString()

   sets a print representation for the counter

        Overrides:
                toString in class java.lang.Object

You should submit this and the following assignments electronically.

In general, to submit a lab electronically, one should type the command ‘submit class lab# file1 file2 ...’ in the terminal window.
In this course, ‘class’ stands for ‘c201af’.
Assume ‘lab5’ for the current lab.
Consequently, for the current lab, you should type ‘submit c201af lab5 Counter.java’.

Note: Make sure to read your cis emails. Notices from the submit program, and the grader’s comments, will be directed to that address.

Q&A | Practice Example | Q&A

5.12 Assignment #6: Reverse Engineering APIs

Due: Mo, Apr 14, midnight

Prepare a file ‘Bool.java’ that provides a web page with tables of fields, construcors, and methods similar to those offered for java.lang.Boolean, when compiled with the command ‘javadoc -package Bool.java’.
Your web page should differ from the given web page only in the references to the class name Boolean. It should use the Bool class name instead of the Boolean class name. (Note, however, that the references to the primitive data type boolean should remain intact.)
The compiled HTML documentation does not need to include the same comments as the Boolean documentation.

Assume ‘lab6’ for the submit program.

[next] [prev] [prev-tail] [front] [up] [toc]

Chapter 5Programming for API’s

5.1 Background

5.2 javadoc

5.3 Classes

5.4 Fields

5.5 Constructors

5.6 Methods

5.7 Packages

5.8 Inheritance

5.9 Implementation

5.10 API’s Comments

5.11 Assignment #5: Reverse Engineering APIs

5.12 Assignment #6: Reverse Engineering APIs

Chapter 5
Programming for API’s