The XINS Front-end Framework is based on a calling convention. You will need to declare this calling convention in the impl.xml file to be able to use the framework:
<calling-convention name="xinsff" class="org.xins.server.frontend.FrontendCallingConvention" />
Templates are used for the presentation layer. The templates (also refered as XSLT) transform the XML returned by the function in HTML (or XHTML, WAP, iHTML).
The location of the templates is specified using the templates.<api name>.xinsff.source runtime property. The value must be a URL (file URL or http URL).
The requests can accept special parameters.
Table 1. Special parameters
|Parameter with value||Description|
|mode=source||Returns the XML produced by the function before it is transformed using the template.|
|mode=template||Returns the XSLT source code used to transform the function return|
|command=Control||Shows information about the API such as the list of the functions, the value of the sessionproperties, the version of XINS and of the API.|
XINS FF includes the possibility to cache the templates. Caching the templates will increase the response time as the XSLT file doesn't need to be parsed again and compiled (in case you use XSLTC). On the other side caching the templates will increase the memory usage of your web application.
I would advice to disable the cache during the development of the application and to enable it when deploying the application on production.
Enabling/disabling the cache is done by the templates.cache runtime property. The value can be true or false. If the value is not set, the cache is enabled by default.
If you execute the Control command, you have at the bottom of the page a few links to manage the cache. The flush link will clear the cache. The cache will be filled as the pages are used. The second link will clear the cache and reload all the templates in the cache.
XINS Front-end Framework includes some settings to help you having a secure web application.
You first need to specify the login page. This is done be defining the xinsff.login.page bootstrap property.
Once this property set, all pages except the login page and the Control command will redirect to this page if the user is not logged in. If you have other pages that you would like to be accessible to everybody, you will need to specify them as a comma separated list in the value of the xinsff.unrestricted.pages bootstrap property.
There can be some case where you want the user to have certain
privileges to access a specific page, so you want to check for the
access to this page inside the function. For this purpose, if you create
an error code named
NotLoggedIn and you return this
error code from the function, the framework will redirect it to the
To indicate that the a customer is logged in is done by putting
the session ID as session property with the value
Boolean.TRUE. The session ID is put as a cookie in
your browser using the
SessionId cookie name.
The workflow is the redirection between pages.
You can specify the default command by setting the xinsff.default.page bootstrap property. The browser will be redirected to this page when no command is specify in the request.
You can specify the redirection by returning a output parameter
redirect to your function. Note that the
parameter will need to be declared in your function
You can redirect a command to another page by setting the xinsff.redirect.<function name> bootstrap property. If the function exists, the function is executed and if the result of the function is successful, the browser is redirected to the value of the property. If the function does not exist, the browser is directly redirected to the value of the property.
It is also possible to specify conditional redirection. The conditions are defined using XPath using the generated XML source as XML to evaluate the XPath. The bootstrap property looks like xinsff.redirect.<function name>[xpath]. If none of the condition matches, the page is redirected to the xinsff.redirect.<function name> bootstrap property value. And if this property is not set the page is not redirected.
The function name is the concatenation of the command name with
the action name. For example if the command is
and the action is
okay, the front-end framework will
try to execute the
LoginOkay function. The show
action is the default action, so the Login command with the show action
will try to execute the Login function.
The session is used to stored information about the user or about the state of the application for this user. The session needs to be declared as a shared object so that the session can be accessible from every function.
<instance name="_session" getter="getSessionManager" class="org.xins.server.frontend.SessionManager" />
Then you can use the session by calling
property names should be in lowercases. All session properties are put
in the XML using
Also all input parameters are stored automatically in the session. The
session also contains a _inputs property which
Map with the input parameters and
their values of the request.
If you put in the session an object which is of type
org.xins.common.xml.Element or a
objects, then this (or these) object(s) will be put in the data section
of the generated XML.
The session manager uses
to keep the
HttpSession. This means that it
assumes 1 thread = 1 request. The Servlet container should be configured
for it. Tomcat for example needs the property
The session manager can be overridden so that you can use your own session system if you want to.
Let's have a look of what the XML produce by the front-end calling convention is.
<commandresult command="SearchPet"> <parameter name="session.petName">test</parameter> <parameter name="input.command">SearchPet</parameter> <parameter name="input.mode">source</parameter> <parameter name="input.action">Okay</parameter> <parameter name="input.petName">test</parameter> </commandresult>
Here is an example of the of result when the request is invalid:
<commandresult command="Login"> <parameter name="input.password"/> <parameter name="input.command">Login</parameter> <parameter name="input.mode">source</parameter> <parameter name="input.email">testtest.com</parameter> <parameter name="input.action">Okay</parameter> <parameter name="error.type">FieldError</parameter> <data> <errorlist> <fielderror type="mand" field="password"/> <fielderror type="format" field="email"/> </errorlist> </data> </commandresult>
From it, the XML can be translated to anything (WAP, iHTML, text) using XSLT. We will more focus in this part in transforming the XML to XHTML and using cascading style sheets (css).
For an example, I suggest you have a look at the Pet store demo XSLT files located in the demo\xins-project\apis\petstore\xslt directory.