Java Applications

This is David Schwartz's attempt to give a concise explanation of the command-line enviroment and other related things. The document is based on the handout supplied to David Gries's CS100J students in Spring 2003, Sun's on-line tutorial and downloading instructions, and numerous postings from CS100/CS211 staff. For more information, see Sun's tutorial. Some sections are still under concstruction, given the upcoming changes in Java 1.5.

1. Java Programs
2. Command-Line Environments
3. Command-Line Environments Arguments
4. Development Environments
5. Stand-Alone Java Applications (JAR Files)
6. Javadoc

1. Java Programs

1.1 Applications and Applets

You can write Java programs in two general ways:

Java applet: Program that run a browser. See http://java.sun.com/docs/books/tutorial/applet/index.html.
Java application: Program that runs "on its own" (not from a browser) by executing the main method of a given class. A Java application is typically composed of many classes.

1.2 Main Class

To be an application, one Java class must contain a main method. The main method typically has this header:

public static void main(String[] args)

Every class in Java can have a main method. The user must decide which class to use for a particular application. The class whose main you use to run your program is called the Main Class.

1.3 Files and Classes

This section describes general rules for where you place your code:

All code (except for import statements) must be written inside a class.
One class must be public and contain a main method. The main method header must declare main as public static void:
- public: allow an outside source/user to call the method.
- void: the main method returns nothing.
- static: the outside user/source doesn't create an object of the Main Class. However, the code inside the class can create an object of that class. For example,
```
	  public class Thing {
             public static void main(String[] args) {
	        Thing t = new Thing(); 
                /* code that uses t */ 
             } 
          }
```
Each class should be in a separate file called Classname.java. You can break this rule, but we strongly advise against doing so!
Each file should contain one public class. All other classes should not have public in their headers. You can actually break this rule if you a database-driven IDE, like CodeWarrior, but we strongly advise against doing so!

2. Command-Line Environments

2.1 Operating Systems and Window Environments

The advice herein is really just a snippet of Sun's instructions at http://java.sun.com/docs/books/tutorial/getStarted/cupojava/index.html:

Command windows: Assuming you download a copy of the JDK, you can compile and run your programs from a command window. A command window is special kind of window in which you enter text-based commands to your operating system to perform a variety of tasks. Before we had windowing environments, text-based screens were all we had. Talk to some older computer users, and they will regale you will tales of teletype and punchcards....
Command line: The area in a window in which you type commands. You press Enter or Return after typing your commands.
Command prompt: A special collection of characters that indicate where you should type your command line.

2.1.1 Using Microsoft Windows

Accessing command windows:

From Start menu, select Run. In the window that pops up, enter cmd.
Try also Start→All Programs→Accessories→Command Prompt.
For more information, see Sun's tutorial.

Using MSDOS: for a full set of DOS commands, enter help at the DOS prompt. I've summarized common commands, below:

C:: change to a particular drive.
dir: list files in a directory. Try dir | more to page through long listings.
tree: show directory tree for current directory.
cd: change directories.

For names with spaces, use ~1. For example, to access Program Files on the C drive,
To move up one directory, use cd ...
Desktop: I use cd C:\docume~1\dis\desktop. [to add--Shortcuts?]

type: view contents of a file. For example, type Thing.java.
edit: create/edit/save a text file.
copy: copy a file. For example, copy Thing.java ThingCopy.java.
ren: rename a file. For example, ren ThingOld.java ThingNew.java.
del: delete a file. For example, del Thing.java.

2.1.2 Mac

We need more info here. For now, see Sun's tutorial.

2.1.3 Unix

Unix windows:

All hail Unix!
If you're using Unix, you probably don't need any help :-)
See here just in case.
For information on windowing environments in Unix, see http://www.plig.org/xwinman/.

Unix commands:

http://www.bsd.org/unixcmds.html
See also Introduction to Unix by David I. Schwartz

2.2 Editing Java Programs

Inside a command window, you can enter all of Java command along with operating systems commands, but your system must be set up to know where the commands reside. The primary Java commands that you need (java ,javac) are located in the directory that contains the JDK programs.

2.2.1 ASCII Text

[need to add this section: how to save from Word, Notepad, Wordpad, using DOS's EDIT, using DOS's TYPE command to view text]

2.2.2 Common Editors

Microsoft Windows: If you do not wish to install another text editor, use Notepad or Wordpad, but be sure to save your work in ASCII or UNICODE text format. See also the DOS command edit.
Unix: Use emacs. Enough said. Some people prefer vi. [need to add links]
Mac: I have no idea what you use at this point.

Note that you can use the text editors that are part of most IDEs.

2.2.3 Other Text Editors

You must create a file in ASCII text format. Some commonly used text editors are as follows:

2.3 Compiling and Running Java Programs

There are two directory paths (the list of directories from the top to the current directory) that you need to keep track of:

Java software: Look for a directory name, like j2sdk, jdk, j2se:
- Microsoft Windows: The Java software commands are somewhere in C:\, like C:\j2sdk1.4.2_03\.
- Unix: On my system, /usr/j2se.
- Max: beats me.
Inside the Java directory, there is a subdirectory called bin. Inside of it, you will see programs called javac and java:
- javac: This program compiles your Java programs (.java extensions) into class files .class extensions) that contain Java bytecodes. In Microsoft Windows, this program is called javac.exe.
- java: This program runs your compiled Java classes. In Microsoft Windows, this program is called java.exe.
Java file: You need to pick a specific place to put your Java files. Generally, you should create a new directory each time you want to work on a new program with multiple classes.

2.4 Path and Classpath Variables

To find your Java files, your operating system needs to "know" which Java files to compile and run. For example, if you do not want to bother setting the Microsoft Windows PATH variable, you might have to enter something like the following command-line to compile a Java program called MyProgram:

C:>\j2sdk1.4.2_

yourversion

\bin\javac  
       C:\docume~1\dis\desktop\MyProgram.java

To run a compiled program, you issue this command:

C:>\j2sdk1.4.2_

yourversion

\bin\java  
       C:\docume~1\dis\desktop\MyProgram

.java

.class)

Irritating, isn't it? See below for salvation!

2.4.1 Microsoft Windows

I recommend that you permanently set the PATH variable for all command windows:

Select Start→Control Panel and find System. On my system its under Performance and Maintenance.
Click on the Advanced tab.
Click on the Environment Variables button.
Select PATH in the System Variables portion of the panel.
Click on the Edit button.
Move the end of the PATH value.
Enter a semicolon ; and then the path to your Java software, followed by the word bin.
For example, on my system I have entered the following:
Note the semicolon in front of this path to separate it from the previous individual path in the list.
Click OK. If you are finished, click OK on the Environment Variables and OK on the System Properties window.
To check the current path, enter path at the prompt in a command window.

When you want to run Java commands on specific files, you have the same issue: The operating system needs to know which files you want to act upon. You can either type the path name for each file or use Java's CLASSPATH variable.

Access the Environment Variables panel, just as you did for changing PATH.
See if a variable called CLASSPATH is set in the User variables panel.
Either create or change CLASSPATH to be just . (just one period). The lone period means the current directory. So, when you run the Java compiler (javac.exe) or interpreter (java.exe), Java will use the current directory to compile or run the Java files you specify on the command line.

To temporarily set the path variables, use this: set classpath=. or set class path=%classpath%;. (include the .)

For more information, see Sun's Installation Guide and Additional Help.

2.4.2 Unix

Some minor help:

My alias for javac: /usr/j2se/bin/javac
My alias for java: /usr/j2se/bin/java

See Sun's help for more information.

2.4.3 Mac

need someone to fill this in....

2.5 Compiling A Java Program From The Command-Line

Assuming you have set you system's paths as described in Section 2.4 above, you have very little work to compile a Java program!

Open a command window.
Change directories to the directory that contains the Java files you want to compile:

To compile a single file, enter javac MyProgram.java.
To compile all Java files in the directoy, enter javac *.java.

Assuming you have programmed perfectly, your current directory will now contain .class for all classes in the Java files in that directory.

2.6 Executing A Java Program From The Command-Line

Again, assuming you have set you system's paths as described in Section 2.4 above, you have very little work to run a Java program!

Open a command window.
Change directories to the directory that contains the Java files you want to compile.
Enter java MyProgram, where MyProgram is the name of Main Class:

Recall that the Main Class is the class that with main that you want to run.
Do not enter java MyProgram.java or java MyProgram.class.

3. Command-Line Arguments

3.1 Definition

Command-line arguments are strings that you supply to the main method from the command-line. How does do they work? Since main is a method that you activate at the prompt, you (and the operating system) are effectively another part of a larger program that is calling a particular method. Since all methods can take arguments, why can't main? So, whatever you type after java MyProgram at the command-line is entered in the arguments of main.

3.2 Applications

Command-line arguments have great importatn when you want various applications to "communicate" with each other when developing larger tools. When programming in C and doing Unix development, communicating at the command-line is crucial. Moreover, having the ability to enter data directly into main makes running larger numbers of the same program vastly easier for grading!

3.3 Syntax

Method main expects the user to enter zero to many Strings. Here are some rules:

The name of parameter, which is typically args could be any legal Java name.
When you run a program, the command java and Main Class MyProgram are not included as command-line arguments unlike some other languages.
If you enter no arguments, args is an array of length zero.
If you enter at least one arugment, each argument is read as a Java String and stored in args from left to right, starting at index 0 in the args array.
Special characters, like the double quote (") must be quoted with a backslash (\).

Since command-line arguements are often meant to be values other than strings, you will need to use methods, like Integer.parseInt(String) and Double.parseDouble(String). For example, if the user enters java MyProgram 1 to particular program, inside MyProgram's main method the programmer, could write Integer.parseInt(args[0]) to convert the String "1" to an integer 1.

3.4 Example

Compile the following program:

   public class TestArgs {
      public static void main(String[] args) { // could use any name for args!
         for (int i=0; i < args.length; i++)
            System.out.println(args[i]);
         }
      }
   }

Run the program at the command-line as follows:

java TestArgs: no output.

java TestArgs a 1 outputs a and 1 on new lines.

4. Development Enviroments

This section provides a brief overview of how various IDEs handle Main Classes and command-line arguments.

4.1 CodeWarrior

4.2 Main Class settings

Click on the Targets tab in a CodeWarrior project.
Double on the target Java Application Release, which opens a new window.
Open the Target options in the Java Application Release Settings window.
Select Java Target.
In the Java Target panel, enter your desired class name (the name with the main method that you wish to run!) in Main.

4.3 Command-Line Arguments

Click on the Targets tab in a CodeWarrior project.
Double on the target Java Application Release, which opens a new window.
Select Runtime Settings open from the Target Setting Panels, which are inside Target.
In the Runtime Settings panel, enter your desired strings in Program Arguments.

Other IDEs...

need more input here

5. Stand-Alone Java Applications (JAR Files)

under construction!

Working on converting and cleaning up http://www.cs.cornell.edu/courses/cs212/2003fa/Sam/DOWNLOADS/applications.html.

5.1 Definition and Purpose

5.2 Creating JAR files

5.2 Running JAR files

[ java -jar file-name.jar ]

6. Javadoc

under construction!

Working on converting and cleaning up http://www.cs.cornell.edu/courses/cs212/2003fa/Sam/DOWNLOADS/applications.html. Temporary version: Suppose you write the comment for every public class and method and static or nonstatic field as follows: /** here is the comment */ That is, it begins with "/**". These are "javadoc" comments. Navigate to the directory where your Java program is and type this: mkdir doc javadoc -d doc *java

6. User I/O and File

under construction!

[to add: Windows vs Unix: use System.getProperty("line.separator") (\n\r or ....)]