Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.


Channels ▼
RSS

JVM Languages

How do I Interface Java to my PalmPilot?


Java Q&A

Cliff, vice president of technology at Digital Focus, can be contacted at cliffbdf@ digitalfocus.com. To submit questions, check out the Java Developer FAQ web site at http://www.digitalfocus.com/faq/.


Microsoft's planned "palm PC" product indicates that the idea trailblazed by 3Com's PalmPilot is at least good enough to be copied. But then, that's something PalmPilot users have known for a long time. All PalmPilot owners, in fact, have a theory about why the gadget is so successful, usually having to do with size, simplicity, reliability, and ability to easily back up data. It's hard to go to a meeting anymore without several people whipping out PalmPilots, looking each other in the eye with an unspoken understanding: "So you're one of us."

In short, the PalmPilot has become a common feature in techno-gadgeteer's landscape. As you probably guessed, I own one, too. Furthermore, it should come as no surprise that I wanted to interface to my PalmPilot with Java.

Luckily, IBM, which has licensed the PalmPilot and is reselling it under the IBM WorkPad brandname (see http://www.pc .ibm.com/us/workpad/), has developed a Java interface called the "PilotBean" (see http://www.alphaworks.ibm.com/formula.nsf/toolpreview/). At this writing, the bean is an early version of what it will become. Still, it is interesting enough to write about right away; at worst, you'll find some improvements by the time you download the PilotBean after this article goes to print.

The PilotBean Interface

At the present time, the PilotBean has methods only for dealing with PalmPilot memos and datebook entries. Support for the other applications will surely come soon.

The PilotBean has a single memo method, for adding a new memo; Listing One. Listing Two shows methods for adding new datebook entries, while Example 1 illustrates example use of these methods. There are also methods for retrieving and modifying datebook entries; see Listing Three. At present, you can list dates, but there is not yet a method for getting a list of dates within a time/date range. Listing Four lists the PilotDate type constructors and methods.

The PilotMonitor

When you construct a PilotBean instance, the instance automatically creates a PilotMonitor object, which contains a sleep loop that wakes every 60 seconds and checks whether a memo has been added or a datebook entry added or changed. If it detects one of these three conditions, it calls the newEntry() method, which dispatches an event to listeners of the corresponding event type.

There are three defined event types: MemoAddedEvent, DateAddedEvent, and DateModifiedEvent. For each, there is a corresponding event-listener interface with a single callback method; see Listing Five. You can implement these interfaces and register yourself with the PilotBean to receive notification of the three types of events. Listing Six presents the PilotBean listener-registration methods.

MemoSaver

To illustrate how you use the PilotBean, I've written MemoSaver, a stand-alone Java application that lets you paste a memo into a text area, then click a button to save that text as a memo in a PalmPilot (see Figure 1). For this application to work, you need to have the PalmPilot Desktop Software Version 2 installed on your computer (a Version 2 Desktop can read Version 1 data; so if you have Version 1, you can upgrade safely).

To use the PilotBean, I first construct an instance of a PilotBean:

pilot = new PilotBean(pilotDir, userName);

pilotDir is the directory on your computer where the pilot desktop is installed. The default location for this on a Windows machine is C:\pilot. For the PilotBean, however, you must use the form:

c:/pilot/

When you install the Pilot Desktop software, it also asks you for a user name to identify you. This is because the Pilot Desktop is designed to be able to handle more than one Pilot, for different users. The name you enter during Pilot installation, however, may contain spaces, and the Desktop software converts names into a short version without spaces. For example, my name, "Cliff Berg," gets converted to "BergC." To find out what it did to your name, look in the pilot directory and find the directory corresponding to your name. That is the name you must use as the user name in the PilotBean constructor. I chose to define properties to contain these values.

To save a memo, the essential call is:

pilot.addMemo("<memo text>");

All you do is make this call, and the memo gets saved to the Pilot Desktop application and, when you next do a sync, to the Pilot organizer. It is that simple. Of course, the bean has many other functions for saving and retrieving Pilot data, as already described. I'll leave it to you to add datebook functionality to the application.

The PilotBean you download is a self-extracting archive. Double-click on it, and it will unpack itself. You will then discover that it includes a DLL, jpdn20.dll. This module is accessed by native methods in the bean. There is also a JAR file, pilotbean.jar. This will need to be added to the classpath when the program is run. Further, the jpdn20.dll accesses a Pilot DLL, called pdn20.dll, which is normally found in the pilot directory. Both of the DLLs need to be in the PATH of the program when the program starts.

To run the program using the JRE, enter:

jre -cp .;pilotbean.jar 
	-Dmemos.pilot.dir=c:/pilot/
	-Dmemos.pilot.user="BergC" 
	MemoSaver

The -cp option appends the specified string to the classpath of the jre process. I have appended the current directory (the jre does not automatically include the current directory in the classpath), and the pilotbean.jar JAR file. The two -D options define Java properties used by my program. The first, memos.pilot.dir, specifies the pilot directory. The second, memos.pilot.user, specifies the Pilot user. These two property values are passed to the PilotBean constructor.

When you run the program, you can enter a memo into the text field either by typing it or by pasting it from another application. Then click "Add As Memo," and the application will invoke the Pilot Desktop's DLL (via the PilotBean) to write the new memo into the Pilot Desktop.

The MemoSaver class implements the PilotBean's MemoAddedListener interface. This enables it to receive notification when new memos are added in one of three ways: as a result of direct user entry into the Pilot Desktop; as a result of an update with a Pilot organizer; or as a result of our own addition from the MemoSaver. The PilotMonitor's polling routine (which runs once a minute) checks for new additions. When it detects that a new memo has been added, it notifies the MemoSaver program via the MemoAddedListener callback, memoAdded(), which prints a message indicating that a memo has been added.

The completed MemoSaver application is available electronically from DDJ or from the Digital Focus web site (http://www.digitalfocus.com/).

Conclusion

The PilotBean makes it easy to integrate the PalmPilot into a Java application. It is not hard to think of workflow applications that could take advantage of this, perhaps making entries automatically in response to application events. Imagine, for instance, a scenario in which users drag e-mail into a "reply to by phone" bin, and the program simultaneously adds a To-Do entry to call the person identified by the e-mail. Another scenario would be adding pop-up menus to Java applications that allow you to instantly send information -- memos, appointments, To-Do items, and name and address-book entries (when the PilotBean adds support for these) -- from highlighted selections to the Pilot without having to go into the Pilot Desktop.

In conclusion, the Pilot Desktop is a wonderful interface that mimics the PalmPilot interface -- and the PilotBean allows for integration of the Pilot into the actual work process.

DDJ

Listing One

public void addMemo(String memo);

</p>

Back to Article

Listing Two

public void addDate(String day, String startTime, String endTime, String desc, String note);

</p>
public void addDate(String day, String startTime, String endTime, String desc);


</p>
public void addDate(PilotDate, PilotDate, String, String);


</p>
public void addDate(PilotDate startDate, PilotDate endDate, String desc);
    long time = System.currentTimeMillis();


</p>
public void addDate2(String day, String startTime, String duration, String desc, String note);


</p>
public void addDate2(String day, String startTime, String duration, String desc);


</p>

Back to Article

Listing Three

public int getNumDates();public DatebookEntry getNthDate(int);
public int getNumUpdatedDates();
public DatebookEntry getNthUpdatedDate(int);
public int getNumNewDates();
public DatebookEntry getNthNewDate(int);
public void setStartDate(DatebookEntry, PilotDate);
public void setEndDate(DatebookEntry, PilotDate);
public void appendDescription(DatebookEntry, String);
public void appendNote(DatebookEntry, String);


</p>

Back to Article

Listing Four

public PilotDate();public PilotDate(PilotDate);
public PilotDate(String);
public PilotDate(String,String);
public PilotDate(int);
public PilotDate(long);
public void copy(PilotDate);
public String getDateString();
public String getTimeString();
public long getNumSeconds();
public int getYear();
public int getMonth();


</p>
public int getDay();
public int getHour();
public int getMinute();


</p>

Back to Article

Listing Five

public interface interface MemoAddedListener implements EventListener {    public abstract void memoAdded(MemoAddedEvent);
}
public interface interface DateAddedListener implements EventListener {
    public abstract void dateAdded(DateAddedEvent);
}
public interface interface DateModifiedListener implements EventListener {
    public abstract void dateModified(DateModifiedEvent);
}


</p>

Back to Article

Listing Six

public synchronized void addMemoAddedListener(MemoAddedListener);public synchronized void removeMemoAddedListener(MemoAddedListener);
public synchronized void addDateAddedListener(DateAddedListener);
public synchronized void removeDateAddedListener(DateAddedListener);
public synchronized void addDateModifiedListener(DateModifiedListener);
public synchronized void removeDateModifiedListener(DateModifiedListener);


</p>

Back to Article


Copyright © 1998, Dr. Dobb's Journal


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.