Modified the build to compile and include source and web files locaed in a...

Modified the build to compile and include source and web files locaed in a custom directory.  This commit also includes documentation changes to explain how to use the new build functionality.

git-svn-id: http://svn.igniterealtime.org/svn/repos/openfire/trunk@7963 b35dd754-fafc-0310-a699-88a17e54d16e

build/build.xml

@@ -100,8 +100,16 @@
     <property name="jar.starter.name" value="startup.jar"/>
     <property name="jar.dest.dir" value="${work.dir}/lib"/>
     <property name="resources.dir" value="${src.dir}/resources"/>
+
+    <property name="overlay.dir"   value="${basedir}/custom"/>
+    <property name="overlay.src.dir"   value="${overlay.dir}/source"/>
+    <property name="overlay.web.dir"   value="${overlay.dir}/webapp"/>
+    <property name="overlay.properties.file"   value="overlay.properties"/>
+    <property name="overlay.compile.dir" value="${work.dir}/overlay/classes"/>    
+
     <property name="javadoc.src.dir" value="${src.dir}/javadoc"/>
     <property name="javadoc.dest.dir" value="${work.dir}/javadoc"/>
+    <property name="jspc.jsp.src.dir" value="${work.dir}/jspc/jsp"/>
     <property name="jspc.dest.dir" value="${work.dir}/jspc"/>
     <property name="jspc.java.dest.dir" value="${work.dir}/jspc/java"/>
     <property name="jspc.classes.dest.dir" value="${work.dir}/jspc/classes"/>
@@ -238,6 +246,7 @@
         </tstamp>
 
         <mkdir dir="${work.dir}"/>
+        <mkdir dir="${overlay.compile.dir}"/>
 
         <!-- Setup the full version property correctly -->
         <if>
@@ -273,6 +282,32 @@
                 <path refid="compile.dependencies"/>
             </classpath>
         </javac>
+
+        <available file="${overlay.src.dir}" type="dir" property="overlay.source.found"/>
+        <if>
+            <equals arg1="${overlay.source.found}" arg2="true"/>
+            <then>
+
+                <mkdir dir="${overlay.compile.dir}"/>
+                <javac
+                        destdir="${overlay.compile.dir}"
+                        includeAntRuntime="no"
+                        debug="on"
+                        source="1.5"
+                        target="1.5"
+                        >
+                    <src path="${overlay.src.dir}"/>
+                    <patternset refid="compile.sources"/>
+                    <classpath>
+                        <path refid="compile.dependencies"/>
+                        <path location="${compile.dir}"/>
+                    </classpath>
+                </javac>
+
+            </then>
+            <else><echo>Nothing to compile from custom here </echo></else>
+        </if>
+
     </target>
 
     <!-- i18n ================================================================================== -->
@@ -283,6 +318,20 @@
         <copy file="${src.i18n.dir}/${i18n.basename}_${i18n.default.locale}.properties"
               tofile="${target.i18n.dir}/${i18n.basename}.properties"/>
 
+        <!-- if title override file exists, overwrite all i18n files -->
+        <available file="${overlay.dir}/${overlay.properties.file}" type="file" property="overlay.props.found"/>
+        <if>
+                <equals arg1="${overlay.props.found}" arg2="true"/>
+                <then>
+                  <echo>Found overlay file: ${overlay.dir}/${overlay.properties.file}</echo>
+		          <property file="${overlay.dir}/${overlay.properties.file}"/>
+                    <replace dir="${target.i18n.dir}">
+                        <replacefilter token="title = Wildfire" value="title=${title}"/>
+                        <replacefilter token="short.title = Wildfire" value="short.title=${short.title}"/>
+                    </replace>
+
+                </then>
+        </if>
     </target>
 
     <target name="plugins-dev">
@@ -329,7 +378,12 @@
         <!-- Make main Openfire jar -->
         <jar jarfile="${jar.dest.dir}/${jar.name}" index="true" duplicate="preserve">
             <fileset dir="${compile.dir}" includes="**/*.class"
-                     excludes="org/jivesoftware/openfire/starter/ServerStarter*.class,org/jivesoftware/openfire/launcher/*.class"/>
+                     excludes="org/jivesoftware/openfire/starter/ServerStarter*.class,org/jivesoftware/openfire/launcher/*.class">
+                <!-- don't include files that have an overlay counterpart -->
+                 <present present="srconly" targetdir="${overlay.compile.dir}"/>
+            </fileset>
+            <!-- now include overlay files -->
+            <fileset dir="${overlay.compile.dir}" includes="**/*.class"/>                      
             <fileset dir="${src.i18n.dir}" includes="*.properties"/>
             <fileset dir="${target.i18n.dir}" includes="*.properties"/>
             <fileset dir="${resources.dir}/jar" includes="**"/>
@@ -450,13 +504,33 @@
     </target>
     
     <target name="-jspc-impl" unless="no.jspc">
+
+        <!-- we're forced to create a temp dir to properly overwrite sources from overlay directory -->
+        <mkdir dir="${jspc.jsp.src.dir}"/>
+
+        <copy todir="${jspc.jsp.src.dir}">
+            <fileset dir="${web.dir}"/>
+        </copy>
+        <!-- copy overlay -->
+
+        <available file="${overlay.web.dir}" type="dir" property="overlay.webdir.found"/>
+        <if>
+            <equals arg1="${overlay.webdir.found}" arg2="true"/>
+            <then>
+                <copy todir="${jspc.jsp.src.dir}" overwrite="true">
+                    <fileset dir="${overlay.web.dir}"/>
+                </copy>
+            </then>
+        </if>
+
+
         <java classname="org.apache.jasper.JspC" fork="true">
             <classpath>
                 <pathelement location="${java.home}/../lib/tools.jar"/>
                 <pathelement path="${compile.dir}"/>
                 <path refid="jspc.dependencies"/>
             </classpath>
-            <arg line="-uriroot '${web.dir}'"/>
+            <arg line="-uriroot '${jspc.jsp.src.dir}'"/>
             <arg line="-d '${jspc.java.dest.dir}'"/>
             <arg line="-p org.jivesoftware.openfire.admin"/>
             <arg line="-webinc '${jspc.dest.dir}/web.partial.xml'"/>

documentation/docs/index.html

@@ -79,6 +79,10 @@ messaging (IM) services using the XMPP protocol.
         <a href="database-guide.html">Database Schema Guide</a> -
         A tour of the Openfire database schema for developers and database administrators.
     </li>
+    <li>
+        <a href="overlay.html">Customization Guide</a> -
+        Instructions on customization support within the build process for Openfire.
+    </li>
 </ul>
 
 <br>

documentation/docs/overlay.html

+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+<title>Openfire: Database Installation Guide</title>
+<link href="style.css" rel="stylesheet" type="text/css">
+</head>
+<body>
+
+<div id="pageContainer">
+
+<a name="top"></a>
+
+	<div id="pageHeader">
+		<div id="logo"></div>
+		<h1>Customization Guide</h1>
+	</div>
+	<div class="navigation">
+		<a href="index.html">&laquo; Back to documentation index</a>
+	</div>
+
+	<div id="pageBody">
+
+     <p>
+        Openfire provides ways to customize application code as well as the Admin console,
+        while maintaining that code in a separate location from the distribution source.
+        The base code and custom code are integrated during the build process.
+     </p>
+
+        <h2><a name="mysql">File Structure</a></h2>
+
+        <p>To cusomize files, create the following file structure in your <tt>openfireHome</tt>
+        directory (where all the source files are on your filesystem).
+        </p>
+
+<pre>custom/
+| - overlay.properties       &lt;- Properties file to replace text in i18n files (optional)
+| - source/                  &lt;- Directory to place java source files to be overridden
+| - webapp/                  &lt;- Directory to place any web file (image, CSS or jsp)
+</pre>
+
+        <p>
+            In the <tt>custom/source</tt> directory, mirror the contents under the <tt>src/java</tt> directory.
+            Any files you place under <tt>custom/source</tt> will override the current source files in the build.
+            For example, to override the
+class <tt>org.jivesoftware.openfire.Channel</tt> you would place a Channel.java file under the directory <tt>custom/source/org/jivesoftware/openfire/</tt>
+        </p>
+        <p>
+In the <tt>custom/webapp</tt> directory, mirror the contents of the <tt>src/web</tt> directory.  Any files you place
+there will override the current source files in the build.  For example, if you want to modify <tt>src/web/login.jsp</tt>
+            then add login.jsp to the directory <tt>custom/webapp</tt>.
+           </p>
+        <p>
+Currently, overridden files will simply be included in the built war or jar files.  We have not added
+            functionality to bundle these changes in a separate jar file.
+        </p>
+
+        <h2>Overlay Properties File</h2>
+
+        <p>The i18n files have been modified to be as generic as possible (not to mention this project
+            by name).  In cases where that could not be avioded, two keys are responsible.  We have
+            made it possible to modify these keys by means of an optional properties file, <tt>overlay.properties</tt>
+            which you place in your <tt>custom/</tt> folder.  If you want to override these
+            default properties just create this file.  The build will continue to work if you haven't
+            created the file.
+        </p>
+
+        <p>
+        The overlay.properties file will currently replace the following keys in the i18n files.
+            Note: this properties file should follow the java.util.Properties text file format.
+        </p>
+        <ul>
+            <li><em>title</em> - Title key (usually in the title bar of an HTML page)</li>
+            <li><em>short.title</em> - Short title, also used frequently</li>
+        </ul>
+
+        <h2>Build</h2>
+        <p>Simply build the application as normal.  You may need to run the ant <tt>clean</tt>
+            task for your changes to be picked up.
+        </p>
+    </div>
+
+</div>
+
+</body>
+</html>