Getting Started with Jaxcent
- Configuring the Jaxcent Servlet or Connector
- Writing the Jaxcent Configuration XML File
- Adding the JavaScript include statement
- Writing the Jaxcent implementation classes
- Adding Jaxcent to existing applications
- Designing New Applications in Jaxcent
- Performance Considerations
- Form Submit Behavior
- Other Documentation
Jaxcent works with standard Java servlet containers (Java application servers.)
It can also be configured to work directly with Microsoft IIS (Internet
Information Services) web-server, or the Apache web-server.
The Jaxcent servlet (or connector) needs to be available at the URL location
/servlet/JaxcentServlet20
The location can be changed, but this would require editing the jaxcent20.js file also.
Depending upon your available environment, please visit the appropriate link
below for configuring the Jaxcent servlet/connector.
When the servlet or connector is correctly configured, visit the URL http://localhost/servlet/JaxcentServlet20
(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/JaxcentConnector20.dll instead.)
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.
<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>
1. Publish Jaxcent20.js
Make sure jaxcent20.js is
available at your website!
If jaxcent20.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 jaxcent20.js to provide the correct URL for the Jaxcent servlet/connector.
2. Modify HTML Content
Then add the statement
<SCRIPT TYPE="text/javascript" SRC="/jaxcent20.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.
Now you are ready to write Jaxcent classes.
The Jaxcent classes 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 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.
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.
- 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.)
- 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!
-
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. Care should be taken to stop threads on page unload.
Jaxcent helps by throwing IllegalStateException on Jaxcent operations
after the page has unloaded. To take
advantage of this mechanism, make sure you catch Jaxception and
not Exception in your threads. If you catch the IllegalStateException (by
catching Exception) and continue the thread processing, it will not be able to serve its intended purpose
of terminating your threads when you forgot to!
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;">
or
<BUTTON ID="myButton" onClick="return false;">A Button</BUTTON>
Other documentation files: