MODCLUSTER-439 Overhaul distribution profile

Goals:

* create a distribution archive *per* tomcat version
* create separate demo distribution
* create assembly component to be shared across tomcat assemblies
* allow building for a specific tomcat version
* above including building -PTC9 which rebuilds tomcat85 sources with tomcat9 jars
* include jars in the lib/ folder and standard text files for licence and installation procedure
* provide executable demo scripts
* support files viewable and usable on windows
* improve README.md file

.gitattributes

@@ -1 +1,8 @@
+# Default behavior for all files
 * text=auto
+
+# Set text and script files which are bundled as part of the distribution to use CRLF line endings
+# so that they are human readable on Microsoft Windows-based systems
+README.md       text eol=crlf
+LICENSE.txt     text eol=crlf
+*.bat           text eol=crlf

README.md

@@ -1,27 +1,28 @@
 mod_cluster
 ===========
 
-Project mod_cluster is a httpd-based load-balancer. It uses a communication channel to forward
-requests from httpd to one of a set of application server nodes. Unlike mod_jk and mod_proxy,
-mod_cluster leverages an additional connection between the application server nodes and httpd
-to transmit server-side load-balance factors and lifecycle events back to httpd. This additional
-feedback channel allows mod_cluster to offer a level of intelligence and granularity not found in
-other load-balancing solutions.
+Project mod_cluster is an intelligent load-balancer. It uses a communication channel to forward requests from a reverse
+proxy server to one of a set of application server nodes. Unlike mod_jk and mod_proxy, mod_cluster leverages an
+additional connection between the application server nodes and the reverse proxy to transmit server-side load-balance
+factors and lifecycle events back to the proxy. This additional feedback channel allows mod_cluster to offer a level of
+intelligence and granularity not found in other load-balancing solutions. There are currently two reverse proxy
+implementations: a native [https://httpd.apache.org/](Apache HTTP Server) implementation and a pure Java 
+[http://undertow.io/](Undertow)-based implementation.
 
-Mod_cluster boasts the following advantages over other httpd-based load-balancers:
+Project mod_cluster boasts the following advantages over other httpd-based load-balancers:
 
 * Dynamic configuration of httpd workers
 * Server-side load balance factor calculation
 * Fine grained web-app lifecycle control
 * AJP is optional
 
-[http://www.jboss.org/mod_cluster](http://www.jboss.org/mod_cluster)
+[http://mod-cluster.jboss.org/](http://mod-cluster.jboss.org/)
 
 
-Installation
-------------
+Installation Instructions
+-------------------------
 
-### JBoss AS 7/WildFly 8+
+### JBoss AS 7/WildFly 8 (or newer)
 
 These versions already ship with bundled mod_cluster. It is configured via mod_cluster
 subsystem.
@@ -33,57 +34,75 @@ This is the first version of AS that bundled mod_cluster, the configuration is l
 `/server/<profile>/deploy/mod_cluster.sar/META-INF` directory.
 
 
-### JBoss Web / Tomcat
+### Tomcat 7 (or newer)
 
-The `tar.gz` from the assembly contains the `JBossWeb-Tomcat`.
+Distribution archives are provided for each Tomcat version.
 
-1. Extract the `JBossWeb-Tomcat` directory.
-2. Copy the JAR files from `JBossWeb-Tomcat/lib` to the Tomcat lib.
-3. Remove the `mod_cluster-container-tomcat(n).jar` that don't correspond to
-   the Tomcat version you are using.
-3. Copy the `JBossWeb-Tomcat/lib/jboss-logging-jdk.jar` and `JBossWeb-Tomcat/lib/jboss-logging-spi.jar`
-   dependency jars into the same `lib` directory.
-4. Modify `server.xml` within the `conf` directory and add a non-cluster mode
-   engine listener as documented [here](http://docs.jboss.org/mod_cluster/1.2.0/html/Quick_Start_Guide.html).
+1. Obtain the distribution archive corresponding to the intended Tomcat version by either downloading from the project
+   website or if building from source located in `dist/target/` directory.
+2. Download and unzip or untar the distribution archive and navigate to the extracted directory.
+3. Copy the `lib/` directory to the Tomcat installation directory adding jars to its `lib/` directory. If upgrading from
+   a different version, it is necessary to remove all jars copied previously.
+4. Modify `server.xml` within the `conf` directory and add the mod_cluster listener as documented
+   [here](http://docs.jboss.org/mod_cluster/1.3.0/). The minimal listener configuration is as follows:
+
+```xml
+<Listener className="org.jboss.modcluster.container.tomcat.ModClusterListener" connectorPort="8009"/>
+```
 
 
 Project Structure
 -----------------
 
+Project is split up into multiple modules:
+
 ```
-core
+core (contains the implementation of container-independent core mod_cluster concepts)
 container
-  spi (contains no dependencies on a specific web container)
+  spi (SPI classes for container integrations, has no dependencies on a specific web container)
   tomcat (base for Tomcat container implementations, based on Tomcat 7.0)
   tomcat8 (Tomcat 8.0 container implementation)
   tomcat85 (Tomcat 8.5 and 9.0 milestone container implementation)
+load-spi (SPI classes for load metric computation)
 demo
   client
   server
 ```
 
 
+Sources
+-------
+
+Sources for the mod_cluster project are located on GitHub:
+
+[https://github.com/modcluster/mod_cluster](https://github.com/modcluster/mod_cluster)
+
+
 Building
 --------
 
 ### Servlet Container Modules
 
-Before building, ensure you have Maven version 3.0 or newer (`mvn -version`) and JDK 6.0 or newer (`java -version`). 
-It is possible to build modules for all containers:
+When building from source, first ensure that Maven version 3.2.5 or newer (run `mvn -version`) and JDK 7.0 or newer
+(run `java -version`) are installed. The following command builds modules for all containers:
+
+```
+mvn install -Pdist
+```
 
-    mvn install
+Distribution files for Tomcat and a demo application will be built in the `dist/target/` directory.
 
-Distribution package:
 
-    mvn -P dist package
+Reporting Issues
+----------------
 
-Dynamic load-balancing demo is located in the `/demo` directory:
+Project mod_cluster uses JBoss Jira issue tracker under MODCLUSTER project:
 
-    mvn install
+[https://issues.jboss.org/browse/MODCLUSTER](https://issues.jboss.org/browse/MODCLUSTER)
 
 
 License
 -------
 
-This software is distributed under the terms of the GNU Lesser General Public License (see [lgpl.txt](lgpl.txt)).
+This software is distributed under the terms of the GNU Lesser General Public License (see [LICENSE.txt](LICENSE.txt)).
 

demo/client/pom.xml

@@ -37,4 +37,25 @@
             <artifactId>jfreechart</artifactId>
         </dependency>
     </dependencies>
+    <!-- consumed by dist/ module -->
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-dependencies-demo</id>
+                        <phase>process-resources</phase>
+                        <goals>
+                            <goal>copy-dependencies</goal>
+                        </goals>
+                        <configuration>
+                            <overWriteIfNewer>true</overWriteIfNewer>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
 </project>

demo/client/src/main/resources/run-demo.bat

@@ -5,7 +5,8 @@ set CP=
 
 for %%i in (lib\*.jar) do call :concatsep %%i
 
-set "OPTS=-Xmn200M -Xmx300M -Xms300M -Xss8K -XX:ThreadStackSize=8k -XX:CompileThreshold=100 -XX:SurvivorRatio=8 -XX:TargetSurvivorRatio=90 -XX:MaxTenuringThreshold=31"
+REM Uncomment the following line for enabling JVM performance options
+REM set "OPTS=-Xmn200M -Xmx300M -Xms300M -Xss8K -XX:ThreadStackSize=8k -XX:CompileThreshold=100 -XX:SurvivorRatio=8 -XX:TargetSurvivorRatio=90 -XX:MaxTenuringThreshold=15"
 
 REM Tell the HttpURLConnection pool to maintain 400 connections max
 set "OPTS=%OPTS% -Dhttp.maxConnections=400"

demo/client/src/main/resources/run-demo.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-CP=./classes
+CP=
 
 for i in lib/*.jar
 do