Changeset 7609

Timestamp:

Feb 27, 2019, 1:42:03 PM (5 years ago)

Author:

Nicklas Nordborg

Message:

References #2151: Pre-compile all JSP pages before releases

Updated documentation with changes related to source code incompatibilities.

Location:

trunk/doc/src/docbook

Files:

• admin/installation.xml (modified) (4 diffs)
• appendix/incompatible.xml (modified) (1 diff)
• appendix/update_warnings.xml (modified) (1 diff)
• appendix/web.xml.xml (modified) (1 diff)

trunk/doc/src/docbook/admin/installation.xml

@@ -47 +47 @@
 
     <important id="installation.upgrade.important">
-      <title>Important information for upgrading to BASE 3.14</title>
+      <title>Important information for upgrading to BASE 3.15</title>
       <para>
         This section list some important information that may or may not
@@ -62 +62 @@
         by the upgrade script. The recommendation is to replace this feature with 
         an external files solution instead.
+      </para>
+      
+      <bridgehead>Customizations made in the global web.xml file</bridgehead>
+      <para>
+        In the configuration directory for Tomcat there is a <filename>web.xml</filename>
+        file that define global options for all web applications. The settings in this file
+        can be overridden per web application in the <filename>WEB-INF/classes/web.xml</filename>.
+        BASE 3.15 re-defines the <code>jsp</code> <sgmltag class="starttag">servlet</sgmltag>
+        definition to make sure that JSP files are compiled with proper settings. Changes that
+        have been made to the global <filename>web.xml</filename> file for the <code>jsp</code>
+        <sgmltag class="starttag">servlet</sgmltag> must be moved or copied to the 
+        <filename>web.xml</filename> file for the BASE web application.
       </para>
       
@@ -621 +633 @@
             <listitem>
               <para>
-                Disable strict parsing of JSP files.
-                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
-              </para>
-            </listitem>
-            <listitem>
-              <para>
                 Unless you have manually downloaded and installed JAI (Java Advanced
                 Imaging) native acceleration libraries (see <ulink 
@@ -649 +655 @@
             class="directory">bin</filename>): 
 <programlisting>CATALINA_OPTS="-Xmx1G 
--Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
 -Dcom.sun.media.jai.disableMediaLib=true
 -Djava.awt.headless=true"</programlisting>

trunk/doc/src/docbook/appendix/incompatible.xml

@@ -46 +46 @@
       <code>SECONDARY</code> has been removed.    
     </para>
+    
+    <bridgehead id="appendix.incompatible.generics">Introduced generic return parameters</bridgehead>
+    <para>
+      Some API methods with a return type of <classname>Object</classname> have been 
+      changed to <code>&lt;T&gt; T</code> (for example <code>public &lt;T&gt; T getObject(String name)</code> in
+      <classname>ItemContext</classname>)
+      which means that no explicit cast is needed since the compiler can typically infer this from the 
+      assignment made by the calling code. Note that this change is binary compatible with existing
+      code, but in some cases it may be source code incompatible. Thus, already compiled code 
+      should continue to work, but source code may have to modified if compiling against the 
+      BASE 3.15 API. Here are some examples:
+    </para>
+    
+    <programlisting language="java">
+<![CDATA[
+// With BASE 3.14 (also works with BASE 3.15)
+ItemContext cc = ...
+Hardware hardware = (Hardware)cc.getObject("item");
+
+// With BASE 3.15
+Hardware hardware = cc.getObject("item");
+
+// This will not compile against BASE 3.15!
+Set<AnnotatedItem> items = (Set<AnnotatedItem>)cc.getObject("AnnotatedItems");
+
+// The explict cast must be removed
+Set<AnnotatedItem> items = cc.getObject("AnnotatedItems");
+]]>
+</programlisting>
+    
+    <para>
+      Besides the change in the <methodname>ItemContext.getObject()</methodname> method there
+      are several similar changes in the <classname docapi="net.sf.basedb.core">ItemContext</classname> 
+      class as well as in <classname docapi="net.sf.basedb.core">SessionControl</classname>, 
+      <classname docapi="net.sf.basedb.clients.web.formatter">FormatterFactory</classname>,
+      <classname docapi="net.sf.basedb.core">ParameterValues</classname> and several other 
+      classes. In all cases, it should be relatively simple to update the code that doesn't compile.
+    </para>
+    
+    <note>
+      <title>Beware of JSP files</title>
+      <para>
+        Since this change doesn't affect already compiled code, extensions and plug-ins are
+        typically not affected. The exception is of course JSP files that are part of an 
+        extension since they are compiled at runtime by Tomcat. It may be wise to test this
+        before upgrading a live BASE installation to BASE 3.15.
+      </para>
+    </note>
   </sect1>
   

trunk/doc/src/docbook/appendix/update_warnings.xml

@@ -47 +47 @@
     </para>
   
+    <bridgehead>Customizations made in the global web.xml file</bridgehead>
+    <para>
+      In the configuration directory for Tomcat there is a <filename>web.xml</filename>
+      file that define global options for all web applications. The settings in this file
+      can be overridden per web application in the <filename>WEB-INF/classes/web.xml</filename>.
+      BASE 3.15 re-defines the <code>jsp</code> <sgmltag class="starttag">servlet</sgmltag>
+      definition to make sure that JSP files are compiled with proper settings. Changes that
+      have been made to the global <filename>web.xml</filename> file for the <code>jsp</code>
+      <sgmltag class="starttag">servlet</sgmltag> must be moved or copied to the 
+      <filename>web.xml</filename> file for the BASE web application.
+    </para>
   
   </sect1>

trunk/doc/src/docbook/appendix/web.xml.xml

@@ -146 +146 @@
         as requests to extension servlets. Do not modify. Do not disable even if
         extensions are not used.
+        </para>
+      </listitem>
+    </varlistentry>
+  
+    <varlistentry>
+      <term><sgmltag class="starttag">servlet</sgmltag>: jsp</term>
+      <listitem>
+        <para>
+        Overrides the default JSP servlet defined by Tomcat. The parameters included
+        with the distribution are required, but it may be customized if desired.
         </para>
       </listitem>