Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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