<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
 "http://www.w3.org/TR/html4/loose.dtd">
<!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
-->
<html>
<head>
 <!-- saved from url=(0014)about:internet -->
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
 <meta name="Author" content="Malcolm Edgar"/>
 <meta name="description" lang="en" content="Apache Click Java web application framework"/>
 <meta name="keywords" lang="en" content="Apache Click, Click Framework, Java, JEE, J2EE, web application framework, open source"/>
 <title>Apache Click</title>
 <link rel="stylesheet" type="text/css" href="../help.css"/>
 <link rel="stylesheet" type="text/css" href="../syntax-highlighter.css"/>
 <style type="text/css">
  dl {
    margin-left: 2em;
  }
  dt {
    font-weight: 700;
    margin-top: 1.5em;
    margin-bottom: 0.5em;
  }
  .change {
    margin-bottom: 0.75em;
  }
  .upgrade {
    margin-bottom: 0.75em;
    margin-top: 0.75em;
  }
  .release-header {
    background: #EFEFF7;
    padding: 4px;
    padding-left: 8px;
    border: 1px solid #99A4DF;
  }
  pre {
    padding: 4px;
    border: 1px solid #99A4DF;
  }
  a {
  	text-decoration: none;
  }
 </style>
<script type="text/javascript" src="../syntax-highlighter.js"></script>
</head>
<!--Activate syntax highlighting-->
 <body onload="prettyPrint();">

<h1>Upgrade Path</h1>

This section discusses the changes you will need to make when upgrading from
one Click version to the next. Please note while the upmost effort is made to ensure
there is no impact between releases, some architectural changes will require
you to modify existing applications to upgrade to a newer version.
<p/>
If you experience any unexpected and undocumented impacts when upgrading between
versions please email the Click user group.

<p>&nbsp;</p>

<h2>Version Upgrades</h2>

<dl>
  <dt><a name="2.1.0"></a>
  <div class="release-header">Version 2.1.0 Upgrade</div></dt>
  <dd>
    <ul style="padding: 0em; margin-left:0em;margin-bottom: 2em">
      <li class="change">
      	  Requires Java version 1.5 or later.
      </li>
      <li class="change">
          Deprecated methods: <a href="click-api/org/apache/click/Control.html#getHtmlImports()">Control.getHtmlImports()</a> and
          <a href="click-api/org/apache/click/Page.html#getHtmlImports()">Page.getHtmlImports()</a>.
          These methods have been deprecated in favor of
          <a href="click-api/org/apache/click/Control.html#getHeadElements()">Control.getHeadElements()</a>
          and <a href="click-api/org/apache/click/Page.html#getHeadElements()">Page.getHeadElements()</a>.
      </li>
      <li class="change">
          Deprecated methods: <a href="click-api/org/apache/click/Page.html#getPageImports()">Page.getPageImports()</a>
          and <a href="click-api/org/apache/click/Page.html#setPageImports(org.apache.click.util.PageImports)">Page.setPageImports()</a>.
          These methods have been deprecated in favor of
          <a href="click-api/org/apache/click/Page.html#getHeadElements()">Page.getHeadElements()</a>.
      </li>
      <li class="change">
          Click automatically deploy resources from JARs and folders on the
          classpath that are located under a predefined directory. In previous
          versions of Click that directory was <tt>META-INF/web</tt>.
          <p/>
          The new Servlet 3.0 specification introduced a similar concept where
          resources can be packaged in a JAR and served directly without having
          to be deployed. The directory defined by Servlet 3.0 is
          <tt>META-INF/resources</tt>.
          <p/>
          Click 2.1.0 aligns with Servlet 3.0 in that resources are also deployed
          from <tt>META-INF/resources</tt>.
          <p/>
          For backwards compatibility Click will still deploy resources from
          <tt>META-INF/web</tt>, however it is highly recommended to deploy
          resources from <tt>META-INF/resources</tt> instead.
      </li>
    </ul>
  </dd>

  <dt><a name="2.0.1"></a>
  <div class="release-header">Version 2.0.1 Upgrade</div></dt>
  <dd>
    <div style="margin-top: 15px; margin-left:-2em;margin-bottom:1em;">
      This is our first Apache Incubator release and is based on <a href="#1.5.1">Click 1.5.1</a>.
      <p/>
      Please note that because of licensing issues, certain third-party
      libraries were removed and are hosted externally.
      <p/>
      Note the following changes when upgrading from 1.5 to 2.0.1:
    </div>
    <ul style="padding: 0em; margin-left:0em;margin-bottom: 2em">
      <li class="change">
        All <tt>net.sf.click.*</tt> packages have been renamed to <tt>org.apache.click.*</tt>.
        When upgrading you must replace all references to <tt>net.sf.click.*</tt> with
        <tt>org.apache.click.*</tt>.

        <p/>
        You can use your favorite IDE and do a global search/replace or
        alternatively use Ant's <a target="blank" class="external" href="http://ant.apache.org/manual/CoreTasks/replace.html">replace task</a>.

        <p/>
        Make sure you update the files <tt>web.xml</tt> and <tt>click.xml</tt> as well.
      </li>
      <li class="change">
          JSCalendar which is licensed under LGPL is incompatible with Apache license
          and had to be removed. DateField was refactored accordingly and does
          not contain any Calendar specific code.
          <p/>
          The following methods were removed:
          <ul>
              <li>
                  <tt>public String getCalendarPattern()</tt>
              </li>
              <li>
                  <tt>public boolean getShowTime()</tt> and <tt>public void setShowTime(boolean showTime)</tt>
              </li>
              <li>
                  <tt>public String getStyle()</tt> and <tt>public void setStyle(String style)</tt>
              </li>
              <li>
                  <tt>protected int getFirstDayOfWeek()</tt>
              </li>
              <li>
                  <tt>protected String parseDateFormatPattern(String pattern)</tt>
              </li>
          </ul>
          <p/>
          Since the calendar popup is not available to help users pick dates, it
          becomes difficult for users to know the format of the Date.
          To remedy this situation, Click 2.0.1 introduces a new resource key,
          <tt>date-title</tt>, which is set as the title of DateField. The new
          property provides users with visual feedback of the <tt>date format</tt>
          specified on the DateField. For those building i18n applications remember to add this property
          to <span style="color:navy;">DateField_&lt;lang&gt;.properties.</span>
          You can also send us patches for your languages and we will
          include it in the distribution.
      </li>
      <li>
          A new project called <a target="blank" class="external" href="http://code.google.com/p/click-calendar/">Click Calendar</a>
          was created as a port of the old DateField functionality. This project
          contains a CalendarField which can be used as a replacement for the
          old DateField.
          <p/>
          For example to have the popup Calendar functionality replace this:
          <pre class="prettyprint">
import org.apache.click.extras.control.DateField;

...

DateField dateField = new DateField("date");
</pre>

          with this:
          <pre class="prettyprint">
import net.sf.click.extras.control.CalendarField;

...

DateField dateField = new CalendarField("date");
</pre>
          CalendarField subclasses DateField so the above snippet is valid.
          <p/>
          See the <a target="blank" class="external" href="http://code.google.com/p/click-calendar/">Click Calendar</a>
          project for more details.
      </li>
      <li class="change">
          The Chart controls which is licensed under LGPL is incompatible with
          Apache license and had to be moved.
          <p/>
          A new project called <a target="blank" class="external" href="http://code.google.com/p/click-charts/">Click Charts</a>
          was created as a port of the Chart controls. This project consists of
          the BarChart, LineChart and PieChart controls and can be used as drop
          in replacements. See the project for more details.
      </li>
      <li class="change">
          The ColorPicker was replaced by Sebo Zoltan's implementation, available from
          <a target="blank" class="external" href="http://www.dhtmlgoodies.com/index.html?whichScript=submitted-color-picker">www.dhtmlgoodies.com</a>.
          <p/>
          Changes was only made to the JavaScript, CSS and
          images. The ColorPicker API remains unchanged.
      </li>
      <li class="change">
          The RichTextArea, found in Click examples, was based upon the
          <a target="blank" class="external" href="http://tinymce.moxiecode.com/">TinyMCE</a>
          project (LGPL) and was replaced by the <a target="blank" class="external" href="">YUI editor</a>
          (BSD license), which is compatible with the Apache license.
          <p/>
          The TinyMCE example was moved to the <a target="blank" class="external" href="http://code.google.com/p/clickclick/">ClickClick extensions</a>
          project.
      </li>
    </ul>
  </dd>

  <dt><a name="1.5"></a>
  <div class="release-header">Version 1.5 Upgrade</div></dt>
  <dd>
    <ul style="padding: 0em; margin-left:0em;">
      <li class="upgrade">
       <b>Please Note</b> Click version 1.5 is <b>not</b> binary compatible with version 1.4. To upgrade your
       applications to use version Click 1.5 you will need to:
       <ol style="margin-top:1em;">
        <li>Recompile your application with the 1.5 Click libraries.</li>
        <li>Retrofit the new Control 
        <a href="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render()</a>
        method to any on your custom control rendering.</li>
        <li>Replace any Control <tt>toString()</tt> methods with an equivalent <a href="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render()</a>
        method. For further details see the example below.</li>
        <li>Form.add(Field), FieldSet.add(Field) and Table.addColumn(Column) now return
        their argument instead of void, which enables you to chain calls for example<br>
        <pre class="prettyprint">
  table.add(new Column("name")).setSortable(true);
  form.add(new TextField("firstname")).setValue("Bob"); </pre>
        If you created a custom Form, FieldSet or Table and overrode the <em>add</em>
        or <em>addColumn</em> method, you will be forced to return the methods argument.
        For example if you had:
        <pre class="prettyprint">
public class MyTable {
    public void addColumn(Column column) {
      ...
    }
} </pre>
       you will need to update as follows:
       <pre class="prettyprint">
public class MyTable {
    public Column addColumn(Column column) {
      ...
      // You must return the column
      return column;
    }
} </pre>
        </li>
       </ol>
       Note that Click 1.5 is still compatible with Java JDK 1.4 or later.
      </li>
      <li class="upgrade">
       Deprecated methods: <a href="click-api/org/apache/click/Control.html#setListener(java.lang.Object, java.lang.String)">Control.setListener(Object, String)</a> and
       <a href="click-api/org/apache/click/Control.html#getContext()">Control.getContext()</a>.
       These methods have been deprecated on the Control interface as they are not required for ClickServlet -> Control API. 
       This refactoring is part of making the Control interface as small as possible, 
       which  allows more flexibility in future releases.
       <p/>
       Note these methods are still available on <a href="click-api/org/apache/click/control/AbstractControl.html">AbstractControl</a>,
       so this change should have minimal impact on existing code bases.
      </li>
      <li class="upgrade">
       Upgrade custom Control rendering code to use new 
       <a href="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render</a>
       method. This method allows improved rendering performance, because all controls can be
       rendered from a single buffer that is created when rendering starts.
       <p/>
       If your created custom controls override <em>toString()</em>, please adapt it to the following pattern. From this:
       <pre class="prettyprint">
public class HtmlTable extends AbstractControl {
    ...

    public String toString() {
        int estimatedControlSize = 1000;
        HtmlStringBuffer buffer = new HtmlStringBuffer(estimatedControlSize);

        // Rendering Start
        buffer.elementStart(<span style="font-weight:bold;color:#000099">"table"</span>);
        appendAttributes(buffer);
        buffer.elementClose();
    
        renderRows(buffer);

        buffer.closeElement(<span style="font-weight:bold;color:#000099">"table"</span>);
        // Rendering End
     
        return buffer.toString();
    } 
} </pre>
       to this:
<pre class="prettyprint">
public class HtmlTable extends AbstractControl {
    ...

    public void render(HtmlStringBuffer buffer) {
        // Rendering Start
        buffer.elementStart(<span style="font-weight:bold;color:#000099">"table"</span>);
        appendAttributes(buffer);
        buffer.elementClose();
    
        renderRows(buffer);

        buffer.closeElement(<span style="font-weight:bold;color:#000099">"table"</span>);
        <span style="color:green">// Rendering End</span>
    }

    public String toString() {
        int estimatedControlSize = 1000;
        HtmlStringBuffer buffer = new HtmlStringBuffer(estimatedControlSize);
        render(buffer);
        return buffer.toString();
    } 
} </pre>
       Note, the code between the commented section, was moved from <em>toString</em> to the <em>render</em> method.
       <p/>
       Also note that invoking a Control's <a href="click-api/org/apache/click/control/AbstractControl.html#toString()">toString()</a>
       method still outputs the same HTML representation, as toString() delegates to the
       <a href="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render</a>
       method.
       <p/>
       <b>Please note</b> a common problem when overriding <em>render</em> in custom components, is
       invoking <em>super.toString()</em> in order to render the Control's default
       markup:
       <pre class="prettyprint">
public class CustomField extends Field {
    ...

    public void render(HtmlStringBuffer buffer) {
        <span style="background:#F3FF0F">String field = super.toString();</span> // BEWARE this line will cause StackOverflowError
        ...
    }

    public String toString() {
        HtmlStringBuffer buffer = new HtmlStringBuffer();
        render(buffer);
        return buffer.toString();
    }
} </pre>
      The highlighted line above will cause a StackOverflowError, meaning an infinite
      loop was encountered. The reason for the error will become obvious when 
      tracing the sequence of calls:
      <ol style="margin-top: 2em;;margin-bottom: 2em">
          <li>The first statement in the method <em>CustomField.render</em> invokes
              <em>super.toString</em>. In this example the super class is Field, thus
              the actual method invoked is <em>Field.toString</em></li>
          <li><em>Field.toString</em> performs its own rendering by invoking <em>Field.render</em>.
            However since CustomField overrides <em>Field.render</em>, <em>Field.toString</em>
            will invoke <em>CustomField.render</em> instead.</li>
          <li>This leads us back to step 1. where <em>CustomField.render</em> invokes
              <em>super.toString</em>. This creates the infinite loop and leads to the StackOverflowError.</li>
      </ol>
      <p/>
      The fix is straight forward. If you override a Control's <em>render</em>
      method, but still want to render the Control's default markup, invoke
      <em>super.render</em> instead of <em>super.toString</em>.
      Here is the correct version:
      <pre class="prettyprint">
public class CustomField extends Field {
    ...

    public void render(HtmlStringBuffer buffer) {
        <span style="background:#F3FF0F">super.render(buffer);</span> // NOTE StackOverflowError won't occur
        ...
    }

    public String toString() {
        HtmlStringBuffer buffer = new HtmlStringBuffer();
        render(buffer);
        return buffer.toString();
    }
} </pre>
      </li>
      <li class="upgrade">
       Certain controls were retrofitted as containers. These include 
       <a href="click-api/org/apache/click/control/Form.html">Form</a>,
       <a href="click-api/org/apache/click/control/FieldSet.html">FieldSet</a>
       and <a href="click-api/org/apache/click/control/Panel.html">Panel</a>.
      </li>
      <li class="upgrade">
       Click 1.5 introduces two new properties: <span style="color:navy;">file-size-limit-exceeded-error</span>
       and <span style="color:navy;">post-size-limit-exceeded-error</span>.
       For those building i18n applications remember to add these two properties
       to your <span style="color:navy;">click-control_&lt;lang&gt;.properties.</span>
       <br>If you send us patches for your preferred language we will include them in the distribution.
      </li>
      <li class="upgrade">
       ClickLogger has been replaced with <a href="click-api/org/apache/click/service/LogService.html">LogService</a>.
       LogService is an interface with a default implementation <a href="click-api/org/apache/click/service/ConsoleLogService.html">ConsoleLogService</a>.
       There are also alternative implementations <a href="extras-api/org/apache/click/extras/service/Log4JLogService.html">Log4JLogService</a>
       and <a href="extras-api/org/apache/click/extras/service/JdkLogService.html">JdkLogService</a>.
       <p/>
       It is possible to write your own LogService instance or extend from
       an existing implementation. To setup Click to use an alternative instance you have to
       specify the LogService implementation in <em>click.xml</em>:
       <pre class="prettyprint">
&lt;click-app charset="UTF-8"&gt;
    &lt;pages package="org.apache.click.examples.page"/&gt;
    &lt;log-service classname="org.apache.click.extras.service.JdkLogService"/&gt;
&lt;/click-app&gt; </pre>
       <p/>
       While it is generally not recommended to use the Click LogService in your application code, you can retrieve it using the ClickUtils method
       <a href="click-api/org/apache/click/util/ClickUtils.html#getLogService()">getLogService()</a>.
      </li>
    </ul>
  </dd>
</dl>

</body>
</html>