How it Works

The Guara servlet executes these steps for every user request:

  1. Create a RunData instance: this instance is passed to all pipeline valves
  2. Select one Pipeline instance: may use a request parameter on the selection
  3. Execute the selected Pipeline: call execute(RunData) on all valves
  4. Reclycle the RunData instance: not implemented yet

The RunData object

The RunData object is created for every request and passed to all pipeline valves.

Through this object the developer has access to:

  • Request and response details
  • Page generation info
  • The Context object that glues Java and some markup (HTML)
  • The current Pipeline
After the end of the request, the RunData object is reclycled!

The Pipeline

The Pipeline object is composed of valves that get executed on a particular order defined declaretively.

The file that defines the pipeline format is configured at guara.xml. Often it will be called pipeline.xml.

Pipeline valves are single instances, create and initialized by the Factory component.

The default Pipeline is this:

<?xml version="1.0" encoding="ISO-8859-1" ?> <pipelines> <pipeline> <valve name="logStartRequest" className=""> <message text="---- Default Pipeline START ----"/> </valve> <valve name="populateContextWithTools" className=""/> <valve name="populateContextWithConstants" className=""/> <valve name="executeAction" className=""/> <valve name="executeScreen" className=""/> <valve name="renderScreen" className=""> <homePage template="Index"/> <onTemplateNotFound template="screens.TemplateNotFound"/> </valve> <valve name="renderLayout" className=""> <onLayoutNotFound template="layouts.LayoutNotFound"/> </valve> <valve name="logEndRequest" className=""> <message text="---- Default Pipeline END ----"/> </valve> </pipeline> </pipelines>
The logXX valves are used for audit purposes and can be ignored for now

The populateContextWithTools valve uses the PullManager to add objects to the Context

The populateContextWithConstants valve adds some default objects to the Context

The executeAction valve executes action modules

The executeAction valve executes screen modules

The renderScreen and renderLayout valves merge the Context objects from RunData with templates on PageInfo objects using the TemplateEngine

Please note that valves accept configuration values.

Guara URLs

Guara adds some specific url parameters to used for it's own control. For instance :

  • pipeline: the pipeline that will be executed
  • template: the template you want to render
  • layout: the layout that will be applied to the template above
  • screen: the screen module to be executed
  • action: the action module to be executed
You can add parameters to the url using the $link referece (LinkTool). Examples :
  • $link.setTemplate("MyTemplate")

    will generate : http://host:port/context/template/MyTemplate
  • $link.setTemplate("MyTemplate").setAction("MyAction")

    will generate : http://host:port/context/template/MyTemplate/action/MyAction

Please note that MyTemplate does not contains the file extension (.vm|.ftl). This happens because Guara is designed to be template engine agnostic.

The real file extension is resolved at runtime by the template engine

Guara uses the "." dot as package or directory separator for templates and modules.

Template Example:

$link.setTemplate("dir.MyTemplate") will render the template called $TEMPLATE_ROOT/screens/dir/MyTemplate.vm if the VelocityTemplateEngine is beeing used.

Module Example:

$link.setAction("dir.MyAction") will start the module search process at $PACKAGE_NAME/dir/MyAction.

The default ParameterParser adopts Turbine's convention for extracting parameters from the url using this simple scheme : http://host:port/context/var/value/