JavaDoc - Java API Documentation Generator
Transcript of JavaDoc - Java API Documentation Generator
09/08/2000 12:26
1
Matthew Morgenstern 1 CS211 Class - Sept. 7, 2000
Java Program Style and Design - ContinuedJava Program Style and Design - Continued
l Program Design Concepts:u Design Patterns
u Refinement
u Abstractions - Program Conceptualization
– Object-oriented programming and abstraction
u Pseudo-code: abstraction and refinement
Today:
u JavaDoc
u Software Lifecycle
u UML - Unified Modeling Language
Matthew Morgenstern 2 CS211 Class - Sept. 7, 2000
JavaDoc - Java API Documentation GeneratorJavaDoc - Java API Documentation Generatorjavadoc <sourcefiles.java> *l Parses the declarations and documentation comments in a set
of Java source files
l Produces a set of HTML pages describing public and protectedclasses, interfaces, constructors, methods, and fields.
u One .html file for each .java file and each package
u Class hierarchy (tree.html) & index of members (AllNames.html)
u Includes class and member signatures.
u You can add further documentation by including doc /**comments in the source code - may include html tags/** * This is a <b>doc</b> comment. */
u Doc comments only recognized immediately before class,interface , constructor, method, or field declarations.
09/08/2000 12:26
2
Matthew Morgenstern 3 CS211 Class - Sept. 7, 2000
JavaDoc - 2JavaDoc - 2l First sentence of each doc comment should be a sum-
mary sentence - for method summary at top of html file.
l javadoc parses special tags within a Javadoc comment.These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with "at"sign (@):
u @param parameter-name descriptionu @return descriptionu @exception fully-qualified-class-name descriptionu @author name-textu @version version-textu @see classname:
Adds a hyperlinked "See Also" entry to the class.
l Class, method, and Field doc comments supported.
l http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javadoc.html
Matthew Morgenstern 4 CS211 Class - Sept. 7, 2000
An example of a method doc commentAn example of a method doc comment/** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue()
*/ public char charAt(int index) { ... }
For Java API - JavaDoc output see:http://java.sun.com/products/jdk/1.2/docs/api/index.html
09/08/2000 12:26
3
Matthew Morgenstern 5 CS211 Class - Sept. 7, 2000
Overview pageOverview page
Matthew Morgenstern 6 CS211 Class - Sept. 7, 2000
Package pagePackage page
09/08/2000 12:26
4
Matthew Morgenstern 7 CS211 Class - Sept. 7, 2000
Classic ‘Waterfall’ LifecycleWaterfall model stages in the software development process are seen to
cascade down from one to another.
Classic ‘Waterfall’ LifecycleWaterfall model stages in the software development process are seen to
cascade down from one to another.
Is project technically, operationally, financially & legally feasible ?Is project technically, operationally, financially & legally feasible ?
Gather and Analyze the requirements for the systemGather and Analyze the requirements for the system
• Architectural highlevel design (whatprograms are we going toneed & how will they interact),
• Interface design (what are theinterfaces going to look like),
• Detailed low level design (how theindividual programs are going towork),
• Data design (what data are wegoing to need).
• Architectural highlevel design (whatprograms are we going toneed & how will they interact),
• Interface design (what are theinterfaces going to look like),
• Detailed low level design (how theindividual programs are going towork),
• Data design (what data are wegoing to need).
Implementation:Designs are translated into codeImplementation:Designs are translated into code
Module TestsModule Tests
Add extra things &/or changeexisting things over time .Add extra things &/or changeexisting things over time .
Operation &MaintenceOperationOperation &&MaintenceMaintence
System TestsSystem Tests
Matthew Morgenstern 8 CS211 Class - Sept. 7, 2000
09/08/2000 12:26
5
Matthew Morgenstern 9 CS211 Class - Sept. 7, 2000
Matthew Morgenstern 10 CS211 Class - Sept. 7, 2000The FOUNTAIN Model for an individual class or a subsystemThe FOUNTAIN Model for an individual class or a subsystem
Notefeedback ateach stage
Notefeedback ateach stage
09/08/2000 12:26
6
Matthew Morgenstern 11 CS211 Class - Sept. 7, 2000
Iterative Lifecycle ModelIterative Lifecycle Model“Producing software by successive refinement”
Spiral Development emphasizes iterative phases“Producing software by successive refinement”
Spiral Development emphasizes iterative phases
Matthew Morgenstern 12 CS211 Class - Sept. 7, 2000
Unified Modeling Language (UML)Unified Modeling Language (UML)
l One of the main goals of system modeling is to
u partition a system into cohesive components
u that have stable interfaces, creating a
u core that need not change in response to subsystem-levelchanges
l UML was developed by Grady Booch, JamesRumbaugh, and Ivar Jacobson
09/08/2000 12:26
7
Matthew Morgenstern 13 CS211 Class - Sept. 7, 2000
UML Modeling Techniques for Development ProcessUML Modeling Techniques for Development Process
We focus on:We focus on:
Matthew Morgenstern 14 CS211 Class - Sept. 7, 2000
UML Modelling DiagramsUML Modelling Diagramsl Use case diagrams: external interaction with system:
u Enroll students in courses; • Produce student transcripts.
l Class diagrams: object models, classes & their interrelationships:u including inheritance, aggregation, and associations, • Object diagrams
l Sequence / object-interaction diagrams: event-trace diagram:u defines the logic of how objects interact; e.g. in a use case scenario.
l Component diagrams: show the software components used:u shows their dependencies, interfaces, and interrelationships.
l Deployment diagrams: configuration of run-time processing units
u including the hardware and software.
l Statechart diagrams: represent states in the behavior of an object:u shows events which cause transitions betwn stages & resulting actions.
l Collaboration diagrams: show the message flow between objects:u implies the basic associations between objects in an O-O application.
http://www.sdmagazine.com/uml/focus.ambler.htm , http://www.rational.com/uml/index.jsp
09/08/2000 12:26
8
Matthew Morgenstern 15 CS211 Class - Sept. 7, 2000
UML Class DiagramUML Class Diagram
Matthew Morgenstern 16 CS211 Class - Sept. 7, 2000
09/08/2000 12:26
9
Matthew Morgenstern 17 CS211 Class - Sept. 7, 2000
Qualified AssociationQualifiedQualified AssociationAssociation
ConstraintConstraintConstraint
Association classesAssociation classesAssociation classes Role names & derived associationRole names & derived associationRole names & derived association
Matthew Morgenstern 18 CS211 Class - Sept. 7, 2000
dependence on ownerdependence on owner
09/08/2000 12:26
10
Matthew Morgenstern 19 CS211 Class - Sept. 7, 2000
Matthew Morgenstern 20 CS211 Class - Sept. 7, 2000
"You can model 80 percent of most prob-lems by using about 20 percent of theUML."-- Grady Booch
"You can model 80 percent of most prob-lems by using about 20 percent of theUML."-- Grady Booch
09/08/2000 12:26
11
Matthew Morgenstern 21 CS211 Class - Sept. 7, 2000
UML for Java's AWT Container ClassesUML for Java's AWT Container Classes
Matthew Morgenstern 22 CS211 Class - Sept. 7, 2000
From UML of Java's AWT Container ClassesFrom UML of Java's AWT Container Classes
l UML highlights selected aspects the Container class in Java's AWT.
l Container is a subtype of Component.
l Components can be made visible or active
l Other kinds of components include labels, buttons, etc.
l Containers include components (which may be other containers) andalso have a layout manager.
u From a component can find its container.
u Not all components need a container.
l Subtypes of container include panels and windows.
l Windows can show and dispose themselves.
l Window has subclasses frame and dialog.
l Frames and dialogs have titles and can be set to resize or not.u Although both subclasses of window do this, this behavior is not part of
window itself.
l Dialogs can be marked as modal, but frames cannot.
09/08/2000 12:26
12
Matthew Morgenstern 23 CS211 Class - Sept. 7, 2000Address
<<elementtype>>city
CountryCode
USA
ENG
GER
FR
<<enumeration>>
LanguageCode
ENG
FR
IT
<<enumeration>>
DocStates
Submit
Accept
Reject
<<enumeration>>
InternatAddr
<<elementtype>>country
language
{ENG}
DocProcess
<<elementtype>>
PurchaseOrder
<<elementtype>>
shipTo{0}
billTo{1}1..*1..*
lineItem
{3}
Data model of asimplified
Purchase Orderdocument
Data model of asimplified
Purchase Orderdocument
Matthew Morgenstern 24 CS211 Class - Sept. 7, 2000
Address
<<elementtype>>
String
(from Logical View)
<<datatype>>
name
{0}
street
{1}
city
{2}
Price
digits = 5
decimals = 4
<<scalar>>
anon0
<<sequence>>
name
{0}
cost
{2}
int
(from Logical View)
<<datatype>>
quantity
{1}
Accept
Reject
PurchaseOrder
<<elementtype>>
shipTo{0}
billTo{1}1..*
*
1..*
*
lineItem
{2}
09/08/2000 12:26
13
Matthew Morgenstern 25 CS211 Class - Sept. 7, 2000
Intent: This pattern makes the clients of a component communicatewith a representative (a surrogate) rather than to the component itselfIntent: This pattern makes the clients of a component communicatewith a representative (a surrogate) rather than to the component itself
Proxy - Design PatternProxy - Design Pattern
refers-torefers-torefers-to refers-to ->refers-to refers-to - ->>
{abstract}{abstract}
Matthew Morgenstern 26 CS211 Class - Sept. 7, 2000
Proxy Server - Design PatternProxy Server - Design PatternMotivating Problems:
• Different clients need access to a remote server
• Need optimization for access data: startup, batching
• Inappropriate to access component directly
• Do not want to hard code physical location (e.g. TCPIP address)
• Need security / access control
• Access need to be transparent and simple for the clients
Structure:
• Use a representative (Proxy) between client and component
• Offer interface of the component but performs additional pre and
post-processing such as access-control, caching, logging, etc
09/08/2000 12:26
14
Matthew Morgenstern 27 CS211 Class - Sept. 7, 2000
Java Implementation of Proxy Design PatternJava Implementation of Proxy Design Pattern
public class Proxy extends Subject{RealSubject refersTo;public void Request(){
if (refersTo == null)refersTo = new RealSubject();
refersTo.Request()}
}
Matthew Morgenstern 28 CS211 Class - Sept. 7, 2000
Applications of Proxy PatternApplications of Proxy Pattern
l Remote Proxy : clients or remote components should beshielded from network addresses and inter-processcommunication protocols
l Protection Proxy : Components under access control
l Cache Proxy : Multiple clients share read-only results fromremote components
l Synchronization Proxy : Multiple simultaneous accesses toa component must be synchronized
l Counting Proxy: Audit trail for component counts
l Firewall Proxy: Protect local client from outside world