smith project

Documentation

Installation

Smith can be easily integrated into any Java web application. It requires JDK (Java Development Kit), version 1.4 or higher, and some servlet container installed and configured. Smith itself consists of the single Java archive file (smith.jar) and several dependencies - all of them are well-known, open-source Java libraries:

Library	Web Site
Commons Codec 1.3	http://jakarta.apache.org/commons/codec/
Commons Collections 3.1	http://jakarta.apache.org/commons/collections/
Commons Mail 1.0	http://jakarta.apache.org/commons/email/
Commons Http Client 3.0	http://jakarta.apache.org/commons/httpclient/
c3p0 database connection pool	http://sourceforge.net/projects/c3p0
GuessEncoding	http://glaforge.free.fr/wiki/index.php?wiki=GuessEncoding
Jakarta Oro 2.0.6	http://jakarta.apache.org/oro/
Jodd	http://jodd.sourceforge.net/
Log4j 1.2.8	http://logging.apache.org/log4j/docs/index.html
JUG - Java Uuid Generator	http://jug.safehaus.org/
Java Mail API	http://java.sun.com/products/javamail/
Xalan - Java XSLT processor	http://xml.apache.org/xalan-j/
Xerces - Java XML parser	http://xerces.apache.org/xerces-j/

Optionally, appropriate JDBC drivers are needed for connecting to a database.
Every Java Web application running Smith (in further text Smith instance) needs to have those libraries on its classpath, most usually on the WEB-INF/lib directory.

Each Smith instance requires web descriptor file (web.xml) at the application root directory containing few important definitions. Typically, web.xml has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4"
         id="smith">

    <!-- Smith servlets -->
    <servlet>
        <servlet-name>admin</servlet-name>
        <servlet-class>com.youngculture.smith.engine.servlets.Admin</servlet-class>

        <!-- optional param 1 -->
        <init-param>
            <param-name>adminallowed</param-name>
            <param-value>true</param-value>
        </init-param>
        
        <!-- optional param 2 -->
        <init-param>
            <param-name>configfile</param-name>
            <param-value>
                <!-- HERE GOES FULL PATH TO THE CONFIG FILE -->
            </param-value>
        </init-param>

        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>admin</servlet-name>
        <url-pattern>/IDE/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>cfmservlet</servlet-name>
        <servlet-class>com.youngculture.smith.engine.servlets.SmithServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>cfmservlet</servlet-name>
        <url-pattern>*.cfm</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>cfmservlet</servlet-name>
        <url-pattern>*.cfc</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>all</servlet-name>
        <servlet-class>com.youngculture.smith.engine.servlets.AllServlet</servlet-class>
    </servlet>

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

    
    <!-- welcome files -->
    <welcome-file-list>
        <welcome-file>/index.cfm</welcome-file>
    </welcome-file-list>

    <!-- OPTIONALLY, OTHER DEFINITIONS, NOT RELATED TO SMITH -->

</web-app>

There are two optional parameters in the Admin servlet definition affecting Smith administration:

Optional parameter 1 is called adminallowed and its value should be true or false (default). If this parameter is set to true, the Smith instance will allow access to Smith administration screens.
Optional parameter 2 is called configfile and its value should be full path of the config file that the Smith instance uses for its configuration. If this parameter is omited, Smith runs with the default configuration.

See Configuring Smith for more details.

At the end, here is the typical structure of one Smith instance:

    <application root>
        WEB-INF/
            lib/
                activation.jar
                c3p0-0.9.1.2.jar
                commons-codec-1.3.jar
                commons-collections-3.1.jar
                commons-email-1.0.jar
                commons-httpclient-3.0.jar
                commons-logging.jar                
                GuessEncoding.jar
                jakarta-oro-2.0.6.jar
                jodd.jar
                jug-lgpl-2.0.0.jar
                log4j-1.2.8.jar
                mail.jar
                smith.jar
                xalan.jar
                xercesImpl.jar
            web.xml
        index.cfm
        ... 
        ColdFusion stuff

One common way to deploy Java web application is to pack this structure in the single Web archive (WAR) file and simply drop it on the web apps directory under the servlet container (i.e. Apache Tomcat).

Download WAR file containing required structure at download section.