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
References as parameters • Reference variables hold reference values (addresses). • Java allows you to use reference values as parameters and as return values. • References are still passed by value. • Any object that has a reference to another object can use its public instance variables and methods. Class Interfaces and wrapping up other stuff NSCC CSC 142 Notes f-1 NSCC Passing a reference CSC 142 Notes f-2 Returning a reference Client code that uses the Point class as supplier (from LineSegment class): Client code that uses the Point class as supplier (from LineSegment class): public class LineSegment { private Point p1, p2; public Point midpoint( ) { double midX = ( p1.getX( ) + p2.getX( ) ) / 2.0; double midY = ( p1.getY( ) + p2.getY( ) ) / 2.0; Point result = new Point( midX, midY ); return result; } public void setFirstPoint( Point p ){ p1 = p; System.out.println( p.getX( ) ); } // other code } NSCC CSC 142 Notes f-3 NSCC this Many programmers will use this explicitly within a class public class Test{ public int x; public Test( ) { this.showSomething( ); } public void showSomething( ) { System.out.println( “x value is “ + this.x ); } } public class Test{ public int x; public Test( int x ) { this.x = x; } ... } CSC 142 Notes f-4 this • Sometimes an object needs to refer to itself • Use the keyword this Example: if an instance variable and parameter have the same name NSCC CSC 142 Notes f-5 NSCC CSC 142 Notes f-6 CSC 142 Notes f-1 3 Views of a class 3 Views of a class 1) Source code (implementation) • only readable by programmers, not always available • contains ALL implementation details that describe exact behavior 3) UML class diagram (abstract) • smallest – intended as development aid • contains no implementation or even description • may or may not show private class members • NOTE: this is NOT an object diagram! 2) Javadocs specification ( abstract ) • generated from javadocs comments within source code • does not show implementation details • usually only shows public ‘interface’ NSCC CSC 142 Notes f-7 NSCC How to create Javadocs? Include a Javadoc comment for every class, every method and every instance variable in your code • /** * This is the typical format of a simple comment. */ To save space you can put a comment on one line: A common mistake is to put an import statement between the class comment and the class declaration. Avoid this, as Javadoc will ignore the class comment. f-9 Point ( ) <query methods> + double getX( ) + double getY( ) <command methods> + void setX( double ) + void setY( double) CSC 142 Notes f-8 • Standard and in-line tags - A tag is a special keyword within a doc comment that Javadoc can process. Javadoc has standard tags, which appear as @tag... NSCC CSC 142 Notes f - 10 How to generate Javadocs? There are 4 essential tags required for this course: @author name-text Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. @version version-text Adds a "Version" subheading... A doc comment may contain at most one @version tag. Version normally refers to the version of the software or its date of creation. @param parameter-name description Adds a parameter to the "Parameters" section. The description may be continued on the next line. @return description Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values. CSC 142 Notes <constructors> A comment is a description possibly followed by tags - The description begins after the starting delimiter /** and continues until the tag section. The tag section starts with the first character @ that begins a line (ignoring leading asterisks, white space and comment separator). The description cannot continue after the tag section begins. There can be any number of tags -- some types of tags can be repeated while others cannot. This @param starts the tag section: Javadoc @tags NSCC - double y /** * This is a doc comment. * @param x is a location */ /** This comment takes up only one line. */ CSC 142 Notes - double x How to create Javadocs? ( from http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html#javadoctags ) NSCC Point <attributes> f - 11 • In DrJava, select ‘Javadoc’ button • In BlueJ, select 'Generate Documentation' • Javadocs will be created for each class in project. • Javadocs are html files stored in a folder named ‘doc’. • Does not include private methods or variables by default. EX: Point.java, BankAccount.java NSCC CSC 142 Notes f - 12 CSC 142 Notes f-2 Importance of Javadocs Packages • They are the standard way to provide abstract (without implementation) description of a class. • They provide an easy way to understand the public interface of a class in the face of complexity... When dealing with such large numbers of classes, it is helpful to organize them into packages. – uwcse.jar has over 40 classes arranged into 5 packages – Java 1.4.2 has over 2500 classes arranged into 135 packages – The only way to survive is to refer to Javadocs NSCC CSC 142 Notes f - 13 Helps to avoid name collisions (2 classes with the same name). EX: java.awt.Rectangle vs uwcse.graphics.Rectangle NSCC import public Test( ) { public Test( ) { java.awt.Color c = new Color c = new Color( 20, 40, 60 ); java.awt.Color( 20, 40, 60 ); } NSCC You can either import a single class: import java.awt.Color; public class Test{ public class Test { } or the entire package: import java.awt.*; } } CSC 142 Notes Careful when importing entire packages -naming collisions may result. f - 15 NSCC The Java API f - 16 • java.lang also contains the Math class. • Math contains many mathematical functions. – All Math methods are static methods (or class methods), so there is no need to create an instance of the Math class. Instead, use the name of the class as the method qualifier, like this: – What are Java’s packages? • Java automatically imports all classes from java.lang package. • java.lang contains the String class. Exercise: find the Javadocs for the String class. CSC 142 Notes CSC 142 Notes Math class • A set of pre-defined classes is called a library or an API (Application Programming Interface). NSCC f - 14 Import statement The import statement allows you to refer to classes by simple names Example: import java.awt.Color; CSC 142 Notes double y = Math.sqrt( x ); class name, not an instance name Exercise: find the Javadocs for the Math class. f - 17 NSCC CSC 142 Notes f - 18 CSC 142 Notes f-3