Simple Pluglet

This example illustrates how to create a pluglet and package it into a jar which you simply place in the browser's "plugins" directory. Before we get started, let's see it run!

Required Code Artifacts

Creating a pluglet requires creating several code arifacts:

1. A Java class that implements PlugletFactory.

   Details

   1. package simple;
   2.  
   3. import java.awt.Button;
   4. import java.awt.Frame;
   5. import java.awt.List;
   6. import java.awt.Panel;
   7. import java.awt.event.ActionEvent;
   8. import java.awt.event.ActionListener;
   9. import java.awt.print.PrinterJob;
   10. import java.io.BufferedReader;
   11. import java.io.InputStream;
   12. import java.io.InputStreamReader;
   13. import org.mozilla.pluglet.Pluglet;
   14. import org.mozilla.pluglet.PlugletFactory;
   15. import org.mozilla.pluglet.PlugletStreamListener;
   16. import org.mozilla.pluglet.mozilla.PlugletManager;
   17. import org.mozilla.pluglet.mozilla.PlugletPeer;
   18. import org.mozilla.pluglet.mozilla.PlugletStreamInfo;
   19. import org.mozilla.pluglet.mozilla.PlugletTagInfo;
   20. import org.mozilla.pluglet.mozilla.PlugletTagInfo2;
   21.  
   22.  
   23. public class SimplePluglet implements PlugletFactory {
   24.     public SimplePluglet() {
   25.         org.mozilla.util.DebugPluglet.print("--test.test()\n");
   26.     }
   27.     /**
   28.      * Creates a new pluglet instance, based on a MIME type. This
   29.      * allows different impelementations to be created depending on
   30.      * the specified MIME type.
   31.      */
   32.     public Pluglet createPluglet(String mimeType) {
   33.         org.mozilla.util.DebugPluglet.print("--test.createPlugletInstance\n");
   34.         return new SimplePlugletInstance();
   35.     }
   36.     /**
   37.      * Initializes the pluglet and will be called before any new instances are
   38.      * created.
   39.      */
   40.     public void initialize(String plugletPath, PlugletManager manager) {
   41.         org.mozilla.util.DebugPluglet.print("--test.initialize(" +
   42.                                             plugletPath + ")\n");
   43.     }
   44.     /**
   45.      * Called when the browser is done with the pluglet factory, or when
   46.      * the pluglet is disabled by the user.
   47.      */
   48.     public void shutdown() {
   49.         org.mozilla.util.DebugPluglet.print("--test.shutdown\n");
   50.     }
   51. }

2. A Java class that implements Pluglet, instances of which are created and returned by the PlugletFactory.

   Details

   1. class SimplePlugletInstance implements Pluglet {
   2.     Panel panel;
   3.     Button button;
   4.     List list;
   5.     PlugletPeer peer;
   6.     public SimplePlugletInstance() {
   7.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.SimplePlugletInstance() \n");
   8.         panel = new Panel();
   9.         button = new Button("Press me :)");
   10.         button.addActionListener(new ActionListener() {
   11.                 public void actionPerformed(ActionEvent e) {
   12.                     int t = list.getSelectedIndex();
   13.                     t++;
   14.                     if (t >= list.getItemCount()) {
   15.                         t = 0;
   16.                     }
   17.                     list.select(t);
   18.                 }
   19.             }
   20.                                  );
   21.         panel.add(button);
   22.         list = new List(4,false);
   23.         list.add("Pluglet");
   24.         list.add("not");
   25.         list.add("bad");
   26.         list.select(0);
   27.         panel.add(list);
   28.     }
   29.     /**
   30.      * Initializes a newly created pluglet instance, passing to it the pluglet
   31.      * instance peer which it should use for all communication back to the browser.
   32.      *
   33.      * @param peer the corresponding pluglet instance peer
   34.      */
   35.  
   36.     public void initialize(PlugletPeer peer) {
   37.         this.peer = peer;
   38.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.initialize\n");
   39.         peer.showStatus("Hello world");
   40.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.initialize  "+peer.getMIMEType());
   41.         /*
   42.         try {
   43.             OutputStreamWriter out = new OutputStreamWriter(peer.newStream("text/plain","_new"));
   44.             String msg = "Hello, world";
   45.             out.write(msg,0,msg.length());
   46.             out.flush();
   47.             out.close();
   48.         } catch (Exception e) {
   49.             ;
   50.         }
   51.         */
   52.     }
   53.     /**
   54.      * Called to instruct the pluglet instance to start. This will be called after
   55.      * the pluglet is first created and initialized, and may be called after the
   56.      * pluglet is stopped (via the Stop method) if the pluglet instance is returned
   57.      * to in the browser window's history.
   58.      */
   59.     public void start() {
   60.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.start\n");
   61.     }
   62.     /**
   63.      * Called to instruct the pluglet instance to stop, thereby suspending its state.
   64.      * This method will be called whenever the browser window goes on to display
   65.      * another page and the page containing the pluglet goes into the window's history
   66.      * list.
   67.      */
   68.     public void stop() {
   69.        org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.stop\n");
   70.     }
   71.     /**
   72.      * Called to instruct the pluglet instance to destroy itself. This is called when
   73.      * it become no longer possible to return to the pluglet instance, either because
   74.      * the browser window's history list of pages is being trimmed, or because the
   75.      * window containing this page in the history is being closed.
   76.      */
   77.     public void destroy() {
   78.        org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.destroy\n");
   79.     }
   80.     /**
   81.      * Called to tell the pluglet that the initial src/data stream is
   82.      * ready.
   83.      *
   84.      * @result PlugletStreamListener
   85.      */
   86.     public PlugletStreamListener newStream() {
   87.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.newStream\n");
   88.         return new TestStreamListener();
   89.     }
   90.     /**
   91.      * Called when the window containing the pluglet instance changes.
   92.      *
   93.      * @param frame the pluglet panel
   94.      */
   95.     public void setWindow(Frame frame) {
   96.         org.mozilla.util.DebugPluglet.print("--Test...SetWindow "+frame+"\n");
   97.         if(frame == null) {
   98.             return;
   99.         }
   100.         PlugletTagInfo info = peer.getTagInfo();
   101.         if (info instanceof PlugletTagInfo2) {
   102.             PlugletTagInfo2 info2 = (PlugletTagInfo2)info;
   103.             frame.setSize(info2.getWidth(),info2.getHeight());
   104.             org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.SetWindow width "+info2.getWidth()+ " height "+info2.getHeight()+"\n");
   105.             org.mozilla.util.DebugPluglet.print("--Test...SetWindow "+frame+"\n");
   106.         }
   107.         frame.add(panel);
   108.         frame.pack();
   109.         frame.show();
   110.     }
   111.      /**
   112.      * Called to instruct the pluglet instance to print itself to a printer.
   113.      *
   114.      * @param print printer information.
   115.      */
   116.     public void print(PrinterJob printerJob) {
   117.     }
   118.    
   119.     protected void finalize() {
   120.         org.mozilla.util.DebugPluglet.print("--SimplePlugletInstance.finalize()\n");
   121.     }
   122.  
   123.  
   124. }

3. A Java class that implements PlugletStreamListener, if the Pluglet uses the getURL() or postURL() methods on the PlugletManager passed to plugletFactory.initialize().

   Details

   1. class TestStreamListener implements PlugletStreamListener {
   2.     public TestStreamListener() {
   3.         org.mozilla.util.DebugPluglet.print("--TestStreamListener.TestStreamListener()\n");
   4.     }
   5.     /**
   6.      * Notify the observer that the URL has started to load.  This method is
   7.      * called only once, at the beginning of a URL load.<BR><BR>
   8.      */
   9.     public void onStartBinding(PlugletStreamInfo streamInfo) {
   10.         org.mozilla.util.DebugPluglet.print("--TestStreamListener.onStartBinding ");
   11.         org.mozilla.util.DebugPluglet.print("length "+streamInfo.getLength());
   12.         org.mozilla.util.DebugPluglet.print(" contenet type "+ streamInfo.getContentType());
   13.         org.mozilla.util.DebugPluglet.print(" url "+ streamInfo.getURL());
   14.         org.mozilla.util.DebugPluglet.print(" seekable "+ streamInfo.isSeekable());
   15.        
   16.     }
   17.     /**
   18.      * Notify the client that data is available in the input stream.  This
   19.      * method is called whenver data is written into the input stream by the
   20.      * networking library...<BR><BR>
   21.      *
   22.      * @param input  The input stream containing the data.  This stream can
   23.      * be either a blocking or non-blocking stream.
   24.      * @param length    The amount of data that was just pushed into the stream.
   25.      */
   26.     public void onDataAvailable(PlugletStreamInfo plugletInfo, InputStream input,int  length) {
   27.         try{
   28.             org.mozilla.util.DebugPluglet.print("--TestStreamListener.onDataAvailable ");
   29.             org.mozilla.util.DebugPluglet.print("--length "+input.available()+"\n");
   30.             String cur = null;
   31.             BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(input));
   32.             while (null != (cur = bufferedReader.readLine())) {
   33.                 org.mozilla.util.DebugPluglet.print(cur);
   34.             }
   35.         } catch(Exception e) {
   36.             ;
   37.         }
   38.     }
   39.     public void onFileAvailable(PlugletStreamInfo plugletInfo, String fileName) {
   40.         org.mozilla.util.DebugPluglet.print("--TestStreamListener.onFileAvailable\n");
   41.         org.mozilla.util.DebugPluglet.print(" fileName" + fileName);
   42.     }
   43.     /**
   44.      * Notify the observer that the URL has finished loading.
   45.      */
   46.     public void onStopBinding(PlugletStreamInfo plugletInfo,int status) {
   47.         org.mozilla.util.DebugPluglet.print("--TestStreamListener.onStopBinding\n");
   48.     }
   49.     public int  getStreamType() {
   50.         org.mozilla.util.DebugPluglet.print("--TestStreamListener.getStreamType\n");
   51.         return 1; //:)
   52.     }
   53. }

4. A Java JAR file containing the .class files compiled from the above Java files. The manifest for the JAR must contain the following entries:

   Manifest attribute name	Explanation	Value for this example
   MIMEDescription	The mime-type to be handled by this pluglet.	application/x-simple-pluglet
   Pluglet-Class	The fully qualified class name of the Java class implementing PlugletFactory.	simple.SimplePluglet

5. Some HTML markup that includes the pluglet. Note: this step is exactly the same as for any other native plugin.

   Details

   1.  
   2. <EMBED type="application/x-simple-pluglet" name="test"
   3.        src="index.html" width=400 height=200>

Calling a Pluglet from JavaScript

This release of pluglets allows a limited degree of communication between JavaScript and the Pluglet class. Through the magic of Netscape's XPConnect code, it is possible to invoke, from JavaScript in the page in which the pluglet is embedded, an arbitrary method on the pluglet, provided the method returns String, and takes anywhere between zero and ten String arguments. Such a method is called a "conforming method" for the rest of this discussion.

In the above example, the four plain ole' HTML buttons labeled "Call Pluglet N arg" (where N is a number between 0 and 3) call a Java method on the pluglet. Click the Details button on the right to see the JavaScript code.

Details

1. var embed = document.embeds[0];
2.  
3. function callPluglet0()
4. {
5. var strs2 = {
6.     value : []
7. };
8.  
9. var strslen2 = {
10.     value : strs2.value.length
11. };
12.  
13.   embed.callPlugletMethod("calledFromJavaScript0", strslen2, strs2);
14.   alert("Pluglet returned " + strs2.value);
15. }
16. function callPluglet1()
17. {
18. var strs2 = {
19.     value : [ "arg0" ]
20. };
21.  
22. var strslen2 = {
23.     value : strs2.value.length
24. };
25.  
26.   embed.callPlugletMethod("calledFromJavaScript1", strslen2, strs2);
27.   alert("Pluglet returned " + strs2.value);
28. }
29. function callPluglet2()
30. {
31. var strs2 = {
32.     value : [ "arg0", "arg1" ]
33. };
34.  
35. var strslen2 = {
36.     value : strs2.value.length
37. };
38.  
39.   embed.callPlugletMethod("calledFromJavaScript2", strslen2, strs2);
40.   alert("Pluglet returned " + strs2.value);
41. }
42. function callPluglet3()
43. {
44. var strs2 = {
45.     value : [ "arg0", "arg1", "arg2" ]
46. };
47.  
48. var strslen2 = {
49.     value : strs2.value.length
50. };
51.  
52.   embed.callPlugletMethod("calledFromJavaScript3", strslen2, strs2);
53.   alert("Pluglet returned " + strs2.value);
54. }

Line 1 is standard JavaScript to get the 0th <EMBED> element in the page, which happens to be our pluglet. The functions callPluglet0, callPluglet1, callPluglet2 and callPluglet3, declared on lines 3, 16, 29, and 42, respectively, are called from the onclick handler of the HTML buttons in the page. Each of these functions calls a Java method implemented on the pluglet using the special callPlugletMethod JavaScript function defined on the XPConnect API for pluglet. The general form of this JavaScript method is:

The Java code for the methods calledFromJavaScriptN (where N is a number between 0 and 3) can be seen by expanding the Details button on the right. These methods are defined on the class SimplePlugletInstance.

Details

1.     public String calledFromJavaScript3(String arg0, String arg1, String arg2) {
2.         org.mozilla.util.DebugPluglet.print("calledFromJavaScript2\n");
3.         return "3 args.  arg0: " + arg0 + " arg1: " + arg1 + " arg2: " + arg2 + "";
4.     }
5.  
6.     public String calledFromJavaScript2(String arg0, String arg1) {
7.         org.mozilla.util.DebugPluglet.print("calledFromJavaScript2\n");
8.         return "2 args.  arg0: " + arg0 + " arg1: " + arg1 + "";
9.     }
10.  
11.     public String calledFromJavaScript1(String arg0) {
12.         org.mozilla.util.DebugPluglet.print("calledFromJavaScript1\n");
13.         return "1 args.  arg0: " + arg0 + "";
14.     }
15.  
16.     public String calledFromJavaScript0() {
17.         org.mozilla.util.DebugPluglet.print("calledFromJavaScript0\n");
18.         return "0 arg hard coded result";
19.     }
20.  

NOTE: One convenient interchange format would be to return JSON strings from your conforming methods.