------------------------------------------------------------------------------

                                Millstone(tm) 
				
  Open Sourced User Interface Library for Internet Development With Java(tm)

                                version 3.1.0

                       (c) 2000-2005, IT Mill Ltd

------------------------------------------------------------------------------

0. Contents
------------------------------------------------------------------------------
1. 	Prerequisites
1.1.	Base requirements
1.2.	Additional requirements
1.2.	Additional requirements
2.	Installing
2.1.	Installing the Millstone examples WAR
2.1.1.	Installing the Millstone examples WAR on Tomcat
2.1.2.	Installing the Millstone examples WAR on Sun ONE
2.1.3.	Installing the Millstone examples WAR on jo!
2.2.	Installing your own Millstone application
2.3.    Configuration of the applications
2.4.    Selecting XSLT processor 

------------------------------------------------------------------------------

1. Prerequisites
----------------

1.1 Base requirements
---------------------

  - Java version 1.4 or 1.5

  - Servet container conforming to servlet specification 2.2. 
    Millstone 3.1.0 has been tested with Tomcat, available from 
    http://jakarta.apache.org/tomcat/, and jo! 1.0, available from
    http://www.tagtraum.com/

  - Millstone is compatible with Crimson and Xerces
    XML-parsers and Xalan and Saxon XSLT-processors, as well as
    many others. Sun J2SDK 1.4 contains Xalan and Crimson, that work
    well with Millstone. Saxon (tested version 7.3) is a lot faster
    than Xalan and is thus recommended.


1.2 Additional requirements
---------------------------
  - Building Millstone-examples WAR need Html-document builder Java2Html
    (http://www.java2html.de)
  - The StonePlayer example uses Java Layer 0.1.1 library for playing
    (http://www.javazoom.net/javalayer/javalayer.html). 
    However, you need not worry about this if you are using the 
    Millstone examples WAR, since the WAR includes all required
    libraries.


2. Installing
-------------

A good starting point to get aquainted with Millstone is to install
the Millstone-examples WAR. This is a package containing all 
required libraries to run the examples, and is easy to install on
any servlet container supporting WARs for application deployment.
See section 2.1 for more instructions on this.

If you are developing and deploying your own Millstone application,
the procedure is somewhat different. Consult section 2.2 for more
information on this. You might however want to produce a WAR for
easy deployment when your application is ready - studying the 
Millstone examples WAR might give valuable information on this topic.


2.1 Installing the Millstone examples WAR
-----------------------------------------

Most current application servers support autodeployment of WARs - this
makes it very easy to deploy applications. The procedure and/or
location of the WARs might vary between server brands, so a quick
look in your particular server's documentation might be useful.

The general approach is to copy the WAR to deployment-directory (in 
Tomcat this is called 'webapps'), which will cause the server to 
deploy the application automatically. To add paramters to application, 
you must edit the server deployment configuration (in Tomcat this
can be found in conf/server.xml).


2.1.1 Installing the Millstone examples WAR on Tomcat
-----------------------------------------------------

Tomcat is a nice servlet container produced by the Apache Foundation and 
released under the Apache Software License.  You can get Tomcat from
	http://jakarta.apache.org/tomcat/

Tomcat is used in the official Reference Implementation for the Java Servlet 
and JavaServer Pages technologies and is the default server used by Millstone 
developers.

  1. Download Tomcat installer for your platform from 
     Tomcat website at http://jakarta.apache.org/tomcat/
  
  2. Install Tomcat according to the included installation
     instructions.
     
  3. Copy millstone-examples war-file to webapp-directory of
     the tomcat. 
     
  4. Modify the server.xml found in $TOMCAT_HOME/conf. In default
     installation this is not required, but if you wantto change
     the context parameters or URI you may wish modify them.
     If you do, ensure the tomcat is unpackWars="true" parameter 
     is specified for Host-element. This makes the tomcat to first 
     extract the WAR-archive, and it is required by the Web Adapter.
     For complete reference about available options refer to
     Tomcat documentation at http://jakarta.apache.org/tomcat/.     

  5. Start Tomcat(follow the instructions included in Tomcat
     documentation as necessary). The examples are accessible through 
     default URL http://<host>:<port>/<Examples WAR name>/
     for example: http://localhost:8080/millstone-examples-3.1/
     
  6. Some examples are not very usable without little more
     configuration. Especially the stoneplayer requires
     an extra parameter to be specified for MP3-directory
     to be accessible. You can do this in web.xml of
     the examples:
     
       <servlet>
          <servlet-name>stoneplayer</servlet-name>

	   [...]

 	   <init-param>
	      <param-name>mp3path</param-name>
	      <param-value>c:\music\</param-value>
	   </init-param>

       </servlet>

     Or you can specify it as servlet parameter in the
     server.xml found under $TOMCAT_HOME/conf:
     
       <Context path="/examples" docBase="[ ... ]" >
  
         [ ... ]
      
           <!-- Default MP3 Source -->
           <Parameter name="mp3path" value="c:\music" />

         [ ... ]
	 
       </Context>
	  

2.1.2 Installing the Millstone examples WAR on Sun ONE
------------------------------------------------------

Examples are packaged as standard web application.

Intallation instructions for Sun ONE Application Server
can be found at: http://docs.sun.com/source/816-7150-10/index.html


2.1.3 Installing the Millstone examples WAR on jo!
--------------------------------------------------

jo! is an easy to use web server released under the LGPL license. jo! has
a graphical interface, and is easy to install. You can get jo! from
	http://www.tagtraum.com/


  1. Download jo! 1.0 from tagrum industries at http://www.tagtraum.com/
     You can choose between .tar.gx (for unix systems), .zip or .exe formats.
     The .exe has a simple installation program.

  2. Install jo! according to instructions. The directory where you installed
     jo! will henceforth be called <JO_HOME.

  3. Start jo! (read the instructions, the installer on windows places jo! in
     the start menu) and verify that everything is working by browsing to
     to your own computer, port 8080 (try http://127.0.0.1:8080/)

  4. Copy the millstone-examples-x.y.z.war to the <JO_HOME>/webapp/host -directory.
     Using the defaults in the .exe installer, this should be something like
     C:\Program Files\tagtraum industries\jo\webapp\host

  5. jo! should automatically deploy the application, browse to  
     http://127.0.0.1:8080/millstone-examples-x.y.x/ to try it out!

  6. In jo! you will have to set servlet init-params in the web.xml -file.
     Go to the <JO_HOME>/webapp/host/millstone-examples-x.y.z/WEB-INF -directory
     and edit web.xml located there. 
     For instance, for Stoneplayer to find your mp3 -files, you must tell it 
     where to look. This is done by adding (or modifying) the servlet section
     as outlined below:

       <servlet>
          <servlet-name>stoneplayer</servlet-name>

	   [...]

 	   <init-param>
	      <param-name>mp3path</param-name>
	      <param-value>c:\music\</param-value>
	   </init-param>

       </servlet>

     You might also want to enable (or disable) the UIDL debugging window for 
     the applications:

        <init-param>
            <param-name>debug</param-name>
            <param-value>true</param-value>
        </init-param>


2.2 Installing your own Millstone application
---------------------------------------------

If you are deploying or developing your own Millstone application,
you need to set up a suitable directory structure under your server's
web-application directory - consult your particular server's 
documentation for more information.
The directory structure will look something like:

   your-application/
   your-application/WEB-INF/
   your-application/WEB-INF/web.xml
   your-application/WEB-INF/classes/
   your-application/WEB-INF/lib/

The 'classes' -directory is for your java .class -files, while the
'lib' -directory is for java .jar -libraries.

Install the Millstone base-, webadapter- and theme-libraries
in the 'lib' directory:

   your-application/WEB-INF/lib/millstone-base-x.y.z.jar
   your-application/WEB-INF/lib/millstone-webadapter-x.y.z.jar
   your-application/WEB-INF/lib/millstone-themes-x.y.z.jar

Finally install your .class -files in the 'classes' directory and
modify the web.xml file to so that is look something like:

   [...]
   <web-app>
     <servlet>
        <servlet-name>your-application</servlet-name>
        <servlet-class>org.millstone.webadapter.WebAdapterServlet</servlet-class>
        <init-param>
            <param-name>application</param-name>
            <param-value>your.package.MainClass</param-value>
        </init-param>
     </servlet>

     <servlet-mapping>
       <servlet-name>your-application</servlet-name>
       <url-pattern>/your-application/*</url-pattern>
     </servlet-mapping>

   </web-app>
   [...]

Consult your server's documentation for details. You might also want to study
the Millstone examples and their web.xml.


2.3 Configuration of the applications
-------------------------------------

Typically application require external configuration, such as
setting working directories, defining external resources, etc.

Millstone applications are configured through application
properties. They are assigned to the application before
it is initialised, and are read-only.

In WebAdapter the application properties may specified 
using the the context specific parameters or servlet 
initialization parameters. The actual source for these 
parameters depends on the servlet container implementation.

In Tomcat the context parameters are specified in 
server.xml and the servlet initialization parameters are
specified in web.xml.

For example to enable debug mode in server.xml:

    <Context [...]>
    
        [...]
        
        <Parameter name="debug" value="true" override="false"/>
    </Context>
    
Or in web.xml:
    <servlet>
    
        [...]
    
        <init-param>
            <param-name>debug</param-name>
            <param-value>true</param-value>
        </init-param>
    </servlet>

Note, that the context parameters are common to all applications
running within the context.


2.4 Selecting XSLT processor
----------------------------

By default Millstone Web Adapter uses the default XSLT processor of the
System. You can select different XSLT processor by adding it to classpath
and setting system property through JVM option:
 
 -Djavax.xml.transform.TransformerFactory=transformer.factory.class
 
Some XSLT processors may require explicitly selecting XML-parser. For example
you can use Saxon 7 by adding the following parameters to JVM:

 -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
 -Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl

Usage of Saxon 7 is recommended as it is a lot faster than Xalan. 


------------------------------------------------------------------------------
Millstone is a registered trademark of IT Mill Ltd