David Moskowitz, President, Infoblazer LLC.

July 2009

© David Moskowitz, 2009. All Rights Reserved.

The XX foundation tutorial will create several variations of a simple “Hello World” servlet. The application will be, admittedly, very simple. However, the foundation framework should be able to handle any scenario that a typical servlet could handle. The advantage is the developer no longer has to worry about writing the servlet class, and can additionally take advantage of many additional feature of the framework. All the tutorials are running live on the XXframework.org web site. The complete source code for these tutorials is available on Sourceforge.net.

Quick Installation

The demo is distributed as a JavaEE War file.

The file contains the binary, source, sample Mysql database, and dependency libs.

1-Create the database structure using the included guestbook.sql file.

For Mysql, create schema named guestbook

From the Mysql command prompt, you can restore the sample database with the following command

Mysql> use guestbook

Mysql> \. guestbook

(Assuming the sql file is unpacked to c:\)

2-Make sure a servlet container and database server are available and installed. The demo was developed using Tomcat 6 and Mysql 5.5

To install, auto deploy the war to your servlet container’s deploy directory, or unpack the directory structure and configure the application as appropriate. For Tomcat, you should be able to simply drop the included WAR in the tomcat/webapps directory.

3- Start Tomcat. This should autodeploy the guestbook application to a directory named guestbook

If you need to modify the database connection parameters from the default settings, modify the Hibernate section of the spring configuration file to match the database server you are using. The Spring configuration file is at located at WEB-INF/applicationContext.

At a minimum, the following variables may need to be changed to match the Mysql user name and password.

4- Load the main application page at localhost:8080/guestbook/home.xx

A predefined administrator user has been created in the db load scripts, with login and password “admin”.

(Assuming the tomcat is running on localhost:8080)

The rest of this document describes the workings of the non database components of the Guestbook demo. See the XX Automation tutorial for a discussion of database applications.

Hello World

This application will display the famous “Hello World” message to the screen. The hello world text will be generated directly from the XX (Java) implementation class.

Configuration of an XX application generally involves two components; Spring/SpringMVC configuration and XX configuration. Since XX runs on top of Spring, all of the facilities of Spring are available. If the application mainly contains XX functionality, the Spring configuration will be quite simple and similar for all XX applications.

Step 1 – Add Spring configuration elements to the web.xml file

The XX Framework is configured as a SpringMVC application. We first need to add the appropriate SpringMVC elements to our new or existing web.xml file

We also need a servlet mapping element in web.xml for files that will be handled by Spring. We can specify individual URL patterns or a wildcard pattern, as shown below. Using a discreet extension for XX-Spring files makes the mapping simpler, and allows easier partitioning between an Apache web server and the Java application server, allowing Apache to serve all web content (non *.xx files). The Tomcat container itself will serve all other content, unless Apache or another web server is configured to handle content as well.

We also need a spring-servlet.xml mapping file (See SpringMVC documentation for additional details).

Notice the inclusion of the base XX Framework Servlet implementation org.xxframework.spring.SpringServlet. You will always need this defined in the Spring Servlet config file. The mapping parameters will generally match the mappings specified in web.xml, since the baseSpring servlet will handle all spring content. You could add additional content handlers in addition to those provided by the XX framework, or add XX framework functionality to existing spring applications.

Finally, we need a Spring configuration file (as opposed to the SpringMVC config file defined above. This is the applicationContext.xml file that is used by all Spring applications.

The beans “global”, “baseSpring”, and “viewResolver” are standard components that should be included in all XX Framework applications. (Additional database components will be introduced in the XX Automation tutorial.

The final bean, “helloWorld”, will implement the XX Foundation functionality needed for this application.

Step 2- Create the XX Config File

As configured above, SpringMVC will map all URL parameters of the form *.xx to the XX framework Spring Implementation Servlet. The XX Servlet uses convention to determine the appropriate configuration file to specify what should be done with the request. It will simply look for a file with the same prefix and the extension .xml in the WEB-INF/xml directory.

Here is the xx config file that will be used to implement the first Hello World function

This is about as simple as it gets. We reference a single implementation Spring Bean (helloWorld) and specify the method to call (SayHello). The name of the Spring Bean is the same as is defined in the applicationContext.xml file.

In the class element’s attributes, we specify that the class will use XSL but we won’t apply an XSL transform. In the configuration file, XSL can refer to any text return type, whether XML or HTML. Since we specify not to apply an XSL transform, we will be returning pure HTML. This html will be written directly to the output page.

We also specify the JSP page that should provide the final display, in this case “main.jsp”

Step 3- Create JSP Page

In many cases, the JSP page will not contain all that much, other than a very simple wrapper around the framework’s output.

Here is the code for main.jsp. Several inclusions to small XX framework script libraries are made. These can be examined in the included source code.

Only three elements in the JSP file are XX specific. These elements are highlighted.

The first is needed to import the necessary java classes to use in the JSP code. This will be standard for any JSP file.

The next, the JSP function XXOutput, is a common XX function that will translate the XX output result into display compatible format. Actually, it is simply a check on null, so a null result (ex. If that parameter doesn’t exist) will display as blank instead the word “null”, which would happen when a null value is converted to a string. There are other ways to accomplish this included writing a JSP tag library to handle this output.

The last XX element is the most important. This grabs the XX output of class 1 and writes it to the screen, with the help of the XXOutput function. Values are passed from the framework to the JSP in this format. I won’t describe the specifics of this line, other than saying to implement additional output, simply change the “1” to the relevant class id specified in the xx config file. Again, a JSP tag would make a nice neat wrapper around this function.

We also include a “header and surrounding div tag, although this is obviously optional. This also illustrates how additional content can be added to the JSP page independent of the XX framework or any Java programming. Indeed, it is recommended that as much of the application as possible be defined in static html, which is easier to work with than XSL or java code.

The follow UML diagram shows the relationship between the various implementation components:

Step 4- Java Implementation function

We’ll define the following java class

Again, this implementation is about as simple as it gets. We simply define the class specified in the XX config file. Since we are using XSL/XML and not applying a transform, we simply return the result as a text string.

The input parameter, common to all XX implementation parameters will contain the appropriate request information, in XML format.

We extend an XX specific class, RecordControl, since this will handle much of the parameter passing between the framework and the implementation file. It is possible avoid subclassing RecordControl but implementing org.xxframework.BaseFlow directly. That technique is rarely necessary for XX specific classes such as this one.

Hello World Web

In this variation on Hello World, the hello world text will be read from a web page using http. This page can be local to the application or on another web server across the Internet. This illustrates some of the simple web service features of XX. This approach is also useful in including static HTML code as components of generated pages.

Step 1- Create XX Config file

We need to create the config file specified in the servlet definition, HelloWorldWeb.xml, to map the the ULR “HelloWorldWeb.xx”.

Here it is.

This file is even simpler than the previous example. Since we are retrieving data from the web, as specified in the “use” attribute, we only need to specify an endpoint element. A file on the local web server could be retrieved by specifying “localhost” as the end point. Since “applyxsl” attribute is false, the results, being HTML, will be passed directly for output to the JSP page. The JSP in this case is the same page as was specified in the previous example. This will generally be the case in XX, where it is beneficial to limit the number of JSP pages in the application.

Note that we could set “applyxsl” to be true. In that case, we would be retrieving xml from a web site and then applying an XSL transformation. This is an xml web service. XX will also include the ability to conform to the SOAP standard. This implementation however, it not fully complete at this time

It is also necessary to create the HTML file that will be read in. In this case, the file is simply read from the same web server running Hello World. . Here is some simple HTML output

Since we are reading this HTML into another HTML (JSP actually) wrapper, we do not need to specify the HTML, Body, etc tags. Even if we did include these tags, in the case where HelloWorld.html was a complete stand alone page, most browsers would still display the resultant page correctly. Since the JSP page from the above example is being reused, no additional steps are necessary.

The configuration diagram is as follows:

You should begin to see how the portal approach can be implemented. Most real life applications of XX will involve a combination of various XML and HTML components, some with behind the scenes java implementations and some static pages.

Hello World File

This demo is almost identical to the web demo above. Instead of loading the display HTML over HTTP, the page is loaded from a disk file residing on the web server.

Step 1 – Create XX Config File

The difference between the web and file version are

1. The web version can access html on a different server (i.e. across the internet) where file access is not possible
2. The web version is capable of posting data to the web site (listener), providing web service capability.

Note also the use of the [xmlroot] variable, which represents the XX application’s XML directory.

Hello World XSL

The final example is perhaps the most indicative of the XX approach. In this case, a java implementation will generate an XML result, that result will be transformed using an indicated stylesheet. The results of the transformation will be passed to the JSP page for output.

Step 1 – Create XX Config File

This example is similar to the first Hello World example. In both, an implementation class is specified. Actually, the class is the same for both examples, HelloWorld. However, in this case, we set applyxsl to true, so the results of the class will be transformed using the file specified in the “xsl_file” element, HelloWorld.xsl. We call a different method in the HelloWorld class, SayHelloXML. Here is the implementation method.

This method manually creates an XML document, returning the string representation. The XML String returned is the following:

The XSL file specified, HelloWorld.xsl, is as follows.

Again, this XSL is pretty basic. The transform simply grabs the greeting text from the XML result.

As in the previous example, we reuse the same JSP page, so that is not discussed here.

And finally, here is the configuration diagram: