XulBrowser Specification
R.J. Keller
Draft 0.2 Beta
Send feedback to rlkeller@purdue.edu
Table of contents
- Application Format
- Running Web Applications
- Easier ways of running web applications
- JavaScript<->Java Bridge
- XML ApplicationRunner Language (XAL)
- JDBC Database connections
- Pure Java application execution
Application Format
Each application will be run from a JavaScript file. This file will contain a main() method from where the program will be started. Provided classes will be the entire XulParser and Java 1.5 libraries. For GUI you can use XUL (preferred and increased debugging capabilites) or JFC/Swing.
Connectors to the entire Java library will be provided. XulBrowser’s JavaScript will come with a built-in function to import Java classes. The Package variable will be the connector to all Java packages. So if you want to use JFrame in a variable, you do var myWindow = new Packages.javax.swing.JFrame(“myWindow”);. Of course this can get icky for large class names like the XulParser, so to import java classes like, for example, com.trfenv.parsers.xul, you run importPackage(Packages.com.trfenv.parsers.xul). All extra JavaScript libraries provided with XulBrowser will have JavaDoc API information available.
XUL
Using XUL will significantly simplify your life in the long run, but does have a huge learning curve that can make things difficult.
Despite this, there are a number of tutorials on XUL. One of the best tutorials is at XUL Planet.
Here is an example program using XUL:
File: http://localhost/test.js
importPackage(Packages.com.trfenv.parsers); importPackage(Packages.net.sourceforge.xulbrowser.connectors); function main() { var xulFrame = new xulFrame(new UrlInputStream("http://localhost/test.xul")); xulFrame.JavascriptEngine.setObjectReference(xulFrame, "document"); xulFrame.JavascriptEngine.setObjectReference(xulFrame, "window"); xulFrame.initializeJavascript(); xulFrame.setVisible(true); } function close() { java.lang.System.exit(0); }
File: http://localhost/test.xul
<?xml version="1.0"?> <window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" width="346" height="211" title="Macros"> <script type="application/x-javascript" src="http://localhost/test.js"/> <hbox> <vbox flex="1"> <label value="Macro name:"/> <textbox id="macroName" multiline="false"/> <listbox id="macroList" flex="1"/> </vbox> <vbox> <button label="Run" onclick="run();"/> <button label="New" onclick="newMacro();"/> <button label="Edit" onclick="edit();"/> <button label="Delete" onclick="delete();"/> </vbox> </hbox> </window>
To run this application, just type in http://localhost/test.js into your XulBrowser URL bar or through the command line argument:
java -jar xulbrowser.jar http://localhost/test.js
Running Web Applications
You'll notice that XulBrowser looks like a standard web browser when you load it. This will allow you to browse web pages using Java's HTML 3.2-compliant engine. In order to run a application from a web page, create a link to your JS file containig your main() method. This file must end in .js and when clicked will run your application with full privileges.
Note that XulBrowser is not designed to be used as a web browser because of its poor HTML & CSS support. Only use it to access your web applications.
There are two ways that XulBrowser will be able to run a Web application. One of those ways if from a web page. If you have a link to a file ending in .js, this will automatically trigger the JS engine to run the main() method of that file. If you want to use server-side code in your main method, we recommend you use a XUL file (executed in main()) that can end in any extension and import JS files in any extension. The onload attribute of the window XUL tag should give you similar capabilities.
A second way to run your web apps (especially for people wanting to use PHP or some other server-side scripting in their application) is to use the XML ApplicationRunner format. This will allow a number of applications provided by an organization to be displayed in Windows-explorer like interface. The user can then double-click the icon to run the app. The icons and the JS file they connect to will be loaded using a special XML format that will end in xal (XML ApplicationRunner Language). This, just like JS files, will trigger the XulBrowser to open the IconViewer window.
Easier ways of running web applications
Having your user’s type in a URL every time they want to run your application is tedious. XulBrowser will allow you to take in a URL as a command-line argument or allow you to open up a xal file (described above) through File->Open. These files can be held locally and allow a easy way to run web apps off the desktop. But since .xal files need to be updated manually to add new applications, it is recommended that you use the command-line arguments for running your application in order to keep manageability as high as possible.
JavaScript<->Java Bridge
We will, in your XUL documents, provide a way to import Java class files into your JavaScript application. This will be done using the importClassFile() function, which takes in a string URL to your class file location on the server and add it to your classpath.
You can also access your JS documents from within Java. To do this, you can use com.trfenv.xulbrowser.ui.frmBrowser.getJsEngine(). This returns a JS engine object that will allow you to run certain JavaScript statements, functions, or add input streams to the scope.
Most of the connections between JavaScript and Java are provided by Rhino, a port of mozilla.org's JavaScript engine to Java. Although Rhino is not quite as up to date as the JavaScript engine Firefox uses, it's very close, so it does provide extensive scripting abilities. Information about using Rhino with Java can be found in the Rhino documentation page (http://www.mozilla.org/rhino/doc.html).
These can be linked from a web page or typed directly in the URL bar.
XML ApplicationRunner Language (XAL)
Will be in the following format:
<appDisplay xmlns="http://xulbrowser.sourceforge.net/languages/xal"> <application> <script type="application/javascript" src="http://rj.pcblaze.com/app-portal/test.js"/> <name>XulParser</name> </application> <application> ... <application> </appDisplay>
When the JavaScript code is parsed and executed, the main() function is then ran.
JDBC Database connections
Although you can very easily use server-side scripting in your web apps to perform database queries, XulBrowser will come with a simple set of APIs that will allow you to access JDBC information. The process will be simplified through a easy-to-use database which can be extended for a database engine that might not use JDBC. Through this united database interface, we will provide a JDBC Connector and a MySQL connector. Although you can use the JDBC Connector to hook into your MySQL database, the MySQL Connector simplifies things a bit when connecting.
You may be asking, why make another separate database API when we have JDBC? The problem with JDBC is it's much more dificult to use and implement than something like PHP+MySQL. The goal for this API is to make it as easy as PHP+MySQL. Not only that, it's easier to support other database/storage formats with a simplified API.
Pure Java application execution
If you already have a Java application that you would like to run through XulBrowser without having to port it to XUL/JS, you can execute that application by importing the Java classes using the methods above in JS and making your JavaScript main() method call your Java main method. This will save you all of the time to port your application plus save you money on having to train your programming team on a new language.
Unlike applets or other ways of running Java apps on a users computer, XulApp grants full permissions to your applications. You can do whatever you want on the users computer without having to worry about security! By using XulBrowser, the user agrees to running applications only from sources they trust.