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

<document>

  <properties>
        <author email="cstaylor@java-internals.com">Christopher Taylor</author>
        <title>Getting Started with Slide development using Eclipse and JDK 1.4</title>
    </properties>
  
  <body>
  
  <section name="Introduction">
    
    <p>
        There are some things this HOWTO will not cover. First, this HOWTO will not explain how to use the <a href="http://www.eclipse.org/">Eclipse</a> IDE.  A book that I highly recommend is 
        <a href="http://www.amazon.com/exec/obidos/tg/detail/-/0321159640/qid=1061283200/sr=8-1/ref=sr_8_1/002-4564703-5586460?v=glance&amp;s=books&amp;n=507846">The Java Developer's Guide to Eclipse</a>
        Second, this HOWTO will not cover Tomcat, Ant, CVS, or any related tools required to build Slide from source code.  Finally, this HOWTO will not explain how to build using a previous version of
        the Java Developer's Kit.
    </p>
    
    <p>
        Here are the necessary steps:
        <ul>
        <li>Set up a CVS respository link to the Jakarta Slide source code</li>
        <li>Checkout the Slide source code</li>
        <li>Download the required third-party libraries:</li>
            <ul>
            <li>JDOM</li>
            <li>Java Transaction API</li>
            <li>Servlet 2.3</li>
            <li>Jakarta Commons HTTP Client</li>
            <li>Java Management Extension (JMX)</li>
            <li>Catalina components (Jakarta Tomcat version 4.1)</li>
            <li>Log4J</li>
            </ul>
       <li>Modify build.xml to use the new libraries</li>
       <li>Build Jakarta Slide</li>
       <li>Create a new Tomcat project</li>
       <li>Copy the built Slide libraries into the WEB-INF/lib folder in your new Tomcat project</li>
       <li>Copy the Domain.xml and web.xml files from the Slide source folder</li>
       <li>Associate the Slide libraries and source folder in your new Tomcat project</li>
       <li>Modify the web.xml file</li>
       <li>Update application context in server.xml</li>
       <li>Set breakpoints and start Tomcat</li>
       </ul>
    </p>
    
  </section>
  
  <section name="Set up the CVS repository link to the Jakarta Slide source code">
    
    <p>
        In Eclipse, using the CVS Repository Exploring perspective, create a new entry for Jakarta:
        <ul>
        <li>Host: cvs.apache.org</li>
        <li>Repository path: /home/cvspublic</li>
        <li>User: anoncvs</li>
        <li>Password: anoncvs</li>
        <li>Connection type: pserver</li>
        </ul>
    </p>
    <p>
        <img src="images/eclipse-cvs.png" />    
    </p>
  </section>
  <section name="Checkout the Slide source code">
    <p>
        After you have the CVS repository link set up, you'll need to checkout a particular version of the source tree.  In this example we will use the 1.0.16 tagged version of Slide.  
        First, open the Jakarta CVS repository and select the <b>Versions</b> subtree:
    </p>
    <p>
        <img src="images/eclipse-cvs2.png" />    
    </p>
    <p>
        Locate the project labeled <b>jakarta-slide</b>, right-click on the label, and select <b>Configure Branches and Versions</b> from the context menu.  The following window should appear:
    </p>
    <p>
        <img src="images/eclipse-cvs3.png" />    
    </p>
    <p>
        In the <b>Browse files for tags</b> section, choose the <code>.cvsignore</code> file, then press the <b>Add Selected Files</b> button.  You should see a list of tags appear in the 
        <b>New tags found in the selected files</b> section.  Pressing the <b>Ok</b> button will return you to the <b>Versions</b> subtree of the CVS perspective:
    </p>
    <p>
        <img src="images/eclipse-cvs4.png" />    
    </p>
    <p>
        Select the SLIDE_1_0_16 (version 1.0.16) child of the version list, right-click, and choose <b>Check out as Project</b> from the context menu.  The source code will then be downloaded
        to your computer.
    </p>
  </section>
  <section name="Download and install the required third-party libraries">
  <p>
    You must install the following third-party libraries before building Slide:
        <ul>
        <li><a href="http://www.jdom.org/">JDOM</a></li>
        <li><a href="http://java.sun.com/products/jta/">Java Transaction API</a></li>
        <li><a href="http://cvs.apache.org/builds/jakarta-servletapi-4/nightly/">Servlet 2.3</a></li>
        <li><a href="http://jakarta.apache.org/commons/httpclient/downloads.html">Jakarta Commons HTTP Client</a></li>
        <li><a href="http://java.sun.com/products/JavaManagement/download.html">Java Management Extension (JMX)</a></li>
        <li><a href="http://www.apache.org/dist/jakarta/tomcat-4/binaries/">Catalina components (Jakarta Tomcat version 4.1)</a></li>
        <li><a href="http://www.apache.org/dist/jakarta/log4j/">Log4J</a></li>
        </ul>
    Download each of the packages from the above links, and place the following JAR files in your <code>jakarta-slide/lib</code> folder:
        <ul>
        <li>JDOM - <code>jdom.jar</code></li>
        <li>Java Transaction API - <code>jta.jar</code></li>
        <li>Servlet 2.3 - <code>servlet.jar</code></li>
        <li>Jakarta Commons HTTP Client - <code>commons-httpclient.jar</code></li>
        <li>Java Management Extension (JMX) - <code>jmxri.jar</code></li>
        <li>Catalina components - <code>naming-common.jar</code>, <code>naming-resources.jar</code>, <code>catalina.jar</code></li>
        <li>Log4J - <code>log4j.jar</code> (you will need to rename the <code>log4j-1.2.8.jar</code> file)</li>
        </ul>
  </p>
  </section>
  <section name="Modify build.xml to use the new libraries">
    <p>The Ant <b>build.xml</b> file must be modified to point at the third-party libraries.  Change the following <b>property</b> entries:
        <table>
        <tr>
        <th align="center">Property Name</th>
        <th align="center">Old Value</th>
        <th align="center">New Value</th>
        </tr>
        <tr>
        <td>servlet.jar</td>
        <td>${servletapi.home}/lib/servlet.jar</td>
        <td>./lib/servlet.jar</td>
        </tr>
        <tr>
        <td>jmx.jar</td>
        <td>${jmx.home}/lib/jmxri.jar</td>
        <td>./lib/jmxri.jar</td>
        </tr>
        <tr>
        <td>naming.jar</td>
        <td>${catalina.dist}/common/lib/naming-common.jar</td>
        <td>./lib/naming-common.jar</td>
        </tr>
        <tr>
        <td>resources.jar</td>
        <td>${catalina.dist}/common/lib/naming-resources.jar</td>
        <td>./lib/naming-resources.jar</td>
        </tr>
        <tr>
        <td>catalina.jar</td>
        <td>${catalina.dist}/server/lib/catalina.jar</td>
        <td>./lib/catalina.jar</td>
        </tr>
        </table>
        </p>
    <p>
        You will also need to remove some of the commands from the <code>build.xml</code> file so the build does not fail.<br />Remove the following lines:<br />
        &lt;copy todir="${slide.dist}/slide/lib" file="${jaxp.jar}" /&gt;<br />
        &lt;copy todir="${slide.dist}/slide/lib" file="${xmlapi.jar}" /&gt;<br />
        &lt;copy todir="${slide.dist}/slide/lib" file="${xmlparser.jar}" /&gt;<br />    
        &lt;copy todir="${webdavclient.dist}/lib" file="${jaxp.jar}" /&gt;<br />
        &lt;copy todir="${webdavclient.dist}/lib" file="${xmlapi.jar}" /&gt;

    </p> 
  </section>
  <section name="Build Jakarta Slide">
    <p>Now you are ready to build the Slide libraries.  From the terminal, type <code>ant dist</code>, and the build should run successfully.  
    The files you'll need are in the <code>jakarta-slide/dist/slide/lib</code> folder:
    <ul>
    <li>slide-kernel.jar</li>
    <li>slide-roles.jar</li>
    <li>slide-stores.jar</li>
    <li>slide-webdavservlet.jar</li>
    </ul>
    </p>
  </section>
  <section name="Create a new Tomcat project">
    <p>Start by creating a new Tomcat project in Eclipse:
    </p>
    <p>
        <img src="images/tomcat-project.png" />    
    </p>
    <p>
    After you finish the project create sequence, your Eclipse workspace you should have a new project folder.  In that folder is a directory called <code>WEB-INF</code> that contains the directory structure for your web application.
    </p>
  </section>
  <section name="Copy the built Slide libraries into the WEB-INF/lib folder in your new Tomcat project">
    <p>Now you'll want to copy these four libraries over from <code>jakarta-slide/dist/slide/lib</code> into <code>WEB-INF/lib</code>:
    <ul>
    <li>slide-kernel.jar</li>
    <li>slide-roles.jar</li>
    <li>slide-stores.jar</li>
    <li>slide-webdavservlet.jar</li>
    </ul>
    </p>
  </section>
  <section name="Copy the Domain.xml and web.xml files from the Slide source folder">
  <p>Copy the file <code>jakarta-slide/src/doc/samples/Domain.sample</code> to your new project's <code>WEB-INF</code> folder, but you'll need to rename the file <code>Domain.xml</code>.  Next,
  copy the file <code>jakarta-slide/src/conf/webapp/web.xml</code> to your <code>WEB-INF</code> folder.
  </p>
  </section>
  <section name="Associate the Slide libraries and source folder in your new Tomcat project">
  <p>
  In Eclipse, open the <b>project preferences</b> by right-clicking the project folder and selecting <b>properties</b>. Select <code>Java Build Path</code>, <code>Libraries</code>, and <code>Add Jars</code>:
  </p>
  <p>
    <img src="images/add-jars.png" />
  </p>
  <p>
  Open your project from the list and twiddle down to <code>WEB-INF/lib</code> and select the four libraries you copied in the previous task.  Press <b>Ok</b> to return to the <b>project preferences</b>, then
  press <b>Ok</b> to return back to the Eclipse IDE.
  </p>
  <p>
  Next you'll want to associate the source folders of Slide with the libraries you just installed.  From the project pane, right-click on <code>slide-kernel.jar</code> and choose <b>properties</b> from the
  context menu:
  </p>
  <p>
    <img src="images/jar-properties.png" />
  </p>
  <p>
    From the <b>Properties for <code>slide-kernel.jar</code></b>, choose <code>Java Source Attachment</code> and <code>Workspace</code>.  A new window should appear labeled <b>Source Location Selection</b>.
    Choose the <code>src</code> folder beneath the <code>jakarta-slide</code> project folder:
  </p>
    <p>
    <img src="images/attach-source.png" />
  </p>
  <p>
    Press <b>Ok</b> to return to the <b>Properties for <code>slide-kernel.jar</code></b>, then press <b>Ok</b> again to return back to the Eclipse IDE.  Now the icon for the <code>slide-kernel.jar</code>
    should look different:
  </p>
  <p>
    <img src="images/source-attached.png" />
  </p>
  <p>
    Repeat the same steps for the remaining three jar files.
  </p>
  </section>
  <section name="Modify the web.xml file">
  <p>
    Open the <code>web.xml</code> file in Eclipse and look for the Servlet <code>init-param</code> <b>domain</b>.  The current value should read: <code>/Domain.xml</code>.  Change that value to <code>/WEB-INF/Domain.xml</code>
    and save the file.
  </p>
  </section>
  <section name="Update application context in server.xml">
  <p>
    From the project pane, right-click on your project's folder in the project pane, navigate to <b>Tomcat project &gt;</b>, then select <b>Update context in server.xml</b>:
  </p>
  <p>
    <img src="images/update-context.png" />
  </p>
  </section>
  <section name="Set breakpoints and start Tomcat">
  <p>
    Now set whatever breakpoints you want in the WebDAV servlet (<code>org.apache.slide.webdav.WebdavServlet</code>), then start the Tomcat container by selecting <b>Tomcat</b> ---&gt;<b>Start Tomcat</b>.
    You are now running the server portion of Slide within Eclipse and the Eclipse Java debugger.
  </p>
  </section>
</body>
</document>
