#

## Appendix C

## Tuner Extensions

A newer feature of Castanet (as of this writing) is the ability to allow Windows or Solaris native-code libraries (DLLs or .so files) to be installed on the local client system (that is, on the system on which the tuner runs) and used by channels that run on that system. Tuner extensions are not downloaded and installed automatically, as normal channel files are; instead, the tuner extension files must be intentionally downloaded installed by the user for your channel to take advantage of them. In this way, tuner extensions are somewhat analogous to browser plug-ins: they extend the capabilities of channels to include specific functionality.

This appendix gives a quick overview of Tuner extensions; more information will appear on Marimba's Web site at `http://www.marimba.com/developer/`.

### When to Use Tuner Extensions

If at all possible, your channel should be written entirely in Java so that it has all the cross-platform and security features of Java and can be updated and provide channel feedback as all normal Java channels can. However, there may be instances where you need to include access to native libraries for select parts of your channel, for example:

- To access specific system features such as CD-ROM drives or special display systems that might not be accessible from within Java.
- To speed up very processor-intensive parts of a channel–for example, to do complex 3D rendering or mathematical equations.
- To leverage large amounts of existing code that has not (yet) been ported to Java.

Tuner extensions provide a way of gaining access to native capabilities and speed while still maintaining the flexibility of channels. Tuner extensions accomplish this by combining the channel code written in Java with a set of native libraries.

Tuner extensions are not a mechanism for getting around Castanet's use of Java; in fact, because they require the user to install the libraries, they don't provide any advantage over a regularly downloaded and installed program. Keep in mind also that tuner extensions are not cross-platform (you'll have to port them for each system that needs to run your channel), and are not updated automatically as part of the channel.

### Creating Tuner Extensions

Tuner extensions are created using Java's native method capabilities. If you don't know how to create native methods, any good Java book will have instructions on using native methods and developing the native code to implement those methods. (In fact, there's a good book that will teach you just that on the CD that comes with this book: Teach Yourself Java in 21 Days.) Your extension will generally be made up of a single Java class definition with a set of native methods, and then any number of native-code libraries to implement those methods. Try and keep the parts of your code that use native methods and the bulk of your channel separate from each other; this will make it easier to install, to update, and to manage the channel.

Keep in mind that because native code libraries must be downloaded and installed before they can be used by your channel, there is a strong possibility that a user might subscribe to your channel and NOT have those libraries installed. You can test for this case by catching the `NoClassDefFound` exception the first time you instantiate the Java class that uses the native code. If your channel runs and the native code is not yet installed, your channel will throw that exception. In the catch clause, you can then show an alert to tell the user where to download and install your native libraries (or, perhaps, work around the fact that they don't exist by running a slower or less efficient Java version of that code).

### Installing Extensions

On the client system, the native DLL file and your Java class with native methods must be installed in the top-level Tuner folder, in a directory called `etc` (for example, `C:\Marimba\Castanet Tuner\etc\` or `/usr/local/castanet/tuner/etc`). You may have to create this directory if it does not exist. You or the user must download and install those libraries manually; for security reasons they cannot be automatically installed by the channel itself.

Once you or your user has installed the extensions, restart the Tuner for the changes to take effect. On restart the `etc` directory will be added to the Java classpath for channels so that your channel can find any native libraries it needs.

### Summary

The intent for tuner extensions is to provide a simple mechanism for a channel to access native code functionality where it is required. It is not a mechanism for allowing native code to substitute for Java. Extensions are not part of the Castanet channel mechanism; they are not automatically updated, their libraries are not shared between channels, nor do they have access to the application context to be able to start or restart the way regular channels can. Also, because extensions are not subject to the security restrictions that channels are, they must be intentionally installed by each user.

For these reasons, its a good idea to keep the channel and the extension as separate as possible and to include only the bare minimum in the extension itself. Keep the bulk of the Java code for your channel in the channel itself so it can be updated and shared.

Marimba will provide more examples of tuner extensions on their Web server at `http://www.marimba.com/developer/`.