bikleDemo6.htm
05-06-2002 Bikle
-----------------

Bikle Java Demo #6

This is a demo of some classes which illustrate a few simple
programming techniques.

The resulting GUI is a two field dialog box which asks the user
for two pieces of information:

-The hostname of a website (www.google.com for example).
-A "GET" string

Next, the user is expected to press a "submit" button.

At that point, a Java class is triggered which opens a socket to
the host on port 80 and sends the GET string.

If the host returns data, the data is copied into a String which is
then passed to a JTextArea object for display to the user.

More discussion about each class is presented below.

aMain-java.txt

The above class acts as the demo entry point.  It supplies an initial
hostname and GET String to an object of type urlPrompt.

urlPrompt-java.txt

The above class acts as a GUI for the user to supply a hostname and
GET String to a target webserver.  Aside from creating GUI objects
for the user this class does not do much.  It does need to pass the
data it collects from the user to an object I call a "button handler".
The button handler does most of the interesting activity in this demo.

buttonHandler-java.text

The above class makes use of the keyword: "implements".  This means
that this class may be termed as an implentation of an "interface".

To be more precise, the buttonHandler class implements the ActionListener interface.

Any decent introductory Java class will teach the main idea behind interface.
If you are the type of student who plays golf rather than attending class,
consult the link listed below:

http://java.sun.com/docs/books/tutorial/java/interpack/usinginterface.html

It is worth learning because the technique is widely used.

The next line of syntax in the class worthy of note is listed below:

  Socket socket;

What is an object of type "Socket"?

I think of a Socket as an object which I can plug into.  Instead of
pulling electricity out of a Socket, I pull out a stream of data.
Also, I may push data into a Socket.  The syntax to do these two things
will be discussed later in this demo.

The next line of syntax in the class worthy of note is listed below:

  OutputStream out = null;

What is an object of type "OutputStream"?

I compare an OutputStream to a cord which connects my toaster to
my electrical socket.  A cord carries electrons; an OutputStream
carries data.

The same may be said for an object of type "InputStream".

The next line of syntax worthy of note is listed below:

  urlPrompt XurlPrompt;

The above line helps me connect the buttonHandler object to the 
urlPrompt object.  References to the urlPrompt object appear in
three places within the buttonHandler class:

-Declaration Section
-Constructor Argument list
-Inside the Constructor

This is a pattern I frequently create when I want to pass data from
one object to another.  It is a technique I picked up during a day I
attended intro Java class rather than playing golf.

If you closely study urlPrompt-java.txt you will see that it
needs to make reference to buttonHandler-java.text in order to
complete the connection.

The next bit of syntax worthy of note is listed below:

  // Constructors
  // /////////////////
  public buttonHandler (urlPrompt PurlPrompt)
  {
    XurlPrompt = PurlPrompt;
    // Now that the objects are passed in, 
    // I may gain access to the data within them.
  }

This is the constructor of the class.  I see it as a bit of code (or
function if you are a C programmer) which gets run when this syntax is
invoked at another place:

buttonHandler XbuttonHandler = new buttonHandler(AurlPromptObject);

The next bit of syntax worthy of note is listed below:


  // Methods
  // /////////////////

  public void actionPerformed(ActionEvent Event)

This is the start of the one and only method in the buttonHandler class.

I wrote this particular method so that it follows some rules.

"What rules?", you may ask while waiting on a foursome of old ladies.

I reply, "The ActionListener interface has a rule which says that any
implementing class must contain a method named actionPerformed with
argument of type ActionEvent."

"How did you find the rule?" , you may ask.

My answer, "I typed 'ActionListener interface' at google and it led me to this page:
http://java.sun.com/j2se/1.3/docs/api/java/awt/event/ActionListener.html."

The next bit of syntax worthy of note is listed below:

    urlInput = XurlPrompt.aJTextFieldU.getText();
    getInput = XurlPrompt.aJTextFieldG.getText();

Here I fill a couple of String variables via a call to getText().  I'm
able to access the data in the JTextField objects because I had passed
their owner object (XurlPrompt) into the buttonHandler constructor.

The next bit of syntax worthy of note is listed below:


    String aString = "User pressed the button! Time to do some work!\n";
    aString = aString + "The user input this URL:\n";
    aString = aString + urlInput;
    aString = aString + "\n";
    aString = aString + "The user input this GET line:\n";
    aString = aString + getInput;
    aString = aString + "\n";

    GUIoutJTA XGUIoutJTA3  = new GUIoutJTA (aString);

I put the above syntax in as a debugging aid.  I wanted to see if the
urlInput and getInput String variables contained the data I wanted to
send to the code which would contact the webserver.

The next bit of syntax worthy of note is listed below:

    try 
    {

This is a feature of Java.  It's easy to see the idea behind it
via the use of a good keyword "try".  The program wants to try 
something.  If it works, great.  If not, deal with it.  This idea
is new compared to error handling in C programing.  There, the
programmer is expected to anticipate all the errors which may
happen during run time.  The Java programmer is given a little
more slack; he is given a way to "try" some syntax without the
need to attach to it a bunch of error checking code.

The next bit of syntax worthy of note is listed below:

    socket = new Socket(urlInput,80);

Here I see how to create an object of type Socket.  I just
feed a hostname and a port number to the Socket constructor.

The next bit of syntax worthy of note is listed below:

    out = socket.getOutputStream();

We saw earlier that "out" is an object of type, OutputStream.

I know that the Socket object is going to want some data from me.

I learned from a Java book that the way to give it access is by
attaching an OutputStream object to the getOutputStream() method.

Notice I used a variable name to keep my mind connected to the
concept that out going data is from my perspective rather
than the webserver's perspective.

An experienced Java programmer would have figured this out
by consulting the web page below:

http://java.sun.com/j2se/1.4/docs/api/java/net/Socket.html

The next bit of syntax worthy of note is listed below:

    out.write(getInput.getBytes()); 

This is an important bit of syntax to keep in my list of Java notes.
It is showing me how to copy data out of a String into an object of
type OutputStream.  I learned it from a book.

Also it is discussed here:

http://java.sun.com/j2se/1.4/docs/api/java/lang/String.html#getBytes()
http://java.sun.com/j2se/1.4/docs/api/java/io/OutputStream.html#write(byte[])

A savvy programmer would read the above pages and then tell this to his
golfing buddies while waiting for tee off time:

I now know an OutputStream object has a method named write(); that must be
the way I use it to send data out.  This method takes an argument of type byte[].
So, I had to find a way to convert a String to an array of byte types.  I looked
at the String methods in the Java docs and found a handy method named getBytes()
which does exactly that.

The next bit of syntax worthy of note is listed below:

      out.flush();

I learned this from a Java book.  I think of it like this: bytes get stuck
in an outputStream; I need to flush them out.

The next bit of syntax worthy of note is listed below:

      in = socket.getInputStream();

I learned this from a book.  I'm expecting data from the webserver via
the Socket object; I access via a call to getInputStream().

Next, I wondered how do I transform this data coming in from an
inputStream into a String?  I wanted it in a String so I could then
hand it to a JTextArea object for display.  I knew how to display
a String in a  JTextArea object.

First, I tried this:

    StringFromWS = in.toString();

It did nothing.

After a bit of reading I found a way to convert an OutputStream to a
String.  Then I found a way to convert an InputStream to an
OutputStream.  Then I cooked up some syntax which implemented this
idea:


      // Convert in (an InputStream object) to String.
      // I wish I could just do this: StringFromWS = in.toString();
      xOutputStream = new ByteArrayOutputStream(aBuffSize); 
      while ( (k=in.read(buff) ) != -1) 
       xOutputStream.write(buff,0,k);
      // I can now grab the string I want
      StringFromWS = StringFromWS + xOutputStream.toString(); 
      xOutputStream.close();
      // That was a lot of work to pull a String out of an inputStream.

The above syntax seems to work; I'm not sure it's the best way to do it.


The next bit of syntax worthy of note is listed below:

      // I close objects I'm done with
      out.close(); // don't need it anymore, close it
      in.close();
      socket.close();
    }

Notice the last "}"; it corresponds to this: "try {".

The next bit of syntax worthy of note is listed below:


    catch (java.io.IOException e) 
    {
      GUIoutJTA eGUIoutJTA  = new GUIoutJTA (e.toString());
    }

This is where Java works some of its error handling magic.
If any of my code runs into bizarre run-time errors, the JVM
will probably allow me to get a clue via a toString() method
in the java.io.IOException object.  I feed the String to 
a handy GUI object so I can see it.

The next bit of syntax worthy of note is listed below:

    // show what we got from the webserver
    GUIoutJTA XGUIoutJTA4  = new GUIoutJTA (StringFromWS+"\n");
    // re-initialize StringFromWS
    StringFromWS = "StringFromWS: \n"; 

This syntax is easy to follow.  I just feed the String I filled with
data from the InputStream object to a GUI object so the user can
see the String.  Then, I reinitialize the String.

At this point the buttonHandler exits and all is quiet until the
user presses the submit button again.

Notice that I make use of a class named: GUIoutJTA

The source code for that class is linked below:

GUIoutJTA-java.txt
WindowControlDispose-java.txt

The link below is source code for a class which makes it easier for
the user to end the entire program by clicking the "X" in the XurlPrompt object:
WindowControlExit-java.txt