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