Creating a Castanet Channel
By John Muchow

For more information about Marimba and Castanet, visit http://www.marimba.com; at this site, you can also download the Castanet Tuner along with an evaluation version of Bongo.

There's quite a bit of excitement in the developer community these days about Marimba's Castanet. Castanet simplifies the process of distributing, updating, and managing data and applications on intranets and the Internet. This efficient method of software distribution and content delivery is possible thanks to Castanet channels.

A channel is a Java program and all its associated data. This can be almost any program you can dream up—from a stock-tracking application to an online testing center. Channels are unique because they provide a means for software updates. Once you've subscribed to a channel, the updates are automatically and incrementally downloaded onto your computer. In addition, since a channel is downloaded in its entirety when you subscribe to it, you'll have increased performance and can run the channel offline.

In this article, we'll show you how to use JBuilder to create the Castanet channel shown in Figure A. This channel is a slimmed-down version of Blaster News, an online news and information source about Marimba and Channel Blaster. At the end of the article, we'll tell you more about where to find, and how to subscribe to, Blaster News.

Figure A: We'll show you how to create this Castanet channel.

Creating a channel
Three essential software components make up Castanet: the Tuner, the Transmitter, and the Publisher. The Tuner is a client application that allows users to subscribe to and view Castanet channels. The Transmitter is analogous to a Web server—however, it serves up channels. The Publisher makes a channel available on a Transmitter.

Generally, you (the developer) create a Java channel. Using the Publisher, you then transfer the files to the Transmitter. The rest of the world then uses the Tuner to subscribe to and view the channel.

We'll keep our example rather simple by limiting the channel's features. Figure A shows the channel as it appears when launched with the Marimba Tuner. The window displays two articles and provides an Options tab that lets us update the channel content online.

We created our channel's interface using Bongo, a GUI development tool available from Marimba. Although you don't have to use Bongo to create Castanet channels, doing so can greatly reduce interface development time. Figure B shows Bongo at work.

Figure B: Marimba's Bongo lets you easily create Castanet channels.

As you can see, Bongo provides control over property information, as do other visual development tools. The window shown in Figure B displays information for a Bongo static textbox. Note the Name field—stxtDate—because you'll see it again very soon.

Figure C shows the visual interface that Bongo presents. Here, you add, arrange, and size components, which Bongo refers to as widgets.

Figure C:You add and manipulate widgets in Bongo's visual interface.

The textbox containing the date is stxtDate. You'll see this name one last time when we discuss how our Java program interacts with the Bongo interface.

Bongo's output is called a presentation. This binary file, also called a gui file, contains all the information about the interface you create. You'll use this file when you publish the channel. Now, let's create the JBuilder project.

The JBuilder project
Once you have JBuilder up and running, select File | New… from the main menu. Double-click on Application to launch the Project Wizard. Fill in the text fields and click Finish. At this point, you'll be in Step 1 of the Application Wizard. In the Package and Class fields, enter BlasterNews. Click Next to move to step 2. Once again, enter BlasterNews in the Class field, then click Finish.

Before moving on, save the project by choosing File | Save As…. Enter the filename BlasterNews.jpr and click Save. You've now created the basic shell of your channel.

The Java source
Here's my favorite part—deleting code. Since you aren't going to use a frame to display your interface, you can remove all frame references. At the same time, you'll delete all the initialization code that JBuilder so kindly wrote for you. (You'll build all you need from scratch.)

Click on BlasterNews.java in the Navigation Pane's upper-left corner, then click in the source code window. Mark the entire document and press [Delete]. Now type the following lines at the top of the source file:

package BlasterNews;
import java.awt.*;
import java.util.*;
import java.net.*;
import java.io.*;
import marimba.gui.*;
import marimba.channel.*;
import marimba.io.*;

Importing marimba.gui.* gives you access to the widgets you created within Bongo. Importing marimba.channel.* provides the classes that you need specifically for creating and manipulating channels, and the marimba.io.* files provide extensions to the Java classes for input and output. We've elected to use these classes because they're very fast and unsynchronized.

Next, enter the main class definition, as follows:

public class BlasterNews extends ApplicationPlayerFrame

We use the ApplicationPlayerFrame class when we have a channel that uses a Bongo presentation file for the interface, as is the case here. Marimba will handle all the details of loading the interface and presenting it onscreen.

The next important declarations are those of the widgets in the Bongo presentation—at least those widgets that you'd like to access from within your class file. Here are two of the declarations:

private CommandButtonWidget btnUpdateW;
private StaticTextWidget stxtDateW;

In a moment, we'll show how to initialize and access these variables.

Inside a Castanet channel
The application interface supplied by Marimba defines four methods: start(), stop(), handleEvent(), and setContext(). We're interested only in the first three for this example.

The start() method
You call start() once to initialize the channel. In our example, the code is as follows:

public void start()
{
super.start();
btnUpdateW = (CommandButtonWidget)
util.getWidget("btnUpdate");
stxtDateW = (StaticTextWidget)
util.getWidget("stxtDate");
loadStories();
}

Notice how you've now tied the Bongo widgets btnUpdate and stxtDate to local variables defined in this class. Through the call to util.getWidget(), you create a reference to the variable as defined from within Bongo. Once you have this reference, you can update the interface at any time in your program by calling the setText() method, as follows:

stxtDateW.setText("September 14, 1997");

When we discuss event handling, we'll demonstrate how to use btnUpdateW.

You can put any other initialization code you need for your channel in start(). For example, the loadStories() method reads the articles and stores them in widgets.

The Stop() method
You call stop() once when exiting the channel. Place any necessary clean-up code here, to perform such tasks as saving user options to disk.

The handleEvent() method
The handleEvent() method includes several Castanet-specific events we're interested in catching. DATA_AVAILABLE_EVENT tells your channel that a change has taken place. These changes can be content (as in an article) or class file changes (as in a new interface).

Typical processing for this event is as follows:

case DATA_AVAILABLE_EVENT:
context.installData("");
return;

The parameter to installData() is a filename or directory to update. By passing in "", you request that all changes be installed. DATA_INSTALLED_EVENT is called after all updates have taken place. At this point, you can perform any changes to the application. For instance, you might want to call loadStories() once again to update the articles on the display.

Action events are handled as they are in a typical Java program. Our example uses the following lines:

case evt.ACTION_EVENT:
if (evt.target == btnUpdateW)
{
context.update(); // Do immediate update
return true;
}

Notice that you're looking to see if the target of the event is the Bongo button btnUpdateW. If so, you call the Marimba update() method to perform an immediate update of the channel content. This step is useful if you know the content has changed and you'd like the data immediately, rather than waiting until the scheduled update occurs.

We've now discussed several unique features that distinguish a channel from a typical Java application. To complete this channel, enter the remaining code, available in feb98.zip, into JBuilder and make the project. The next step is to publish your files to a Transmitter.

Using the Publish tool
Figure D shows the Marimba Publish tool interface. The Name field holds the name that the Tuner will display when listing channels on a Transmitter.

The Classpath field specifies the search path to locate class files that are downloaded with the channel. The Main Class field refers to the class called when starting the channel. Our example, BlasterNews.BlasterNews, implies that the main class is in a package (directory) called BlasterNews, with the class name BlasterNews. The GUI File is the Bongo presentation to load when starting the channel.

In the Type field, you select one of four types of channels to publish: Application, Applet, Presentation, or HTML. Let's look at each of these options.

Figure D: You'll use this Publish tool to place your channel files on a Transmitter.

Channel-type options
Application channels are Java programs that implement the Marimba classes, such as the channel we're discussing here. An Applet channel lets you publish almost any Java applet. In addition, if you make a few minor modifications, you can use the Castanet channel features, such as reading and writing local channel files and communicating with the Transmitter.

A Presentation channel is created solely from within Bongo. Note that Bongo includes what are referred to as Java scripts. Through scripting, you can override or add your own methods. However, if you find yourself writing long, complicated scripts, you should consider implementing the Marimba classes for an Application channel and loading the Bongo presentation(s) from there.

An HTML channel is essentially a Web site viewed as a channel. This feature is significant because it lets you download an entire Web site and have the files available locally on your machine. You can view your favorite Web pages offline and use the Tuner periodically to update the information.

Blaster News online
Blaster News is currently hosted on a Transmitter at Marimba. The exact location is trans.havefun.com:5282. (For what it's worth, 5282 is JAVA, as spelled using a telephone keypad.)

Figure E shows the Tuner and the channel listing for trans.havefun.com. To subscribe to a channel, double-click on the entry; doing so will download all the files for that channel and launch it on your computer.

Figure E: You can subscribe to Blaster News using the Tuner.

The next time you'd like to run the channel, you'll find it listed in your Windows Start menu under Channels. This is a nice feature, since you don't need to be connected to the Internet to run a channel—instead, you can download the channel and read it at your leisure. You must check back with the Transmitter only when you want to get channel updates.

Summary
In this article, we've offered some insight into just what it takes to create a Castanet channel. It's very similar to a standard Java application. Essentially, you simply need to familiarize yourself with the Marimba classes and their methods. Our example provides a good starting point to explore what the excitement is all about regarding channels.