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

The samples folder contains a file RunSamples containing the command necessary to start the Jaxcent stand-alone web-server on the samples. After running this command successfully, the samples may be viewed at http://localhost/

Running Jaxcent from the Command Line

Jaxcent can be used with standard Web Servers and/or Java Application Servers.

Jaxcent also includes a small standalone web server, that can be started from the command line. To use this server, the files jaxcentFramework21.jar and jaxcent21.jar need to be in the classpath.

To start the server from the command line, the syntax is:

    java jaxcentServer.ServerMain <port-number> <HTML-root> <XML-Config-file> <Optional-Reloadable-classpath>
For instance,
    java jaxcentServer.ServerMain 80 C:\MyHtmlFiles C:\JaxcentConfig.xml
    java jaxcentServer.ServerMain 80 C:\MyHtmlFiles C:\JaxcentConfig.xml C:\MyJaxcentClasses
If the <Optional-Reloadable-classpath> is provided, Jaxcent will look in there for classes to load (in addition to the standard classpath), and will reload these classes whenever they change. This can help during development. (But should not be used if running within an IDE.)

Running Jaxcent in an IDE

The command line method outlined above, can also be used when running Jaxcent in an IDE. To use this method in an IDE:

In addition, the Jaxcent server can also be started programmatically. To do this, instantiate the class jaxcentServer.ServerMain. This class extends java.lang.Thread. After instantiating it, start the thread. E.g.

    ServerMain jaxcentServer = new ServerMain( 80, htmlDir, xmlConfigFile, reloadableClasspath );
The last parameter reloadableClasspath can be null. In debugging, typically you may want to provide null here, and specify the full classpath in the IDE.

Using Jaxcent with Web Servers or Java Servlet Containers

Jaxcent works with standard Java servlet containers (Java application servers) such as Tomcat.

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.

This URL location can be changed, but the HTML files must have the correct URL.

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

This URL location can also be changed, and would require editing the jaxcent21.js file to specify the correct URL.

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

When the servlet, connector or Jaxcent web-server is correctly configured and running, visit the URL http://localhost/servlet/JaxcentServlet21 (changing the domain name as appropriate) in a browser, to make sure the servlet is working as expected. (For IIS direct connector, visit http://localhost/scripts/JaxcentConnector21.dll instead.)

Writing the Jaxcent configuration file

The Jaxcent configuration file is an XML file that maps incoming URLs to Jaxcent classes you write. Whenever the configuration file is changed, by default Jaxcent will re-read it. A sample configuration file is shown below.

Adding JavaScript include statement to the HTML content

1. Publish Jaxcent21.js

Make sure jaxcent21.js is available at your website! If jaxcent21.js is not available at the website, Jaxcent will not work! If you are going via a Java servlet-container/application-server and have another web-server as the front end, the .js file will need to be placed at the content-root of the front end web-server.

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

Then add the statement
<SCRIPT TYPE="text/javascript" SRC="/jaxcent21.js"></SCRIPT>
in the <HEAD> section of your HTML content, changing the path if necessary.

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

Now you are ready to write Jaxcent classes (jaxlets.)

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

Adding Jaxcent capabilities to existing applications is very simple. The existing application can continue to work as always, and Jaxcent can be added piecemeal. For any web page in the existing application that needs to be made more dynamic, simply add a URL mapping in the Jaxcent configuration file, and then add the Jaxcent JavaScript include to the page. That's it, the web page can now be handled by Jaxcent!

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

Designing New Applications in Jaxcent

If you are familiar with Java server-side programming, note that the session and application context are available in Jaxcent. If you are not familiar with these, you may want to briefly read up on these, as they can help simplify the application development.

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

JavaScript can be added to Jaxcent pages without involving 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:

Note: The three functions above are not normally required. For an example of when they are required, see the "AutoSuggest" integration samples provided at the Jaxcent website.

Performance Considerations

Virtual Host configuration

When used with the Jaxcent Apache connector or via a servlet container, virtual hosts can be configured with Jaxcent.

Form Submit Behavior

In general, submitting a form with an empty target will cause the page to refresh. This is usualy undesired behavior in Jaxcent, because the new page will get another new Jaxcent object assigned to it. Usually this is not a problem, because most form submit actions cause a navigation to a new page. But in Jaxcent programming, it is likely that many form submit actions will continue to work on the same page. Therefore, if the action of a form submit (or a button that causes a submit) is not navigation to a different page, the form submits should be disabled by adding onsubmit or onclick handlers that return false, e.g.
    <FORM ID="myForm" onSubmit="return false;">
    <BUTTON ID="myButton" onClick="return false;">A Button</BUTTON>

Other Documentation

Other documentation files: