Getting Started

Basic Application

Building a simple framework application

Search Source configuration

Developing the search interface

Putting it all together

Building a simple Raritan Framework application

This tutorial will show how a simple web search application can be developed using the Raritan Framework. This application will provide a simple search capability into a Composers/Songwriters database stored as a "flat file". Subsequent tutorials will build on the modules developed in this application to provide more advanced features such as data-aware musical genre and nationality select lists, sorting controls and annotation. The goal of the tutorials is to get a overall idea of how framework applications are built.

The Composer/Songwriter Database Application

This application uses a text file exported from a spreadsheet to provide a simple Search Source. The spreadsheet for the application is Composers.xls.

To keep the example simple, we will use a FlatFileSearchSource to turn this data file into a searchable source. (For larger data sets, a relational database combined with a RTI SQLSearchSource, or a search engine such as Autonomy (Verity) or Fast could be used.)

The FlatFileSearchSource is configured by detailing location of the files to be used and the order or data columns in the files. These parameters are configured in the <Files> and <Columns> sections respectively. The source configuration XML for the Contacts spreadsheet is shown here:

  <SourceType name="ComposerDatabase" type="FlatFileSource"
              sourceFactoryClass="com.raritantechnologies.searchApp.FlatFileSearchSource" 
              queryProcessor="com.raritantechnologies.searchApp.FlatFileSearchSource"
              delimiter=","
              blankQueryReturnsAll="false"
              refreshInterval="never"
              fieldOperator="AND"
              caseSensitive="false" >

    <!-- List of files to be imported into the FlatFile Search Source -->
    <Files>
      <File name="BASE_PATH/data/Composers.csv" />
    </Files>

    <!-- Defines the column order of the flat file(s). The ID parameter  -->
    <!-- determines the name of the field in the FlatFileSearchSource.   -->
    <Columns>
      <Column ID="LastName" />
      <Column ID="FirstName" />
      <Column ID="YearOfBirth" />
      <Column ID="YearOfDeath" />
      <Column ID="Genre" />
      <Column ID="Nationality" />
      <Column ID="Keywords" />
      <Column ID="WikipediaLink" />
    </Columns>

  </SourceType>

Developing the search interface

For the search interface, we need a search input form and a way to display the search results. These components are provided by the RTI framework SearchForm and DisplayForm components respectively.

For a basic multi-field Search input form for several search fields, we will use the RTI BasicSearchFormRenderer. Its configuration looks like this:

   <SearchForm name="ComposerSearchForm" category="ComposerDatabase" >
     <Field ID="FirstName"   type="text" width="50" name="First Name" />
     <Field ID="LastName"    type="text" width="50" name="Last Name" />
     <Field ID="Genre"       type="text" width="50" name="Musical Genre" />
     <Field ID="Nationality" type="text" width="50" name="Nationality" />
   </SearchForm>

For the Result Display, we will use a BasicDisplayFormRenderer that will show each field and value in the contact database in a single line. Its XML configuration looks like this:

    <DisplayForm name="ComposerDisplayForm" 
      rendererClass="com.raritantechnologies.searchApp.taglibrary.BasicDisplayFormRenderer"
      headerWidth="200" resultWidth="640" noResultsMessage="" >

      <Field ID="FirstName"     type="text" name="First Name" />
      <Field ID="LastName"      type="text" name="Last Name" />
      <Field ID="YearOfBirth"   type="text" name="Year of Birth" />
      <Field ID="YearOfDeath"   type="text" name="Year of Death" />
      <Field ID="Genre"         type="text" name="Musical Genre" />
      <Field ID="Nationality"   type="text" name="Nationality" />
    </DisplayForm>

Putting it all together

To complete the picture, the individual components need to be integrated into a configuration file, and a JSP page written to organize the application search page. We will then need to put all of the files into a J2EE application directory structure, deploy it to a J2EE application server and run it.

The full application Configuration XML looks like this:

<MainConfiguration>

  <FieldSpecs>
    <Field>
      <ID>LastName</ID>
      <Name>Last Name</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>FirstName</ID>
      <Name>First Name</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>YearOfBirth</ID>
      <Name>Year of Birth</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>YearOfDeath</ID>
      <Name>Year of Death</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>Genre</ID>
      <Name>Genre</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>Nationality</ID>
      <Name>Nationality</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>Keywords</ID>
      <Name>Keywords</Name>
      <Type>AlphaNumeric</Type>
    </Field>
    <Field>
      <ID>WikipediaLink</ID>
      <Name>Wikipedia Link</Name>
      <Type>AlphaNumeric</Type>
    </Field>
  </FieldSpecs>

  <SearchForms>
    <SearchForm name="ComposerSearchForm" category="ComposerDatabase" >
       <Field ID="FirstName"   type="text" width="50" name="First Name" />
       <Field ID="LastName"    type="text" width="50" name="Last Name" />
       <Field ID="Genre"       type="text" width="50" name="Musical Genre" />
       <Field ID="Nationality" type="text" width="50" name="Nationality" />
    </SearchForm>
  </SearchForms>

  <DisplayForms>
    <DisplayForm name="ComposerDisplayForm" 
      rendererClass="com.raritantechnologies.searchApp.taglibrary.BasicDisplayFormRenderer"
      headerWidth="200" resultWidth="640" noResultsMessage="" >

      <Field ID="FirstName"    type="text" name="First Name" />
      <Field ID="LastName"     type="text" name="Last Name" />
      <Field ID="YearOfBirth"  type="text" name="Year of Birth" />
      <Field ID="YearOfDeath"  type="text" name="Year of Death" />
      <Field ID="Genre"        type="text" name="Musical Genre" />
      <Field ID="Nationality"  type="text" name="Nationality" />
    </DisplayForm>

  </DisplayForms>

  <SourceType name="ComposerDatabase" type="FlatFileSource"
              sourceFactoryClass="com.raritantechnologies.searchApp.FlatFileSearchSource" 
              queryProcessor="com.raritantechnologies.searchApp.FlatFileSearchSource"
              delimiter=","
              blankQueryReturnsAll="false"
              refreshInterval="never"
              fieldOperator="AND"
              caseSensitive="false" >

    <!-- List of files to be imported into the FlatFile Search Source -->
    <Files>
      <File name="BASE_PATH/data/Composers.csv" />
    </Files>

    <!-- Defines the column order of the flat file(s). The ID parameter  -->
    <!-- determines the name of the field in the FlatFileSearchSource.   -->
    <Columns>
      <Column ID="LastName" />
      <Column ID="FirstName" />
      <Column ID="YearOfBirth" />
      <Column ID="YearOfDeath" />
      <Column ID="Genre" />
      <Column ID="Nationality" />
      <Column ID="Keywords" />
      <Column ID="WikipediaLink" />
    </Columns>

  </SourceType>

 </MainConfiguration>

The JSP page will present the SearchForm and DisplayForm modules using RTI Custom Tags.

The JSP SearchForm Tag looks like this:

  <search:SearchForm
     formName="ComposerSearchForm" 
     categoryName="ComposerDatabase"
     action="SimpleAppDemo.jsp"
   />

The formName and categoryName parameters map to the name and category parameters of the <SearchForm> tag in the main configuration XML shown above.

The JSP results DisplayForm Tag looks like this:

  <results:DisplayForm formName="ComposerDisplayForm" pageSize="10" />

The formName parameter maps to the name parameter of the <DisplayForm> tag in the main configuration XML shown above.

The complete JSP page for the demo:

  <%@ taglib uri="./WEB-INF/SearchForm.tld" prefix="search" %>
  <%@ taglib uri="./WEB-INF/DisplayForm.tld" prefix="results" %>

  <html>
  <head>
    <title>Composer Database Demo</title>
  </head>

  <body>

  <search:SearchForm
         formName="ComposerSearchForm" 
         categoryName="ComposerDatabase"
         action="SimpleAppDemo.jsp"
       />

  <hr>

  <results:DisplayForm formName="ComposerDisplayForm" pageSize="10" />

  </body>
  </html>

Packaging and deploying the application:

1) Create a J2EE Application with the following directory structure:

  SimpleFrameworkApp
    css
    data
    WEB-INF
      classes
      conf
      lib

2) Copy the Main XML Configuration (shown above) to a text file, name it MainConfiguration.xml and put this file in the conf directory.

3) Create a file called SourceMap.xml and put the following XML in it:

<SourceMap>

  <Object type="category" >
    <Category ID="ComposerDatabase" name="Composer Database"  >
      <Sources>
        <Source name="ComposerDatabase" />
      </Sources>
    </Category>
  </Object>

</SourceMap>

4) Copy the JSP page above, put in a text file named SimpleAppDemo.jsp and put this file in the main SimpleFrameworkApp directory.

5) Copy the SearchForm.tld, DisplayForm.tld and web.xml files from the Framework Distribution package. Put these in the WEB-INF directory.

6) Copy the Contacts.csv file from the Framework Distribution package and put it in the data directory.

7) Create the Config.properties file with the following content:

  ConfigurationManager.class=com.raritantechnologies.quickstart.QuickstartConfigurationManager
  SecurityManager.Class=com.raritantechnologies.searchApp.PropertiesSecurityManager

  QuickAppConfigXML=BASE_PATH/WEB-INF/conf/MainConfiguration.xml
  SourceMapXML=BASE_PATH/WEB-INF/conf/SourceMap.xml

8) Save the Config.properties file in the classes directory.

9) Copy the raritan.jar file from the Framework Distribution package to the lib directory.

The final application should look like this.