Download Lecture 5 PowerPoint

CSCI E-70 Lecture #5
Using Threads in GUIs
Java Documentation: JavaDoc
Daniel Bromberg
26 Feb 2003
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
1 of 18
Threads
• An independent path of execution in a program
– Threads execute in “parallel”
• On single processors, by time multiplexing
– Allocated its own stack and given base function
– Terminated when base function returns; stack removed
• Threads in Java
– basic startup and shutdown
• “main” thread started, enters main function
• “Reference Handler” thread started (Garbage Collector)
• JVM exits when all non-daemon threads exit
– daemon: system maintenance tasks such as Garbage Collector
– no need to keep JVM running if there’s nothing left to maintain.
• System object has state accessors; IDEs have thread browsers
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
2 of 18
Swing Threads
• Maintain user interactivity in complex environment
– Program may have long-running non-GUI tasks
• Event thread (AWT-EventQueue) started when first
Swing bean instantiated
– Context in which all listeners & painters are run
• Rule #1: Don’t tie it up; return quickly
• Rule #2: Don’t manipulate (setXyz()) a bean’s view outside of
this thread!
– May cause inconsistent appearance
– Pass messages instead: after updating model, call repaint()
• Other threads, safe to ignore:
– AWT-Shutdown
– AWT-Windows (daemon)
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
3 of 18
Event/Thread Schematic
Threads communicate safely through carefully managed
Data Structures
Example: Event Queue
please
paint Y
key
pressed
mouse
clicked
please
paint X
Your own Thread
AWT Event
Thread
listen for event;
determine recipient;
dispatch event;
26 Feb 2003
update internal state (counters)
update model
notify observers:
observer requests repaint
sleep
CSCI E-70 Lecture 5 / Bromberg
4 of 18
Code Example: Updating Label
• Implement the Runnable interface
public void run() {
for ( ; ; ) {
SimpleUpdater.java
counter++;
setChanged();
notifyObservers(new Integer(counter));
try {
Thread.sleep(sleep);
} catch ( InterruptedException ie ) {
System.err.println(“We were interrupted: " + ie);
}
}
}
See:
• Create a Thread:
– Thread runnerThread = new Thread(runner);
• Start it from main or a constructor:
– runnerThread.start();
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
5 of 18
Creating Javadoc
• Generated from appropriately placed &
formatted comments within your code
• HTML formatting may be embedded:
<em>, <br>, <code>, <ul>, even <table>
• Special non-HTML tags give standard
structure:
– General info: @author, @version
– Method spec: @param, @return, @throws
– References: @since, @serial,
@see, {@link classname}
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
6 of 18
Making a comment
•
•
•
Part 1: a description with arbitrary HTML
Blank line (containing a ‘*’)
Part 2: Series of tags
/**
* A sentence generally describing <em>frombulation</em>.
* Going on to enumerate the steps: first, it ...
*
* @param froozle – The String you want frombulated
* @param bazMap – A {@link Map} of {@link Bazorg} constraints
*
to control the frombulation process
* @return A newly allocated, frombulated String
*/
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
7 of 18
Format Guidelines
•
•
•
•
•
•
Start with two *’s, end with one
Line up all *’s
One space between asterisk and text
Break lines at 80 chars
Separate paragraphs in description with <p>
Follow standard order:
–
26 Feb 2003
author, version, param, return, exception, see,
since, serial, deprecated
CSCI E-70 Lecture 5 / Bromberg
8 of 18
Style pointers
• Use { @link } sparingly
– avoid well-known classes (java.lang)
– it draws attention, too many are distracting
– only use in first reference within comment
• bullets, phrases are acceptable
– brevity is desirable
• description goes beyond API name
– don’t just say that addText “adds text.”
– but not always possible; completeness more important
• description uses 3rd person: “Appends the text in
<code>sText</code> to display area.”
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
9 of 18
Tag specifics
• @author – Creator(s) of class
– Can be multiple, list in chronological order
• @param – Argument(s) to method
– List in declaration order
• @throws – Checked Exception(s) thrown
– List in alphabetical order
• @return – Value returned
– Include for all methods except void, even if trivial
– Specify exceptional cases such as error codes, null
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
10 of 18
Tag Specifics (cont.)
• @see – Related items
– List in closeness of “scope”: in class, in package,
outside package
– Within scope, list in order of: fields, constructors,
methods
• @since – Version when API first introduced
• @serial – Don’t worry about it, but:
– Serialization is stream encoding of objects for saving to
disk or sending over networks
– Later reconstituted at another time or in another JVM
– Specifies field precisely enough to serialize: what are
acceptable values
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
11 of 18
Package Overviews
• Create a package.html with a template
– place in source directory (containing .java files
for that package)
• javadoc will automatically process:
– translates all @see, @link, @since tags
– merges into full docs:
• copies all between <body> and </body> into
generated package-summary.html
• first sentence into generated overview.html
• Sample template
java.sun.com/j2se/javadoc/writingdoccomments/package-template
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
12 of 18
Following Up
• These slides distilled from:
– java.sun.com/j2se/javadoc/writingdoccomments/index.html
– java.sun.com/products/jdk/1.2/docs/tooldocs/win32/javadoc.html
• “JavaDoc Tags” link
• Package Overviews: “Package-Level Comments” link
– JavaDoc home page: java.sun.com/j2se/javadoc/index.html
• Running JavaDoc:
– javadoc –sourcepath source_dir –d
destination_dir
package_name1 package_name2 ...
• Other tags to read about
– @serial, {@docRoot}, {@linkplain}...
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
13 of 18
RTSL
You can See How It’s Done!
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
14 of 18
Two Distinct Purposes
• Complete Technical Specification
– Boundary conditions, exact allowable input formats, all
error conditions, mathematical symbolism (“for
each”..., “such that...”)
– Intended for implementors, conformance tests,
developers already familiar with all concepts
• Programmer’s guide
– Help newcomer to your package actually use it
– Longer descriptions including:
• Code examples, conceptual overviews, intended & typical
usage, warnings of pitfalls
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
15 of 18
Spec vs. Newcomer Example
• Creating a color
– Spec: “The r field 8-bit unsigned integer (0
min, 255 max) specifies the red component of
the RGB color vector.”
– Newcomer: “Showing color information on a
computer display involves describing each
color by a series of numbers according to an
accepted standard, called a color model. The
RGB model in most common, because it maps
directly...”
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
16 of 18
JavaDoc and You
• Java online API strongly biased towards pure
technical spec
– Why it’s Not So Useful and you have to Buy The Book
• Decide on emphasis (spec/newcomer) beforehand
• Fulfilling both purposes are possible
– Very long & time consuming
• Take time to develop your own documentation
style; there is no ultimate authority
– Be consistent
– Pick audience; avoid unnecessary review/repetition
– You will get much faster at it with practice
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
17 of 18
JavaDoc and final project
• Required on final project
• Insert compliant JavaDoc comments in:
–
–
–
–
public methods, including empty ones (abstract & interface)
any static, final, or non-private fields
top of classes, interfaces
packages
• Complete enough for another programmer at your level to
extend or insert your API into another project
– Think beans: which components are pluggable elsewhere?
• Turn in generated HTML file set
26 Feb 2003
CSCI E-70 Lecture 5 / Bromberg
18 of 18