Pluglet Overview

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

• Pluglet Definition
• How Pluglets Work
• Required Interface Implementations

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 C++ Plugin API of Mozilla.

How Pluglets Work

When a MIME type is first encountered by the Mozilla browser, it checks if there is a native Plugin for it. If there is not, it creates an instance of PlugletFactory and attempts to created an instance of Pluglet for the MIME type.

A manifest file, which the Pluglet developer must write, informs the PlugletFactory instance if there is an implementation of Pluglet that handles the MIME type. This occurs through the createPluglet() method of PlugletFactory, which takes the MIME type as an argument. (For more on MIME types and manifest files, see MIME Types and Manifest Files.)

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 there is normally 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.

The Pluglet developer must implement the following three interfaces:

• PlugletFactory
• Pluglet
• PlugletStreamListener

They are described in general in the sections below, and in detail in the API.

Other interfaces that the 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.

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 should call 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 PlugletStreamListener interface is described below.)

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:

• STREAM_TYPE_NORMAL
• STREAM_TYPE_SEEK
• STREAM_TYPE_AS_FILE or
• STREAM_TYPE_AS_FILE_ONLY

(See the API 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 for failure of the load.