Getting Started with Jaxcent

1. Running Jaxcent Samples
2. Running Jaxcent from the Command Line
3. Running Jaxcent in an IDE
4. Configuring Jaxcent with a Web Server or a Java Application Server
5. Writing the Jaxcent Configuration XML File
6. Adding the JavaScript include statement
7. Writing the Jaxcent implementation classes
8. Adding Jaxcent to existing applications
9. Designing New Applications in Jaxcent
10. JavaScript and Jaxcent
11. Performance Considerations
12. Form Submit Behavior
13. Virtual Host configuration
14. Other Documentation

Running Jaxcent Samples

Running Jaxcent from the Command Line

    java jaxcentServer.ServerMain <port-number> <HTML-root> <XML-Config-file> <Optional-Reloadable-classpath>

    java jaxcentServer.ServerMain 80 C:\MyHtmlFiles C:\JaxcentConfig.xml

    java jaxcentServer.ServerMain 80 C:\MyHtmlFiles C:\JaxcentConfig.xml C:\MyJaxcentClasses

Running Jaxcent in an IDE

    ServerMain jaxcentServer = new ServerMain( 80, htmlDir, xmlConfigFile, reloadableClasspath );
    jaxcentServer.start();

Using Jaxcent with Web Servers or Java Servlet Containers

It can also be configured to work directly with Microsoft IIS web-server, or the Apache web-server.

If using a Java servlet container, Apache or IIS, the file jaxcent21.js must be made available at the URL location.

    /jaxcent21.js

Also, the Jaxcent servlet (or connector) needs to be available at the URL location

    /servlet/JaxcentServlet21

Depending upon your environment, please visit the appropriate link below for configuring the Jaxcent servlet/connector.

• Configuring Jaxcent with a Java servlet container (Java application server) such as Tomcat
• Configuring Jaxcent to work directly with Internet Information Services (IIS) web server.
• Configuring Jaxcent to work directly with the Apache web server.

Writing the Jaxcent configuration file

<JaxcentConfiguration>
 <Page>
    <PagePath>/clockSample.html</PagePath>
    <PageClass>sample.ClockSample</PageClass>
 </Page>
 <Page>
    <PagePath>/clockImageSample.html</PagePath>
    <PageClass>sample.ClockImageSample</PageClass>
 </Page>
 <Page>
    <PagePath>/WidgetsSample.html</PagePath>
    <PageClass>sample.WidgetsSample</PageClass>
 </Page>
 <Page>
    <PagePath>/TableSample.html</PagePath>
    <PageClass>sample.TableSample</PageClass>
 </Page>
 <Page>
    <PagePath>/ChatSample.html</PagePath>
    <PageClass>sample.ChatSample</PageClass>
 </Page>
</JaxcentConfiguration>

Adding JavaScript include statement to the HTML content

1. Publish Jaxcent21.js

If necessary, edit jaxcent21.js to provide the correct URL for the Jaxcent servlet/connector.

Note: This step is not applicable if you are using the Jaxcent Development Server, because jaxcent21.js is embedded in the server itself.

2. Modify HTML Content

<SCRIPT TYPE="text/javascript" SRC="/jaxcent21.js"></SCRIPT>

This change needs to be made to all HTML content that you want to handle with Jaxcent. The HTML content itself can be coming from HTML, JSP, ASP, servlet, or other sources. As long as the JavaScript file has been correctly included, the HTML will be available for access via the Jaxcent API.

Writing the Jaxcent classes

The Jaxcent classes (jaxlets) you write must extend jaxcent.JaxcentPage, and can override various methods in there. Typically, you can declare and initialize one or more fields corresponding to one or more HTML tags on the page. You can access methods and properties of these HTML tags directly from your Jaxcent class.

Jaxcent has classes corresponding to various HTML tags. The class jaxcent.HtmlElement is a catch-all class that you can use if you are not particular about using the exact matching class.

When you create an object of a class corresponding to an HTML tag, Jaxcent needs a way to locate the actual tag on the HTML page. This is done by providing a "search" method. The default (and recommended) search method is to search by the "ID" field. This requires adding an ID attribute to the HTML field, and then specifying the same ID string to the corresponding Jaxcent object's constructor.

There are other methods of locating the HTML tags on the page, as well, such as searching by the tag or by NAME or by TYPE (applies to INPUT tags).

New elements can be created by using the createNew argument instead of a search-type.

If you are interested in receiving events from any of the objects you have created, simply override the event method.

The processing typically starts by overriding the onLoad method of jaxcent.JaxcentPage class, or from event handlers. Before onLoad is called (in the constructor), data cannot be retrieved from the HTML page, because the page has not loaded yet. However, data can be sent out, and values of fields can be set in the constructor. These will get queued up, and will be processed when the page does get loaded.

The provided samples can be compiled, tested and reviewed for a good start.

Adding Jaxcent to existing applications

The rest of the web application's behavior can continue as it used to.

Designing New Applications in Jaxcent

When designing new applications using Jaxcent, make sure to read about the configuration item "AutoSessionData". If it is configured as true, Jaxcent will save the user's data entry in the session, and when new pages are loaded, will initialize them from the session. When you are ready to process the user's data, you can also retrieve it from the session. For data verification, jaxcent.JaxcentPage provides a convenient getAllFormData method. Events can also be overridden to receive data along with the event. Alternatively, various items can be checked one at a time. In general, checking items one at a time will require many client-server round trips, so whenever reasonable, all the data should be retrieved together.

JavaScript and Jaxcent

Jaxcent can also be easily integrated with JavaScript.

To call JavaScript functions from the Java code, use execJavaScriptCode or evalJavaScriptCode methods of the JaxcentPage class.

To call Java on the server from JavaScript, call JaxcentServerRequest in JavaScript, and override onJavaScriptRequest in the JaxcentPage class.

To add JavaScript verifiers that should be called before an event is sent to the server, call addJavaScriptVerification which is provided by the base JaxcentObject class.

For advanced JavaScript integration, sometimes it may be required to send a JavaScript object that is not a simple string or integer or boolean etc, to the server and to have the server send it back. For this purpose, Jaxcent provides the following functions in JavaScript:

• JaxcentMakeObjectReference( obj ) returns a reference to a JavaScript object, that can be passed as a string to the server and the server can pass it back.
• Call JaxcentGetReferencedObject( ref ) to retrieve the original object from the reference.
• When finished, call JaxcentRemoveObjectReference( ref ) to clear the reference.

Performance Considerations

• Scalability is not a significant concern in Jaxcent programming (compared to other alternatives.) The application server's scalability/clustering model will work with Jaxcent. The Jaxcent servlet itself is relatively small and fast, and the AJAX interaction model combined with Jaxcent's low-data-volume protocol, puts less burden on the server compared to traditional models. Instead, performance considerations need to focus on responsiveness. The primary focus is minimizing the number of client-server round trips. The less round trips required for performing a task, the faster the user's perceived response will be.

• Since most form data is liable to fit in a single internet packet, Jaxcent provides methods to retrieve form data along with the events. For instance, when a button is clicked, the Jaxcent programmer can choose to handle it by overriding a method that supplies all the form data. It may feel slightly counter-intuitive to retrieve all form data if you are only interested in one or two items. But actually, retrieving all the form data with the click will provide better responsiveness, compared to retrieving one or two data items individually after the click!

  Retrieving all form data with the event and responding to it with output requires only a single client-server round-trip, and typically would require only one internet packet coming in. Getting an individual item would also require one internet packet, but doing it after the event means the event requires one packet, the request to get the item requires one packet (in the other direction), and the value of the item requires one more packet!

• The page constructor is a good place for doing as much of the page output as possible. At this point, the page is not loaded, therefore HTML input values cannnot be queried. However, writing to the HTML tags (changing their properties etc) is quite possible. All output from the constructor is queued up and gets sent at once when the connection is established. (Any settings done later may also get batched together, or may not, depending upon the network and server speed etc.)

• Jaxcent attempts to batch multiple outputs in single transmissions. This can be programmatically improved in some cases by using the setBatchUpdates method. The setBatchUpdates method can be useful in improving performance, but it needs to be used with care! Generally, putting this in a try-finally block is a safe approach of using it. It should not be mixed with user input, use it only when doing lots of output to the page. Please note that when batching updates, the Java object is not actually communicating to the HTML page, until the batching updates is reset to false! A couple of samples in the Jaxcent package have examples of calling setBatchUpdates.

• Jaxcent makes it very easy to do all data verification from the server side -- even those parts of the data verification that could have been done entirely at the client side. While not always a very significant consideration (the samples actually include examples of data verifications from the Jaxcent side instead of at the client), too much of this kind of verification can have an adverse effect on responsiveness. Again, such verifications should retrieve the data along with the event to minimize the round trips.

• Since it is very easy to start threads and have them interact with the page, it is also easy to have orphan threads that continue to operate after the page has unloaded! This can drastically bring down server performance on high volume servers. Jaxcent throws an Error on any output to the page after the page has unloaded. This should normally have the effect of terminating the thread. However, programmers should nor rely on this mechanism and should actively terminate the thread on unload.

• The ReloadableClassPath is a convenient mechanism during development for having Java code changes take effect immediately. But it does require additional processing to check class files for changes. In production environments, the Jaxcent classes should be in system or app-server CLASSPATH, and not in the Jaxcent reloadable classpath, for best performance.

Virtual Host configuration

Form Submit Behavior

    <FORM ID="myForm" onSubmit="return false;">

    <BUTTON ID="myButton" onClick="return false;">A Button</BUTTON>

Other Documentation

• License
• Configuration Parameters
• Javadoc Documentation of Jaxcent classes