org.apache.uima.util

Class CasCopier

java.lang.Object

org.apache.uima.util.CasCopier

public class CasCopier
extends Object

Utility class for doing deep copies of FeatureStructures from one CAS to another. To handle cases where the source CAS has multiple references to the same FS, you can create one instance of CasCopier and use it to copy multiple FeatureStructures. The CasCopier will remember previously copied FeatureStructures, so if you later copy another FS that has a reference to a previously copied FS, it will not duplicate the multiply-referenced FS. This class makes use of CASImpl methods, but is only passed CAS objects, which may be CAS Wrappers. To make this more feasible, the implementors of CAS Wrappers need to implement the method getLowLevelCas() which should return a reference to the underlying CAS which can be successfully cast to a CASImpl. The source and target CASs must be separate CASs (that is, not two views of the same CAS), with one exception: If the CopyCasView API is being used, and the target View name is different from the source view name,

Constructor Summary

Constructors

Constructor and Description
CasCopier(CAS aSrcCas, CAS aDestCas) Creates a new CasCopier that can be used to copy FeatureStructures from one CAS to another.
CasCopier(CAS aSrcCas, CAS aDestCas, boolean lenient) Creates a new CasCopier that can be used to copy FeatureStructures from one CAS to another.

Method Summary

Modifier and Type	Method and Description
boolean	alreadyCopied(FeatureStructure aFS) Note: if lenient is in effect, this method will return false for FSs which are not copied because the target doesn't have that type.
boolean	alreadyCopied(int aFS) Note: if lenient is in effect, this method will return false for FSs which are not copied because the target doesn't have that type.
static void	copyCas(CAS aSrcCas, CAS aDestCas, boolean aCopySofa) Does a complete deep copy of one CAS into another CAS.
static void	copyCas(CAS aSrcCas, CAS aDestCas, boolean aCopySofa, boolean lenient) Does a complete deep copy of one CAS into another CAS.
void	copyCasView(CAS aSrcCasView, boolean aCopySofa) Does a deep copy of the contents of one CAS View into another CAS's same-named-view If the destination view already exists in the destination CAS, then it will be the target of the copy.
void	copyCasView(CAS aSrcCasView, CAS aTgtCasView, boolean aCopySofa) Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name.
void	copyCasView(CAS aSrcCasView, String aTgtCasViewName, boolean aCopySofa) Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name.
void	copyCasView(String aSrcCasViewName, boolean aCopySofa) Does a deep copy of the contents of one CAS View into another CAS's same-named-view If the destination view already exists in the destination CAS, then it will be the target of the copy.
void	copyCasView(String aSrcCasViewName, CAS aTgtCasView, boolean aCopySofa) Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name.
FeatureStructure	copyFs(FeatureStructure aFS) Copy 1 feature structure from the originalSrcCas to a new Cas.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CasCopier

public CasCopier(CAS aSrcCas,
                 CAS aDestCas)

Creates a new CasCopier that can be used to copy FeatureStructures from one CAS to another. Note that if you are merging data from multiple CASes, you must create a new CasCopier for each source CAS. Note: If the feature structure and/or feature is not defined in the type system of the destination CAS, the copy will fail (in other words, the lenient setting is false, by default).

Parameters:

aSrcCas - the CAS to copy from.

aDestCas - the CAS to copy into.

CasCopier

public CasCopier(CAS aSrcCas,
                 CAS aDestCas,
                 boolean lenient)

Creates a new CasCopier that can be used to copy FeatureStructures from one CAS to another. Note that if you are merging data from multiple CASes, you must create a new CasCopier for each source CAS. This version of the constructor supports a "lenient copy" option. When set, the CAS copy function will ignore (not attempt to copy) FSs and features not defined in the type system of the destination CAS, rather than throwing an exception.

Parameters:

aSrcCas - the CAS to copy from.

aDestCas - the CAS to copy into.

lenient - ignore FSs and features not defined in the type system of the destination CAS

Method Detail

copyCas

public static void copyCas(CAS aSrcCas,
                           CAS aDestCas,
                           boolean aCopySofa)

Does a complete deep copy of one CAS into another CAS. The contents of each view in the source CAS will be copied to the same-named view in the destination CAS. If the view does not already exist it will be created. All FeatureStructures that are indexed in a view in the source CAS will become indexed in the same-named view in the destination CAS. Note: If the feature structure and/or feature is not defined in the type system of the destination CAS, the copy will fail (in other words, the lenient setting is false, by default).

Parameters:

aSrcCas - the CAS to copy from

aDestCas - the CAS to copy to

aCopySofa - if true, the sofa data and mimeType of each view will be copied. If false they will not.

copyCas

public static void copyCas(CAS aSrcCas,
                           CAS aDestCas,
                           boolean aCopySofa,
                           boolean lenient)

Does a complete deep copy of one CAS into another CAS. The contents of each view in the source CAS will be copied to the same-named view in the destination CAS. If the view does not already exist it will be created. All FeatureStructures that are indexed in a view in the source CAS will become indexed in the same-named view in the destination CAS. This version of the method supports a "lenient copy" option. When set, the CAS copy function will ignore (not attempt to copy) FSs and features not defined in the type system of the destination CAS, rather than throwing an exception.

Parameters:

aSrcCas - the CAS to copy from

aDestCas - the CAS to copy to; must be a completely different CAS than the source (that is, not an alternative "view" of the source)

aCopySofa - if true, the sofa data and mimeType of each view will be copied. If false they will not.

lenient - ignore FSs and features not defined in the type system of the destination CAS

copyCasView

public void copyCasView(CAS aSrcCasView,
                        boolean aCopySofa)

Does a deep copy of the contents of one CAS View into another CAS's same-named-view If the destination view already exists in the destination CAS, then it will be the target of the copy. Otherwise, a new view will be created with that name and will become the target of the copy. All FeatureStructures (except for those dropped because the target type system doesn't have the needed type) that are indexed in the source CAS view will become indexed in the target view. Cross-view references may result in creating additional views in the destination CAS; for these views, any Sofa data in the source is *not* copied.

Parameters:

aSrcCasView - the CAS to copy from. This must be a view in the src Cas set by the constructor

aCopySofa - if true, the sofa data and mimeType will be copied. If false they will not.

copyCasView

public void copyCasView(String aSrcCasViewName,
                        boolean aCopySofa)

Does a deep copy of the contents of one CAS View into another CAS's same-named-view If the destination view already exists in the destination CAS, then it will be the target of the copy. Otherwise, a new view will be created with that name and will become the target of the copy. All FeatureStructures (except for those dropped because the target type system doesn't have the needed type) that are indexed in the source CAS view will become indexed in the target view. Cross-view references may result in creating additional views in the destination CAS; for these views, any Sofa data in the source is *not* copied. Any views created because of cross-view references will have the same view name as in the source.

Parameters:

aSrcCasViewName - the name of the view in the source CAS to copy from

aCopySofa - if true, the sofa data and mimeType will be copied. If false they will not.

copyCasView

public void copyCasView(CAS aSrcCasView,
                        String aTgtCasViewName,
                        boolean aCopySofa)

Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name. If the destination view already exists in the destination CAS, then it will be the target of the copy. Otherwise, a new view will be created with that name and will become the target of the copy. All FeatureStructures (except for those dropped because the target type system doesn't have the needed type) that are indexed in the source CAS view will become indexed in the target view. Cross-view references may result in creating additional views in the destination CAS; for these views, any Sofa data in the source is *not* copied. Any views created because of cross-view references will have the same view name as in the source.

Parameters:

aSrcCasView - The view in the source to copy from

aTgtCasViewName - The name of the view in the destination CAS to copy into

aCopySofa - if true, the sofa data and mimeType will be copied. If false they will not.

copyCasView

public void copyCasView(String aSrcCasViewName,
                        CAS aTgtCasView,
                        boolean aCopySofa)

Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name. All FeatureStructures (except for those dropped because the target type system doesn't have the needed type) that are indexed in the source CAS view will become indexed in the target view. Cross-view references may result in creating additional views in the destination CAS; for these views, any Sofa data in the source is *not* copied. Any views created because of cross-view references will have the same view name as in the source.

Parameters:

aSrcCasViewName - The name of the view in the Source CAS to copy from

aTgtCasView - The view in the destination CAS to copy into

aCopySofa - if true, the sofa data and mimeType will be copied. If false they will not.

copyCasView

public void copyCasView(CAS aSrcCasView,
                        CAS aTgtCasView,
                        boolean aCopySofa)

Does a deep copy of the contents of one CAS View into another CAS view, with a possibly different name. All FeatureStructures (except for those dropped because the target type system doesn't have the needed type) that are indexed in the source CAS view will become indexed in the target view. Cross-view references may result in creating additional views in the destination CAS; for these views, any Sofa data in the source is *not* copied. Any views created because of cross-view references will have the same view name as in the source. If the source and target views are both views of the same CAS, then Feature Structures in the view are effectively "cloned", with the following change: Subtypes of AnnotationBase in the source whose sofaRef is for the source View are cloned with their sofaRefs changed to the new targetView.

Parameters:

aSrcCasView - the CAS view to copy from. This must be a view of the srcCas set in the constructor

aTgtCasView - the CAS view to copy to. This must be a view of the tgtCas set in the constructor

aCopySofa - if true, the sofa data and mimeType will be copied. If false they will not. If true and the sofa data is already set in the target, will throw CASRuntimeException

copyFs

public FeatureStructure copyFs(FeatureStructure aFS)

Copy 1 feature structure from the originalSrcCas to a new Cas. No indexing of the new FS is done. If the FS has been copied previously (using this CasCopier instance) the same identical copy will be returned rather than making another copy. View handling: ignores the view of the targetCas

Parameters:

aFS - the Feature Structure to copy

Returns:

a deep copy of the Feature Structure - any referred to FSs will also be copied.

alreadyCopied

public boolean alreadyCopied(FeatureStructure aFS)

Note: if lenient is in effect, this method will return false for FSs which are not copied because the target doesn't have that type. It also returns false for sofa FSs and the documentAnnotation FS.

Parameters:

aFS - a feature structure

Returns:

true if the given FS has already been copied using this CasCopier.

alreadyCopied

public boolean alreadyCopied(int aFS)

Note: if lenient is in effect, this method will return false for FSs which are not copied because the target doesn't have that type. It also returns false for sofa FSs and the documentAnnotation FS.

Parameters:

aFS - a feature structure

Returns:

true if the given FS has already been copied using this CasCopier.