This tutorial describes the basic steps needed to create a search application with the Raritan Search Application Framework. The initial steps are common to any Java based (J2EE) web application development process - a J2EE web application server environment needs to be set up. The web application can then be developed, deployed and tested. For most applications, this involves writing Java Server Pages (JSP pages), XML configuration files and cascading style sheets (CSS files). Extended features may require the development of additional Java code (see adding features page).

The examples in this tutorial were developed using the Apache Tomcat application server. Procedures for other application servers and/or Integrated Development Environments may differ (see notes section).

Once a web application development environment is established, we can create our first application. The typical directory structure of a framework application is shown below. (Note: this image is clickable. It uses several Framework elements: an ExploreTreeRenderer to render the left side tree and a TreeTabRenderer to to relate the left side tree to the right side diplay.)

FrameworkApplication css images WEB-INF classes conf lib

The main directory typically contains the application JSP and html pages. The name of this directory is the application name that a would be contained in the applications URL:   http://<host name:port>/<main directory name>/aPage.jsp So in this case the URL would be something like:   http://www.somehost.com/FrameworkApplication/aPage.jsp Contains Cascading stylesheets (CSS files) used by JSP and XML configured modules. Contains the images (.gif, .pdf, etc) used by the application. This is a J2EE standard directory that contains: Custom Tag Library Descriptor (tld) files web.xml file which contains Servlet definitions. This is a J2EE standard directory that contains the Config.properties file which is needed for application initialization. This directory contains: The Main XML configuration file Supporting XML configuration files, HTML Scraper configuration and XSLT transforms. The Source Map XML file. A J2EE standard directory that contains the java library files including the Raritan framework code (raritan.jar), open source modules and licenced code from vendors such as Autonomy, Documentum or Fast.

• DisplayForm.tld
    Contains custom tag descriptors for result display modules.
  
  
• SearchForm.tld
    Contains custom tag descriptors for search form modules.
  
  
• Query.tld
    Contains custom tag descriptors for query save/restore/sharing modules.
  
  
• Request.tld
    Contains custom tag descriptors for http request display/processing modules.
  
  
• Tree.tld
    Contains custom tag descriptors for tree display modules.
  
  

The web.xml file is used in J2EE applications to map Java Servlet URLs to servlet classes.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
    <!-- GetContent Servlet: Maps http request to a Framework ContentHandler -->
    <servlet>
      <servlet-name>GetContent</servlet-name>
      <servlet-class>com.raritantechnologies.quickstart.userInterface.GetContentServlet</servlet-class>
    </servlet>

    <servlet-mapping>
      <servlet-name>GetContent</servlet-name>
      <url-pattern>GetContent</url-pattern>
    </servlet-mapping>


    <servlet>
      <servlet-name>LoginServlet</servlet-name>
      <servlet-class>com.raritantechnologies.quickstart.userInterface.LoginServlet</servlet-class>
    </servlet>

    <servlet-mapping>
      <servlet-name>LoginServlet</servlet-name>
      <url-pattern>doLogin</url-pattern>
    </servlet-mapping>

    <servlet>
      <servlet-name>LogLinkServlet</servlet-name>
      <servlet-class>com.raritantechnologies.searchApp.logging.LoggingServlet</servlet-class>
    </servlet>

    <servlet-mapping>
      <servlet-name>LogLinkServlet</servlet-name>
      <url-pattern>LogLink</url-pattern>
    </servlet-mapping>

    <!-- setParams servlet - used to dynamically set persistent parameters on the application server -->
    <!-- without requiring a browser page refresh. -->
    <servlet>                                                                   
      <servlet-name>ParamServlet</servlet-name>                                 
      <servlet-class>com.raritantechnologies.quickstart.userInterface.SetPersistentParameterServlet</servlet-class>                                             

    </servlet>                                                                  
                                                                                
    <servlet-mapping>                                                           
      <servlet-name>ParamServlet</servlet-name>                                 
      <url-pattern>setParam</url-pattern>                                       
    </servlet-mapping>    


    <servlet> 
      <servlet-name>GetPieChart</servlet-name> 
      <servlet-class>com.raritantechnologies.quickstart.userInterface.GetPieChartServlet</servlet-class> 
    </servlet> 

    <servlet-mapping> 
      <servlet-name>GetPieChart</servlet-name> 
      <url-pattern>GetPieChart</url-pattern> 
    </servlet-mapping> 

    <servlet> 
      <servlet-name>ChartServlet</servlet-name> 
      <servlet-class>com.raritantechnologies.quickstart.userInterface.ChartServlet</servlet-class> 
    </servlet> 

    <servlet-mapping> 
      <servlet-name>ChartServlet</servlet-name> 
      <url-pattern>ChartServlet</url-pattern> 
    </servlet-mapping> 


    <servlet> 
      <servlet-name>Logout</servlet-name> 
      <servlet-class>com.raritantechnologies.searchApp.taglibrary.Logout</servlet-class> 
    </servlet> 

    <servlet-mapping> 
      <servlet-name>Logout</servlet-name> 
      <url-pattern>Logout</url-pattern> 
    </servlet-mapping> 

</web-app>

The Config.properties file controls the initialization of the framework ConfigurationManager by identifying the ConfigurationManager and SecurityManager implementation classes and the location of the main configuration and source map XML files and other supporting configurations.

# Config.properties - contains main starting point for
# Framework Applications ConfigurationManager and SecurityManagers

ConfigurationManager.class=com.raritantechnologies.federated.FederatedConfigurationManager
SecurityManager.Class=com.raritantechnologies.searchApp.PropertiesSecurityManager

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

SearchSource.CBSNews.ConfigPath=BASE_PATH/WEB-INF/conf/CBSNews/
SearchSource.GoogleSOAP.ConfigPath=BASE_PATH/WEB-INF/conf/Google/

SearchSource.PubChemSmilesFinder.ConfigPath=BASE_PATH/WEB-INF/conf/PubChem/

<!-- JSP tablib include tags for the Raritan Framework modules -->
<%@ taglib uri="../WEB-INF/SearchForm.tld" prefix="search" %>
<%@ taglib uri="../WEB-INF/DisplayForm.tld" prefix="results" %>

<html>

<head>
  <title>[ The page Title ]</title>

  <!-- include CSS stylesheets -->
  <link rel="stylesheet" type="text/css" href="../css/raritan.css">
</head>

<body>

HTML and JSP custom tags...

</body>
</html>

The main configuration XML file contains configuration settings for all of the modules used in the application. The configuration XML is normally put in the WEB-INF/conf directory within the web application. However, this can be changed if necessary (see notes for scenarios that use non-standard locations). In either case, the location of the application configuration XML file must be specified is Config.properties file (see above):

  QuickAppConfigXML=<Path to Application Configuration File>

<FrameworkConfiguration>

<!-- Describes the abstract (source-independent) field names used in the application -->

<FieldSpecs>

<Field>

<ID>

The Field ID

</ID>

<Name>

Display Name

</Name>

</Field>

</FieldSpecs>

<!-- Describes the search input forms used in the application -->

<SearchForms>

<SearchForm>

</SearchForms>

<!-- Describes the result display forms used in the application -->

<DisplayForms>

<DisplayForm>

</DisplayForms>

<!-- Describes the search sources (data sources) used in the application -->

<SourceType>

<!-- Describes the document content handlers used in the application -->

<ContentHandlers>

<ContentHandler>

</ContentHandlers>

<!-- Section that contains miscellaneous configurable objects -->

<!-- (such as PageImportRenderers, TabRenderers and others.) -->

<SystemObjects>

<SystemObject>

</SystemObjects>

</FrameworkConfiguration>

The Source Map XML file describes how search actions are linked to data sources. The exact format of the Source Map XML file depends on the type of Source Selection component that is used. The basic source selection control (CategorySourceMap) relates a category identifier to one or more search sources, defined in the main Configuration XML's <SourceType> section.

<SourceMap>

<Object type="category">

<Category ID="FrameworkDocs" name="Framework Javadocs">

<Sources>

<Source name="FrameworkDocs">

</Sources>

</Category>

<Category ID="FrameworkTreeSource" name="Framework Tree Source">

<Sources>

<Source name="FrameworkTreeSource">

</Sources>

</Category>

<Category ID="CBSNews" name="CBSNews">

<Sources>

<Source name="CBSNews">

</Sources>

</Category>

<Category ID="FederatedNews" name="FederatedNews">

<Sources>

<Source name="GoogleSOAP">

<Source name="CBSNews">

</Sources>

</Category>

<Category ID="GoogleSOAP" name="GoogleSOAP">

<Sources>

<Source name="GoogleSOAP">

</Sources>

</Category>

<Category ID="TechLinks" name="Technology Links">

<Sources>

<Source name="TechLinks">

</Sources>

</Category>

</Object>

</SourceMap>

This section contains the Java binaries used in the application. This will typically include

• raritan.jar - contains the java classes for the Raritan Framework.
  
• open source code - such as Xerces, Axis, Apache commons, Lucene, etc.
  
• Vendor code (requires licences) - such as Automony(Verity), Documentum, Fast, etc.
  

The two main activities in developing a framework application are writing the JSP page(s) and configuring the associated framework modules. Framework modules are linked to the JSP page through a set of JSP custom tags. Although some module parameters are set in the custom tag attributes, the majority are configured in XML. The JSP pages and the associated XML configuration modules are generally developed in parallel by starting with basics and adding features until the final application is finalized. This process is detailed in the simple application tutorial and subsequent tutorials that show how features can be added to a framework application in an incremental fashion.