Readme for JavaLlama

Description

JavaLlama is a set of Java classes for sending and retreiving information to and from an Apple MessagePad, and then manipulating that information on the desktop machine.

How To Use In A Project

It is very easy to use JavaLlama in a Java project. First, simply import the llama classes with the Java import statement.

import llama.*;

When you want to communicate with the server, instantiate a NewtConnect class and then call a method to either get or put frames on the server.

    try {
      NewtonService connect = new NewtonService("fire.cc.gatech.edu");
      Vector frames = connect.GetSoup("Notes");
 
      //... use the vector of frames ...
    }
    catch ( Throwable j ) { System.out.println ( "Error: " + j ); }

Frames On The Desktop

Newton frames are unique in that they are dynamic. Unlike static languages like C, C++, or Java, the Newton does not use compile-time byte offsets to access fields in a structure. Instead, it relies on the name of the "slot" (field) in the frame to access the information. As a result, frames are incredibly flexible and new slots can be added at runtime. Since the lookup is by name only, new slots can be added at the end, or even in the middle of the frame without affecting any application using that frame.

This flexibility poses some difficulties when mapping frames into a static language like Java. Instead of being able to use a native data type, we must "roll our own" to represent a frame. The NewtFrame class encapsulates an entire frame, and contains (internally) a Vector which holds each of the children.

The above picture shows a frame on the Newton and how it is represented as a collection of NewtFrame classes on the desktop. Note that atomic types (such as strings and integers) are stored as a NewtFrame even though they are not frames themselves.

To access the slot f.c.foo in the above structure, you would do the following:

// assume we have the frame in variable f
try {
	NewtFrame c = f.GetSlot ( "c" );
	NewtFrame foo = c.GetSlot ( "foo" );
	System.out.println ( foo.GetData() );
} 
catch ( SlotNotFoundException e ) {
	System.out.println ( "Slot not found" );
}

Through a combination of GetSlot() and GetData(), you can access any information in a frame as long as you know its overall structure.

Creating Your Own Frames

The true power of JavaLlama is that it allows you to take information from a desktop or network source (like the Internet) and turn it into information that the Newton understands. To do this, you must create a frame on the desktop and send it to the Newton using SendFrame().

The NewtFrame class has the following fields (declared in NewtFrame.java):

Field Name	Description
slotType	An integer describing the type of the data this slot represents (string, integer, or frame, for example). Constants for the types supported by the Newton are in the Java file.
varType	Mostly unused, set the same as slotType
childCnt	How many children does this frame have? 0 for slots that are not frames. This is also the same value as children.size(), but is duplicated for symmetry with the C++ version.
peerCnt	unused, I think.
length	The length of the data.
data	The actual data.
slotName	The name used to access this slot
oClass	The class name for this slot (extra identifying information used by the Newton).
children	A vector (list) of the children frames. Empty if this slot is not a frame.

Talk to Jason Ellis for more information about creating your own frames.

Supported Methods

These are the methods supported by the NewtonService class and what they do:

GetSoupNames	return a list of all soup names on a given device
GetSoup	return a list of all frames in a soup on a given device
GetSoupOverview	return a short description about each item in a soup on a given device. This only works on soups for which an overview is provided (such as Notes, Names, Calls, etc).
FindText	Returns a list of frames which contain the text string in a particular soup on a given device.
GetFindOverview	Combination of find with overview described above.
GetEntry	Returns a particular frame, identified by the frame's ResourceId.
StoreFrames	Send a list of frames to a particular device or to a Global Soup
ClearSoup	Clears a specified Global Soup
GetGlobalSoup	Get all frames from a specified Global Soup
GetAndClearGlobalSoup	A combination of the above two routines, but done in one atomic action, so nothing can slip in between the get and the clear.

Last updated 6/4/97.