Ellipse Tutorial

WARNING: This tutorial is being written! Do not hesitate to report any errors or suggestions.

Quick access:
   Global structure of the file WEB-INF/web.xml
   Configuration of the Ellipse track module
   Configuration of the statistical module
   Configuration of the index engine
   Configuration through the Ellipse plugin

Although not using all the web technologies proposed by the J2EE platform, the Ellipse framework is nonetheless based on the servlet concept. This choice for ensuring that the web pages developed through Ellipse will be able to run on any J2EE application server (JBoss, ...), even simply with Tomcat. Of this choice derives the fact that an Ellipse Web application must be deployed in a WAR and have to be configured by the intermediary of the file WEB-INF/web.xml. It is on the content of this file that this chapter will focus its attention.

The file WEB-INF/web.xml is what the J2EE architecture calls a deployment descriptor: it contains any configuration informations on the various web components to deploy on the Tomcat server (or other). Traditionally this file contains at least two aspects (although the J2EE standard supports more others): the servlets configurations and the parameters definitions of initialization of the associated context with the application. Consider these two points one by one.

The Ellipse framework is based on an architecture MVC 2 with still some shades of implementation, as compared to other similar Java frameworks (Struts 1, Struts 2 or also JSF). Despite these shades, the approach MVC 2 imposes a common point to all these frameworks. A servlet uses as a main controller: then it will give hand to the secondary controllers (implemented as classes of Web page). The main controller is represented by the class corelib.services.web.webapplications.ControllerServlet. A servlet configuration is required for this controller. This configuration will be, moreover, in relation with all the requests ending with .wp. You can define alternative configurations of servlets, but they will not go into play in the normal functioning of your web pages.

With regard to your configuration settings, they will be introduced via the XML tag XML <context-param>. A parameter will be formed by two parts: its name and its value. The name of a parameter will be introduced through the sub-tag <param-name>. The associated value, will be through a sub-tag <param-value>. The example below (corresponding to the configuration file of the demonstration application of the Ellipse framework) shows you an example of a parameter definition and the setting up of your main controller (the servlet of type ControllerServlet).

 
01 <?xml version="1.0" encoding="UTF-8"?>
02 <!DOCTYPE web-app PUBLIC
03   "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
04   "http://java.sun.com/dtd/web-app_2_3.dtd">
05 
06 
07 <web-app>
08 
09     <display-name>Virtual Caddy - Ellipse Sample</display-name>
10     <description>Ellipse Sample</description>
11 
12     <context-param>
13     	<param-name>TRACE_ENABLED</param-name>
14     	<param-value>true</param-value>
15     </context-param>
16     <context-param>
17     	<param-name>TRACE_LOCALHOST_ONLY</param-name>
18     	<param-value>true</param-value>
19     </context-param>
20     <context-param>
21     	<param-name>TRACE_URL</param-name>
22     	<param-value>Trace.wp</param-value>
23     </context-param>
24 
25 
26     <servlet>
27       <servlet-name>Ellipse Servlet</servlet-name>
28       <servlet-class>corelib.services.web.webapplications.ControllerServlet</servlet-class>
29     </servlet>
30 
31     <servlet-mapping>
32         <servlet-name>Ellipse Servlet</servlet-name>
33         <url-pattern>*.wp</url-pattern>
34     </servlet-mapping>
35 
36 </web-app>

For the association of the extension ".wp" to our main controller (lines 31 to 34), note that there is no requirement in the absolute. if you prefer to use another extension (why not ".toto") that will work very well. But, ".wp" for "Web Page" may not be so bad here.

The Ellipse framework includes a shades module that create the content history of the requests made by a web application. The configuration of this tracks module is done, of course, from the file WEB-INF/web.xml. The image below shows an example of tracks display for the demonstration application of the framework. And after you will find a table showing all the configuration parameters of the tracks module.

The framework also proposes a statistics module to know the number of open sessions per day, the proportions of browsers used on your web application, ... Of course, this module is customizable, although it is at an early stage. Here is the list of the supported parameters at this day.

The Ellipse framework also proposes an engine for indexing your Web pages. For more information, I referrals you from the technical file associated with this module.

The file WEB-INF/web.xml can, of course, be edited by hand. Nevertheless, the use of the Ellipse plugin for Eclipse will greatly simplify your life. For example, consider the construction of a new Web project based on the Ellipse framework: to do this, please take the following steps:

1. From the "File" menu, create a new project of type "Java Web Project". To do so, click on "Other...": the dialog box below appears: pull down the folder "Java Web Development" and select in "Java Web Project".
 

 
2. A second dialog box appears: it allows you to enter the characteristics of your project. Just as in the screenshot below, give it a name, why not "Demo".
 

 
3. Please note that you can specify the Web server used (or application server Java EE). If you use Tomcat, then configure your project to use your server. Click on "Next": a new dialog box appears to continue the configuration of your Web project.
 

 
4. Just look that the Ellipse facet is selected. Then click on "Next" and once again on "Next": the next dialog box must appear.

 
5. You can now set up the three integrated services of the Ellipse framework: the marks service, the statistics service and the indexing service. Please note that we can see the elements presented earlier in this document.