<!--
	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.
-->
<chapter id="ugr.tools.uimafit.migration">
  <title>Migration Guide</title>
  <para>This section provides helpful information on incompatible changes between versions.</para>
  <section>
    <title>Version 3.0.x to 3.1.x</title>
    <formalpara>
      <title>Changes to ExternalResourceFactory</title>
      <para>The renaming of methods in the <literal>ExternalResourceFactory</literal> had
      unfortunately introduced another name clash between unrelated methods. To fix this
      clash, the following methods have been renamed from <literal>bindResource</literal> to 
      <literal>bindResourceOnce</literal>:
        <itemizedlist>
          <listitem><para>
            <literal>void bindResource(ResourceCreationSpecifier aDesc, String aBindTo, ExternalResourceDescription aRes)</literal>
            was <emphasis role="strong">removed</emphasis> and replaced by
            <literal>void bindResourceOnce(ResourceCreationSpecifier aDesc, String aBindTo, ExternalResourceDescription aRes)</literal>
          </para></listitem>
          <listitem><para>
            <literal>void bindResource(ExternalResourceDescription aRes, String aBindTo, ExternalResourceDescription aNestedRes)</literal>
            was deprecated and replaced by
            <literal>void bindResourceOnce(ExternalResourceDescription aRes, String aBindTo, ExternalResourceDescription aNestedRes)</literal>
          </para></listitem>
          <listitem><para>
            <literal>void bindResource(ResourceManagerConfiguration aResMgrCfg, String aBindTo, ExternalResourceDescription aRes)</literal>
            was deprecated and replaced by
            <literal>void bindResourceOnce(ResourceManagerConfiguration aResMgrCfg, String aBindTo, ExternalResourceDescription aRes)</literal>
          </para></listitem>
          <listitem><para>
            <literal>void bindResource(ResourceCreationSpecifier aDesc, String aBindTo, String aRes)</literal>
            was <emphasis role="strong">removed</emphasis> and replaced by
            <literal>void bindResourceOnceWithoutNested(ResourceCreationSpecifier aDesc, String aBindTo, String aRes)</literal>
          </para></listitem>
          <listitem><para>
            <literal>void bindResource(ResourceManagerConfiguration aResMgrCfg, String aBindTo, String aRes)</literal>
            was deprecated and replaced by
            <literal>void bindResourceOnceWithoutNested(ResourceManagerConfiguration aResMgrCfg, String aBindTo, String aRes)</literal>
          </para></listitem>
          <listitem><para>
            <literal>void bindResource(ResourceSpecifier aDesc, String aKey, String aUrl)</literal>
            was deprecated and replaced by
            <literal>void bindResourceUsingUrl(ResourceSpecifier aDesc, String aKey, String aUrl)</literal>
          </para></listitem>
        </itemizedlist>
      </para>
    </formalpara>
  </section>
  <section>
    <title>Version 2.x to 3.x</title>
    <formalpara>
      <title>Legacy support module removed</title>
      <para>The legacy support in uimaFIT 2.x was present allow being compatible with the
      pre-Apache uimaFIT versions which were based on UIMA 2.x. Since uimaFIT 3.x is not 
      compatible with UIMA 2.x anyway, the legacy module was removed now.</para>
    </formalpara>
    <formalpara>
      <title>Using List instead of Collection</title>
      <para>The <literal>CasUtil</literal>, <literal>JCasUtil</literal> and 
      <literal>FSCollectionFactory</literal> classes were adjusted to return results
      using <literal>List</literal> instead of the more general <literal>Collection</literal>. 
      Often, lists are already used internally and then again wrapped into new lists in client 
      code. This API change avoids this in the future.</para>
    </formalpara>
    <formalpara>
      <title>Throwing specific exceptions instead of UIMAException</title>
      <para>Several uimaFIT methods were throwing the generic <literal>UIMAException</literal>. 
      These have been adjusted to declare throwing several of the sub-types of 
      <literal>UIMAException</literal> to be better able to handle
      specific causes of errors in client code.</para>
    </formalpara>
    <formalpara>
      <title>CasUtil.selectSingle signature changed</title>
      <para>Signature of <literal>CasUtil.selectSingle</literal> has been changed to return
      <literal>AnnotationFS</literal>. The original signature is available as 
      <literal>selectSingleFS</literal></para>
    </formalpara>
    <formalpara>
      <title>Removal of deprecated methods</title>
      <para>Various methods that were deprecated in uimaFIT 2.4.0 or earlier have been removed in
      this release. For details, please refer to the <literal>api-change-report.html</literal>
      file included in the release.</para>
    </formalpara>
    <formalpara>
      <title>Changes to ExternalResourceFactory</title>
      <para>Most methods in the <literal>ExternalResourceFactory</literal> have seen changes to 
      their names and signature to avoid problematic ambiguities as well as to be shorter. In 
      general, the <literal>External</literal> component of the method names was either
      removed or replaced. So most methods called <literal>createExternalResourceDescription</literal>
      are now called <literal>createResourceDescription</literal>. However, some have also been 
      given a more specific name and/or a slightly different order of parameters. For example, this
      method</para>
      <programlisting>public static ExternalResourceDescription createExternalResourceDescription(
  Class&lt;? extends SharedResourceObject&gt; aInterface, String aUrl, Object... aParams)</programlisting>
      <para>was changed to</para>
      <programlisting>public static ExternalResourceDescription createSharedResourceDescription(
  String aUrl, Class&lt;? extends SharedResourceObject&gt; aInterface, Object... aParams)</programlisting>
    </formalpara>
    <formalpara>
      <title>Changes to logging</title>
      <para>UIMA v3 has is using SLF4J. As a consequence, the <literal>ExtendedLogger</literal>
      which uimaFIT had returned on calls to <literal>getLogger()</literal> has been removed
      and instead the regular UIMA v3 logger class is returned which offers methods quite compatible
      with what <literal>ExtendedLogger</literal> offered before. However, it is recommended
      that you go through all your logging calls and replace calls which use string concatenation
      to construct the logging message with corresponding calls using placeholders. For example,
      replace <literal>getLogger().error("Cannot access " + filename, exception);</literal> with
      <literal>getLogger().error("Cannot access {}", filename, exception);</literal>.</para>
    </formalpara>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 3.0.2, Spring Framework 4.3.22 and Java 8.</para>
    </formalpara>
  </section>
  <section>
    <title>Version 2.3.0 to 2.4.0</title>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 2.10.2, Spring Framework 3.2.16 and Java 7.</para>
    </formalpara>
    <formalpara>
      <para>Mind the updated version requirements. There should be no other potentially problematic
      changes in this upgrade.</para>
    </formalpara>
  </section>
  <section>
    <title>Version 2.2.0 to 2.3.0</title>
    <formalpara>
      <title>CasIOUtil deprecated</title>
      <para>The functionality of the uimaFIT CasIOUtil class has been superseded by the core UIMA
      class CasIOUtils added in UIMA 2.9.0. The method signatures in the new class are not the
      same, but provide more functionality. CasIOUtil has been deprecated and documentation has
      been added which of the CasIOUtils methods should be used instead.</para>
    </formalpara>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 2.9.1, Spring Framework 3.2.16 and Java 7.</para>
    </formalpara>
    <formalpara>
      <para>Mind the updated version requirements. There should be no other potentially problematic
      changes in this upgrade.</para>
    </formalpara>
  </section>
  <section>
    <title>Version 2.1.0 to 2.2.0</title>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 2.8.1, Spring Framework 3.2.16 and Java 7.</para>
    </formalpara>
    <formalpara>
      <para>Mind the updated version requirements. There should be no other potentially problematic
      changes in this upgrade.</para>
    </formalpara>
  </section>
  <section>
    <title>Version 2.0.0 to 2.1.0</title>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 2.6.0 and Java 6.</para>
    </formalpara>
    <formalpara>
      <title>AnnotationFactory.createAnnotation()</title>
      <para>No longer throws <literal>UIMAExcption</literal>. If this exception was cought, some
        IDEs may complain here after upgrading to uimaFIT 2.1.0. </para>
    </formalpara>
  </section>
  <section>
    <title>Version 1.4.0 to 2.0.0</title>
    <formalpara>
      <title>Version requirements</title>
      <para>Depends on UIMA 2.4.2.</para>
    </formalpara>
    <formalpara>
      <title>Backwards compatibility</title>
      <para>Compatibility with legacy annotation is provided by the Legacy support module.</para>
    </formalpara>
    <formalpara>
      <title>Change of Maven groupId and artifactId</title>
      <para>The Maven group ID has changed from <literal>org.uimafit</literal> to
          <literal>org.apache.uima</literal>.</para>
    </formalpara>
    <para>The artifact ID of the main uimaFIT artifact has been changed from
        <literal>uimafit</literal> to <literal>uimafit-core</literal>.</para>
    <formalpara>
      <title>Change of package names</title>
      <para>The base package has been renamed from <literal>org.uimafit</literal> to
          <literal>org.apache.uima.fit</literal>. A global search/replace on Java files with for
        lines starting with <literal>import org.uimafit</literal> and replacing that with
          <literal>import org.apache.uima.fit</literal> should work.</para>
    </formalpara>
    <formalpara>
      <title>@ConfigurationParameter</title>
      <para>The default value for the mandatory attribute now is <literal>true</literal>. The
        default name of configuration parameters is now the name of the annotated field only. The
        classname is no longer prefixed. The method
          <code>ConfigurationParameterFactory.createConfigurationParameterName()</code> that was
        used to generate the prefixed name has been removed.</para>
    </formalpara>
    <formalpara>
      <title>Type detection: META-INF/org.uimafit folder</title>
      <para>The <literal>META-INF/org.uimafit</literal> was renamed to
          <literal>META-INF/org.apache.uima.fit</literal>.</para>
    </formalpara>
    <formalpara>
      <title>JCasUtil</title>
      <para>The deprecated <code>JCasUtil.iterate()</code> methods have been removed.
          <code>JCasUtil.select()</code> should be used instead.</para>
    </formalpara>
    <formalpara>
      <title>AnalysisEngineFactory</title>
      <para>All <literal>createAggregateXXX</literal> and <literal>createPrimitiveXXX</literal>
        methods have been renamed to <literal>createEngineXXX</literal>. The old names are
        deprecated and will be removed in future versions.</para>
    </formalpara>
    <para>All <literal>createAnalysisEngineXXX</literal> methods have been renamed to
        <literal>createEngineXXX</literal>. The old names are deprecated and will be removed in
      future versions.</para>
    <formalpara>
      <title>CollectionReaderFactory</title>
      <para>All <literal>createDescriptionXXX</literal> methods have been renamed to
          <literal>createReaderDescriptionXXX</literal>. The old names are deprecated and will be
        removed in future versions.</para>
    </formalpara>
    <para>All <literal>createCollectionReaderXXX</literal> methods have been renamed to
        <literal>createReaderXXX</literal>. The old names are deprecated and will be removed in
      future versions.</para>
    <formalpara>
      <title>JCasIterable</title>
      <para><code>JCasIterable</code> now only accepts reader and engine descriptions (no instances)
        and no longer implements the <code>Iterator</code> interface. Instead, new
          <code>JCasIterator</code> has been added, which replaces <code>JCasIterable</code> in that
        respect.</para>
    </formalpara>
    <formalpara>
      <title>CasDumpWriter</title>
      <para><literal>org.uimafit.component.xwriter.CASDumpWriter</literal> has been renamed to
          <literal>org.apache.uima.fit.component.CasDumpWriter</literal>.</para>
    </formalpara>
    <formalpara>
      <title>CpePipeline</title>
      <para><literal>CpePipeline</literal> has been moved to a separate module with the artifact ID
          <literal>uimafit-cpe</literal> to reduce the dependencies incurred by the main uimaFIT
        artifact.</para>
    </formalpara>
    <formalpara>
      <title>XWriter removed</title>
      <para>The <literal>XWriter</literal> and associated file namers have been removed as they were
        much more complex then acutally needed. As an alternative, <literal>CasIOUtil</literal> has
        been introduced providing several convenience methods to read/write JCas/CAS data. </para>
    </formalpara>
    <formalpara>
      <title>JCasFactory</title>
      <para>Methods only loading JCas data have been removed from <literal>JCasFactory</literal>.
        The new methods in <literal>CasIOUtil</literal> can be used instead.</para>
    </formalpara>
  </section>
</chapter>