Title Slid

1
Title Slid
CSC 444
Java Programming Utilities
By Ralph B. Bisland, Jr.
2
The Java Compiler Options
orca javac Usage pc options files where
options include -classpath pathname use
given classpath -d filename
redirect classfile output -experimental
enable experimental features -g
include debug
information -java
accept only standard Java input -nowarn
suppress warning messages
-pizza accept
standard Pizza input -printsearch
print information where classfiles are
searched
-prompt stop after each
error
3
Java Compiler Options (ctd)
-s emit java sources
instead of classfiles -scramble
scramble private identifiers in bytecode
-scrambleall scramble package visible
identifiers in bytecode -switchcheck warn
about fall-through in switches -verbose
print detailed log -version
version information -pizzadoc run
pizzadoc
4
What Is Pizza?

• A small, fast and free compiler for an important
  superset of the Java Programming Language.
• Extensions to Java
• Parametric polymorphism
• First-class functions
• Class cases and pattern matching
• Web site for more information www.cis.unisa.au
  /pizza

5
JAR Files

• Java Archives.
• Similar to the UNIX utility tar (tape archive).
• Allows you to package up (archive) several
  class files and compress them for easy
  transportation to other systems.
• The JAR specification corresponds to the
  well-known ZIP format used on PCs.
• The jar utility is part of the JDK.

6
The jar Utility

• jar ltoption-stringgt JARfile manifest-file
• input-files
• Option-string Required string that tells the
• jar utility what to do - more on this later.
• JARfile Optional name of the archive file
• that is the destination for the input files
• when the new archive is to be created. It can
• also be the name of an existing archive from
• Which the contents are to be listed or
• extracted.

7
The jar Utility (ctd)

• Manifest-file Optional, specifies the file that
  describes the contents of an archive with its
  authentication information. If this file is not
  specified, jar will create one automatically from
  other command line information.
• Input-files The names of the files that are
  input to create a new archive, or extend an
  existing archive. This can include the wildcard

8
jar Utility Options

• c Creates a new JAR file. The input files from
  the input-files argument are used to create the
  archive.
• x Extracts files from an existing archive.
• t Lists the contents of the specified JAR.
• f Specifies that the JAR file to be processed is
  specified as the second command line argument.

9
jar Utility Options (ctd)

• v Verbose output from the utility. Includes
  additional information such as file sizes and
  timestamps. This is a helpful option.
• 0 (zero) Does not compress the files when
  archiving them. Only use this when you are
  placing a signature on in an archive file.

10
jar Utility Options (ctd)

• m The name of the manifest file is the next
  parameter after the JAR file. A manifest file
  describes the contents of a JAR and its
  authentication information. If you do not specify
  this option, the utility creates the manifest
  file anyway. Generally this option is not used.
• M o not include the manifest file in the
  archive. Generally this option is not used.

11
Creating A JAR

• Works best if you place all of the files to be
  included in the archive in a separate
  subdirectory.Easier to use wildcards.
• Can include both .java and .class files if you
  wish.
• Execute the jar utility with the needed options
  and input file names.

12
Creating A JAR (ctd)

• Since there are multiple copies of the JDK on
  orca, you must make sure that you search the
  proper directory for the proper version of the
  jar utility first.
• The proper directory is /usr/local/java/bin
• To do this you must reset your PATH
  variable export PATH/usr/local/java/bin
  PATH

13
Using The jar Utility
orca cat JarTest.java class JarTest public
static void main (String args)
System.out.println ("Hello there, I'm Jar-Jar
Binx") orca javac JarTest.java orca
java JarTest Hello there, I'm Jar-Jar Binx orca
ls -l total 2 -rw------- 1 bisland faculty
433 Mar 23 1946 JarTest.class -rw------- 1
bisland faculty 134 Mar 23 1945
JarTest.java
14
Using The jar Utility (ctd)
orca export PATH/usr/local/java/binPATH orca
jar cfv Jarjar.jar JarTest.java adding
JarTest.java (in134) (out118) (deflated
11) orca ls -l total 3 -rw------- 1 bisland
faculty 433 Mar 23 1946 JarTest.class -rw--
----- 1 bisland faculty 134 Mar 23 1945
JarTest.java -rw------- 1 bisland faculty
528 Mar 23 1951 Jarjar.jar orca This command
creates a JAR file called JarJar.jar which is
comprised of the compressed file called
JarTest.java
15
Using Wildcards
orca jar cvf jarclass.jar .class adding
JarTest.class (in433) (out295) (deflated
31) orca ls -l total 4 -rw------- 1 bisland
faculty 433 Mar 23 1946 JarTest.class -rw--
----- 1 bisland faculty 134 Mar 23 1945
JarTest.java -rw------- 1 bisland faculty
528 Mar 23 1951 Jarjar.jar -rw------- 1
bisland faculty 708 Mar 23 2108
jarclass.jar This command recurses through all
subdirectories below the current directory to
find all the .class files.
16
Including Only Files From A Directory
orca jar cvf jarclassonly.jar JARTest
.class JARTest no such file or
directory adding JarTest.class (in433)
(out295) (deflated 31) orca ls -l total
5 -rw------- 1 bisland faculty 433 Mar
23 1946 JarTest.class -rw------- 1 bisland
faculty 134 Mar 23 1945 JarTest.java -rw---
---- 1 bisland faculty 528 Mar 23 1951
Jarjar.jar -rw------- 1 bisland faculty
708 Mar 23 2108 jarclass.jar -rw------- 1
bisland faculty 708 Mar 23 2117
jarclassonly.jar orca This includes only the
.class files in the JARTest subdirectory
17
Listing The Contents Of An Archive
orca jar tf Jarjar.jar META-INF/MANIFEST.MF JarTe
st.java orca jar tvf Jarjar.jar 156 Thu Mar
23 195128 CST 2000 META-INF/MANIFEST.MF 134
Thu Mar 23 194536 CST 2000 JarTest.java orca
18
Extracting The Contents Of An Archive
orca jar xvf Jarjar.jar extracted
META-INF/MANIFEST.MF extracted
JarTest.java orca ls -l total 6 -rw------- 1
bisland faculty 480 Mar 23 2122
JarTest.class -rw------- 1 bisland faculty
134 Mar 23 2130 JarTest.java -rw------- 1
bisland faculty 528 Mar 23 1951
Jarjar.jar drwx------ 2 bisland faculty
1024 Mar 23 2130 META-INF/ -rw------- 1
bisland faculty 708 Mar 23 2108
jarclass.jar -rw------- 1 bisland faculty
708 Mar 23 2117 jarclassonly.jar
19
The MANIFEST FILE
orca cd META-INF orca ls -l total 1 -rw-------
1 bisland faculty 156 Mar 23 2130
MANIFEST.MF orca cat MANIFEST.MF Manifest-Version
1.0 Name JarTest.java Digest-Algorithms SHA
MD5 SHA-Digest FiDf4aEtdLOQUaG7vjf1ES0cqNU MD5-D
igest xfRh2N91kg7HSS6ln19jgQ
20
More On The Jar Utility
The jar utility is particularly effective when
creating applets. More on this when we get to
applets.
21
The javadoc Utility

• Part of the Sun standard JDK.
• Complete documentation on the javadoc utility can
  be found at java.sun.com/products/jdk/javadoc
• Javadoc allows the user to insert documentation
  comments into Java source code.
• When processed by javadoc, the comments become an
  html file which can be viewed by any browser.

22
Using javadoc

• To use the javadoc utility use the following
  call javadoc options
  files javadoc options packages
• Caution This utility will produce an index.html
  file each time it is run.

23
Javadoc Options
orca javadoc Usage pc -pizzadoc options
files where pizzadoc options include
-public Shows only public classes
and members. -protected Shows public
and protected classes and members.
default -package
Shows all members that are visible within the
package.
-private Shows all classes and
members. -author Include _at_author
tags, which are omitted by
default. -sourceversion Include
_at_version tags, which are omitted by
default. -since
Include _at_since tags, which are omitted by
default.
24
Javadoc Options (ctd)
-nosourcename Don't include source filenames
in the pages. -nointerface Don't
generate pure class interface pages. -newindex
Generate new index files instead of
updating the
old. -tree Generate class
hierarchy page. -notree Don't
generate class hierarchy page. default -index
Generate index page.
-noindex Don't generate index page.
default -linktrans Transform
links with prefixes read from
.pizzadoc or use standard
transformation.
default -nolinktrans Don't transform
links. -nodeprecated Exclude _at_deprecated
paragraphs. -excludedeprecated Exclude classes
or members which are
marked as deprecated.
25
Javadoc Options (ctd)
where standard options include -d filename
redirect doc pages output
-classpath pathname use given classpath
-verbose print detailed
log orca
26
Source File Parameters

• Comments / multi-line comment /
• _at_author Used to define the author of the code.
• _at_deprecated Used to document library classes and
  methods that have been superseded and generally
  should not be used in new applications.
• _at_exception or _at_throws Used to document that the
  code can throw and the circumstances which can
  cause an exception.

27
Source File Parameters (ctd)

• _at_link Generates a link to another part of the
  documentation within the documentation that is
  produced.
• _at_parm Used to describe the parameters for a
  method.
• _at_return Used to document the value returned from
  a method.
• _at_see Used to specify cross references to some
  other part of the code such as anoter class or
  method. It can also reference a URL.

28
Source File Parameters (ctd)

• _at_version Used to allow you to specify your
  version of the source code.

29
Other Notes On The javadoc Utility

• You can use any HTML tag in the documentation
  (except for the header tag) to assist javadoc in
  formatting the web page.
• Java documentation comments are usually placed
  before classes, methods, interfaces,
  constructors, and fields.

30
Partial Example
/ A class representing an improved Date.
For example ltpregt MyDate today
new MyDate() lt/pregt _at_author Ralph B.
bisland, Jr. _at_version 3.04 _at_see
util.date / Class myDate extends Date //
MyDate class stuff
31
A Bigger Example
orca cat JDT.java / A class to test out
the javadoc utility. It is a really
complicated program. For example ltpregt
It displays two
strings lt/pregt _at_author Werner von Braun,
Rocket Scientist _at_version 3.04 _at_see
util.date /
32
A Bigger Example (ctd)
class JDT / Method Dump It _at_parm s -
the stringof what is to be displayed
_at_return Nothing, this is void method /
public static void DumpIt (String s)
System.out.println (s)
33
A Bigger Example (ctd)
/ Method Main - La grande fromage /
public static void main (String args)
DumpIt ("This is a test") DumpIt ("This
is not") orca javac JDT.java orca
java JDT This is a test This is not orca
34
A Bigger Example (ctd)
orca ls -l total 2 -rw------- 1 bisland
faculty 498 Mar 26 2007 JDT.class -rw------
- 1 bisland faculty 642 Mar 26 2011
JDT.java orca javadoc - package - author
-sourceversion JDT.java generating
JDT.html generating JDT.interface.html generati
ng NN.html generating index.html orca ls
-l total 4 -rw------- 1 bisland faculty
498 Mar 26 2007 JDT.class -rw------- 1 bisland
faculty 642 Mar 26 2011
JDT.java -rw------- 1 bisland faculty
679 Mar 26 2012 NN.html -rw------- 1 bisland
faculty 815 Mar 26 2012 index.html