David Moskowitz, President, Infoblazer LLC.

January 2006

© David Moskowitz, 2006. 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 are available on http://localhost/downloads.shtml.

Prior to the steps in this tutorial, the XX framework and related class libraries must be installed. Please see the installation document on the XX Framework web site further information.

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.

Step1 – Add a web servlet to web.xml

Here we add the following new servlet element

We also need a servlet mapping element in web.xml

In addition, XX requires the following environment variable in the web.xml file as well. This variable needs to be set only once for the entire web.xml file. All servlets will inherit this value. The entry value should specify the absolute path of the application’s XML directory, usually immediately below the WEB-INF directory.

Step 2- Create the XX Config File

Here is the xx config file that will be used. This file should be stored in the application’s XML directory.

This is about as simple as it gets. We define a single implementation class ( org.xxframework.tutorial.HelloWorld) and specify the method to call (SayHello). In the class element’s attributes, we specify that the class will use XSL and 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 “simple.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 simple.jsp

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 “home” link to get you back to the frameworks homepage as well as a box around the XX framework output, 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.

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- Add Servlet

This step is no different than the previous example. Simply add a new servlet to web.xml with a pointer to the XX config file.

Step 2- Create XX Config file

We need to create the config file specified in the servlet definition, HelloWorldWeb.xml. 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- Add Servlet

There is nothing new here

Step 2 – 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- Add Servlet

There is nothing new here

Step 2 – 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: