| <!-- |
| 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<? extends SharedResourceObject> aInterface, String aUrl, Object... aParams)</programlisting> |
| <para>was changed to</para> |
| <programlisting>public static ExternalResourceDescription createSharedResourceDescription( |
| String aUrl, Class<? extends SharedResourceObject> 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> |
