Author: markt Date: Mon Aug 5 20:24:51 2013 New Revision: 1510708 URL: http://svn.apache.org/r1510708 Log: Initial migration guide
Added: tomcat/site/trunk/docs/migration-8.html (with props) tomcat/site/trunk/xdocs/migration-8.xml - copied, changed from r1510686, tomcat/site/trunk/xdocs/migration-7.xml Modified: tomcat/site/trunk/docs/migration.html tomcat/site/trunk/xdocs/migration.xml Added: tomcat/site/trunk/docs/migration-8.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/migration-8.html?rev=1510708&view=auto ============================================================================== --- tomcat/site/trunk/docs/migration-8.html (added) +++ tomcat/site/trunk/docs/migration-8.html Mon Aug 5 20:24:51 2013 @@ -0,0 +1,638 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title>Apache Tomcat - Migration Guide - Tomcat 8.0.x</title> +<meta name="author" content="Apache Tomcat Project"> +<link type="text/css" href="stylesheets/tomcat.css" rel="stylesheet"> +<link type="text/css" href="stylesheets/tomcat-printer.css" rel="stylesheet" media="print"> +</head> +<body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"> +<table border="0" width="100%" cellspacing="0"> +<!--PAGE HEADER--> +<tr> +<td> +<!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="left" alt="Tomcat Logo" border="0"></a></td><td><font face="arial,helvetica,sanserif"> +<h1>Apache Tomcat</h1> +</font></td><td> +<!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td> +</tr> +</table> +<div class="searchbox noPrint"> +<form action="http://www.google.com/search" method="get"> +<input value="tomcat.apache.org" name="sitesearch" type="hidden"><input value="Search the Site" size="25" name="q" id="query" type="text"><input name="Search" value="Search Site" type="submit"> +</form> +</div> +<table border="0" width="100%" cellspacing="4"> +<!--HEADER SEPARATOR--> +<tr> +<td colspan="2"> +<hr noshade size="1"> +</td> +</tr> +<tr> +<!--LEFT SIDE NAVIGATION--> +<td width="20%" valign="top" nowrap="true" class="noPrint"> +<p> +<strong>Apache Tomcat</strong> +</p> +<ul> +<li> +<a href="./index.html">Home</a> +</li> +<li> +<a href="./taglibs/">Taglibs</a> +</li> +<li> +<a href="./maven-plugin.html">Maven Plugin</a> +</li> +</ul> +<p> +<strong>Download</strong> +</p> +<ul> +<li> +<a href="./whichversion.html">Which version?</a> +</li> +<li> +<a href="./download-70.cgi">Tomcat 7.0</a> +</li> +<li> +<a href="./download-60.cgi">Tomcat 6.0</a> +</li> +<li> +<a href="./download-connectors.cgi">Tomcat Connectors</a> +</li> +<li> +<a href="./download-native.cgi">Tomcat Native</a> +</li> +<li> +<a href="http://archive.apache.org/dist/tomcat/">Archives</a> +</li> +</ul> +<p> +<strong>Documentation</strong> +</p> +<ul> +<li> +<a href="./tomcat-7.0-doc/index.html">Tomcat 7.0</a> +</li> +<li> +<a href="./tomcat-6.0-doc/index.html">Tomcat 6.0</a> +</li> +<li> +<a href="./connectors-doc/">Tomcat Connectors</a> +</li> +<li> +<a href="./native-doc/">Tomcat Native</a> +</li> +<li> +<a href="http://wiki.apache.org/tomcat/FrontPage">Wiki</a> +</li> +<li> +<a href="./migration.html">Migration Guide</a> +</li> +</ul> +<p> +<strong>Problems?</strong> +</p> +<ul> +<li> +<a href="./security.html">Security Reports</a> +</li> +<li> +<a href="./findhelp.html">Find help</a> +</li> +<li> +<a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a> +</li> +<li> +<a href="./lists.html">Mailing Lists</a> +</li> +<li> +<a href="./bugreport.html">Bug Database</a> +</li> +<li> +<a href="./irc.html">IRC</a> +</li> +</ul> +<p> +<strong>Get Involved</strong> +</p> +<ul> +<li> +<a href="./getinvolved.html">Overview</a> +</li> +<li> +<a href="./svn.html">SVN Repositories</a> +</li> +<li> +<a href="./ci.html">Buildbot</a> +</li> +<li> +<a href="https://reviews.apache.org/groups/tomcat/">Reviewboard</a> +</li> +<li> +<a href="./tools.html">Tools</a> +</li> +</ul> +<p> +<strong>Media</strong> +</p> +<ul> +<li> +<a href="http://blogs.apache.org/tomcat/">Blog</a> +</li> +<li> +<a href="http://twitter.com/theapachetomcat">Twitter</a> +</li> +</ul> +<p> +<strong>Misc</strong> +</p> +<ul> +<li> +<a href="./whoweare.html">Who We Are</a> +</li> +<li> +<a href="./heritage.html">Heritage</a> +</li> +<li> +<a href="http://www.apache.org">Apache Home</a> +</li> +<li> +<a href="./resources.html">Resources</a> +</li> +<li> +<a href="./contact.html">Contact</a> +</li> +<li> +<a href="./legal.html">Legal</a> +</li> +<li> +<a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> +</li> +<li> +<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> +</li> +</ul> +</td> +<!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Table of Contents"> +<!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + +<ul> +<li> +<a href="#General">General</a> +</li> +<li> +<a href="#Migrating_from_7.0.x_to_8.0.x">Migrating from 7.0.x to 8.0.x</a> +<ol> +<li> +<a href="#Java_7_required">Java 7 required</a> +</li> +<li> +<a href="#Specification_APIs">Specification APIs</a> +</li> +<li> +<a href="#Servlet_3.1_API">Servlet 3.1 API</a> +</li> +<li> +<a href="#Default_connector_implementation">Default connector implementation</a> +</li> +<li> +<a href="#Web_application_resources">Web application resources</a> +</li> +<li> +<a href="#Internal_APIs">Internal APIs</a> +</li> +</ol> +</li> +<li> +<a href="#Upgrading_8.0.x">Upgrading 8.0.x</a> +<ol> +<li> +<a href="#Tomcat_8.0.x_configuration_file_differences">Tomcat 8.0.x configuration file differences</a> +</li> +</ol> +</li> +</ul> + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="General"><strong>General</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + + +<p>Please read general <a href="migration.html">Migration Guide page</a> first, +for common considerations that apply to migration or upgrade between versions +of Apache Tomcat.</p> + + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Migrating from 7.0.x to 8.0.x"> +<!--()--></a><a name="Migrating_from_7.0.x_to_8.0.x"><strong>Migrating from 7.0.x to 8.0.x</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + + +<p> This section lists all the known changes between 7.0.x and 8.0.x which may + cause backwards compatibility problems when upgrading.</p> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Java 7 required"> +<!--()--></a><a name="Java_7_required"><strong>Java 7 required</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>Apache Tomcat 8.0.x requires Java 7 or later. Apache Tomcat 7.0.x + required Java 6.</p> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Specification APIs"> +<!--()--></a><a name="Specification_APIs"><strong>Specification APIs</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>Apache Tomcat 8 supports Java Servlet 3.1, JavaServer Pages 2.3, + Expression Language 2.3 and Java WebSocket 1.0 + <a href="http://wiki.apache.org/tomcat/Specifications">specifications</a>. + The changes between versions of specifications may be found in the + <em>Changes</em> appendix in each of specification documents. + </p> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Servlet 3.1 API"> +<!--()--></a><a name="Servlet_3.1_API"><strong>Servlet 3.1 API</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>In JSP pages that use wildcard import syntax the new classes added in + Servlet API may conflict with ones in web applications. + For example, if package <code>"a"</code> contains class + <code>ReadListener</code>, the following JSP page will cease to compile in + Tomcat 8:</p> + + +<div align="left"> +<table cellspacing="4" cellpadding="0" border="0"> +<tr> +<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td> +</tr> +<tr> +<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"> +<pre> +<%@page import="a.*"%> +<% ReadListener listener = new ReadListener(); %></pre> +</td><td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td> +</tr> +<tr> +<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td> +</tr> +</table> +</div> + + +<p>This happens because implicit import of <code>javax.servlet.*</code> + and explicit import of <code>a.*</code> will provide conflicting + definitions of class <code>ReadListener</code> that was added in Servlet + 3.1. The solution is to use the explicit import, + <code>import="a.ReadListener"</code>.</p> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Default connector implementation"> +<!--()--></a><a name="Default_connector_implementation"><strong>Default connector implementation</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>The default HTTP and AJP connector implementation has switched from the + Java blocking IO implementation (BIO) to the Java non-blocking IO + implementation (NIO). BIO may still be used but Servlet 3.1 and WebSocket + 1.0 features that use non-blocking IO will then use blocking IO instead + which may cause unexpected application behavior.</p> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Web application resources"> +<!--()--></a><a name="Web_application_resources"><strong>Web application resources</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>The Aliases, VirtualLoader, VirtualDirContext, JAR resources and external + repositories features that all provided a way to add resources to a web + application have been replaced with a single framework rather than each + being implemented separately (this was becoming increasingly difficult to + maintain). The <a href="tomcat-8-docs/config/resources.html">resources</a> + documentation provides details on how the new implementation may be used. + </p> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Internal APIs"> +<!--()--></a><a name="Internal_APIs"><strong>Internal APIs</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>Whilst the Tomcat 8 internal API is broadly compatible with Tomcat 7 + there have been many changes at the detail level and they are not binary + compatible. Developers of custom components that interact with Tomcat's + internals should review the JavaDoc for the relevant API.</p> + + +<p>Of particular note are:</p> + +<ul> + +<li>The Manager, Loader and Resources have moved from Container to Context + since Context is the only place they are used.</li> + +<li>The Mapper has moved from the Connector to the Service since the + Mapper is identical for all Connectors of a given Service.</li> + +<li>A new Resources implementation that merges Aliases, VirtualLoader, + VirtualDirContext, JAR resources and external repositories into a + single framework rather than a separate one for each feature.</li> + +</ul> + + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Upgrading 8.0.x"> +<!--()--></a><a name="Upgrading_8.0.x"><strong>Upgrading 8.0.x</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + +<p>When upgrading instances of Apache Tomcat from one version of Tomcat 8 to + another, particularly when using separate locations for $CATALINA_HOME and + $CATALINA_BASE, it is necessary to ensure that any changes in the + configuration files such as new attributes and changes to defaults are applied + as part of the upgrade. To assist with the identification of these changes, + the form below may be used to view the differences between the configuration + files in different versions of Tomcat 7.</p> + + +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Tomcat 8.0.x configuration file differences"> +<!--()--></a><a name="Tomcat_8.0.x_configuration_file_differences"><strong>Tomcat 8.0.x configuration file differences</strong></a></font></td> +</tr> +<tr> +<td> +<blockquote> + + +<p>Select a configuration file, old version and new version from the boxes + below and then click "View differences" to see the differences. + The differences will be shown in a new tab/window.</p> + + +<script type="text/javascript" language="JavaScript"> + function updateTc8ActionUrl() { + var revisions = { + "HEAD":"HEAD", + "8.0.0-RC1":"1509411", + }; + var formSubmit= document.getElementById('tc8Submit'); + var elementsSelect= document.getElementById('tc8Select').elements; + formSubmit.action = "http://svn.apache.org/viewvc/tomcat/trunk/" + + elementsSelect['filename'].value; + formSubmit.elements['r1'].value = revisions[elementsSelect['r1'].value]; + formSubmit.elements['r2'].value = revisions[elementsSelect['r2'].value]; + return true; + } + </script> + + +<form id="tc8Select" action="not-used"> + +<p>Configuration file: + <select name="filename"> + <option value="conf/catalina.policy">catalina.policy</option> + <option value="conf/catalina.properties">catalina.properties</option> + <option value="conf/context.xml">context.xml</option> + <option value="conf/logging.properties">logging.properties</option> + <option value="conf/server.xml">server.xml</option> + <option value="conf/tomcat-users.xml">tomcat-users.xml</option> + <option value="conf/web.xml">web.xml</option> + </select> + +</p> + +<p>Old version: + <select name="r1"> + <option value="8.0.0-RC1" selected>8.0.0-RC1</option> + </select>, new version: + <select name="r2"> + <option value="HEAD" selected>trunk (unreleased)</option> + </select> + +</p> + +</form> + +<form id="tc8Submit" action="to-be-replaced" method="get" target="_blank"> + +<p> + +<input type="hidden" name="diff_format" value="h"> + <input type="hidden" name="r1"><input type="hidden" name="r2"> + <input type="submit" value="View Differences" onClick="return updateTc8ActionUrl();"> + +</p> + +</form> + +<p>You can also use Subversion command similar to the following (all on one line):</p> + +<pre> svn diff + --old=http://svn.apache.org/repos/asf/tomcat/tags/TOMCAT_8_0_0/conf/ + --new=http://svn.apache.org/repos/asf/tomcat/tags/TOMCAT_8_0_1/conf/ + </pre> + +</blockquote> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> + + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> +</td> +</tr> +<!--FOOTER SEPARATOR--> +<tr> +<td colspan="2"> +<hr noshade size="1"> +</td> +</tr> +<!--PAGE FOOTER--> +<tr> +<td colspan="2"> +<div align="center"> +<font color="#525D76" size="-1"><em> + Copyright © 1999-2013, The Apache Software Foundation + <br> + Apache Tomcat, Tomcat, Apache, the Apache feather, and the Apache Tomcat + project logo are trademarks of the Apache Software Foundation. + </em></font> +</div> +</td> +</tr> +</table> +</body> +</html> Propchange: tomcat/site/trunk/docs/migration-8.html ------------------------------------------------------------------------------ svn:eol-style = native Modified: tomcat/site/trunk/docs/migration.html URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/migration.html?rev=1510708&r1=1510707&r2=1510708&view=diff ============================================================================== --- tomcat/site/trunk/docs/migration.html (original) +++ tomcat/site/trunk/docs/migration.html Mon Aug 5 20:24:51 2013 @@ -203,6 +203,12 @@ <li> <a href="#Upgrading_between_7.0.x_versions">Upgrading between 7.0.x versions</a> </li> +<li> +<a href="#Migrating_from_7.0.x_to_8.0.x">Migrating from 7.0.x to 8.0.x</a> +</li> +<li> +<a href="#Upgrading_between_8.0.x_versions">Upgrading between 8.0.x versions</a> +</li> </ul> </blockquote> @@ -353,6 +359,55 @@ accordingly.</p> </td> </tr> </table> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Migrating from 7.0.x to 8.0.x"> +<!--()--></a><a name="Migrating_from_7.0.x_to_8.0.x"><strong>Migrating from 7.0.x to 8.0.x</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + + +<p>See <a href="migration-8.html">Migration Guide - Tomcat 8.0.x</a>.</p> + + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> +<tr> +<td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica,sanserif"><a name="Upgrading between 8.0.x versions"> +<!--()--></a><a name="Upgrading_between_8.0.x_versions"><strong>Upgrading between 8.0.x versions</strong></a></font></td> +</tr> +<tr> +<td> +<p> +<blockquote> + + +<p>See <a href="migration-8.html#Upgrading_8.0.x">Migration Guide +- Tomcat 8.0.x</a>.</p> + + +</blockquote> +</p> +</td> +</tr> +<tr> +<td> +<br> +</td> +</tr> +</table> </td> </tr> <!--FOOTER SEPARATOR--> Copied: tomcat/site/trunk/xdocs/migration-8.xml (from r1510686, tomcat/site/trunk/xdocs/migration-7.xml) URL: http://svn.apache.org/viewvc/tomcat/site/trunk/xdocs/migration-8.xml?p2=tomcat/site/trunk/xdocs/migration-8.xml&p1=tomcat/site/trunk/xdocs/migration-7.xml&r1=1510686&r2=1510708&rev=1510708&view=diff ============================================================================== --- tomcat/site/trunk/xdocs/migration-7.xml (original) +++ tomcat/site/trunk/xdocs/migration-8.xml Mon Aug 5 20:24:51 2013 @@ -3,7 +3,7 @@ <properties> <author>Apache Tomcat Project</author> - <title>Migration Guide - Tomcat 7.0.x</title> + <title>Migration Guide - Tomcat 8.0.x</title> </properties> <body> @@ -20,426 +20,95 @@ of Apache Tomcat.</p> </section> -<section name="Migrating from 6.0.x to 7.0.x"> +<section name="Migrating from 7.0.x to 8.0.x"> - <p> This section lists all the known changes between 6.0.x and 7.0.x which may + <p> This section lists all the known changes between 7.0.x and 8.0.x which may cause backwards compatibility problems when upgrading.</p> - <subsection name="Java 6 required"> + <subsection name="Java 7 required"> - <p>Apache Tomcat 7.0.x requires Java 6 or later. Apache Tomcat 6.0.x - required Java 5.</p> + <p>Apache Tomcat 8.0.x requires Java 7 or later. Apache Tomcat 7.0.x + required Java 6.</p> </subsection> - <subsection name="Servlet 3.0 API"> + <subsection name="Specification APIs"> - <p>Apache Tomcat 7 supports Java Servlet 3.0, JavaServer Pages 2.2 and - Expression Language 2.2 + <p>Apache Tomcat 8 supports Java Servlet 3.1, JavaServer Pages 2.3, + Expression Language 2.3 and Java WebSocket 1.0 <a href="http://wiki.apache.org/tomcat/Specifications">specifications</a>. The changes between versions of specifications may be found in the <em>Changes</em> appendix in each of specification documents. </p> + </subsection> + + <subsection name="Servlet 3.1 API"> + <p>In JSP pages that use wildcard import syntax the new classes added in Servlet API may conflict with ones in web applications. - For example, if package <code>"a"</code> contains class <code>Part</code>, - the following JSP page will cease to compile in Tomcat 7:</p> + For example, if package <code>"a"</code> contains class + <code>ReadListener</code>, the following JSP page will cease to compile in + Tomcat 8:</p> <source> <%@page import="a.*"%> -<% Part page = new Part(); %></source> +<% ReadListener listener = new ReadListener(); %></source> - <p>That happens because implicit import of <code>javax.servlet.http.*</code> + <p>This happens because implicit import of <code>javax.servlet.*</code> and explicit import of <code>a.*</code> will provide conflicting - definitions of class <code>Part</code> that was added in Servlet 3.0. - The solution is to use explicit import, <code>import="a.Part"</code>.</p> - - </subsection> - - <subsection name="Regular expressions"> - - <p>All configuration options that use regular expression now require a - single regular expression (using <code>java.util.regex</code>) rather than a - list of comma-separated or semi-colon-separated expressions.</p> - - <p>This concerns the following:</p> - - <ul> - <li><code>allow</code> and <code>deny</code> attributes in - RemoteAddrFilter, RemoteHostFilter - <a href="/tomcat-7.0-doc/config/filter.html">filters</a> - and in RemoteAddrValve, RemoteHostValve - <a href="/tomcat-7.0-doc/config/valve.html">valves</a>; - </li> - <li><code>internalProxies</code>, <code>trustedProxies</code> attributes in - <a href="/tomcat-7.0-doc/config/filter.html">RemoteIpFilter</a>, - <a href="/tomcat-7.0-doc/config/valve.html">RemoteIpValve</a>; - </li> - <li><code>filter</code> attribute in - <a href="/tomcat-7.0-doc/config/cluster-valve.html">ReplicationValve</a>;</li> - <li><code>restrictedUserAgents</code>, <code>noCompressionUserAgents</code> - attributes in - <a href="/tomcat-7.0-doc/config/http.html">HTTP connectors</a>.</li> - </ul> - - <p>Note that separate regular expressions can be concatenated using the - "<code>|</code>" operator (or). Using "<code>|</code>" works both in this - and in earlier Tomcat versions.</p> - - </subsection> - - <subsection name="Deployment"> - - <p>XML context descriptors (<code>META-INF/context.xml</code> files) - are no longer copied from deployed WARs and directories to the host's - <code>xmlBase</code>. The default - Tomcat 6 behavior can be enabled by setting the <code>copyXML</code> - attribute of the <strong>Host</strong> element to <code>true</code>.</p> - - <p>The WARs outside of the host's <code>appBase</code> are no longer - unpacked, regardless of the value of the <code>Host</code>'s - <code>unpackWARs</code> setting. See issue - <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=51294#c1">51294</a>. - </p> - </subsection> - - <subsection name="Manager application"> - - <p>The Manager application has been re-structured for Tomcat 7 onwards and - some URLs have changed. All URLs used to access the Manager application - should now start with one of the following options:</p> - - <ul> - <li><ContextPath>/html for the HTML GUI</li> - <li><ContextPath>/text for the text interface</li> - <li><ContextPath>/jmxproxy for the JMX proxy</li> - <li><ContextPath>/status for the status pages</li> - </ul> - - <p>Note that the URL for the text interface has changed from - "<ContextPath>" to "<ContextPath>/text".</p> - - <p>The roles required to use the Manager application were changed from the - single <code>manager</code> role to the following four roles. You will need to - assign the role(s) required for the functionality you wish to access.</p> - - <ul> - <li><code>manager-gui</code> - allows access to the HTML GUI - and the status pages</li> - <li><code>manager-script</code> - allows access to the text interface - and the status pages</li> - <li><code>manager-jmx</code> - allows access to the JMX proxy - and the status pages</li> - <li><code>manager-status</code> - allows access to - the status pages only</li> - </ul> - - <p>The HTML interface is protected against CSRF but the text and JMX - interfaces are not. To maintain the CSRF protection:</p> - - <ul> - <li>users with the <tt>manager-gui</tt> role should not be granted - either the <tt>manager-script</tt> or <tt>manager-jmx</tt> roles.</li> - <li>if the Manager application is accessed through a browser by a user - who has <tt>manager-script</tt> or <tt>manager-jmx</tt> roles - (e.g. for testing the text or jmx interfaces since these interfaces - are intended for tools not humans) then all browser windows - must be closed afterwards to terminate the session.</li> - </ul> - - <p>The roles command has been removed from the Manager application since it - did not work with the default configuration and most Realms do not support - providing a list of roles.</p> + definitions of class <code>ReadListener</code> that was added in Servlet + 3.1. The solution is to use the explicit import, + <code>import="a.ReadListener"</code>.</p> </subsection> - <subsection name="Host Manager application"> - - <p>The Host Manager application has been re-structured for Tomcat 7 onwards - and some URLs have changed. All URLs used to access the Host Manager - application should now start with one of the following options:</p> - - <ul> - <li><ContextPath>/html for the HTML GUI</li> - <li><ContextPath>/text for the text interface</li> - </ul> - - <p>Note that the URL for the text interface has changed from - "<ContextPath>" to "<ContextPath>/text".</p> - - <p>The roles required to use the Host Manager application were changed from - the single <code>admin</code> role to the following two roles. You will need to - assign the role(s) required for the functionality you wish to access.</p> - - <ul> - <li><code>admin-gui</code> - allows access to the HTML GUI - and the status pages</li> - <li><code>admin-script</code> - allows access to the text interface - and the status pages</li> - </ul> + <subsection name="Default connector implementation"> - <p>The HTML interface is protected against CSRF but the text interface is - not. To maintain the CSRF protection:</p> - - <ul> - <li>users with the <tt>admin-gui</tt> role should not be granted the - <tt>admin-script</tt> role.</li> - <li>if the Host Manager application is accessed through a browser - by a user who has <tt>admin-script</tt> role (e.g. for testing - the text interface since this inteface is intended for tools - not humans) then all browser windows - must be closed afterwards to terminate the session.</li> - </ul> + <p>The default HTTP and AJP connector implementation has switched from the + Java blocking IO implementation (BIO) to the Java non-blocking IO + implementation (NIO). BIO may still be used but Servlet 3.1 and WebSocket + 1.0 features that use non-blocking IO will then use blocking IO instead + which may cause unexpected application behavior.</p> </subsection> - <subsection name="Session manager configuration"> - <p>A number of changes have been made to the session manager to improve the - performance of session generation and destruction including changes to - session ID generation. The session ID generation changes take advantages of - improvements in <code>java.secure.SecureRandom</code> since the session ID - generation was first written. The configuration changes are:</p> - - <ul> - <li><code>randomClass</code> attribute of <strong>Manager</strong> - has changed to <code>secureRandomClass</code> and the provided class - must extend <code>java.secure.SecureRandom</code></li> - <li>Two new properties <code>secureRandomAlgoithm</code> and - <code>secureRandomProvider</code> have been added to enable the selection - of a SecureRandom implementation.</li> - <li>The <code>algorithm</code> attribute has been removed</li> - <li>The <code>entropy</code> attribute has been removed</li> - </ul> - - <p>One known issue with <code>java.secure.SecureRandom</code> is that - it initialization requires some random data from an entropy source. With - some entropy source implementations it may require some time to gather - enough random data. If initialization of session id generator takes - noticeable time (more than 100ms), a diagnostic message will be logged. - E.g.:</p> + <subsection name="Web application resources"> - <p> - <code><em>DATE</em> org.apache.catalina.util.SessionIdGenerator createSecureRandom</code><br /> - <code>INFO: Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [406] milliseconds.</code> + <p>The Aliases, VirtualLoader, VirtualDirContext, JAR resources and external + repositories features that all provided a way to add resources to a web + application have been replaced with a single framework rather than each + being implemented separately (this was becoming increasingly difficult to + maintain). The <a href="tomcat-8-docs/config/resources.html">resources</a> + documentation provides details on how the new implementation may be used. </p> - <p>It is possible to change the entropy source used by JRE by defining - a system property. E.g.:<br /> - <code>-Djava.security.egd=file:/dev/./urandom</code></p> - - <p>The "/./" characters in the above value are to workaround - <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6202721">JRE issue #6202721</a>.</p> </subsection> - <subsection name="Session cookie configuration"> - - <p>With the addition of <code>SessionCookieConfig</code> in the Servlet 3.0 - specification, a number of session cookie configuration options have been - removed to reduce configuration and code complexity.</p> - - <ul> - <li><strong>Connector</strong><code>.emptySessionPath</code>: This has been removed. An equivalent - effect can be obtained by configuring sessionCookiePath="/" in the global - context.xml (in <code>CATALINA_BASE/conf/context.xml</code>).</li> - - <li><code>org.apache.catalina.SESSION_COOKIE_NAME</code> system property: This has been - removed. An equivalent effect can be obtained by configuring the - <code>sessionCookieName</code> attribute for the global context.xml - (in <code>CATALINA_BASE/conf/context.xml</code>).</li> - - <li><code>org.apache.catalina.SESSION_PARAMETER_NAME</code> system property: This has - been removed. An equivalent effect can be obtained by configuring the - <code>sessionCookieName</code> attribute for the global context.xml - (in <code>CATALINA_BASE/conf/context.xml</code>).</li> - - <li><strong>Context</strong><code>.disableURLRewriting</code>: This has - been removed. An equivalent effect can be obtained by configuring the - <code>session-config/tracking-mode</code> elements in a web application - or in the global <code>CATALINA_BASE/conf/web.xml</code> file.</li> - </ul> - - <p>The session and SSO cookies in Tomcat 7 are being sent with HttpOnly - flag by default, to instruct browsers to prevent access to those cookies - from JavaScript. This is considered more secure, but it will prevent - JavaScripts from accessing the value of the cookie. - This feature can be controlled by <code>useHttpOnly</code> attribute - on the <strong>Context</strong> element. - (This feature is also implemented in latest versions of Tomcat 6.0 - but is off by default. It can be enabled by setting - <code>useHttpOnly="true"</code> on <strong>Context</strong> element in - a web application or in the global - <code>CATALINA_BASE/conf/context.xml</code> file).</p> - - </subsection> - - <subsection name="Cookies"> - - <p>Tomcat no longer accepts non-specification compliant name-only cookies by - default. However, a new system property has been added, - <code>org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY</code>, that - can be used to accept name-only cookies.</p> - - </subsection> - - <subsection name="Request attributes"> - - <p>The custom request attribute - <code>javax.servlet.request.ssl_session</code> provided to access the SSL - session ID has been deprecated in favour of the new standard request - attribute that is defined in the Servlet specification, - <code>javax.servlet.request.ssl_session_id</code>. Support - for the custom attribute will be removed in Tomcat 8.</p> - - </subsection> - - <subsection name="Comet"> - - <p>To enable Comet to work correctly when running under a security manager, - the Comet classes have been moved from the <code>org.apache.catalina</code> - package to the <code>org.apache.catalina.comet</code> package. Code that - uses Comet will need to be updated and recompiled to reflect the new - package name.</p> - - </subsection> - - <subsection name="XML validation"> - - <p>The configuration of XML validation has been simplified. The - <code>xmlValidation</code> and <code>xmlNamespaceAware</code> attributes - have been removed from the <strong>Host</strong> element. These - attributes, along with <code>tldValidation</code> and - <code>tldNamespaceAware</code>, are now set per <strong>Context</strong> - element. The defaults (<code>false</code> for each attribute) have not been - changed. However, in line with the requirements of the Servlet - specification, if the - <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> system - property is set to <code>true</code>, XML validation and namespace - awareness will be enabled by default.</p> - - </subsection> - - <subsection name="System properties"> - - <p>The <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> system - property has been modified to provide greater control over its effects. Each - behavioural change is now controlled by a dedicated system property. The - default behaviour is unchanged. The - <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> system property - now controls whether or not specification compliant defaults are used for - the other system properties. Even if - <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is - <code>true</code>, setting the individual system properties will always take - priority.</p> - - <p>The <code>org.apache.coyote.MAX_TRAILER_SIZE</code> has been removed and - is replaced by the maxTrailerSize attribute of the - <strong>Connector</strong>.</p> - - </subsection> - - <subsection name="Processing of conf/web.xml file"> - - <p>Servlet 3.0 specification defines how web.xml file of an application - can be combined from web fragments and annotations. Processing of the - global <code>conf/web.xml</code> file that defines server-wide defaults - was changed as a result of implementing those rules.</p> - - <p>One noticeable - difference is that Filters defined in the global <code>conf/web.xml</code> - now follow the ones defined in a web application, instead of preceding - them. See issues - <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=51754#c1">51754</a> - and - <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=52138#c4">52138</a> - for clarifications.</p> - - </subsection> - - <subsection name="Welcome files processing"> - - <p>The welcome file processing was changed to follow clarifications in the - Servlet 3.0 specification. If your list of welcome files includes ones that - are processed by a servlet (such as *.jsp), you may observe the change in - behaviour. See the <code>resourceOnlyServlets</code> option on - <strong>Context</strong>. - </p> - - </subsection> - - <subsection name="Annotation scanning"> - - <p>The annotation scanning required by the Servlet 3.0 specification - may have impact on the startup time of your web application, as well as - increase requirements on the memory needed to load scanned classes. - Note, that upon clarification from the Servlet EG, even applications - using Servlet 2.4 and older versions of specification are being scanned. - See issue - <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=53619">53619</a> - and related discussions on the users mailing list. - </p> - - <p>There are several ways to deal with this issue. The recommended way is - to mark those applications that do not require annotation scanning as such. - It can be done in the <code>WEB-INF/web.xml</code> of your application by - the following steps:</p> - - <ul> - <li> - Update the <code>web-app</code> element to indicate that the web - application is using specification version 3.0. You may copy the values - for the <code>version</code>, <code>xsi:schemaLocation</code>, - <code>xmlns</code> and <code>xmlns:xsi</code> attributes from the default - <code>conf/web.xml</code> file. - </li> - <li> - Add <code>metadata-complete="true"</code> attribute to the - <code>web-app</code> element. - </li> - <li> - Add an empty <code><![CDATA[<absolute-ordering />]]></code> element. - </li> - </ul> - - <p>The <code>metadata-complete</code> attribute is supported starting with - Servlet 2.5 specification. The <code>absolute-ordering</code> element - requires Servlet 3.0.</p> - - <p>The second way is to configure JarScanner component to ignore certain JAR - files according to their names. This is usually configured in the - <code>conf/catalina.properties</code> file. See documentation on the - <code>jarsToSkip</code> properties in the - <a href="/tomcat-7.0-doc/config/systemprops.html">System properties</a> - chapter of the Configuration Reference for details. - Starting with Tomcat 7.0.30 it is possible to separately configure - which JARs are skipped for Servlet 3.0 scanning (scanning for annotations - and web application fragments), TLD scanning (tag libraries) or both. - Further versions of Tomcat may provide better ways to control this feature.</p> - - </subsection> - <subsection name="Internal APIs"> - <p>Whilst the Tomcat 7 internal API is broadly compatible with Tomcat 6 + <p>Whilst the Tomcat 8 internal API is broadly compatible with Tomcat 7 there have been many changes at the detail level and they are not binary compatible. Developers of custom components that interact with Tomcat's internals should review the JavaDoc for the relevant API.</p> <p>Of particular note are:</p> <ul> - <li>A standard implementation of the Lifecycle interface that all - components extend.</li> - <li>Use of generics.</li> - <li>The use of Context name rather than Context path as the unique - identifier for a Context within a Host.</li> + <li>The Manager, Loader and Resources have moved from Container to Context + since Context is the only place they are used.</li> + <li>The Mapper has moved from the Connector to the Service since the + Mapper is identical for all Connectors of a given Service.</li> + <li>A new Resources implementation that merges Aliases, VirtualLoader, + VirtualDirContext, JAR resources and external repositories into a + single framework rather than a separate one for each feature.</li> </ul> </subsection> </section> -<section name="Upgrading 7.0.x"> - <p>When upgrading instances of Apache Tomcat from one version of Tomcat 7 to +<section name="Upgrading 8.0.x"> + <p>When upgrading instances of Apache Tomcat from one version of Tomcat 8 to another, particularly when using separate locations for $CATALINA_HOME and $CATALINA_BASE, it is necessary to ensure that any changes in the configuration files such as new attributes and changes to defaults are applied @@ -447,51 +116,21 @@ of Apache Tomcat.</p> the form below may be used to view the differences between the configuration files in different versions of Tomcat 7.</p> - <subsection name="Tomcat 7.0.x configuration file differences"> + <subsection name="Tomcat 8.0.x configuration file differences"> <p>Select a configuration file, old version and new version from the boxes below and then click "View differences" to see the differences. The differences will be shown in a new tab/window.</p> <script type="text/javascript" language="JavaScript"> - function updateTc7ActionUrl() { + function updateTc8ActionUrl() { var revisions = { "HEAD":"HEAD", - "7.0.0":"954232", - "7.0.2":"982035", - "7.0.4":"1022637", - "7.0.5":"1038717", - "7.0.6":"1057288", - "7.0.8":"1067169", - "7.0.10":"1078282", - "7.0.11":"1080182", - "7.0.12":"1087797", - "7.0.14":"1101230", - "7.0.16":"1134562", - "7.0.19":"1146504", - "7.0.20":"1155255", - "7.0.21":"1162976", - "7.0.22":"1176599", - "7.0.23":"1203305", - "7.0.25":"1232371", - "7.0.26":"1245466", - "7.0.27":"1307817", - "7.0.28":"1350468", - "7.0.29":"1356494", - "7.0.30":"1379863", - "7.0.32":"1393331", - "7.0.33":"1410718", - "7.0.34":"1416816", - "7.0.35":"1431695", - "7.0.37":"1445362", - "7.0.39":"1459741", - "7.0.40":"1479250", - "7.0.41":"1490220", - "7.0.42":"1498817" + "8.0.0-RC1":"1509411", }; - var formSubmit= document.getElementById('tc7Submit'); - var elementsSelect= document.getElementById('tc7Select').elements; - formSubmit.action = "http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/" + + var formSubmit= document.getElementById('tc8Submit'); + var elementsSelect= document.getElementById('tc8Select').elements; + formSubmit.action = "http://svn.apache.org/viewvc/tomcat/trunk/" + elementsSelect['filename'].value; formSubmit.elements['r1'].value = revisions[elementsSelect['r1'].value]; formSubmit.elements['r2'].value = revisions[elementsSelect['r2'].value]; @@ -499,7 +138,7 @@ of Apache Tomcat.</p> } </script> - <form id="tc7Select" action="not-used"> + <form id="tc8Select" action="not-used"> <p>Configuration file: <select name="filename"> <option value="conf/catalina.policy">catalina.policy</option> @@ -513,87 +152,26 @@ of Apache Tomcat.</p> </p> <p>Old version: <select name="r1"> - <option value="7.0.0">7.0.0</option> - <option value="7.0.2">7.0.2</option> - <option value="7.0.4">7.0.4</option> - <option value="7.0.5">7.0.5</option> - <option value="7.0.6">7.0.6</option> - <option value="7.0.8">7.0.8</option> - <option value="7.0.10">7.0.10</option> - <option value="7.0.11">7.0.11</option> - <option value="7.0.12">7.0.12</option> - <option value="7.0.14">7.0.14</option> - <option value="7.0.16">7.0.16</option> - <option value="7.0.19">7.0.19</option> - <option value="7.0.20">7.0.20</option> - <option value="7.0.21">7.0.21</option> - <option value="7.0.22">7.0.22</option> - <option value="7.0.23">7.0.23</option> - <option value="7.0.25">7.0.25</option> - <option value="7.0.26">7.0.26</option> - <option value="7.0.27">7.0.27</option> - <option value="7.0.28">7.0.28</option> - <option value="7.0.29">7.0.29</option> - <option value="7.0.30">7.0.30</option> - <option value="7.0.32">7.0.32</option> - <option value="7.0.33"></option> - <option value="7.0.34">7.0.34</option> - <option value="7.0.35">7.0.35</option> - <option value="7.0.37">7.0.37</option> - <option value="7.0.39">7.0.39</option> - <option value="7.0.40">7.0.40</option> - <option value="7.0.41" selected="selected">7.0.41</option> - <option value="7.0.42">7.0.42</option> + <option value="8.0.0-RC1" selected="selected">8.0.0-RC1</option> </select>, new version: <select name="r2"> - <option value="7.0.0">7.0.0</option> - <option value="7.0.2">7.0.2</option> - <option value="7.0.4">7.0.4</option> - <option value="7.0.5">7.0.5</option> - <option value="7.0.6">7.0.6</option> - <option value="7.0.8">7.0.8</option> - <option value="7.0.10">7.0.10</option> - <option value="7.0.11">7.0.11</option> - <option value="7.0.12">7.0.12</option> - <option value="7.0.14">7.0.14</option> - <option value="7.0.16">7.0.16</option> - <option value="7.0.19">7.0.19</option> - <option value="7.0.20">7.0.20</option> - <option value="7.0.21">7.0.21</option> - <option value="7.0.22">7.0.22</option> - <option value="7.0.23">7.0.23</option> - <option value="7.0.25">7.0.25</option> - <option value="7.0.26">7.0.26</option> - <option value="7.0.27">7.0.27</option> - <option value="7.0.28">7.0.28</option> - <option value="7.0.29">7.0.29</option> - <option value="7.0.30">7.0.30</option> - <option value="7.0.32">7.0.32</option> - <option value="7.0.33">7.0.33</option> - <option value="7.0.34">7.0.34</option> - <option value="7.0.35">7.0.35</option> - <option value="7.0.37">7.0.37</option> - <option value="7.0.39">7.0.39</option> - <option value="7.0.40">7.0.40</option> - <option value="7.0.41">7.0.41</option> - <option value="7.0.42" selected="selected">7.0.42</option> - <option value="HEAD">trunk (unreleased)</option> + <option value="HEAD" selected="selected">trunk (unreleased)</option> </select> </p> </form> - <form id="tc7Submit" action="to-be-replaced" method="get" + <form id="tc8Submit" action="to-be-replaced" method="get" target="_blank"> <p> <input type="hidden" name="diff_format" value="h"/> <input type="hidden" name="r1" /><input type="hidden" name="r2" /> <input type="submit" value="View Differences" - onClick="return updateTc7ActionUrl();"/> + onClick="return updateTc8ActionUrl();"/> </p> </form> <p>You can also use Subversion command similar to the following (all on one line):</p> <pre> svn diff - --old=http://svn.apache.org/repos/asf/tomcat/tc7.0.x/tags/TOMCAT_7_0_27/conf/ - --new=http://svn.apache.org/repos/asf/tomcat/tc7.0.x/tags/TOMCAT_7_0_28/conf/ + --old=http://svn.apache.org/repos/asf/tomcat/tags/TOMCAT_8_0_0/conf/ + --new=http://svn.apache.org/repos/asf/tomcat/tags/TOMCAT_8_0_1/conf/ </pre> </subsection> Modified: tomcat/site/trunk/xdocs/migration.xml URL: http://svn.apache.org/viewvc/tomcat/site/trunk/xdocs/migration.xml?rev=1510708&r1=1510707&r2=1510708&view=diff ============================================================================== --- tomcat/site/trunk/xdocs/migration.xml (original) +++ tomcat/site/trunk/xdocs/migration.xml Mon Aug 5 20:24:51 2013 @@ -58,5 +58,18 @@ accordingly.</p> </section> +<section name="Migrating from 7.0.x to 8.0.x"> + +<p>See <a href="migration-8.html">Migration Guide - Tomcat 8.0.x</a>.</p> + +</section> + +<section name="Upgrading between 8.0.x versions"> + +<p>See <a href="migration-8.html#Upgrading_8.0.x">Migration Guide +- Tomcat 8.0.x</a>.</p> + +</section> + </body> </document> --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org