Runtime

## org.eclipse.gmf.runtime.emf.clipboard.core
Class PasteChildOperation

    java.lang.Object
      org.eclipse.gmf.runtime.emf.clipboard.core.ClipboardOperation
          org.eclipse.gmf.runtime.emf.clipboard.core.BasePasteOperation
              org.eclipse.gmf.runtime.emf.clipboard.core.PasteChildOperation

Direct Known Subclasses:
  OverridePasteChildOperation, PostPasteChildOperation

public class PasteChildOperation
extends BasePasteOperation

An operation to paste a child object into a new target parent object.

Field Summary
`protected static java.lang.String` `COPY` Localized prefix to prepend onto element names to disambiguate them in resolving paste collisions.
`protected static PasteChildOperation[]` `EMPTY_ARRAY` A reusable empty array of paste child operations.

Fields inherited from class org.eclipse.gmf.runtime.emf.clipboard.core.BasePasteOperation
`PASTE`

Fields inherited from class org.eclipse.gmf.runtime.emf.clipboard.core.ClipboardOperation
`TOTAL_WORK, WORK_UNIT`

Constructor Summary
`protected` `PasteChildOperation(PasteChildOperation mainChildPasteProcess)` Initializes me as an override- or post-paste operation.
`` `PasteChildOperation(org.eclipse.gmf.runtime.emf.clipboard.core.internal.PasteIntoParentOperation parentPasteProcess, ObjectInfo childEObjectInfo)` Initializes me.

Method Summary
`protected boolean` `canBeReplaced(EObject eObject)` Queries whether the specified object that already exists in the target resource can be replaced by an element being pasted, in case of a collision that is resolved by replacement.
`protected EObject` `doPasteInto(EObject pasteIntoEObject)` Pastes my child object into the specified object.
`protected EObject` `doPasteInto(EObject pasteIntoEObject, EReference reference)` Pastes my child object into the specified containment reference of an object.
`protected EObject` `doPasteInto(PasteTarget pasteTarget)` Pastes my child object into the specified object.
`protected EObject` `doPasteInto(Resource pasteIntoResource)` Pastes my child object into the specified resource
`protected java.util.List` `getAlwaysCopyObjectPasteOperations()` Obtains a list of operations to paste the "copy always" objects related to the object that I am pasting.
`protected PasteChildOperation` `getAuxiliaryChildPasteProcess(ObjectInfo auxiliaryChildEObjectInfo)` Obtains the paste operation that pastes the auxiliary object indicated by the specified object info.
`protected ObjectInfo` `getChildObjectInfo()` Gets the object info meta-data for the object that I am pasting.
`protected EReference` `getContainmentFeature()` Gets the containment feature into which I would prefer to paste my child element into the parent.
`protected EObject` `getCopyParentEObject()` Gets the original parent of the object that I am pasting, if it was copied along with the child.
`protected ObjectInfo` `getCopyParentObjectInfo()` Gets the object meta-data for my copy object's parent, if it was serialized along with the child.
`EObject` `getEObject()` Retrieves the object that I am pasting from the deserialized clipboard string into the target parent object.
`protected EObject` `getEObject(java.lang.String objId)` Looks up an object in the resource to which we are pasting, by its ID.
`protected java.lang.String` `getEObjectID(EObject eObject)` Looks up the ID of an object in the resource to which we are pasting.
`protected EObject` `getLoadedDirectContainerEObject()` Obtains the direct container object, from the deserialized copied elements, of the object that I am pasting.
`protected EObject` `getLoadedEObject(java.lang.String objId)` Looks up an object deserialized from the clipboard string by its ID.
`protected java.lang.String` `getLoadedEObjectID(EObject eObject)` Looks up the ID of an object deserialized from the clipboard string.
`protected PasteChildOperation` `getMainChildPasteProcess()` Gets the child paste operation that I am overriding or extending, if I am an auxiliary paste operation.
`EObject` `getParentEObject()` Gets the target object into which we are pasting a child.
`org.eclipse.gmf.runtime.emf.clipboard.core.internal.PasteIntoParentOperation` `getParentPasteProcess()` Obtains the paste operation that created me to paste a child into the target parent element.
`XMLResource` `getParentResource()` Obtains the XML resource into which we are pasting.
`PasteTarget` `getParentTarget()` Gets the target object into which we are pasting a child.
`EReference` `getPasteContainmentFeature(EObject parentEObject)` Consults the clipboard support to get the best-match containment feature of the specified parent object to paste my child object into, according to the copied object's original containment feature.
`protected EObject` `getPastedDirectCopyParent()` After pasting has completed, obtains the pasted object corresponding to the specified originally copied object's parent.
`EObject` `getPastedElement()` After pasting is completed, obtains the element that I pasted.
`protected EObject` `getPastedEObject(EObject eObject)` After pasting has completed, obtains the pasted object corresponding to the specified originally copied object.
`PasteChildOperation` `getPostPasteOperation()` Gets an operation to be invoked after I have completed my pasting, to do some follow-up pasting.
`protected PasteTarget` `getSuitableParentUsingAncestry(java.lang.String preferredTypeName)` Finds some parent in the containment chain (ancestry) of the parent element into which I am pasting that my child element can be pasted into.
`protected boolean` `handleCollision(EReference reference, EObject object, EObject eObject, ObjectInfo eObjectInfo)` Handles the collision of an `eObject` that is to be pasted into the specified scalar reference, where it collides with the existing element.
`protected boolean` `handleCollision(EReference reference, java.util.List list, EObject eObject, ObjectInfo eObjectInfo)` Handles the collision of an `eObject` that is to be pasted into the specified values of a reference, where it collides with one or more of these existing elements.
`protected boolean` `hasCopyParent()` Queries whether the object that I am pasting had its parent object copied along with it, as an alternative element to try to paste when I can't be directly pasted into the target element.
`boolean` `isAuxiliaryOperation()` Queries whether I am an auxiliary operation.
`protected boolean` `isCopyAlways()` Queries whether the object that I am pasting was copied because it is always copied along with an element that was originally selected for copying.
`protected boolean` `isCopyParentDirectParent()` Queries whether my copy object's parent object that was copied along with it was a direct container or not.
`protected PasteChildOperation` `makeAuxiliaryChildPasteProcess(ObjectInfo auxiliaryChildEObjectInfo)` Constructs a paste operation to paste the auxiliary object indicated by its object info.
`protected void` `mergeEObjects(boolean weakMerge, EObject targetEObject, EObject eObject, ObjectInfo objectInfo)` Merges an elements to be pasted with an existing element that collides.
`protected java.util.List` `mergeLists(EReference reference, java.util.List targetObjectList, java.util.List objectList, ObjectInfo objectInfo)` Merges the elements to be pasted into a many containment reference with those objects already in that reference with which they collide.
`void` `paste()` Performs the paste operation.
`protected void` `setPastedElement(EObject pastedElement)` After pasting has completed, records the element that I have successfully (or not) pasted from the original copy.
`protected boolean` `shouldPasteAlwaysCopyObject(ObjectInfo alwaysCopyObjectInfo)` Queries whether we should paste the specified "copy always" object associated with the element we are pasting.

Methods inherited from class org.eclipse.gmf.runtime.emf.clipboard.core.BasePasteOperation

`addCriticalResolveFailure, addMergedElementEntry, addPastedElement, addPasteFailuresObject, getAllCriticalResolveFailuresSet, getAllMergedElementsMap, getAllPastedElementSet, getAllPasteFailuresObjectSet, getCriticalResolveFailuresSet, getLoadOptionsMap, getMergedElementsMap, getPastedElementSet, getPasteFailuresObjectSet, getResourceInfo, getSpawningPasteOperation, removeCriticalResolveFailure, throwCancelException`

Methods inherited from class org.eclipse.gmf.runtime.emf.clipboard.core.ClipboardOperation
`catchException, getClipboardOperationHelper, getProgressMonitor, isCancelled, throwCancelException, throwException`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### COPY

    protected static final java.lang.String COPY

  Localized prefix to prepend onto element names to disambiguate them in resolving paste collisions.

### EMPTY_ARRAY

    protected static final PasteChildOperation[] EMPTY_ARRAY

  A reusable empty array of paste child operations.

Constructor Detail

### PasteChildOperation

    public PasteChildOperation(org.eclipse.gmf.runtime.emf.clipboard.core.internal.PasteIntoParentOperation parentPasteProcess,
                               ObjectInfo childEObjectInfo)

  Initializes me.

Parameters:
  `parentPasteProcess` - my superordinate operation, that created me in order to paste one of its copied objects into its target parent object
  `childEObjectInfo` - the metadata for the child object to be pasted

### PasteChildOperation

    protected PasteChildOperation(PasteChildOperation mainChildPasteProcess)

  Initializes me as an override- or post-paste operation.

Parameters:
  `mainChildPasteProcess` - the paste-child process that I am overriding or extending

Method Detail

### getContainmentFeature

    protected EReference getContainmentFeature()

  Gets the containment feature into which I would prefer to paste my child element into the parent.

  Returns:
    the preferred containment feature to paste into

### getLoadedDirectContainerEObject

    protected EObject getLoadedDirectContainerEObject()

  Obtains the direct container object, from the deserialized copied elements, of the object that I am pasting.

  Returns:
    my object's direct container

### getParentPasteProcess

    public org.eclipse.gmf.runtime.emf.clipboard.core.internal.PasteIntoParentOperation getParentPasteProcess()

  Obtains the paste operation that created me to paste a child into the target parent element.

  Returns:
    my parent operation

### getAuxiliaryChildPasteProcess

    protected PasteChildOperation getAuxiliaryChildPasteProcess(ObjectInfo auxiliaryChildEObjectInfo)

  Obtains the paste operation that pastes the auxiliary object indicated by the specified object info.

  Parameters:
    `auxiliaryChildEObjectInfo` - the auxiliary object's info
  Returns:
    the paste operation that pastes the auxiliary object

### makeAuxiliaryChildPasteProcess

    protected PasteChildOperation makeAuxiliaryChildPasteProcess(ObjectInfo auxiliaryChildEObjectInfo)

  Constructs a paste operation to paste the auxiliary object indicated by its object info.

  Parameters:
    `auxiliaryChildEObjectInfo` - the auxiliary object's info
  Returns:
    the appropriate paste child operation

### getEObject

    public EObject getEObject()

  Retrieves the object that I am pasting from the deserialized clipboard string into the target parent object.

  Returns:
    the object that I am pasting

### getPastedElement

    public EObject getPastedElement()

  After pasting is completed, obtains the element that I pasted.

  Returns:
    the pasted element, or `null` if I did not succeed in pasting

### getLoadedEObject

    protected EObject getLoadedEObject(java.lang.String objId)

  Looks up an object deserialized from the clipboard string by its ID.

  Parameters:
    `objId` - the object ID to look up
  Returns:
    the corresponding object, or `null` if not found

### getLoadedEObjectID

    protected java.lang.String getLoadedEObjectID(EObject eObject)

  Looks up the ID of an object deserialized from the clipboard string.

  Parameters:
    `eObject` - the object whose ID we want to look up
  Returns:
    the corresponding ID, or `null` if not found

### hasCopyParent

    protected boolean hasCopyParent()

  Queries whether the object that I am pasting had its parent object copied along with it, as an alternative element to try to paste when I can't be directly pasted into the target element.

  Returns:
    whether my copy object was copied with its parent

### isCopyAlways

    protected boolean isCopyAlways()

  Queries whether the object that I am pasting was copied because it is always copied along with an element that was originally selected for copying.

  Returns:
    whether my copy object is copied because of a "copy always" rule

### getCopyParentEObject

    protected EObject getCopyParentEObject()

  Gets the original parent of the object that I am pasting, if it was copied along with the child.

  Returns:
    the copy parent, or `null` if it was not copied
  See Also:
    `PasteChildOperation.hasCopyParent()`

### getEObject

    protected EObject getEObject(java.lang.String objId)

  Looks up an object in the resource to which we are pasting, by its ID.

  Parameters:
    `objId` - the object ID to look up
  Returns:
    the corresponding object, or `null` if not found

### getEObjectID

    protected java.lang.String getEObjectID(EObject eObject)

  Looks up the ID of an object in the resource to which we are pasting.

  Parameters:
    `eObject` - the object to look up its ID
  Returns:
    the corresponding ID, or `null` if not found

### getSuitableParentUsingAncestry

    protected PasteTarget getSuitableParentUsingAncestry(java.lang.String preferredTypeName)

  Finds some parent in the containment chain (ancestry) of the parent element into which I am pasting that my child element can be pasted into.

  Parameters:
    `preferredTypeName` - the fully-qualified class name of the preferred element type to paste into
  Returns:
    the suitable parent, if found, otherwise `null`

### getPastedEObject

    protected EObject getPastedEObject(EObject eObject)

  After pasting has completed, obtains the pasted object corresponding to the specified originally copied object.

  Parameters:
    `eObject` - the originally copied object
  Returns:
    the corresponding pasted object, or `null` if the `eObject` was not successfully pasted

### getPastedDirectCopyParent

    protected EObject getPastedDirectCopyParent()

  After pasting has completed, obtains the pasted object corresponding to the specified originally copied object's parent.

  Returns:
    the corresponding pasted object, or `null` if the copy parent was not successfully pasted

### getParentEObject

    public EObject getParentEObject()

  Gets the target object into which we are pasting a child.

  Returns:
    the parent (target) object of the paste operation

### getParentTarget

    public PasteTarget getParentTarget()

  Gets the target object into which we are pasting a child.

  Returns:
    the parent (target) object of the paste operation

### getParentResource

    public XMLResource getParentResource()

  Obtains the XML resource into which we are pasting.

  Returns:
    the target resource

### getPostPasteOperation

    public PasteChildOperation getPostPasteOperation()

  Gets an operation to be invoked after I have completed my pasting, to do some follow-up pasting. `OverridePasteChildOperation`s can redefine this method to provide custom post-paste behaviour.

  IMPORTANT: This function must be invoked AFTER the paste() function has been called.

  Returns:
    an additional operation to do more pasting

### paste

    public void paste()
               throws java.lang.Exception

  Description copied from class: `BasePasteOperation`
  Performs the paste operation.

  Specified by:
    `paste` in class `BasePasteOperation`
  Throws:
    `java.lang.Exception` - if anything goes wrong in pasting

### doPasteInto

    protected EObject doPasteInto(EObject pasteIntoEObject)

  Pastes my child object into the specified object.

  Parameters:
    `pasteIntoEObject` - the object to paste into
  Returns:
    the newly pasted object, or `null` if the paste did not succeed

### doPasteInto

    protected EObject doPasteInto(PasteTarget pasteTarget)

  Pastes my child object into the specified object.

  Parameters:
    `pasteTarget` - the object to paste into
  Returns:
    the newly pasted object, or `null` if the paste did not succeed

### doPasteInto

    protected EObject doPasteInto(EObject pasteIntoEObject,
                                  EReference reference)

  Pastes my child object into the specified containment reference of an object.

  Parameters:
    `pasteIntoEObject` - the object to paste into
    `reference` - the containment reference to paste into
  Returns:
    the newly pasted object, or `null` if the paste did not succeed

### doPasteInto

    protected EObject doPasteInto(Resource pasteIntoResource)

  Pastes my child object into the specified resource

  Parameters:
    `pasteIntoResource` - the resource to paste into
  Returns:
    the newly pasted object, or `null` if the paste did not succeed

### getAlwaysCopyObjectPasteOperations

    protected java.util.List getAlwaysCopyObjectPasteOperations()

  Obtains a list of operations to paste the "copy always" objects related to the object that I am pasting. By default, these will be executed as a post-paste operation following me.

  Returns:
    the copy-always object paste operations (which may be empty)
  See Also:
    `PasteChildOperation.getPostPasteOperation()`

### shouldPasteAlwaysCopyObject

    protected boolean shouldPasteAlwaysCopyObject(ObjectInfo alwaysCopyObjectInfo)

  Queries whether we should paste the specified "copy always" object associated with the element we are pasting. This accounts for the possibility that the "copy always" object might collide with some element already in the target resource.

  Parameters:
    `alwaysCopyObjectInfo` - info indicating the "copy always" object
  Returns:
    `true` if the "copy always" object should be pasted; `false`, otherwise

### getPasteContainmentFeature

    public EReference getPasteContainmentFeature(EObject parentEObject)

  Consults the clipboard support to get the best-match containment feature of the specified parent object to paste my child object into, according to the copied object's original containment feature.

  Parameters:
    `parentEObject` - the parent to paste into
  Returns:
    the most appropriate containment feature for the child, or `null` if the parent cannot contain the child at all

### handleCollision

    protected boolean handleCollision(EReference reference,
                                      java.util.List list,
                                      EObject eObject,
                                      ObjectInfo eObjectInfo)

  Handles the collision of an `eObject` that is to be pasted into the specified values of a reference, where it collides with one or more of these existing elements. This may involve, among other things, renaming the object to be pasted in order to make its name unique.

  Parameters:
    `reference` - the many containment reference into which we want to paste the `eObject`
    `list` - the current value (list of `EObject`s) of the containment reference
    `eObject` - the object that we want to paste, which collides with one or more elements in the `list`
    `eObjectInfo` - the `eObject`'s object info meta-data
  Returns:
    `true` if the collision was resolved so that we can go ahead and paste the `eObject` as intended; false, otherwise

### handleCollision

    protected boolean handleCollision(EReference reference,
                                      EObject object,
                                      EObject eObject,
                                      ObjectInfo eObjectInfo)

  Handles the collision of an `eObject` that is to be pasted into the specified scalar reference, where it collides with the existing element.

  Parameters:
    `reference` - the scalar containment reference into which we want to paste the `eObject`
    `object` - the current value of the containment reference
    `eObject` - the object that we want to paste, which collides with one or more elements in the `list`
    `eObjectInfo` - the `eObject`'s object info meta-data
  Returns:
    `true` if the collision was resolved so that we can go ahead and paste the `eObject` as intended; false, otherwise

### mergeLists

    protected java.util.List mergeLists(EReference reference,
                                        java.util.List targetObjectList,
                                        java.util.List objectList,
                                        ObjectInfo objectInfo)

  Merges the elements to be pasted into a many containment reference with those objects already in that reference with which they collide. This is used in the resolution of collisions by merging.

  Parameters:
    `reference` - the many containment reference to merge objects into
    `targetObjectList` - the existing objects in the reference collection
    `objectList` - the objects that we need to merge into the targets
    `objectInfo` - object info
  Returns:
    the merged lists
  See Also:
    `PasteChildOperation.handleCollision(EReference, List, EObject, ObjectInfo)`, `PasteAction.MERGE`

### mergeEObjects

    protected void mergeEObjects(boolean weakMerge,
                                 EObject targetEObject,
                                 EObject eObject,
                                 ObjectInfo objectInfo)

  Merges an elements to be pasted with an existing element that collides.

  Parameters:
    `weakMerge` - `true` to perform a weak merge; `false` for a strong merge
    `targetEObject` - the existing object to merge into
    `eObject` - the object that we need to merge into the target
    `objectInfo` - the `eObject`'s object info
  See Also:
    `PasteChildOperation.handleCollision(EReference, List, EObject, ObjectInfo)`, `PasteChildOperation.handleCollision(EReference, EObject, EObject, ObjectInfo)`, `PasteAction.MERGE`

### getChildObjectInfo

    protected ObjectInfo getChildObjectInfo()

  Gets the object info meta-data for the object that I am pasting.

  Returns:
    my child object's meta-data

### getMainChildPasteProcess

    protected PasteChildOperation getMainChildPasteProcess()

  Gets the child paste operation that I am overriding or extending, if I am an auxiliary paste operation.

  Returns:
    my main child paste process, or `null` if none

### isAuxiliaryOperation

    public boolean isAuxiliaryOperation()

  Queries whether I am an auxiliary operation.

  Returns:
    `true` if I am an auxiliary paste operation; `false`, otherwise

### getCopyParentObjectInfo

    protected ObjectInfo getCopyParentObjectInfo()

  Gets the object meta-data for my copy object's parent, if it was serialized along with the child.

  Returns:
    my copy parent's object info, or `null` if none

### isCopyParentDirectParent

    protected boolean isCopyParentDirectParent()

  Queries whether my copy object's parent object that was copied along with it was a direct container or not.

  Returns:
    `true` if my copy object's parent was copied and was its direct container; `false`, otherwise

### setPastedElement

    protected void setPastedElement(EObject pastedElement)

  After pasting has completed, records the element that I have successfully (or not) pasted from the original copy.

  Parameters:
    `pastedElement` - the pasted element, or `null` if pasting failed

### canBeReplaced

    protected boolean canBeReplaced(EObject eObject)

  Queries whether the specified object that already exists in the target resource can be replaced by an element being pasted, in case of a collision that is resolved by replacement.

  Parameters:
    `eObject` - an object in the target model that might be replaced
  Returns:
    `true` if it can be replaced; `false`, otherwise
  See Also:
    `PasteAction.REPLACE`

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.