Introduction
At the outset do remember that Aspire is an open ended programming system for Java. Any thing that is possible in Java is allowed to program via Aspire. All Aspire does is give value added services and parts on top of the basic Java programming language so that mundane and reusable aspects of Java are provided as prebuilt parts.
Aspire properties file is a declarative mechanism that allows you to invoke these prebuilt java classes or parts (sometimes called executors). It is not uncommon to come out with an impression that these properties files are all there is to Aspire. The core of Aspire is really these reusable classes which use the properties file as a way to configure them.
To understand Aspire properties files you have to understand the java classes that are behind each section of the properties file. Depending on the java class used what goes in to the properties files vary drastically. Let me consider an example
request.GetEmployeeDetails.classname=com.ai.db.DBRequestExecutor2
The above line ties a java class to a symbolic name called "GetEmployeeDetails". How to get employees is totally the responsibility of that java class. It might manufacture them in memory or read from a hard coded url or whatever else. From a properties file responsibility of the caller that is all that is needed.
If the above class was to be a one-of that you have designed and is going to be used only for "GettingEmployees" and nothing else then you could have coded it with out any additional property file arguments. In that case the single line above would have been sufficient. Such classes are called vertical.
But the above class in the example is a pre-built class from Aspire that can be used on more than one occasion. It does this by extending itself using additional arguments as follows:
request.GetEmployeeDetails.classname=com.ai.db.DBRequestExecutor2
request.GetEmployeeDetails.db=database-name
request.GetEmployeeDetails.stmt=\
select * from employees-table \
where employee_id = {employeeId}
The additional arguments of "db" and "stmt" are entirely decided by the DBRequestExecutor2. Consider the following
request.GetEmployeeDetails.classname=com.ai.data.RowFileReader
request.GetEmployeeDetails.filename=c:\\myfilename
Notice how the additional arguments are completely different in this case as the class now is a completely different class.
With that background this document discusses the property file sections that deal with the display pages and update pages in Aspire.
Display and update pages in Aspire
The pages in a web site are classified in to two types. Display and update. The display pages are responsible for painting data and usually read only. Update pages or requests are expected to change the state on a web server. This state change can be in the database or session or sending an email etc.
After an update request, aspire redirects the user to a display page. In this redirection process Aspire hides all the update urls from the browser so that such things as "refresh" and "back" are completely safe and guards against duplicate updates.
Because of this distinction the syntax for display pages is different from the syntax for the update pages.
Display page syntax
Aspire currently supports three types of display pages. A JSP page display, an XSLT page display and an Aspire Tags based Display. In this context also read the following document for more details.
05.02 Painting web pages using Aspire : A step by step approach
Aspire Tags Display Page Syntax
MyPageURL=aspire:\\mydir\\dynamic-page1.html
MyPageURL.formhandlerName=MyPageDataDef
request.MyPageDataDef.form_handler.class_request.className=com.ai.htmlgen.DBHashTableFormHandler1
The class DBHashTableFormHandler1 is a java class that is capable of producing a hierarchical data set (hds). That is why I sometime call this class "hdsProducer". This hdsProducer will require its own properties definition which doesn't change whether you use tags, xslt or JSP. Let me now give an example for the JSP
JSP display page syntax
Read the following document for a more detailed explanation of JSP stuff
MyPageURL=/jsps/test.jsp
MyPageURL.transformType=JSP
request.MyPageURL.transform.className=com.ai.jsp.JSPTransform
MyPageURL.formHandlerName=MyPageDataDef
Data syntax for both of the above
#
#Data definition
#
request.MyPageDataDef.form_handler.class_request.className=\
com.ai.htmlgen.DBHashTableFormHandler1
#
#Maindata request: Outside key value pairs
#
request.MyPageDataDef.maindataRequest.classname=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.maindataRequest.db=reportsDB
request.MyPageDataDef.maindataRequest.stmt=\
\
select first_name as user_first_name \
,last_name as user_last_name \
,email as user_email \
from users \
where user_id = {ownerUserId.quote}
#
# A loop of data for a loop called FoldersLoop
#
request.MyPageDataDef.FoldersLoop.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.FoldersLoop.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.FoldersLoop.query_request.db=reportsDB
request.MyPageDataDef.FoldersLoop.query_request.stmt=\
select * from folders \
where 1=1 \
and parent_folder_id is null \
and public = 'Y' \
and owner_user_id = {ownerUserId.quote} \
order by folder_name
Special notes for display
Notice that there are no redirect url specifications for the display stuff.
Update page syntax
Read the following document for more stuff on updates
Here is the syntax for it in brief
#*****************************************************
#Have a business class responsible for this request
#*****************************************************
request.updateRequest.classname=com.ai.db.DBRequestExecutor2
request.updateRequest.db=(my-database-name)
request.updateRequest.query_type=update
request.updateRequest.stmt=\
insert into table1 (a,b,c) values ('literal',{arg1},{arg2.quote})
#*****************************************************
#Based on sucess or failure redirect the user to a display page
#*****************************************************
request.updateRequest.redirectURL=\
/your-webapp/servlet/DisplayServlet?url=Page1&arg1={any-key}
request.updateRequest.failureRedirectURL=\
/your-webapp/servlet/DisplayServlet?url=Page1&arg1={any-key}&result=error
A more elaborate update syntax example
#*****************************************************
#Have a business class responsible for this request
#*****************************************************
request.updateRequest.classname=com.ai.db.PreTranslateArgsMultiRequestExecutor
request.updateRequest.db=(my-database-name)
request.updateRequest.query_type=update
request.updateRequest.request.1=Update1
request.updateRequest.request.2=Update2
#*****************************************************
#Based on sucess or failure redirect the user to a display page
#*****************************************************
request.updateRequest.redirectURL=\
/your-webapp/servlet/DisplayServlet?url=Page1&arg1={any-key}
request.updateRequest.failureRedirectURL=\
/your-webapp/servlet/DisplayServlet?url=Page1&arg1={any-key}&result=error
#*****************************************************
#Define individual requests
#*****************************************************
request.Update1.classname=com.ai.db.DBRequestExecutor2
request.Update1.db=(my-database-name)
request.Update1.query_type=update
request.Update1.stmt=\
insert into table1 (a,b,c) values ('literal',{arg1},{arg2.quote})
request.Update2.classname=com.ai.db.DBRequestExecutor2
request.Update2.db=(my-database-name)
request.Update2.query_type=update
request.Update2.stmt=\
insert into table1 (a,b,c) values ('literal',{arg1},{arg2.quote})
References
1. Painting web pages using Aspire : A step by step approach