Pluglet Developers Guide

Pluglet Overview

MIME types | display modes | examples | API index

Basics

This section defines what Pluglets are , provides a broad overview of how Pluglets work from a Pluglet developer perspective, and briefly describes the three interfaces that a developer must implement.

Pluglet Definition

A Pluglet is a Mozilla Plugin written in Java using the Pluglet API. Using the Java Native Interface (JNI), the Pluglet API mimics the new C++ Plugin API of Mozilla.

For more information about Mozilla Plugins, see http://www.mozilla.org/docs/plugin.html. (If you are new to Plugins, you may want to refer to the old Netscape Plug-in Guide at http://developer.netscape.com/docs/manuals/communicator/plugin/index.htm). It is a good resource for understanding Plugin fundamentals.)

How Pluglets Work

First, a Pluglet developer implements the three interfaces listed below and writes related manifest files. A manifest file contains a list of supported MIME types. (For more information on MIME types and manifest files, see MIME types above.)

When a MIME type is first encountered by the Mozilla browser, it checks to see that there is a native Plugin for it. If there is not, it looks for a Pluglet that handles the MIME type. It does this through PlugletEngine.

These interfaces are described in general in the sections below, and in detail in the API index. Note that when Pluglet is built and the implementations of these interfaces are compiled, they are placed in a .jar file along with the related manifest file. This .jar file is called the Pluglet bundle.

When PlugletEngine looks for a Pluglet for a MIME type, it looks at each manifest file in each bundle to determine if one handles the MIME type. If the manifest file lists the MIME type, then it also points to the PlugletFactory for the Pluglet.

If a Pluglet is found that can handle the MIME type, the browser creates an instance of PlugletFactory and uses that to create an instance of Pluglet for the MIME type. (PlugletFactory knows the name of the Pluglet class to load.)

Once an instance of Pluglet has been created, the browser may call the newStream() method of Pluglet, creating an instance of PlugletStreamListener, which is used for notification and passing of information about the stream.

Note that for a Pluglet bundle there will be only a single instance of PlugletFactory, but there can be multiple instances of Pluglet and PlugletStreamListener. Note, also, that an instance of Pluglet can handle more than one MIME type.

Pluglets, like Plugins, can be invoked in various ways. They may be embedded in an HTML page via an EMBED or OBJECT tag. They may also be full-page Pluglets existing in a window of their own. (For more information on how Pluglets can be invoked, see Pluglet Display Modes.)

When a Pluglet is embedded in a page with an EMBED or OBJECT tag, the TYPE attribute should normally be included. The TYPE attribute specifies the MIME type of the media.

Other interfaces that the Pluglet developer should know about, and that have been implemented to make Pluglets work, are the following:

ByteRanges
PlugletManager
PlugletManager2
PlugletPeer
PlugletStreamInfo
PlugletTagInfo
PlugletTagInfo2.

For a general description of each, read the overview for each in the API index.

Required Interface Implementations

To create a Pluglet, the developer must implement the following three interfaces.

PlugletFactory Interface

The browser typically passes the MIME type to the createPluglet() method of PlugletFactory, and this method returns an instance of Pluglet for that MIME type. But first PlugletFactory needs to be initialized via its initialize() method, to which an instance of PlugletManager is passed.

When the browser is done with the PlugletFactory instance, it calls shutdown().

Pluglet Interface

Once an instance of Pluglet has been created, its initialize() method should be called, passing to it an instance of PlugletPeer. The Pluglet instance should use the PlugletPeer instance for all communication with the browser.

The start() method may then be called to start the Pluglet instance.

If the Pluglet involves a data stream, when the data stream is ready the browser calls newStream() to inform the Pluglet instance. newStream() returns an instance of PlugletStreamListener, to which the browser sends notifications and information about the stream.

The browser uses the setWindow() method to tell the Pluglet instance what frame it is in, and the implementation of this method may add additional components and functionality to the frame.

The Pluglet interface also includes stop(), print(), and destroy() methods.

PlugletStreamListener Interface

PlugletStreamListener is used for notification. Its methods are called by the browser to make a variety of conditions known and to pass information.

getStreamType() returns the type of the stream, which can be:
(See the API index for a detailed description of each of these stream types.)
onStartBinding() is used for notification that a URL has started to load.
onDataAvailable() is used for notification that data is available on the input stream.
onFileAvailable() is used for notification that a local file name is available and for passing the file name.
onStopBinding() is used for notification that a URL has stopped binding, and it passes status information about the success or failure of the load.