| JSBDoc

JSBDoc Tool

The JSBDoc Tool is useful for creating JavaDoc-style documentation for JavaScript Beans. The structured programming provided by JavaScript Beans in combination with the ability to rapidly generate documentation for JSBs makes it easier to build more powerful JavaScript applications.

The tool itself consists of a command line wrapper around an invisible Java Bean which can be imported into tools like Sun's BeanBox. This makes it possible to build a graphical user interface using the same functionality.

Building and Using the JSBDoc Command-Line Tool

To use, simply set your classpath to include the JSBDoc directory of the CDK:

         classpath = INSTALLDIR/samples/JSBdoc/;rest of your classpath

Running the tool is then a matter of typing "java netscape.samples.jsbdoc.jsbdoc myFile.jsb". Included in the JSBDoc directory are two scripts (use either "jsbdoc.sh" or "jsbdoc.bat" depending on your platform). Make sure these scripts (you may have to edit them) refer to the correct location for the JSBDoc directory -- then, by adding the script to your regular path variable, you can run "jsbdoc myfile.jsb" from anywhere on your filesystem.

Running the tool on the second version of the HelloWorldJSB, you will see the following message:

    Generating documention for JSB HelloWorld
    Generating HelloWorld_jsb.html

The JSBDoc tool has created a HelloWorld_jsb.html file:

- JSBDoc generated from HelloWorld Component Source

The JSBDoc Tool consists of the following Java Classes:

- jsbdoc.java
- ParseJSB.java
- ReadFile.java
- WriteFile.java

The `BuildJSBDoc` script creates two JAR files using two different manifest files, `jsbdocJavaBean.mf` and `jsbdocJSB.mf`. The only difference between the two JAR files is in which file is treated as the main component for the archive. The jsbdocJavaBean.mf and the the jsbdocJavaBean.jar it creates indicates:

        Name: netscape/samples/jsbdoc/jsbdoc.class
        Java-Bean: True

Whereas jsbdocJSB.mf / jsbdocJSB.jar indicates:

        Name: netscape/samples/jsbdoc/jsbdoc.jsb
        Java-Bean: True

This creates two JAR files, each designed to be imported into a slightly different environment. While it is possible to import JavaBeans directly into Web Application Builders (like Visual JavaScript), there are times when it is useful to create a JavaScript Bean to encapsulate Java functionality -- and in this case, provide the JavaScript equivalents of key Java methods to allow for easier integration with the Browser's security infrastructure.

For information on using jsbdocJavaBean.jar, see the next section entitled "Using the JSBDoc component in the BeanBox", which illustrates using the jsbdoc bean in conjunction with another Java Bean to create a very simple appplication build on an AWT canvas.

For information on using jsbdocJavaBean.jar, see the later section below entitled "Using the JSBDoc component in Visual JavaScript", which illustrates using the jsbdoc bean in conjunction with HTML elements to create a full-featured appplication build on an HTML canvas.

Using the JSBDoc component in the BeanBox

The `jsbdocJavaBean.jar` file can be imported directly into the BeanBox . By placing the jsbdocComponents.jar file into the "jars" directory in the SUN BDK and running the BeanBox, one can wire a button to the parser to activate it. A more complex GUI can be built as well, but for now a button will be used to trigger the default parser action, which is to look for a file called "jsbdoc.jsb" in the directory where the BeanBox was run. A more complex GUI could set the file name dynamically.

Once in the BeanBox, drag one "Explicit Button" and one instance of "jsbdoc" which appear in the toolbox into the main BeanBox frame. Select the ExplicitButton that was added to the BeanBox, then choose the menu item "Edit...Events...button pushed...action performed". A red line will appear indicating a connection will be made -- close the connection by clicking on the "jsbdoc" component. An "EventTargetDialog" opens, prompting the choice of a target method. Choose "generateJSBDoc" as the target, and press OK. After the adaptor classes are built, going to the "View...Disable Design Mode" menu and pressing the ExplicitButton will cause the jsbdoc to generate a JSBDoc for the filename specified in the properties box for the jsbdoc component (this will default to looking for a file named "jsbdoc.jsb" in the directory where the beanbox was launched from).

Looking at the command line from which the BeanBox was launched, you will notice that the "jsbdoc" component ouput the same message as the command line tool (after all, it is using the same code):

    Generating documention for JSB jsbdoc
    Generating jsbdoc.html

Note: This example requires that the file `jsbdoc.jsb` is in the same directory as the BeanBox (for example, `BDKINSTALL/beanbox/`). Creating a complete example using JavaBeans that allow the user to choose an arbitrary JSB to convert is beyond the scope of this sample. This sample was intended simply to demonstrate that the JSBDoc JavaBean can be wired up in the BeanBox with a button to trigger a default action (reading, parsing, and writing documentation for jsbdoc.jsb).

Using the JSBDoc component in Visual JavaScript

Using the following steps, it is easy to create a simple HTML GUI for the JSBDoc tool:

- Open a new project in Visual JavaScript.
  - Create a new page.
  - Open the Component Palette and import the jsbdocJSB.jar file from `CDKINSTALL/samples/JSBdoc`.
- Drag the JSBDoc component that appears on the palette to the page.
  - Add a File Upload component to the page; a form will automatically be created around the component.
  - Add an HTML Button to the right of the File Upload component, changing its label to "Convert".

- Wire the "Convert" button to the JSBDoc component (drag connection point from button and drop on the component):
  - Bring up the ScriptBuilder for the "onClick" event and select the "generateJSBDoc()" method call.
  - Add this action to the onClick Script Handler, but do not close the Script Builder yet.

- Now switch to the "setProperty" tab:
  - Position the cursor in the "script handler" portion of the Script Builder, just before the code that got generated in the previous step.
  - Click the "Add Action" button, and highlight the "value?" portion of the script code that got generated:
    `netscape_samples_jsbdoc_jsbdoc1.fileName = value?`
- In the Script Builder, choose a different component from the dropdown, this time selecting "document.form1.FileUpload1", and select the "value" property and add the action.
- Trim the final "= value?" manually from the script, replacing it with a semicolon. Your onClick Script should now look like this:

      netscape_samples_jsbdoc_jsbdoc1.fileName = document.Form1.FileUpload1.value;
      netscape_samples_jsbdoc_jsbdoc1.generateJSBDoc();

- Press ok, apply the changes, then preview the page.
- Hit the "Browse" button to select a JSB file to create documentation for (you may need to set the file filter to "All Files *.*" or the equivalent for your platform).
- After selecting a file and returning to the HTML page, press the "Convert" button.
- A Java Security dialog will appear indicating that an unsigned Web Application is requesting permission to read and write files to your hard disk -- you may grant or deny permission at this time.
  - See the source code to jsbdoc.jsb to see the calls that trigger the necessary permission requests -- look for lines similar to:
    `netscape.security.PrivilegeManager.enablePrivilege("UniversalFileAccess");`
- After granting permission, you can look at the ouput in the Java Console, and you will see the same message (generated by the JSBDoc JavaBean parsing engine) which appeared when using the JSBDoc tool as part of a Java GUI Application, a command line tool, and now as a Web Application:

      Generating documentation for JSB jsbdoc
      Generating jsbdoc.html

A working simplified version of an HTML-GUI for the JSBDoc tool (generated using the steps above), can be found here (Page1.html).

Note: This example can only be run from your local file system if it is not signed. In order for a Web Application which makes use of advanced security functionality to be deployed, it must first be signed. For more information on signing Web Applications, see the Object Signing overview online.

Java Bean Components can be accessed both from Java command-line tools and from more complex GUIs (built using Java's AWT Canvas or an HTML Canvas) while re-using the same code and running across all major computing platforms.

( return to the top of the page )