ࡱ> SURW |%bjbjyy .LQl,@@@T8 <tT 2:     $! #. @. @@  C (@ @   @@  ,T{T,Y 0 ,]$]$TT@@@@Handout 6 Tools Reference This handout provides a quick reference to some of the core Java development tools. The following examples assume the following project directory structure: Under the directory c:\intro2java: .\bin root directory for compiled Java classes (.class files) .\docs directory to hold documentation, e.g. generated by Javadoc .\src root source directory, contains .java files The CLASSPATH The CLASSPATH is a system property that is used by the Java Virtual Machine to find Java classes referenced by an application. The value of the CLASSPATH is simply a semi-colon (Windows) or colon (Unix) delimited list of directories or Jar files. When attempting to import packages referenced by a class, the JVM will check each of these directories and Jar files in turn, until it finds a class with the correct name. Wrongly configuring the CLASSPATH is often the most frustrating and confusing problem encountered with Java programming! As an illustration, assume we have a class that imports the package intro2java, i.e. the class file includes the following line: import intro2java.*; Assuming the above directory structure, the following command will set the CLASSPATH on a Windows machine, appending our directory of class files to the current value of the CLASSPATH: set CLASSPATH=%CLASSPATH%;c:\intro2java\bin The CLASSPATH is read by all of the Java tools so its important to set it before working with them. To view on Windows, use the following command: echo %CLASSPATH% Java Compiler The Java compiler is invoked with the javac executable. E.g: javac MyClass.java javac intro2java/Calculator.java The compiler requires the java extension to be specified. It is good practice to keep your Java source code in a directory structure that maps to their package names. E.g. classes in the package intro2java.examples should be stored in: c:\intro2java\src\intro2java\examples By default the compiler will place the compiled classes in the same directory as the source. Using the d flag allows this behaviour to be altering by indicating an alternate directory into which the classes should be placed: javac d c:\intro2java\bin MyClass.java The compiler will automatically create a directory for each package of classes. Using the d flag is a useful way to keep you source code and compiled classes separate. Java Virtual Machine Assuming the CLASSPATH is set appropriately, a given Java class can be executed using the java command, e.g: java MyClass java intro2java.Calculator If the class is in a package then its fully qualified name must be used. If the class doesnt have a main method of the form: public static void main(String[] args) { } then an error will be generated. The method must be declared exactly as given, although the name of the single parameter can be altered. Javadoc Java includes a documentation generator that will create HTML documentation automatically from Java classes. By default the documentation will list all classes along with their public methods, constants, etc. The documentation is fully cross-referenced, containing, for example, a browse-able A-Z index. The documentation generator is invoked with the javadoc command. The command can accept a list of source files or packages as parameters e.g: javadoc intro2java/Calculator.java javadoc intro2java As the application generates a large number of HTML files, its worthwhile getting it to generate the documentation into a separate directory, e.g: javadoc d c:\intro2java\docs intro2java The generator will read specially formatted comments from within the Java source code and add their contents automatically to the generated documentation. These comments all use the following format: /** * A javadoc comment. Note the double star */ If these comments appear directly before a class, method or constant definition in the source code, then the comments will be added to the generated HTML. E.g: /** * A description of my class, which will be automatically * understood by javadoc */ public class MyClass { //other documentation } The comments may contain normal HTML tags e.g. Paragraph (

), Bold (), Italics () to improve the readability of the output. Javadoc Tags Javadoc understands a number special tags that can be used in the Javadoc comments to further customise the generated documentation. In some cases extra parameters must be passed to javadoc so that it processes this extra information. The most commonly used tags are summarised below: TagWhere UsedExampleDescription@authorClass comments@author Leigh DoddsAdds the authors name to the generated documentation, but only if the additional author flag is passed to javadoc on the command line.@versionClass comments@version 1.0Adds a version indicator. But only if the version flag is included on the command line@deprecatedClass or method comments@deprecated Dont use this method any moreAdds a deprecation message. Deprecation is used to mark code that should no longer be used. The javac compiler will also generate a warning if it encounters deprecation messages.@seeClass or method comments@see package.class#member labelAdds a see also link. The tag should be followed by a class and optionally a method name. The text of the link is the value of label@paramMethod comments@param name descriptionLists the name of a method parameter, and gives it a description. Can be used multiple times.@returnMethod comments@return the value of x+yDescribes the return value of a method Heres a complete example: /** * A simple Calculator * * @see calculator.AdvancedCalculator a more advanced alternative * @author Leigh Dodds * @version 1.0 */ public class Calculator { /** * Adds two numbers together and returns the result * * @param x the first number * @param y the second number * @return the value of x + y */ public int plus(int x, int y) { return x + y; } } Jar The jar command is used to package up java classes into a Java Archive. Jar files are used as a handy way to package up Java code e.g. for delivering as an applet or application. To create a Jar file use the following command: jar cf jarFileName.jar *.class The c parameter indicates that were creating a file, and the f parameter indicates the filename. To examine the contents of a jar file use the t parameter: jar tf jarFileName.jar To extract the contents of a jar file use the x parameter: jar xf jarFileName.jar To update classes in an existing jar file use the v parameter: jar uf jarFileName.jar *.class Only those files that have been changed will be added to the jar file. Jar files can be used to distribute source code and documentation as well as class files. To package up the entire project use: jar cvf project.jar docs bin src or jar cvf project.jar * Manifests A jar file can contain a special index known as a manifest. This is a configuration file that can be used to specify extra information about the contents of the archive. The most useful feature of the manifest is its ability to indicate the class within the archive that contains the main method for the application. To create a manifest, edit a file called Manifest.mf and enter the following: Main-Class: your.class.Name E.g. Main-Class: intro2java.Calculator Then create a Jar file containing the required class(es), but this time include a manifest using the m parameter: jar cmf Manifest.mf jarFileName.jar *.class You can then run your application as follows: java jar jarFileName.jar The JVM will then read the manifest and determine which class it should actually be running. On Windows this also means that you can double-click on a jar file and have its application execute automatically. Further information For more information about the various Java tools, visit:  HYPERLINK "http://java.sun.com/j2se/1.4.1/docs/tooldocs/tools.html" http://java.sun.com/j2se/1.4.1/docs/tooldocs/tools.html  Jar stands for Java ARchive. It is a zip file containing Java classes, and is the preferred means of packaging classes for distribution.  Its very similar to the tar command on Unix systems.  The order in which you pass the m and the f parameters indicates whether the jar command expects the manifest name or jar file name as the next parameter on the command line. E.g. jar cfm jarFileName.jar Manifest.mf *.class Introduction to Java Programming Handout  FILENAME #6 Tools Reference.doc L. Dodds, October 2002  PAGE 2/ NUMPAGES 6 $bgEZ A [ ^  ! 4 i Y  c ex?BKNZ]NUX_3^2R muxWv{|  6mH sH j0JUmH sH 0JCJOJQJmH sH mH sH WbHIDEZ[  A B 3 Q#${%3 4 G H i j X Y  b c 6 K ./dee$TUwx|$& #$/Ifb$TCC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae4 TCC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae4 3^TCC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae42RTCC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae4 gT8CC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae4ghpTdCC2C$& #$/Ifb$$& #$/Ifb$$$IfTl\ <#=F%  t 6 0#644 lae4E\TRRRPPPPP$$IfTl\ <#=F%  t 6 0#644 lae4 \lp *0PTgkmq%&VWvw-.-\]j#+~ +!,!6!7!:!f!!!""###O#P#Q#R#p######$$$$$$$!%"%,%-%C%D%E%F%_%`%f%g%h%i%j%k%u%v%ܷ0JmHnHu0J j0JUmHnHsH u0J j0JU 0JmH sH jUmH sH jUmH sH j0JUmH sH 6]mH sH 0JmH sH A.ij)*. / } ~ &#$ 9!:!f!g!!!!!""""Q##$$$E%F%y%z%{%|%v%w%x%y%{%|%mH sH  j0JU0JmHnHu,1h/ =!"#$% DyK yK phttp://java.sun.com/j2se/1.4.1/docs/tooldocs/tools.html i8@8 NormalCJ_HaJmH sH tH R@R Heading 1$<@&5CJ KH OJQJ\^JaJ T@T Heading 2$<@& 56CJOJQJ\]^JaJN@N Heading 3$<@&5CJOJQJ\^JaJ<A@< Default Paragraph Font0O0 CodeCJOJQJmH sH DOD Style1  & FCJOJQJ^JaJmH sH ZoZ Code Example#$& #$-D@&M mHnHu>O!> Code CharOJQJ_HaJmH sH tH ,@2, Header  !, @B, Footer  !&)@Q& Page Number6@b6  Footnote TextCJaJ8&@q8 Footnote ReferenceH*.U@. Hyperlink >*B*ph>O">Code Example Char mHnHu6|!|!LbHIDEZ[AB34GHijXYbc6 K . / d e  $ T U     wx| 3^2R ghpE\lp *0PTgkmq%&VWvw-.ij)*./}~9:fgQ E!F!y!}!00000000000000000E0E0E00000000000000H0H0H0H0H00Y0Y0Y00c0c0c0c0c06 06 0000 0 0 0 0 00e 0e 0e 0 0 0 0 0000 0 0 00 0 0 0000000000000000(00000000000000000000000000000000000000000000000000000000000000000k0m0m0m0m00W0W0W0W0W000000j0j0j00000000000(0000000~0~0~000000:0:0:0000000@0@0 @0@0@0 OOv%|%"%3 e g\. |% !#${%O|!X*5Lhoqs~!8@0(  B S  ?PQ z!}! $bdtw 4>36jioQ z!}!3333333333333333333     PQ !!D!F!_!i!j!z!}!ldodds Leigh Dodds6C:\projects\lectures\intro2java\#6 Tools Reference.doc(mFh^`OJQJo(hHh^`OJQJ^Jo(hHohpp^p`OJQJo(hHh@ @ ^@ `OJQJo(hHh^`OJQJ^Jo(hHoh^`OJQJo(hHh^`OJQJo(hHh^`OJQJ^Jo(hHohPP^P`OJQJo(hH(mic         3^2R ghp}!@ZZ?@ACDEFGHIKLMNOPQTRoot Entry F`3%,T{VData '1Table/]$WordDocument.LSummaryInformation(BDocumentSummaryInformation8JCompObjjObjectPool`3%,T{`3%,T{  FMicrosoft Word Document MSWordDocWord.Document.89q