Merge pull request #318 from adamretter/refactor/remove-war-build

duncdrum · web-flow · commit 9fe8e05b1cfc · 2019-04-02T23:29:41.000+02:00
We no longer support building a WAR file
diff --git a/src/main/xar-resources/data/configuration/configuration.xml b/src/main/xar-resources/data/configuration/configuration.xml
@@ -22,28 +22,8 @@
         <title>Main configuration file</title>
 
         <para>The main configuration file for <literal>eXist-db</literal> is called
-            <literal>conf.xml</literal>, which is loaded from different directories depending on the
-            server set-up (see <link xlink:href="deployment">Server Deployment</link> for more
-            information). Specifically:</para>
-        <itemizedlist>
-            <listitem>
-                <para>If you installed the standalone eXist-db distribution with the installer, the
-                    <literal>conf.xml</literal> file located in the root directory of the
-                    distribution (as specified by the system property
-                    <literal>exist.home</literal>).</para>
-                <para/>
-            </listitem>
-            <listitem>
-                <para>If eXist-db is installed as a web application (packaged in a
-                    <literal>.war</literal> file) in a servlet engine like tomcat, <literal>
-                    conf.xml</literal> is read from the <literal>WEB-INF</literal> directory of the
-                    web application.</para>
-                <para>eXist-db normally has no access to files outside the context in which it is
-                    running when it is deployed as part of a web application. Therefore, when eXist
-                    is deployed in this way, the configuration is read from the
-                    <literal>WEB-INF</literal> directory.</para>
-            </listitem>
-        </itemizedlist>
+            <literal>conf.xml</literal>, which is loaded the root directory of the
+            distribution (as specified by the system property <literal>exist.home</literal>).</para>
 
         <para>The configuration file <literal>conf.xml</literal> is divided into eleven
             sections:</para>
diff --git a/src/main/xar-resources/data/deployment/deployment.xml b/src/main/xar-resources/data/deployment/deployment.xml
@@ -143,52 +143,6 @@
 
     <!-- ================================================================== -->
 
-    <sect1 xml:id="deploy-servlet">
-        <title>Deploying in a Servlet Container</title>
-
-        <para>The standard distribution by default launches eXist-db as a web application deployed
-            in a <link condition="_blank" xlink:href="http://eclipse.org/jetty/">Jetty</link>
-            servlet container.</para>
-        <para>The Jetty configuration can be found in
-            <literal>tools/jetty/webapps/exist-webapp-context.xml</literal>. It defines a single web
-            application context value <literal>&lt;Set
-            name="contextPath"&gt;/exist&lt;/Set&gt;</literal>, mapped to the
-            <literal>webapp</literal> directory. This value can be set to either
-            <literal>/exist</literal> or <literal>/</literal>. Users modifying this value should
-            subsequently remove the <literal>portal</literal> folder at <literal>
-            /tools/jetty/webapps</literal>, which contains the default exist-db splashscreen
-            displayed during certain redirects.</para>
-        <para>Jetty is small, efficient and stable, so there is no need to switch to a different
-            servlet engine unless your server setup requires this. However, it is not difficult to
-            deploy eXist in a different servlet container, e.g. Apache's Tomcat.</para>
-        <para>We usually provide a <literal>.war</literal> web archive for all major releases. You
-            may either download that or, if you already installed the standard distribution, build a
-            <code>.war</code> archive yourself. For details on how to do this, see <link xlink:href="exist-building">Building eXist-db</link> </para>
-        <para>To install the <code>.war</code>, just copy it into the corresponding folder below
-            your servlet engine installation (usually <literal>webapps</literal>) and rename it to
-            <literal>exist.war</literal>. The servlet engine will normally unpack the file when you
-            restart the server. To have better control of where the file is unpacked, you can also
-            create a directory <literal>exist</literal> below the <literal>webapps</literal> folder
-            and manually extract the <code>.war</code> there. For instance:</para>
-        <programlisting>jar xfv exist.war</programlisting>
-        <important>
-            <para>Please remember that the <literal>data</literal> and <literal>log</literal>
-                directories need to be writable!</para>
-        </important>
-
-        <para>There are a few differences between the standard distribution and the
-            <code>.war</code> install. In particular, the configuration files are found in the
-            <literal>WEB-INF</literal> directory, including the important files
-            <literal>conf.xml</literal> (eXist configuration) and <literal>log4j.xml</literal>
-            (logging). The example data is in <literal>samples</literal>.</para>
-        <para>To start the <link xlink:href="java-admin-client">Java Admin Client</link>, use the
-            following command (from within <literal>exist</literal> web application's root
-            directory):</para>
-        <programlisting>java -jar WEB-INF/lib/start.jar client -ls</programlisting>
-    </sect1>
-
-    <!-- ================================================================== -->
-
     <sect1 xml:id="run-stand-alone">
         <title>Running as a Stand-alone Server</title>
 
@@ -596,4 +550,4 @@
             target directory (which we prepared above), and compile and run it with:</para>
         <programlisting>javac TestDB.java java -Dexist.initdb=true -Dexist.home=. TestDB</programlisting>
     </sect1>
-</article>
+</article>
diff --git a/src/main/xar-resources/data/documentation/documentation.xml b/src/main/xar-resources/data/documentation/documentation.xml
@@ -435,7 +435,7 @@
             <varlistentry>
                 <term> <link xlink:href="exist-building">Building eXist</link> </term>
                 <listitem>
-                    <para>How to build Java <code>.jar</code> or <code>.war</code> files from an
+                    <para>How to build Java <code>.jar</code> files from an
                         eXist distribution.</para>
                 </listitem>
             </varlistentry>
@@ -552,7 +552,7 @@
             <varlistentry>
                 <term> <link xlink:href="exist-building">Building eXist</link> </term>
                 <listitem>
-                    <para>How to build Java <code>.jar</code> or <code>.war</code> files from an
+                    <para>How to build Java <code>.jar</code> files from an
                         eXist distribution.</para>
                 </listitem>
             </varlistentry>
diff --git a/src/main/xar-resources/data/exist-building/exist-building.xml b/src/main/xar-resources/data/exist-building/exist-building.xml
@@ -12,38 +12,7 @@
   </info>
   <!-- ================================================================== -->
 
-  <para>This article will tell you how to build a Java <code>.war</code> or <code>.jar</code> file for eXist-db. If you are building exist-db from source, please also check the <link xlink:href="https://github.com/eXist-db/exist/blob/develop/BUILD.md">build instructions</link> in the source-code repo.</para>
-
-  <!-- ================================================================== -->
-
-  <sect1 xml:id="war">
-    <title>Building a <code>.war</code> file from the Standard Distribution</title>
-
-    <para>If you would like to deploy eXist-db into an existing servlet engine (e.g. tomcat), you will need a <literal>.war</literal> file. We no
-      longer distribute a <literal>.war</literal> build, but it is easy to create one from the standard distribution by
-        <emphasis>repackaging</emphasis> (not building) it:</para>
-    <orderedlist>
-      <listitem>
-        <para>
-          <emphasis role="bold">Install the standard distribution</emphasis>
-        </para>
-        <para>Get a standard distribution from eXist-db <link xlink:href="http://exist-db.org/exist/apps/homepage/index.html#download" condition="_blank">download
-            page</link>. Install it into a directory of your choice. Make sure you include the <emphasis>source package</emphasis>.</para>
-      </listitem>
-      <listitem>
-        <para>
-          <emphasis role="bold">Generate the WAR</emphasis>
-        </para>
-        <para>Open a command line prompt and change to the directory where you just installed eXist-db. Call</para>
-        <programlisting>build.sh dist-war</programlisting>
-        <para>or</para>
-        <programlisting>build.bat dist-war</programlisting>
-        <para>once. This will generate a <literal>.war</literal> archive into directory <literal>dist</literal>.</para>
-      </listitem>
-    </orderedlist>
-    <para>Note that generating a <code>.war</code> archive does only repackage the files in the distribution. So if the distribution worked properly
-      for you, the <code>.war</code> should as well. You don't need to recompile eXist-db or sign any jars.</para>
-  </sect1>
+  <para>This article will tell you how to build a Java <code>.jar</code> file for eXist-db. If you are building exist-db from source, please also check the <link xlink:href="https://github.com/eXist-db/exist/blob/develop/BUILD.md">build instructions</link> in the source-code repo.</para>
 
   <!-- ================================================================== -->
 
@@ -92,11 +61,11 @@
     <title>Using the Build System</title>
 
     <para>You can rebuild all eXist-db packages from the standard distribution or the GitHub repository. You can even create a new distribution from
-      the one you installed. For example, assume you installed eXist using the installer GUI, but you need to have an exist.war package for deployment
-      within a different servlet engine. Just call the main build script (<literal>build.sh</literal> or <literal>build.bat</literal>) and pass it the
-      target <literal>dist-war</literal>:</para>
-    <programlisting>build.sh dist-war</programlisting>
-    <para>This will create a fresh <literal>.war</literal> archive in the <literal>dist</literal> directory.</para>
+      the one you installed. For example, assume you installed eXist using the installer GUI, but you need to have a <literal>.tar.bz2</literal> package for deployment
+      to a server. Just call the main build script (<literal>build.sh</literal> or <literal>build.bat</literal>) and pass it the
+      target <literal>dist-bz2</literal>:</para>
+    <programlisting>build.sh dist-bz2</programlisting>
+    <para>This will create a fresh <literal>.tar.bz2</literal> archive in the <literal>dist</literal> directory.</para>
     <note>
       <para>To be able to use the build system, you need to include the "source" module when selecting installable packages in the installer
         GUI.</para>
@@ -181,18 +150,34 @@
           </row>
           <row>
             <entry>
-              <para>dist-tgz</para>
+              <para>dist-dir</para>
             </entry>
             <entry>
-              <para>Packages eXist-db into a <literal>.tgz</literal> file.</para>
+              <para>Packages eXist-db into a directory.</para>
+            </entry>
+          </row>
+          <row>
+            <entry>
+              <para>dist-bz2</para>
+            </entry>
+            <entry>
+              <para>Packages eXist-db into a <literal>.tar.bz2</literal> file.</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>dist-war</para>
+              <para>dist-tar</para>
             </entry>
             <entry>
-              <para>Packages eXist-db into a <literal>.war</literal> file for deployment within a servlet engine.</para>
+              <para>Packages eXist-db into a <literal>.tar</literal> file.</para>
+            </entry>
+          </row>
+          <row>
+            <entry>
+              <para>dist-tgz</para>
+            </entry>
+            <entry>
+              <para>Packages eXist-db into a <literal>.tgz</literal> file.</para>
             </entry>
           </row>
           <row>
diff --git a/src/main/xar-resources/data/production_good_practice/production_good_practice.xml b/src/main/xar-resources/data/production_good_practice/production_good_practice.xml
@@ -422,7 +422,7 @@
     <sect1 xml:id="web-deploy">
         <title>Web Deployments</title>
 
-        <para>eXist-db, like any Web Application Server (Tomcat, WebLogic, GlassFish, etc.), should
+        <para>eXist-db, like any Web Application Server, should
             not be directly exposed to the Web. Instead, we strongly recommend proxying eXist-db
             through a Web Server such as <link condition="_blank"
             xlink:href="http://wiki.nginx.org/Main">Nginx</link> or <link condition="_blank"
diff --git a/src/main/xar-resources/data/validation/validation.xml b/src/main/xar-resources/data/validation/validation.xml
@@ -422,29 +422,6 @@
                 <para>To avoid potential deadlocking it is considered good practice to store XML
                     instance documents and grammar documents in separate collections.</para>
             </listitem>
-            <listitem>
-                <para>Tomcat has an long standing bug which makes it impossible to register a custom
-                    protocol handler (object <link condition="_blank"
-                    xlink:href="https://docs.oracle.com/javase/10/docs/api/java/net/URLStreamHandler.html"
-                    ><code>URLStreamHandler</code></link>) to the JVM. The alternative is to
-                    register the object by setting the system property
-                    <code>java.protocol.handler.pkgs</code> but this fails as well.</para>
-                <para>As a result, the validation features are only partly useable in Tomcat. There
-                    are two alternatives: (1) switch to a recent version of Jetty, or (2) use
-                    absolute URLs pointing the REST interface, e.g.
-                    <code>http://localhost:8080/exist/rest/db/mycollection/schema.xsd</code>.</para>
-            </listitem>
-            <listitem>
-                <para>eXist relies heavily on features provided by the Xerces XML parser. Out of the
-                    box the eXist izPack installer provides all required <code>.jar</code> files.
-                    However, when eXist is installed in for instance Tomcat, the required parser
-                    libraries need to be copied manually from the eXist <code>lib/endorsed</code>
-                    directory into the server <link condition="_blank"
-                    xlink:href="http://tomcat.apache.org/tomcat-5.5-doc/class-loader-howto.html"
-                    >endorsed</link> directory.</para>
-                <para>Required endorsed files: <code>resolver-*.jar xalan-*.jar serializer-*.jar
-                    xercesImpl-*.jar</code> </para>
-            </listitem>
 
             <listitem>
                 <para>The explicit validation is performed by <link condition="_blank"
