05.00 A 30 minute guide to developing your first web application with Aspire

2-Jul-03 (Created: 2-Jul-03) | More in 'Howto'

05.00 A 30 minute guide to developing your first web application with Aspire

Relevent websites and links

http://www.apache.org for Tomcat downloads/docs
http://www.activeintellect.com for Aspire downloads/docs/newsgroups
http://www.oreillynet.com/pub/au/241 A series of articles on Aspire at O'Reilly
http://216.187.231.34/akc/servlet/DisplayServlet?url=ShowFiledReportsViewJSPURL&ownerUserId=aspire Aspire online docs

Installing Aspire

Download tomcat

Applications that are developed with aspire needs a servlet host (an application server) to run in. I normally use Tomcat for this purpose. You can use any servlet container for this purpose. You can download Tomcat by going to the apache web site listed above and choose to go to "jakarta". With in jakarta go to tomcat. Choose a binary release of 4 or above.

Tomcat will have releases for unix as well as NT. NT releases are usually executable files with .exe extension. Unix files have usually a "tar" in their names. Save this file to your local drive.

Install tomcat on your machine

Double click on the above executable to launch the tomcat installation. It will automatically detect a JDK on your box. If you don't have a JDK tomcat may try to install one. I haven't verified this fact as I always had a JDK on my box. JDK 1.3.1 is a safe choice.

Also try to install it to a simple directory path instead of the default path which puts it under a deeply nested windows directory. This will allow you to be able to get to tomcat config files easily for changes.

Tomcat will create short cuts for starting and stoping. You can drage these short cuts to your task bar for easier access.

Test tomcat on your machine

Go ahead and start tomcat. Then open up a browser and go to "http://localhost:8080". This should take you to the tomcat home page on the local box. Try out a few samples on the home page to make sure everything is running OK.

Download Aspire

If you have come so far, congratulations on completing the first leg of this trip. To download Aspire go to "http://www.activeintellect.com". On the left hand side in the table of contents you will see a link for "quick install". Choose that. In the first couple of paragraphs you will see a link for "aspire distributions" directory. Also this page should describe what to download. The download is usually a single zip file whose name resembles "aspire_jsdk21_r2_b18.xx_src.zip".

Unzip Aspire

Go a head and unzip this file into a convenient location on your hard drive.In the unzipped directory look for a directory called "apptemplate". Make a note of its absolute path as you will be using this shortly.

Point Aspire to Tomcat

When Tomcat starts it runs the registered applications with it. The task here is to register the downloaded aspire application template with Tomcat. This is done by locating a Tomcat configuration file called "tomcat_install_dir\conf\server.xml". With in this config file you need to enter the following line

<Context path="/aspire" docBase="g:/secondary/ai/aspire_samples/apptemplate" debug="0"/&rt;

Notice that my absolute path starts with a "g:". In your case this completely depends on where you have unzipped the file. For unix variants use the appropriate absolute unix path.

The next question is where to put this line with in the file. To do this try to locate other XML nodes that start with "context". Just add the above line as a sibling to one of these nodes. That is just a fancy way of saying put this line underneath those lines. But be aware that you are editing an XML file and adhere to the usual XML file considerations.

Test Aspire installation

Stop and Start tomcat after the above modification is made. When tomcat starts it is set up to run in a command line window. You will see text scorlling by as it initializes various applications. You should see as part of this text a message indicating that the web application that we have defined "aspire" is initialized. You will also see the build numbers of Aspire listed here. If you don't see this, please email me at [email protected].

Now try to hit the site by browsing to "http://localhost:8080/aspire". This should take you to an Aspire page with a few sample screens. Access a couple of these links. This will prompt you for a userid and password. These are usually "demo/aspire".

If the above worked you have successfully tested the installation of Aspire.

You just have created your first web application

You have just finished creating your first web application. Because what you have downloaded is a pre-fabricated Aspire application. All you are going to be doing now is to add your own pages to this application and will eventually delete out the sample pages as you progress with your application.

Adding your first page to the application

This section will take you through a step by step process of adding a new page to the default application that you have installed above. You will be carrying out the followign steps

Create a sub directory under apptemplate
Create a properties file
Define your database in the properties file
Create a definition for your data
Include the properties file in the master aspire.properties
Test your data retrieval
Create an html template file
Create a page defintion that ties the template to the data
Test your page

A detailed explanation of the steps follow

Create a sub directory under apptemplate

Because you are venturing in to developing your own content it is a good idea to keep your efforts separate from the rest of the application template. The best way to do this is to create a subdirectory where you can keep your files. Let me call this sub directory "mydir". The directory structure will now look like

apptemplate\mydir

Create a properties file

Most of the work in Aspire is carried out using definitions. These definitions are kept in text files on the local file system. These text files are then included in a master text file that aspire loads at start up. These text files usually carry an extension of ".properties". So in preparation for the first page let us create a text file called "myfirstpage.properties". So you now have

apptemplate\mydir\myfirstpage.properties

Define your database in the properties file

First thing we are going to add to this text file is your database. Here is how a database definition looks like

# give a name to the database
Database.name = as400db

# Define the jdbc characteristics

Database.as400db.jdbc_driver=com.ibm.as400.access.AS400JDBCDriver
Database.as400db.connection_string=jdbc:as400://ip-address
Database.as400db.userid=your-userid
Database.as400db.password=your-password

Database.alias.as400dbAlias=as400db

Just remember that this section will vary depending on the database type. See the database support of the aspire online docs for definitions for varieties of databases. Also make sure the jar file for your JDBC driver is in the "\apptemplate\web-inf\lib" directory. Depending on the database you may need to obtain this jar file from the vendor.

Save the file after you make these changes.

Create a definition for your data

The next part is to define data for our page. Lets call the page "MyPageURL".


# 0). Identify your URL to the system and have it point to a template page (your design)
# Your template page at this time doesn't exist so set it to "none" 
# We will set this to a valid page in the next section
MyPageURL=none

# 1). Identify a data definition for your page
MyPageURL.formhandlerName=MyPageDataDef

#Identify a pre-built java part that knows how to get the data for that definition
request.MyPageDataDef.form_handler.class_request.className=com.ai.htmlgen.DBHashTableFormHandler1

# 2). Identify if the data definition has any loop data sets
MyPageDataDef.loopNames=dataset1,dataset2

# 3). dataset1 representing a select statement
request.MyPageDataDef.dataset1.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset1.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset1.query_request.db=as400dbAlias
request.MyPageDataDef.dataset1.query_request.stmt=\
your select statement

# 4). dataset2 representing another select statement
request.MyPageDataDef.dataset2.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset2.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset2.query_request.db=as400dbAlias
request.MyPageDataDef.dataset2.query_request.stmt=\
your another select statement

The java classes that are mentioned here usually do not change. So as you create more and more page/data definitions you are largely doing a cut and paste and changing the relevent keys.

Include the properties file in the master aspire.properties

Now that we have the data definition, save that file and it is time to include this in the master properties file called "aspire.properties". This file is available at

\apptemplate\properties\aspire.properties

Include this file at the end of aspire.propeties as follows


application.includeFiles=aspire:\\samples\\hello-world\\properties\\hello-world.properties,\
....other lines
aspire:\\mydir\\myfirstpage.properties,\
....other lines

Please follow the directions in the aspire.properties files for the syntax of inclusion

Test your data retrieval

Now it is time to test the data definition. Restart tomcat if it is already running. If you have included the "myfirstpage.properties" properly, then you should see on the tomcat console a reference to this properties file being loaded.

Now open up a browser and do the following:

http://localhost:8080/aspire/servlet/DisplayServlet?url=MyPageURL&aspire_output_format=object-xml

This will print out an XML data set on your screen. If you are using internet explorer this XML file will be displayed properly as an XML file. If you are using other browsers you may want to use "view source" to see the actual xml file. Either way this xml file will show you the column names etc.

Create an html template file

It is time to create an html template file that keeps your page design. Create your html page first. Then to include your data in this page you will make use of two tags.

Here are the examples of both.

My name is {{name_column_name}}.
My last name is {{lastname_column_name}}

I have worked at the following places

<!--RLF_TAG BGN_LOOP dataset1 -->
I have worked at {{place_column_name}}
<!--RLF_TAG END_LOOP dataset1 -->

I have lived at the following places

<!--RLF_TAG BGN_LOOP dataset2 -->
I have lived at {{place_column_name}}
<!--RLF_TAG END_LOOP dataset2 -->

Save this file as an html file called "myfirstpage.html" in your sub directory. You will now have files as follows

\apptemplate\mydir\myfirstpage.properties
\apptemplate\mydir\myfirstpage.html

Create a page defintion that ties the template to the data

Now let us update the data definition we have so far with this html file as follows

# 0). Identify your URL to the system and have it point to a template page (your design)
MyPageURL=aspire:\\mydir\\myfirstpage.html

The rest of the defintions stays the same

# 1). Identify a data definition for your page
MyPageURL.formhandlerName=MyPageDataDef

#Identify a pre-built java part that knows how to get the data for that definition
request.MyPageDataDef.form_handler.class_request.className=com.ai.htmlgen.DBHashTableFormHandler1

# 2). Identify if the data definition has any loop data sets
MyPageDataDef.loopNames=dataset1,dataset2

# 3). dataset1 representing a select statement
request.MyPageDataDef.dataset1.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset1.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset1.query_request.db=as400dbAlias
request.MyPageDataDef.dataset1.query_request.stmt=\
your select statement

# 4). dataset2 representing another select statement
request.MyPageDataDef.dataset2.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset2.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset2.query_request.db=as400dbAlias
request.MyPageDataDef.dataset2.query_request.stmt=\
your another select statement

Test your page

Restart the tomcat and open up a web browser and type in the following url

http://localhost:8080/aspire/servlet/DisplayServlet?url=MyPageURL

You should see your page with data replaced

The final properties file


# give a name to the database
Database.name = as400db

# Define the jdbc characteristics

Database.as400db.jdbc_driver=com.ibm.as400.access.AS400JDBCDriver
Database.as400db.connection_string=jdbc:as400://ip-address
Database.as400db.userid=your-userid
Database.as400db.password=your-password

Database.alias.as400dbAlias=as400db



# 0). Identify a data definition for your page
MyPageURL=aspire:\\mydir\\myfirstpage.html

The rest of the defintions stays the same

# 1). Identify a data definition for your page
MyPageURL.formhandlerName=MyPageDataDef

#Identify a pre-built java part that knows how to get the data for that definition
request.MyPageDataDef.form_handler.class_request.className=com.ai.htmlgen.DBHashTableFormHandler1

# 2). Identify if the data definition has any loop data sets
MyPageDataDef.loopNames=dataset1,dataset2

# 3). dataset1 representing a select statement
request.MyPageDataDef.dataset1.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset1.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset1.query_request.db=as400dbAlias
request.MyPageDataDef.dataset1.query_request.stmt=\
select statement

# 4). dataset2 representing another select statement
request.MyPageDataDef.dataset2.class_request.className=com.ai.htmlgen.GenericTableHandler6
request.MyPageDataDef.dataset2.query_request.className=com.ai.db.DBRequestExecutor2
request.MyPageDataDef.dataset2.query_request.db=as400dbAlias
request.MyPageDataDef.dataset2.query_request.stmt=\
another select statement

You don't have to repeat the database definition as you create more and more pages.

Where to go from here

In your download directory there is a subdirectory called docs. There is a users guide in there. You will also see some powerpoints etc. The website of aspire also has some online docs and database support docs. Between all these you will be looking for documentation that describes the following: