Porting DynaWorks to a J2ME implementation

It would be even possible (and not too complicated either) to write an emulator for DynaWork using J2SE that would run as a Java apllet from the web in any browser: you wouldn't even need a PalmOS™ ROM image to get that to work!

Writing a port is straight forward: The functionality is very PalmOS™-oriented, so any J2ME™ implementation running on PalmOS™ is likely to support this (still) limited set of methods to make the port easy (This may change in the next versions as DynaWorks will support more PalmOS™ functionality over the time...).

To demonstrate the things you have to do during a port, this section describes all steps that were neccessary to port DynaWorks to the KJava environment that comes with the KVM / CLDC from Sun.

Overview

The details of the underlaying implementation are hidden to the DynaWorks application (and developer); all 'communication' with implementation dependent features is routed through the singelton instance Environment that delegates the request to the actual Implementation running on the device.

So the very first thing a DynaWorks application should do is to tell the environment, which Implementation to use. You can use wrapper classes to do so (see the documentation for further details) or the first statement in the main method of the start-up class should be Environment.setImpl (new J9Impl()) or something like that to initialize the environment. This must be done before anything else on the device can be done from the application!

1. Registering the event queue:
   To receive events (user interactions, notifications, ...) from the PalmOS™, an application has to register an EventQueue object. This is done via the method Environment.register(EventQueue).

2. Accessing the screen:
   To draw on the screen, the application has to ask the Environment for a Graphics object. The application can than use the methods defined on the object to perform graphics operations.

3. Accessing databases:
   To access databases stored on the PalmOS™ device (custom or built-in databases), the application has to ask the

   Environment to create an 'access object' based on database identifiers passed in as arguments to the method.

4. Accessing the speaker (audio):
   To play predefined system tones on the device, the application has to ask the Environment for an Audio object. The application can than use the methods defined on the object to play sound snippets.

Interface	Description
brf.j2me.dynaworks.env.Implementation	Class factory for implementation dependend object instances like Graphics, Audio and Database objects. An Implememtation can also register EventQueue instances with the internal PalmOS™ event loop.
brf.j2me.dynaworks.env.Graphics	A Graphics object represents the screen of the device the application is running on. There is only one Graphics object in DynaWorks (singleton instance) and the screen size is supposed to be 160 x 160 pixel. A reference to the Graphics object is returned by the getGraphics() method of an Implementation object.
brf.j2me.dynaworks.env.Audio	An Audio object represents the audio system of the device and allows the playback of a limited number of 'system tones'. A reference to the Audio object is returned by the getAudio() method of an Implementation object.
brf.j2me.dynaworks.env.Database	A Database object represents a persistent object store on the device. It allows multiple Databases identified by a string that can be read and written with custom records. A Database object is created by the getDatabase() method of an Implementation object.

All these interfaces must be implemented for each environment you want to use. The next sections describe these interfaces in more detail. Each of these sections also include the source code for the KJava implementation.

Of course each implementing class requires a constructor method. You are free to use any constructor arguments you need to perform the object creation in your environment. This comes in handy, since you can use complex initialization arguments if you need and the applications will never need to know: objects are never created via the new operator in a DynaWorks application, but thrught the class factory methods in the Implementation interface Although not explicitly defined by the interface, DynaWorks requires these constructors to confirm to certain rules; these rules are explained for each interface.

public interface Audio { : // play a sound. void playSound (int sound); // dispose any allocated resources. void dispose (); }

The Audio interface allows the application to playback sound snippets defined by the system. There is no support for any kind of other sound snippets or MP3 files - all tones are predefined by the hardware platform. This is a limited approach, but sound is not a main issue in DynaWorks yet.

The following sound constants are defined by the interface:

public interface Graphics { : // get screen dimension int getWidth (); int getHeight (); // clear screen. void clearScreen (); // set/reset a clipping region for drawing. void setDrawRegion (int x, int p, int w, int h); void resetDrawRegion (); // primitive draw methods. void drawBorder (int x, int y, int w, int h, int mode, int width, int round); void drawRectangle (int x, int y, int w, int h, int mode, int round); void drawBitmap (int x, int y, Bitmap icon); void drawLine (int x, int y, int xx, int yy, int mode); // process labels int getStringWidth (String s); int getStringHeight (String s); int drawString (String text, int x, int y, int mode); int drawString (String text, int x, int y); // blitter methods. void bitBlt (int sx, int sy, int w, int h, int tx, int ty, int mode, int from, int to); void bitBlt (int sx, int sy, int w, int h, int tx, int ty, int mode); // dispose object void dispose (); }

The Graphics object represents the 'canvas' where your application can draw bitmaps and primitives (like rectangles, lines, etc.), clear the screen, setting clipping areas and move raster areas around on the screen.

A 'hidden' screen of the same size as the 'visible' screen is available for double-buffering or screen backup purposes.

The coordinate system (x- and y-coordinates) has its origin (0,0) in the upper left corner of the screen. Positive x-coordinates run to the right and positive y-coordinates to the bottom.

Currenly there is no support for color or fonts in DynaWorks. I hope this will change in one of the next versions.

Since the Graphics interface is "derived" from the normal set of graphics routines in the PalmOS™, you find a lot more information about the single methods in the PalmOS™ documentation.

The following constants are defined by the interface:

setDrawRegion(...) defines a clipping area on the screen at the defined position and dimension. Any draw operation that follows only leaves visible 'marks' within the defined clipping area.

resetDrawRegion() removes any clipping area. Please make sure that you nest calls to setDrawRegion() and resetDrawRegion() correctly, since not all implementations may have a stack of clipping areas.

The drawing mode can be set to different value from the constant table above.

Note: Since there are no fonts in DynaWorks yet, the PalmOS™ built-in font is used!

The mode argument can be one of the draw style values (PLAIN, GRAY, ERASE, INVERT). The second method call has PLAIN preset as a mode argument.

The first method is used to bitblt areas on the screen; the second method allows to specify a source ('from' = SCREEN|BUFFER) and a target ('to' = SCREEN|BUFFER), so you can bitblt between screen and background buffer.

The pixel in each area is represented as by a bit; if it is 0 you see the background (white); if it is 1, the pixel is drawn as a black dot. So any 'boolean' operation between pixels can be expressed as bit logic. The bitblt mode decides, which boolean operation should be performed during the operation:

Mode	Description
OVERWRITE	Copy the source pixels over destination
AND	Copy source only where target is black
AND_NOT	Inverted AND
XOR	Toggle pixels in source and destination
OR	Merge source and destination
NOT	Copy inverted source

Generally spoken a Database is just a named container for variable length byte fields that can be addressed by their sequence number (record number). So implementing the functionality for databases is quite easy, even if you J2ME implementation has a different database API.

In an implementing class, you have to construct an Database according to the environment you are working in. Since instances of this interface are always created by an Implementation object, the internal creation of Database object is hidden to DynaWorks and the application developer.

The class factory method defined in the Implementation interface has a string and two integer values as arguments. The meaning of these 'identifier' arguments is fixed in DynaWorks to allow compatibility across different J2ME implementations. The format also defines access to the built-in databases on the Palm. You can find more information in the description of the Implentation interface.

public interface Database {
:
  // return the current database error code.
  int getErrorCode ();

  // Open the database. If the database does not exist, it
  // is created and then opened.
  boolean open ();
    
  // Is the database opened?
  boolean isOpen ();
    
  // Close the database.
  void close ();

  // Return the number of records in the database.
  int numberOfRecords ();

  // add a record to the database.
  int addRecord (Dataset rec);

  // Retreive a record from the database at a specific position.
  boolean getRecord (int idx, Dataset rec);

  // Store a record in the database at a specific position.
  boolean putRecord (int idx, Dataset rec);

  // Delete a record at a specified index.
  boolean deleteRecord (int idx);   
}

The following error codes are defined by the interface:

The following methods have to be implemented:

All information required to address and to open the database were already passed to the object in the constructor call.

Please note: The KVM implementation of the PalmOS™ database is somewhat strange: It returns the overall number of records in the database, including deleted entries (that always show up at the end of the database). More...

public interface Dataset { // Get the 'byte' length of the record. int size (); // Get the byte array representing the record content. byte[] getContent (); // update the record with new data. boolean setContent (byte[] data); }

The method returns the sequence index of the new record in the database.

Please note: The KVM implementation of the PalmOS™ database does not allow access to the unique index of a record. Therefore all record indexing is based on the current sequence of records in the database (and that may change due to deletion operations). This is likely to change in next versions of DynaWorks. More...

Please note: The KVM implementation of the PalmOS™ database does not allow access to the unique index of a record. Therefore all record indexing is based on the current sequence of records in the database (and that may change due to deletion operations). This is likely to change in next versions of DynaWorks. More...

Please note: The KVM implementation of the PalmOS™ database does not allow access to the unique index of a record. Therefore all record indexing is based on the current sequence of records in the database (and that may change due to deletion operations). This is likely to change in next versions of DynaWorks. More...

The behaviour of the method varies among different J2ME implementions. This is vary unsatisfying, so the next release of DynaWorks will have a overhaul of the Database interface...

Please note: The KVM implementation of the PalmOS™ database does not allow access to the unique index of a record. Therefore all record indexing is based on the current sequence of records in the database (and that may change due to deletion operations). This is likely to change in next versions of DynaWorks. More...

public interface Implementation {

  // register an EventQueue. The Implementation is going
  // to dispatch all events to the registered EventQueue instance.
  // Returns previous EventQueue (or null).
  public EventQueue register (EventQueue queue);

  // get access to the Graphics implementation.
  // An Graphics object is a singleton.
  public Graphics getGraphics ();

  // get access to the Audio implementation.
  // An Audio object is a singleton.
  public Audio getAudio ();

  // get a database object identified by a string.
  public Database getDatabase (String id);
}

The following methods have to be implemented:

The method returns the event queue that was registered before (or 'null' in case there was no such queue) to the caller.

1. Creator Id
   The first four characters form the 'Creator ID'. This is a unique id for each application you write and deploy. You should register each such application with Palm.

   A 'Creator Id' is a four character string that can be converted to an int via 'int Environment.decodeIdString (String s)' - whenever you need that number.

2. Type Id
   The next four characters after the delimiter designate the database type. A database type is something like 'DATA', 'RSRC' or the like. It can also be converted to an int via 'int Environment.decodeIdString (String s)'.

3. Database name
   All the rest of the characters after the delimiter form the database name. It can be 32 characters long and can be set by the application.

   The database names for PalmOS™ built-in databases are described in the PalmOS™ database section of the tutorial.