Brought to you by: Check It Out! Java XML Programmers Reference Download Source Code Read part 1 Read part 2 Read part 3 Submit a question on Java XML Read our list of questions and answers on Java XML

If Save & Quit or Save & Continue are clicked, the penDown() event handler

(see Handling penDown() Events) routes processing to the save() method. This method has the responsibility for:

• Opening the JavaXMLProgRef database



• Creating the JavaXMLProgRef database if it doesn't already exist



• Writing a new record at the end of the JavaXMLProgRef database



• Closing the JavaXMLProgRef database

The name "database" is really a misnomer, as the Palm OS provides no way to create and drop tables on a "database." It's better to think of a Palm OS database as a section of permanent data resident in non-volatile memory. The section is comprised of variable-length records. Each record is a variable-length array of bytes. Since we're using a user-defined database, not a system-defined database like the address book, that means the possibility exists that JavaXMLProgRef doesn't exist on the system yet. In that case, we'll create a new, empty database. If it does exist, we'll open the existing one. Then we'll write a record at the end of the database and close it. Let's look at the code.

private void save() {
Database db = new Database(ContactBook.creatorId,
ContactBook.type, Database.WRITEONLY);
if (!db.isOpen()) { 
//the database doesn't exist yet. create it.
Database.create(0, ContactBook.dbName,
ContactBook.creatorId, ContactBook.type, false);
db = new Database(ContactBook.creatorId,
ContactBook.type, Database.WRITEONLY);
}
if (db.isOpen())
db.addRecord(getContactAsXML().getBytes());
db.close();
}
}

ContactBook.creatorType is also an int (actually, the JNI call to the Palm OS requires the C/C++ unsigned long datatype, but that's handled for you). It is used to distinguish between multiple databases with different types of information in them. I've chosen to use 0x32132132.

ContactBook.dbName is a java.lang.String that names our database. It must be unique for all database names on the device. In this case, we have named it JavaXMLProgRef. To truly ensure uniqueness, though, Palm Developer Support recommends using a name, followed by a hyphen, followed by your unique creatorId.

com.sun.kjava.Database.addRecord() creates a new record at the end of the database. Its content is set to the XML document, as bytes. All records must be passed as bytes to com.sun.kjava.Database.addRecord().

Part of adding a record in the database is a call to AddContact.getContactAsXML(). Let's look at that method now.

Since we store XML natively in our JavaXMLProgRef database, we need to generate an XML document from the form fields as filled out by the user. The method which does this is AddContact.getContactAsXML(). Let's take a look at it:

private String getContactAsXML() {
//construct an XML document from the form fields.
//return it as a string
kXMLElement root = new kXMLElement();
root.setTagName("contact");
root.addProperty("fname", fname.getText());
root.addProperty("lname", lname.getText());
root.addProperty("address", address.getText());
root.addProperty("city", city.getText());
root.addProperty("state", state.getText());
root.addProperty("zip", zip.getText());
root.addProperty("country", country.getText());
root.addProperty("phone", phone.getText());
return root.toString();
}

Here we use class nanoxml.kXMLElement from the NanoXML CLDC/KVM port to build a document. kXMLElement has the same methods as nanoxml.XMLElement. This method builds a simple XML document instance using com.sun.kjava.TextField.getText(). getText() returns the text the user entered into a TextField object. Finally, getContactAsXML() returns the built document as a string. Here is a document instance:

<contact fname="Frantic" lname="Neumann"
         address="123 Fake Street" city="Denver"
         state="Colorado" zip="80202" country="USA"
         phone="303-303-3000"/>

BeamContact

public class BeamContact extends com.sun.kjava.Spotlet implements com.sun.kjava.DialogOwner

BeamContact is the core class for sending a contact to the ReceiveContact class. It must extend com.sun.kjava.Spotlet to fit into the package com.sun.kjava application paradigm.

Spotlet is conceptually similar to java.applet.Applet in that it is a class for handling event callbacks. Overriding one of the event handlers, such as penMove(), keyDown(), or keyUp(), will enable the extended class (BeamContact, in this case) to receive notification of these events.

BeamContact behaves similarly to a web search engine result page. When you search for "apples" in a search engine, the result set matching "apples" is typically much larger than what you want displayed in your browser. So search engines usually include Next and Previous hyperlinks, allowing you to scroll through the result set corresponding to a search for "apples." Similarly, BeamContact displays six contact book records per page, with means to scroll through the result set.

BeamContact displays a preset number of buttons on a "page." Each button has text corresponding to the first and last name of a record. Clicking one of these buttons begins the document building and beaming process. Note that in this simple application; only one contact can be beamed at a time.

Here's a screenshot of the application so you get a feel for how it works:

We'll examine three parts of class BeamContact:

• Painting the screen



• Reading from the contact book database, JavaXMLProgRef



• Beaming the document