Return to index
Compiling, Building and Running
Compiling Source Files
Compiling is the process of translating the high-level (natural language-like) instructions of Java source files into a form much closer to the type of low-level instruction (machine code) that the microprocessor inside the computer can use.
In the case of the Java language, there is an extra translation step taken at run-time - interpring the intermediate 'byte code' to actual machine instructions. This step exists in Java to allow the same source code, via the same intermediate 'byte code', to run on different hardware platforms. That is, the 'byte code' can be seen as the language of the 'Java Virtual Machine'.
In TJI, when you select 'Compile', an intelligent build is performed, in which all, and only, those files that need to be recompiled will be. It is a fast process that usually takes just a few seconds, or less. 'Build' guarantees that all the source files will be recompiled where necessary.
The compiler works with the source file on the disk. Therefore, to compile just-edited source code, a save to disk is required. This can be done automatically, as required, which allows you to both save and compile (or even save, compile and run) with one button click or menu select.
If the class or inner classes defined in the current source file use other classes in different source files, these will usually be re-compiled as necessary - whether or not they are currently loaded (see 'Viewing compile-time errors'). The SDK's javac - which performs the compilation - will decide which files to recompile in this case. Classes that are called/used by the class being compiled will be recompiled as necessary, but classes that are referred to but not directly called will not. The latter case typically includes renderers, for example, that are called by the repainting thread.
In the 'Files' tab, Java source files which are more recent than the corresponding class files (and thus will need to be recompiled) are indicated by a small green 'compile' icon appearing in the top left of the file's icon. This visual indication allows you to be sure which files have been recompiled.
TJI uses the standard javac compiler that comes as part of the SDK, with the default options. So you can be sure that you are producing standard Java byte code.
The Classpath
TJI takes care of the classpath automatically in the majority of situations, effectively adding the path to the project files, minus the package part (i.e. the project's 'base directory'), to those within the CLASSPATH environment variable (which primarily stores the location of the SDK class libraries). Hence, even when the source files are in a path that does not include the 'projects' directory, the classpath will still be handled automatically.
However, at some time you may need to consider the following points.
To add third party packages/classes, or if you have developed your own class libraries, go to the 'Project' menu and choose 'Set Project Classpath'. This enables you to add one or more jars or directory locations for additional classes/packages specific to the current project; these are stored in the project description file and thus are remembered when the project is closed and later reopened. You can also edit or remove any existing classpath entries.
If the classes to use exist as separate class files within a directory structure, give the path to the base directory (minus package part); for example, if the classes are part of a package called org.acme.utilities and one class (TU, say) within the subpackage text has the full path
c:/utils/org/acme/utilities/text/TU.class
then the base directory will be :
c:/utils
If the classes to use exist within a jar or zip file, give the full path to the jar/zip file and include the jar/zip file itself; for example :
c:/utils/utilities.jar
The dialog that allows you to add classpaths optionally lets you browse for either a base directory or jar/zip file using the IDE's File Browser.
Alternatively, you can add the path to these classes/jars to the system CLASSPATH, although you do not need to do this. This can be useful for making certain third-party (or your own) packages available to all projects, without you needing to add these packages to the classpath for each project.
For Windows 95 and 98, this is defined within the autoexec.bat file; there will be a line starting CLASSPATH=. Paths on Windows are separated by ';'s. %CLASSPATH% means the existing classpath; this term is used when the classpath is extended on a different line of the autoexec.bat file or another .bat file. Autoexec.bat can be viewed or edited with the Windows Wordpad accessory.
With Windows NT, use the 'System' option within the Control Panel to add paths.
For other operating systems, consult your OS or the SDK documentation. Note that the path separator is likely to be different.
In the case of packages, give the path to the 'base directory'. For example, a file called MyStringUtils.java which has a declared package name of projects.utils will need to be stored in a directory such that the last part of the path is projects/utils. If the full path for that file is C:/java/projects/utils/MyStringUtils.java then the base directory will be C:/java (on Windows, C:/ is the 'root' of the path; on UNIX the root is usually just /). If you wish to add classes contained in a 'jar' file, give the full path, including the jar file name.
Jars designed to work under the Java Extension Framework can be placed in the jre/lib/ext directory of your SDK installation where they will be found automatically.
Don't forget that you will also need to declare those classes that you intend to use that are part of other packages. You do this by using 'import' statements in the relevant source files.
For example :
import org.acme.utilities.*;
import org.acme.utilities.text.UT;
The '*' at the end of the first statement declares that any number of classes in that package may be used.
Import statements basically tell the compiler where to look for classes that are mentioned in the source file.
Building an Application / Applet
The 'Compile' command ('Compile' menu) will compile the current (selected) source file and any others containing classes used (called) by the selected class. Thus, when the current source file is the 'main' source file (where operation begins), the complete application will be recompiled, on an 'as necessary' basis. Hence, choosing 'Compile Main' is equivalent to having the 'main' class open and selecting 'Compile'. By 'main' is meant the class which will be used to start the application or applet; this class will include a public static void main(String[] args) method (applications) or init() method (applets).
Only those source files which are more recent than their class file equivalents will be recompiled (these are the only ones which need to be - and this reduces the period of time taken during the compilation process).
'Build' checks every source file in the base directory, compiling each one as necessary. The compiler also makes sure that they are consistent. For example, that a method called in another class does exist.
Finally, consider the case that you have a class in the project which is not yet used. Because it is not yet used, it does not need to be compiled - but when you select 'run' the IDE will detect that this project class is uncompiled and initiate a project build. Thereafter, choosing 'run' will not initiate a build or compile first unless one of the source files is subsequently changed - the project will simply run!
Compile-Time Errors
In the case that there are compile-time errors, the 'Errors' tab will be selected automatically and the first 10 errors listed, arranged by source file. The first error will be indicated by the particular editor tab being selected and the caret moved to that line. A red wavy underline will show the location within that line of the error.
Compile-time errors are indicated on the editor tabs, in each editor line number bar, in the method list for the current editor, and also the 'whole file view' bar adjacent to the vertical scroll bar (this is clickable). The details of each error can be seen by hovering the mouse cursor over the error icon on the line numbers bar.
Compile-time errors are discovered by the compiler based on what is legal syntax and structure for a Java program, and that all methods and fields exist. Sometimes this means that a mistake in the source code creates an error that is further on in the source code than the actual mistake. The compiler can only detect at what point the source code becomes illegal. This means that a compile-time error may be caused by a mistake earlier in a statement than indicated, or on a previous line of a method, or even in a called method. However, it is usually straightforward to determine the problem by looking at the errors produced.
In the case that there is a compile-time error in another source file (that is, in a used class), the editor tab containing that file will be selected and the error highlighted within it.
If the source file which contains an error is not already open (loaded into an editor), it will be opened automatically and then the error highlighted within it.
Do not take the error descriptions too literally, especially those that state 'X expected'. Be logical and consider what might cause the compiler to complain about the apparent problem. The underlying problem often lies in lines prior to the supposed error location, and can be located elsewhere.
If a large number of disparate errors appear unexpectedly, the problem might be a missing or misplaced parenthesis - ')' or '}' - although TJI does check for {} balance before compiling. Often simple typos are to blame, or variables are referred to but not declared or referenced out of scope, etc.
Running Your Application or Applet
When you select the 'Run' option, whether from the 'Run' menu or the 'Run' button on the tool bar (or, indeed, 'Debug'), TJI will first save any open source files which have been changed (prompting first if this option is enabled - see the 'Options' menu), compiles the application as described above (if it has not already done so), and then, if there are no compile-time errors, runs the application / applet.
Applets
Applets are run in the AppletViewer. Run-time exceptions are caught by TJI and you will be taken straight to the offending line in the source code, with a message detailing the exception.
The main class file to use and the desired dimensions are taken from the applet's associated HTML page. Use the 'HTML' button on the 'Files' tab to specify the HTML file that refers to the applet; the file name will change to red. To change this, select a different file.
If no HTML file exists in the project for starting an applet, TJI will create one when you run the applet. If the applet's main class is named 'Abc' (Abc.java), then the created HTML file will be named 'Abc_run.html'.
It is possible for an applet to specify its size in the source code, thereby overriding any size specified in the HTML file.
Deploying an applet
When you are ready to deploy an applet, the best approach is to create a jar file to contain all the class files and any resource files (such as images). This is easy to do in TJI - simply choose the 'Jar Project' option from the 'Project' menu. Then modify your HTML file to specify your jar file archive as detailed shortly. You can then test your applet in an external browser such as Internet Explorer - open the HTML file and the browser will read your applet tag and load the applet from the jar file.
If no package is involved, the following applet tag is an example of how to include an applet in an HTML web page:
<applet code="MyMainClass.class" archive="myapplet.jar"
width='400' height='200' />
The 'archive' attribute specifies that the classes are to be found within an archive (i.e. a jar or zip file).
If the applet's code sets its size (perhaps a default size), then the size need not be specified in the HTML applet tag. Also, note that with most browsers, the '.class' is not required.
<applet code="MyMainClass" archive="myapplet.jar" />
In the case of an applet involving a package - for example, projects.myapplet - specify the fully qualified class name in the 'code' attribute of the applet tag. For example:
<applet code="projects.myapplet.MyMainClass"
archive="myapplet.jar" />
Our tests show that this does not not work in all browsers, but the following does, so is used by TJI when creating HTML pages:
<applet code="projects/myapplet/MyMainClass"
archive="myapplet.jar" />
If you simply provide classes on your website that are not contained within a jar, the archive attribute should be omitted.
So the applet tag for an applet with no package would be:
<applet code="MyMainClass" />
For an applet with a package, the applet tag would be written this way:
<applet code="projects/myapplet/MyMainClass" />
When classes are not within a jar, they must be placed in a subdirectory structure (relative to the HTML file) to match the package. In the case of the classes being within a jar file, the jar file would normally be placed in the same directory as the HTML file.
A 'codebase' attribute can be included to tell the browser that the jar archive, or class files, are to be found at a base directory (minus the package defined sub-directories) that is different from the location of the HTML file. However, in most cases this is not required.
Applications (GUI or Console type)
You will first need to have specified the 'main' file by using the 'Main' button on the 'Files' tab; first, select the appropriate Java source file from the list, then press the 'Main' button; the file name will change to red. To change this, repeat on a different file.
Thus, you can have more than one class within your project that can start your application (if they each have a public static main(String[] args) method. This can be useful for starting an application in different ways. It is also useful for unit testing particular classes.
TJI continues to run while your program runs, so it is possible to switch back and forth to make changes in the source files based on what you notice while the program is running, ready for the next recompilation. You may need to use your operating system's task manager to switch between TJI and your application if one frame becomes hidden behind another.
Servlets
A servlet project will run by default in TJI's Web Browser (the 'Web' tab), which will be opened automatically if not already open and selected automatically. You can also open a web browser outside of the IDE (such as Netscape or Internet Explorer) and run the servlet project there (though in this case run-time exceptions will not be caught by the IDE to provide detailed exception information).
To invoke your servlet(s), you can either type in the name of an HTML page that calls one of your servlets; for example:
http://localhost:8080/runServlet.html
Or type in the address of the servlet directly; for example:
http://localhost:8080/MyServlet
Or simply select a file to act as the 'main' (Java file) or 'html' (HTML file) starting file - in this case, simply selecting 'Run' will automatically start TJI's Web Browser with that page.
HTML files should be stored at
<homePath>/web/<project_name>
and Java servlet files at
<homePath>/web/<project_name>/WEB-INF/classes
where homePath is the location of ide.jar.
New skeleton projects and imported projects will place files in these locations automatically.
If using a different userHome, substitute userHome for homePath above.
If a servlet class is part of a package, org.acme.servlets say, then the location of the Java servlet would be <homePath>/web/<project_name>/WEB-INF/classes/org/acme/servlets
See the 'Servlets' section of this guide for more information on writing and running servlets.
JSP Projects
A JSP project will run by default in TJI's Web Browser (the 'Web' tab), which will be opened automatically if not already open and selected automatically.
You can also open a web browser outside of the IDE (such as Netscape or Internet Explorer) and run the JSP project there (though in this case run-time exceptions will not be caught by the IDE to provide detailed exception information).
JSP files are stored in the same location as HTML and image files - that is, in
<homePath>/web/<project_name>
and java files (such as Java Beans) in
<homePath>/web/<project_name>/WEB-INF/classes
This follows the standard convention as used, for example, by the TomCat web server.
Tag Handler project files are stored in the common directory
<homePath>/web/taghandlers
such that the tag handler for c:out for example will be stored at
<homePath>/web/taghandlers/c/Out.java
This is a TJI-specific convention.
To invoke a typical JSP page, the address would be, for example
http://localhost:8080/myJspPage.jsp
Or simply select a JSP file as the 'main' starting file - or an HTML file as the 'html' starting page. Once you have done this, simply selecting 'Run' will automatically start TJI's Web Browser with that page.
See the 'JSP' section of this guide for more information on writing and running JSP projects.
If a run-time exception occurrs
which is uncaught by your program, TJI will catch it in the majority of cases. Your program will then be closed and the exact location in the source files of the line which gave rise to the exception will be shown, together with a detailed description of the exception in the message area.
If your program 'freezes' (stops responding)
use whatever task manager is available on your operating system to select and close your program. For example, on Windows 95 and 98 the current tasks can be seen by pressing Ctrl-Alt-Del once. The task you need to end may be listed simply as 'Title' (or whatever your frame title is set to, in the case of a GUI application); do not close the task called 'The Java IDE' (or the OS console used to start the IDE).
If you find that you cannot seem to restart your program
the likely reason is that when your application frame is closed it simply hides but is not disposed (fully ended) - that is, the last run program is still running. If this is the case, you may need to close it by using your operating system's task manager. However, clicking the 'Stop' button on TJI's 'In/Out' or 'Out' console will usually do the trick.
To avoid this problem, code in a DISPOSE_ON_CLOSE:
myJFrame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE)
or add a WindowListener to your application's main frame (as TJI's application framework builder does automatically).
The IDE will run the 'main' or 'html' file if one is set; otherwise a warning is given. The 'main' file is the specified one containing a class which has a public static void main(String[] args) method that starts your application by creating an instance of the main class. In the case of an applet, it is the file containing the class which has the init() method, or an HTML file that refers to the applet using the <applet ...> tag.
More than one class within a project can have a static void main(String[] args) method - indeed every class can have one! This can be very useful for 'unit testing'. Such a unit test will exercise the class in some way to verify that it works correctly. Simply change the 'Main' file from the Java file list in the Files tab by selecting the desired file and then clicking on the 'Main' button. In this way, you can quickly change which class's main method is invoked when you run the project.
Debugging
A very useful way to debug your programs is with the use of
System.out.prinln("x : "+x)
statements at strategic points which tell you the value of x at that point in the running of the program. To this end, a 'System Out' frame is provided during an application run. This frame is movable; however, if your program is full screen size, you can use your operating system's task manager (Alt-Tab on Windows) to switch focus to the System Out frame (listed as 'TJI Java IDE') which brings it to the front (top).
Refer to the 'Tracing, Profiling and Debugging' section of this guide to find out how to use TJI's integrated debugger with breakpoints.
Console Applications
The running of non-graphical, non-applet programs (sometimes called 'console applications') is supported by a 'System In / Out' frame which works rather like an OS console window. User input is typed into the text field at the bottom and entered by pressing the adjacent button or the 'Enter' key; this allows you to edit an input line before it is entered. Hence, if your program waits for a keypress at some point, you will need to use the 'Enter' button or key for this.
Console programs rely on System In and Out for user interaction, employing no graphical components (AWT or Swing). An example is the classic 'Hello World' program. An example console program could be a version of HelloWorld which asks for the user's name and responds with 'Hello Fred', or whoever. Clearly, console applications are of limited value; the event-driven nature of GUI applications is much more suited to an Object Oriented language like Java - and far more user-friendly.
However, an example Console Application that demonstrates reasonably good Object Oriented design is available from the 'Resources' page of our website : BlackJack.