uimafit-doc/src/main/asciidoc/tools.uimafit.migration.adoc - uima-uimafit - Git at Google

 // 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 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.

 == Legacy support module

 The compatibility layer should allow you to migrate to uimaFIT without breaking anything.
 You should then be able to gradually change the codebase to be compatible with uimaFIT .
 As far as my tests go, uimaFIT 1.x and can coexist peacefully on the classpath (and indeed both need to be on the classpath in order to use the legacy support module).

 To enable the legacy support, make sure that you have a dependency on uimaFIT 1.x and then just add a dependency on the legacy module:

 [source]
 ----
 <dependency>
   <groupId>org.uimafit</groupId>
   <artifactId>uimafit</artifactId>
   <version>1.4.0</version>
 </dependency>
 <dependency>
   <groupId>org.apache.uima</groupId>
   <artifactId>uimafit-legacy-support</artifactId>
   <version></version>
 </dependency>
 ----

 uimaFIT automatically detects the presence of the legacy module and uses it - no additional configuration is necessary.

 The following bash script may help to partially automatize the source code migration process.
 Please observe that it does not cover all of the necessary changes!

 [NOTE]
 ====
 The script recursively changes all files under the current working directory! Make sure you are in the right directory before running it! _Use the script at your own
       risk!_
 ====

 [source,bash]
 ----
 #!/bin/sh

 ############################################
 # MAKE SURE TO BACKUP YOUR FILES FIRST!
 # SCRIPT RECURSIVELY CHANGES ALL JAVA FILES!
 # USE AT YOUR OWN RISK!
 ############################################

 # Change of package names
 find . -name '*.java' -print |
 xargs perl -p -i -e 's/org.uimafit/org.apache.uima.fit/g'

 find . -name '*.java' -print |
 xargs perl -p -i -e 's/org.uimafit.component.xwriter.CASDumpWriter/\
 org.apache.uima.fit.component.CasDumpWriter/g'

 # AnalysisEngineFactory
 find . -name '*.java' -print |
 xargs perl -p -i -e 's/createAggregate/createEngine/g'

 find . -name '*.java' -print |
 xargs perl -p -i -e 's/createPrimitive/createEngine/g'

 find . -name '*.java' -print |
 xargs perl -p -i -e 's/createAnalysisEngine/createEngine/g'

 # Readers
 find . -name '*.java' -print |
 xargs perl -p -i -e 's/createDescription/createReaderDescription/g'

 find . -name '*.java' -print |
 xargs perl -p -i -e 's/createCollectionReader/createReader/g'
 ----
	// 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 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.

	== Legacy support module

	The compatibility layer should allow you to migrate to uimaFIT without breaking anything.
	You should then be able to gradually change the codebase to be compatible with uimaFIT .
	As far as my tests go, uimaFIT 1.x and can coexist peacefully on the classpath (and indeed both need to be on the classpath in order to use the legacy support module).

	To enable the legacy support, make sure that you have a dependency on uimaFIT 1.x and then just add a dependency on the legacy module:

	[source]
	----
	<dependency>
	<groupId>org.uimafit</groupId>
	<artifactId>uimafit</artifactId>
	<version>1.4.0</version>
	</dependency>
	<dependency>
	<groupId>org.apache.uima</groupId>
	<artifactId>uimafit-legacy-support</artifactId>
	<version></version>
	</dependency>
	----

	uimaFIT automatically detects the presence of the legacy module and uses it - no additional configuration is necessary.

	The following bash script may help to partially automatize the source code migration process.
	Please observe that it does not cover all of the necessary changes!

	[NOTE]
	====
	The script recursively changes all files under the current working directory! Make sure you are in the right directory before running it! _Use the script at your own
	risk!_
	====

	[source,bash]
	----
	#!/bin/sh

	############################################
	# MAKE SURE TO BACKUP YOUR FILES FIRST!
	# SCRIPT RECURSIVELY CHANGES ALL JAVA FILES!
	# USE AT YOUR OWN RISK!
	############################################

	# Change of package names
	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/org.uimafit/org.apache.uima.fit/g'

	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/org.uimafit.component.xwriter.CASDumpWriter/\
	org.apache.uima.fit.component.CasDumpWriter/g'

	# AnalysisEngineFactory
	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/createAggregate/createEngine/g'

	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/createPrimitive/createEngine/g'

	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/createAnalysisEngine/createEngine/g'

	# Readers
	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/createDescription/createReaderDescription/g'

	find . -name '*.java' -print \|
	xargs perl -p -i -e 's/createCollectionReader/createReader/g'
	----