| 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:
The JSBDoc Tool consists of the following Java Classes:
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:
CDKINSTALL/samples/JSBdoc
.
netscape_samples_jsbdoc_jsbdoc1.fileName = value?
netscape_samples_jsbdoc_jsbdoc1.fileName = document.Form1.FileUpload1.value; netscape_samples_jsbdoc_jsbdoc1.generateJSBDoc();
netscape.security.PrivilegeManager.enablePrivilege("UniversalFileAccess");
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.