DynaWorks Tutorial

How to write applications with the DynaWorks framework

Conduit development in Java for DynaWorks databases

Writing an application for the Palm that uses custom DynaWorks databases is just half of the job - you usually want to save these databases during a HotSync process to your desktop machine for further processing.

The module that links to the HotSync™ Manager and that is activated during a HotSync™ process is called a conduit. The Palm HotSync Manager allows us developers to write custom conduits so you can transfer the data from and to your custom databases on the Palm device.

If you use the "Conduit Development Kit for Java" you can even write these conduits in the Java programming language. The following sections describe how to write a conduit for your custom DynaWorks database and how to re-use your Record class for the desktop-side conduit.
The example in the following sections is a conduit for the DynaDb custom database example. You can find all neccessary source and batch files here:

  • cpl.bat
    Batch file to compile the conduit source code. You have to adapt the directory settings to match your own directory structure.
  • PalmSync.java
    source code of the main conduit module.
  • CMyRecord.java
    SyncManager-compatible record implementation for the custom database.
  • Conduit.reg
    Windows registry settings for the conduit. You have to adapt the directory settings to match your own directory structure.

Neccessary preparations

Before you can start to use the DynaWorks framework for the conduit development, you have to prepare your machine for that:

  • DynaWorks classes for the desktop (Java2/SE 1.3)

    To be able to compile the conduit source code that is presented in the following sections, you have to compile some of the DynaWorks classes with it.

    So you can either make sure your that classpath during compilation contains the DynaWorks source path or you package the needed classes from the KJava/classes directory in your workspace into a JAR file and add that to the classpath. The following classes are needed:

    • brf.j2me.dynaworks.util.*
    • brf.j2me.dynaworks.db.*

    For your convenience you can download a ready-to-go JAR file named DynaDb.SE.jar here.

  • Conduit Development Kit for Java

    Most of the conduit base classes come from the Conduit Development Kit for Java. In order to compile the sample code you have to download and install the CDK4J Version 4.0 from the PalmOS website.

Back to top of page ...

A conduit skeleton

Developing a conduit in Java is fairly easy. Let's have a look on a minimal (compilable) conduit:

import palm.conduit.*;

public class PalmSync implements Conduit {

   public void open (SyncProperties props){
   }

   public String name() {
      return "MyConduit";
   }

   public int configure (ConfigureConduitInfo info) {
      return 0;
   }
}

There are three methods that must be implemented:

void open (SyncProperties props)
This method is the actual "working horse". It will be called during a HotSync to exchange data from and to the Palm device.
String name()
The easy-to-implement method of the class: just return a string identifing your conduit.
int configure (ConfigureConduitInfo info)
This method is called when the user wants to edit the conduit in the HotSync Manager.

Back to top of page ...

Accessing the database during a HotSync

Database handling with the SyncManager is like the database handling in DynaWorks: You work with databases that contain records. To access databases and records you use a helper object called SyncManager. It has all the necessary methods for the database handling. The following code fragment shows how to open a database and to find out how many records there are:

// open custom database
byte flags = (byte)(SyncManager.OPEN_READ |
                    SyncManager.OPEN_WRITE |
                    SyncManager.OPEN_EXCLUSIVE);
int db = SyncManager.openDB (props.remoteNames[0],
                             (short)0, flags);

// find out how many memo records there are
int count = SyncManager.getDBRecordCount (db);

Please notice: I had quite a bit of trouble on my developer machine - the source code above compiled fine but I got an exception during HotSync (read the protocol!) because the 'props.remoteNames[]' array is always empty. And the registry variable "Remote0" is definitely set and correct. I could fix that problem on my machine only by replacing the argument 'props.remoteNames[0]' by "Test" (the actual database name). If you encounter a similar behaviour, please let me know.

A record that can be retrieved from such a SyncManager database must confirm to the palm.conduit.Record interface. This interface defines a set of methods you have to implement for your own record classes.

If you want to access build-in databases you can use the classes that come with the CDK4J. If you have developed custom databases with the DynaDb framework, the easiest way is to re-use your record class you used in the Palm application.

Back to top of page ...

Re-using your Record class

Since we will write a conduit for a custom database application developed with the DynaDb framework we can re-use the Record class defined by the application (MyRecord.java).

What we need to do is to "wrap" another class around MyRecord so that the new class behaves like a record that can be managed by the SyncManager class. The wrapper also make sure that the MyRecord part is always up-to-date.

The following code shows this "wrapper" process for the class MyRecord:

public class CMyRecord extends MyRecord implements Record {

   /////////////////////////////////////////////////////////////////
   /**
    * inner class that implements the basic Record methods.
    */
   private class Delegate extends AbstractRecord {
:
   /**
    * instance of the delegation class.
    */
   private Delegate theDelegate;
}
Look at the full source code

The AbstractRecord is part of the Conduit Development Kit for Java, so make sute you have downloaded and installed that software package.

Back to top of page ...

Implementing the 'open()' method

The implementation the open() method in our example is easy since we only want to write the database entries to an ASCII file. It is up to you to decide what you want to do with te records during a HotSync - this is just an example:

public void open (SyncProperties props){
		
   // Tell the log we are starting
   Log.startSync();
:
}
Look at the full source code

So, a CMyRecord behaves like a MyRecord when it comes to data retreival. This makes it easy to exchange data between Palm an Desktop because you can use the same Record class on both platforms.

Back to top of page ...

Implementing the 'configure()' method

If you want (or need) a configuration dialog with your conduit, you can create and show this dialog in the config() method. You have to take care of the persistence of the configuration info yourself; usually you will use a file to do so.

One last advice: Make sure that your dialog runs in a separate thread; otherwise it would lock the SyncManager thread, leading to 'irritating' redraw problems in the dialog of the HotSync Manager.

Back to top of page ...

Compiling the example

If you have finished the preparations and fleshed out the example classes with your own application logic, you are ready to compile the conduit source code. Compilation as done in the example cpl.bat is straight forward. Change the path and environment settings to match your local installation!

Back to top of page ...

Installing and registering the conduit

First you should create a directory to receive the conduit files. In our example I use c:\pilot\MyDbApp. Copy the files Conduit.jar and Conduit.reg to that directory.

In order to use the conduit with the desktop HotSync Manager you will have to register it. Please terminate any running HotSync Manager on the desktop machine and insert the following definitions into the Windows registry (adapt to your directory structure). You find these settings in the file Conduit.reg:

REGEDIT4

[HKEY_CURRENT_USER\Software\U.S. Robotics\Pilot Desktop\ApplicationMyDbApp]
"Name"="MyDbApp Conduit"
"Conduit"="jsync.dll"
"ClassName"="PalmSync"
"ClassPath"="c:\\pilot\\MyDbApp\\Conduit.jar"
"VM"="SUN"
"Creator"=dword:4D594150
"Directory"="c:\\pilot\\MyDbApp"
"File0"="MyDbApp.txt"
"Priority"=dword:00000001
"Remote0"="Test"

Restart the HotSync Manager. If the conduit is correctly registered, you will see it in the conduit list of the HotSync Manager.

Now you are ready to try out the conduit.

Back to top of page ...

Copyright © 2000, Bernd R. Fix. All Rights Reserved.