(Last updated March 9, 2000)
Copyright (c) 1999..2000 by Charlie Calvert
You will create two applets in this chapter. If you are on the web, you can click the links below to see the applets:
Download the source.
This chapter is designed to show a very simply way to deploy Applets on the web. You will see how to take the programs we created in the last two chapters and make them readily available on a web server.
I'm going to cover two ways to deploy applications:
One technique involves copying your files to a new directory and not deal with the Java packages mechanism.
A second technique shows how to copy your files to a new directory and deal with the Java packages mechanism.
At, or near, the top of each of the programs you have created so far there is a package statement. It usually reads something like "package Adder," or "package untitled1." Overall, packages are good. But the first few times you deploy applets, you are probably better off without using packages. As a result, I'm going to ask you to put together a quick little applet that does not use packages. Later in the chapter I will revisit the issue, and describe how to use packages.
Your first impulse might be to go back to your previous projects and just remove the package statement from the top of the file. That's an interesting idea, but it does not work very well in the JBuilder IDE. JBuilder will become confused about the location of your source files if you remove the package name without also moving the file. At first it seems a bit annoying that JBuilder doesn't handle this better. However, after I get a chance to explain packages in more depth, you'll see that it's really a good thing. It means that the JBuilder IDE is aware of your packages and knows how to deal with them. For now, however, I don't want to worry any further about trying to convert old projects to this different way of thinking, nor do I want to talk any more about packages. Instead, I'm going to ask you to first create a new applet that has no packages in it.
Its time now to get started. The next few paragraphs describe how to put together a tiny applet that does not use packages.
To get started, go into JBuilder and close any projects that happen to be open. Choose File | New | Applet from the menus. Set the directory and name for your project as follows, making allowances for the directory hierarchy on your system:
/home/ccalvert/jbprojects/nopackage/nopackage.jpr
Accept the defaults for the rest of the two pages of the Project Wizard. After you press the Finish button, the Project Wizard closes and the Applet Wizard opens.
On the first page of the Applet Wizard (the third page you have been through if you count the Project and Applet Wizard as one wizard), set your Base class to java.awt.Applet. Set the Package statement to a blank string. This is the key move, the one that allows you to build an applet that has no packages. Now select Generate Headers and Generate Standard Methods. Feel free to step through the next two pages of the wizard, but there is no need to make any changes to them. Click Finish to create your application.
After completing the wizards, you are returned to the IDE. Go into design mode, and click on the main form. In the inspector, which appears on the right side of the IDE layout field to null. Turn to the AWT page in the Component Palette, and drop down a couple buttons and a TextField on your applet. The TextField is the furthest control on the right on the AWT page for the component pallete.
Select the first button, and use the inspector to change its name to leftButton and its label to "Left Button." Select the second button, and use the inspector to change its name to rightButton and its label to "Right Button." Look down at Figure 1 now. It shows what your applet looks like at design time.
Figure 1: Designing the look of your applet. Note that the form is selected in the structure pane, and that the layout is set to null in the inspector. (Screenshot made in Windows)
When you are trying to line up your buttons, you need to perform a little dance with the mouse. First select the leftButton object. Now hold down the shift key and select the rightButton object. You can select the objects either on the form itself, or in the structure pane. When you are done, both buttons ought to be selected, as shown in Figure 2. Make sure that those two buttons, and only those two buttons, are selected. Now right click on one of the buttons and choose Align Top. Continue in this way until you have aligned the controls in a manner you see fit.
Figure 2: Selecting two controls at the same time. Look in the structure pane, notice that leftButton and rightButton are both selected. The gray "handles" on the form give you the same message.
Double click on each button to create two events. Fill in the events as follows:
void leftButton_actionPerformed(ActionEvent e)
{
textField1.setText("You clicked the Left Button");
}
void rightButton_actionPerformed(ActionEvent e)
{
textField1.setText("You clicked the Right Button");
}
Go ahead and run the applet once from inside the IDE. After you press the green run button, you will get prompted to define the main class. Turn to the applet page, and press the set button. A dialog will pop up called "Select Main Class for Project." You should choose Applet1, as shown in Figure 3. Click on the Ok button. The Project Properties dialog should now look as it does in Figure 4. Notice that this time the main class is not shown to be part of any package. (You can access the Project Properties dialog at any time by selecting Project | Project Properties from the JBuilder menu.)
Figure 3: Selecting the main class for your applet.
Figure 4: The Project Properties dialog with the Main class set to Applet One.
When you run the applet, you will find that you can press the buttons and change the text in the edit control. I'll confess that this is not a very exciting application, but it is distinctive looking, and serves as a reminder as to how to perform basic actions when creating an applet in the JBuilder Foundation IDE.
If you had trouble creating this simple applet, you can go back and review the material in earlier chapters. Most of the questions you might have should be answered in those pages.
At this stage you are ready to deploy the applet. Because we did not include any packages in the project, you will find that this step is relatively easy.
To deploy the applet, you need just two things:
In this particular project, there are going to be three class files that you need to copy. One is Applet1.class, and the other two are for the event handlers that you created. The name of the event handler classes will differ depending on whether you used anonymous adaptors or standard adaptors. In the first case, the class files will be called Applet1$1.class and Applet1$2.class. In the second case they will be called: Applet1_button1_actionAdapter.class and Applet1_button2_actionAdapter.class. Regardless of their names, you need to gather them all together, along with Applet1.html and Applet1.class, and copy them to the root of your /home/httpd/html directory.
NOTE: The /home/httpd/html directory is the default location for HTML files on the Linux Apache server. If you are using some other Linux server, then you may have to browse to another directory. On my system, I was not signed on as root, so I had to su to the Super User role in order to add files to /home/httpd/html directory. If you are on Windows, then you might well be running the Internet Information Server or the Personal Web Server. With both of those products, you will probably want to copy your files to the c:\Inetpub\wwwroot directory. Of course, you may have set up IIS or PWS to use another directory, but the one I show here is the default. If you are using some other type of web server, then you will have to consult it's documentation to find the default area to download files. (The Apache web server comes with most distributions of Linux, including Red Hat. If you use Windows 98, you will find that PWS is usually located in a directory of that name on the Win98 CD. It is also usually available as a download from www.microsoft.com.)
If the method above does not work for you, copy the class and the html files to any directory of your choosing, such as c:\temp or /tmp, and use a FILE: url in your browser to launch it. When usingIE, instead of HTTP://localhost/untitled2.html, use FILE://c/temp/untitled2.html or on Linux, use file:/home/joi/java/untitled2.html. This doesn't require the use of a server at all.
Many admins install browsers with java and javascript disabled. You should ensure java is enabled in your browser before launching the applet. If your admin is so paranoid he or she has disabled java support irrevocably, you can fall back to the JDK's appletviewer from a command line.
At this stage, you have all the class files and the Applet1.html file copied out to the root directory for HTML files on your web server. Open up a browser, and browse to your server. Open up Applet1.html, as shown in Figure 5, and you should see your applet running on the web.
Figure 5: An applet deployed on the web in a netscape browser on a Linux box.
In Figure 5, I am signed on to the server called "localhost," which is one way to reference a server on the machine you are currently using. In Figure 6, you can see the same applet, this time from Windows, and this time signed on to a Linux server on a remote machine. Note that in this second example, I have copied the files I created to a directory called called /Java/ThreeButtonTest. Because I was not using packages, I did not need to make any changes to my HTML or class files when moving them to a new directory.
Figure 6: Running on Windows, looking at our simple applet running on remote Linux machine.
NOTE: Its perhaps worth mentioning that I actually built the application shown in Figure 2 on a Windows machine. Figure 1 shows the same applet, but constructed and compiled on a Linux machine. The interesting thing about Figure 2 is that I took my files from the Windows machine, FTP them to a remote Linux machine, and they ran unchanged. This is the great thing about Java: the class files you create will run anywhere!
For now, that is really all you have to know about distributing files on the web. However, I'm going to add some additional information that will help with more advanced causes.
If you want to see this applet running on the world wide web, go to the following site: http://homepages.borland.com/ccalvert/JavaCourse/Applets/Chap04/Applet1.html.
I should perhaps take a moment to answer a question which which might be on some reader's minds. The question, of course, is what is a "class file?"
As you probably know, JBuilder is a compiler. Compilers take source files and convert them into binary files that can be executed. A source file consists of a series of syntactical statements and commands that are typed into an editor. The compiler processes these commands and produces a binary file that the computer can run.
NOTE: Java creates compiled files with .class extension. But the compiled files that you create in JBuilder are usually run inside a VM, or virtual machine. This is how Java allows you to run one set of code that can work on multiple platforms. Your code is not being run directly by the operating system, instead, it is being run by the Virtual Machine, which in turn translates your code into something that can be run on the particular platform you are using. One major variation on this occurs when you run Java on a machine that has a Java chip on it. In that case, there is no need for the virtual machine, and the code is run natively on the chip.
Consider the following bit of source code:
Button MyButton = new Button();
This line of code creates a button. Never mind how it creates the button. All you need to know is that it is the command that you write in Java when you want to create a button.
You type your command into a text file, and then the compiler comes along, reads your text file, and converts what you have created into instructions that the computer can understand -- or rather, instructions that the virtual machine can understand. In short, the compiler translates your code into a portion of a computer program.
The source files that we create in JBuilder will have a .java extension. The compiled versions of our source files have a .class extension. The .java file is a text file readable by humans, the .class file is readable by the computer. In the programs we've created so far, the source file is called Applet1.java, and the class file is called Applet1.class.
If you want, you can set the directory where JBuilder is going to store your .class files for this project. These .class files are going to be needed by the computer when you show your applet in a browser. By default, JBuilder does not put your .class files in the same place where it puts your source files. You can change this, however, if you want.
To set the location where your .class files will be placed choose Project | Project Properties from the JBuilder menu. On the Paths page of the Project Properties dialog, choose the Set button that is next to the Output Path control. It pops up a Select Path dialog. In the dialog you will see the name of the directory you created for you project. In the first program you created, it is called MyFirstApplet. Beneath the MyFirstApplet directory are two more directories. One is called classes, and the other is called src. One directory is where JBuilder will, by default, place your .class files, and the second is where JBuilder will, by default, place your .java files. You can changethe default output for .class files from the classes directory to the src directory. To do this, just click once on the src directory, and then click the okay button.
There! Now you are done. Choose File | Save All from the menu. This makes sure all your work is saved. You should always do this before compiling and running your programs. Now click the green button at the top of the JBuilder IDE. This will run your program.
Packages are one of the most important topics for beginners to master when they are using JBuilder. When you are using the JBuilder IDE, you generally include a package statement at the top of your files or the project won't compile correctly.
You can think of a package as a directory. If you put the words package untitled1 at the top of your source files, then the Java Virtual Machine (VM) is going to expect to find your .class files in a directory called untitled1. Don't try to fight this system, that's the way it works. When you are finished building your project, and want to deploy it on the web, copy the class files into a directory with the same name as you use in the package statement at the top of you source files.
If you look at the source code for your Applet1.html file, you will see the following code:
<APPLET CODEBASE = "." CODE = "untitled1.Applet1.class" NAME = "TestApplet" WIDTH = 400 HEIGHT = 300 HSPACE = 0 VSPACE = 0 ALIGN = middle >
This code was generated automatically when you first created your applet inside the JBuilder environment.
NOTE: Don't get confused here. There are two HTML files that JBuilder creates. One is in the root directory for your project and it will have the same name as your project. For instance, you called your project nopackage.jpr, then the description of your project will be in a file called nopackage.html. This description of your project is just a place for you to write notes. The second HTML file, is named after your applet, so in our case it is called Applet1.html. This file is kept in your src directory beneath the root directory for your project. If you gave your project a package name, then it will be in the src/packagename directory beneath the root directory for your project. For instance, if we had created a package in the nopackage project, it would have gone in the /home/ccalvert/jbprojects/nopackage/src/nopackage directory.
Notice that it applet tag in your Applet1.html file references untitled1.applet1.class. This is another way of saying that the Applet1.class file is in a directory called untititled1. Therefore, the simplest way to deploy this applet is to create a directory called /home/httpd/html/untitled1 and put your class file in it. Then copy the HTML file to the directory beneath that one, namely to /home/httpd/html/. (On Windows it would c:/Inetpub/wwwroot/untitled1 for the class file, c:/Inetpub/wwwroot for the HTML file.)
After you have the files copied out, then everything works the same as in the previous example.
At this stage, you know all you need to know about deploying files. However, I'm going to write a little more about working with packages, so that you can see some of the twists that occur on this theme.
In the full versions of JBuilder, you can use the deployment wizard to help you distribute your applets. However, that is not available in the Foundation product, so I’m only going to discuss deploying applets manually. This may seem like an odd thing to do, but in my opinion, it’s easier to just do things by hand. The reason for this is simple: When using applets, you really have to stick with the available VM and classes deployed on your target system. This means you don’t have to do anything else but copy out the class files from your project.
When deploying your application, you need to think about what package it is in. For instance, if it is in a package called untitled2, then you pretty much have to deploy your classes into a directory called untitled2. You could, of course, remove the package statements from your source files, but that pushes you against the grain of the JBuilder development environment. Therefore, the simplest thing to do is simply recreate your directory structure when you deploy the application. It’s one thing to say you are going to recreate the directory structure, and another thing to actually do it. Suppose your class files are stored in the following directory:
D:\JBuilder\MyClasses\untitled1
This means, that by default, your source files would be stored in a package called untitled1:
package untitled1; import java.awt.*; import java.applet.*;
Suppose the directory structure for your server files looks like this:
C:\InetPub\WWWRoot
This means you might decide to distribute your class files into the following directory:
C:\InetPub\WWWRoot\untitled1;
Assuming your were placing your HTML files in the same directory, then you could create an Applet tag from that HTML that looked like this:
<APPLET CODEBASE = "\" CODE = "untitled3.Applet1.class" NAME = "TestApplet" WIDTH = 400 HEIGHT = 300 HSPACE = 0 VSPACE = 0 ALIGN = middle >
This tag states that the CODEBASE is the WWWRoot directory. In other words, putting “\” as the CODEBASE in the applet tag tells the server that it should start figuring out where untitled3 is by appending it to the root of the web server, which in this case is:
C:\InetPub\WWWRoot
If you append CODE statement from the applet tag to this then you end up with the following:
C:\InetPub\WWWRoot\untitled3.Applet1.class
This, of course, is exactly what you want, and your applet should therefore come up correctly. But what if you don’t want to deploy to this directory:
C:\InetPub\WWWRoot\JavaCode\SillyProjects
The correct thing to do in this case is to deploy to the following location:
C:\InetPub\WWWRoot\JavaCode\SillyProjects\untitled1;
If you simply dragged your whole untitled3 directory from wwwroot to SillyProjects, then you would have trouble. The way to fix the trouble is to open up your HTML file and change the applet statement as follows:
<APPLET CODEBASE = "\JavaCode\SillyProjects\" CODE = "untitled3.Applet1.class" NAME = "TestApplet" WIDTH = 400 HEIGHT = 300 HSPACE = 0 VSPACE = 0 ALIGN = middle >
Now when the browser tries to figure out where you class is, it starts at the web server root:
C:\InetPub\WWWRoot
It then adds on your CODEBASE
C:\InetPub\WWWRoot\JavaCode\SillyProjects\
And finally adds on the CODE itself:
C:\InetPub\WWWRoot\JavaCode\SillyProjects\untitled3.Applet1.class
Low and behold, what do you have? The path to your Applet!
The question then becomes, “What if you want to put your HTML file in some other directory from your class file?” This might seem like a nonsensical question at first, since you would normally want your HTML and your Class files in one spot. But actually there are a number of reasons why you might want to move the HTML file around. For instance, you might want to have one file that can display multiple applets. Rather than putting all the applets in one place, you would want them spread out across a directory tree.
The good news is that your HTML file, as developed in the previous section of the text, is now reasonably portable. You can put it anywhere beneath WWWRoot and it will find your class files. The browser can recreate the path to your class files regardless of the place you put you the HTML file. All it does is start in c:\InetPub\WWWRoot\ and then append your CODEBASE and CODE statements from the Applet tag.
You can even move the HTML file to a virtual directory. For instance, if you have created a virtual directory that is located on D:\MyDocuments\Arts, then the Web Server can still get back to your class by following the technique described in the last paragraph. It doesn’t care where your HTML file is located on drive D and your WWWRoot directory is on drive C, it always knows how to get back to your class file!
If you want, you can put URLs in your HTML Applet Tag:
<applet width="400" height="380" code="com.larmader.tetris.Tetris.class" codebase="http://homepages.borland.com/ccalvert/Games/" archive="Tetris.jar">
In this case you can see that I have specified the codebase as a URL. This particular program has the HTML file on one machine, and the class files on a totally different machine. Because I use a URL in the codebase tag, everything runs smoothly. The user would never know that I arranged things this way unless they dug in and looked at the source and compared it to the URL on the machine they are currently browsing.
This more complex example also uses a Jar file. I will add a discussion of Jar files to this text at a later time.
In this chapter you learned the basics about deploying applets on the web. I suggested that at first you create applets that do not contain package statements. That makes deployment very simply. However, I then went on to explain how to create and deploy applets that use packages.
This chapter also contains a brief discussion of class files and virtual machines. Both of these topics can become quite complex when explored in more depth. However, I have hopefully given you enough information about them so you can begin to understand their importance.
At this stage you know enough about using JBuilder and creating applets to begin building projects of your own. As a result, I encourage you to begin experimenting with the tools I have introduced you to in this text. The more applets you build the easier this process becomes. With time, you will find that everything I have told you so far can become second nature. With a little practice, you can perform all these steps without thinking, and thereby lay the foundation on which you can start to build a much deeper knowledge of Java.
I want to thank Joi Ellis for making some suggestions for improving this document. Write me if you have additional suggestions as to how to improve this document.