Pluglet Developers Guide
Pluglet Overview
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.
Types of Interfaces
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:
ByteRangesPlugletManagerPlugletManager2PlugletPeerPlugletStreamInfoPlugletTagInfoPlugletTagInfo2.
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:-
-
STREAM_TYPE_NORMAL
-STREAM_TYPE_SEEK
-STREAM_TYPE_AS_FILEor
-STREAM_TYPE_AS_FILE_ONLY
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.
Blackwood Release 0.9/Netscape PR3 Last modified 2/05/2001