Runtime

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

    java.lang.Object
      org.eclipse.gmf.runtime.emf.clipboard.core.ClipboardSupportUtil

public final class ClipboardSupportUtil
extends java.lang.Object

Utilities to assist the implementation of `IClipboardSupport`s by plug-ins extending the `clipboardSupport` extension point.

Field Summary
`static int` `NONE` Index in an array or list indicating absence of the element sought.

Method Summary
`static EObject` `appendEObject(Resource resource, EObject referencedObject)` Appends a resource's contents with an additional reference.
`static EObject` `appendEObjectAt(EObject eObject, EReference reference, EObject referencedObject)` Appends an object's many reference with an additional reference.
`static java.util.List` `appendEObjectListAt(EObject eObject, EReference reference, java.util.List referencedObjects)` Appends an object's many reference with a list of additional references.
`static boolean` `containsAny(java.util.Collection collection1, java.util.Collection collection2)` Queries whether two collections intersect.
`static void` `destroyEObject(EObject eObject, EReference reference)` Clears an object's scalar reference.
`static void` `destroyEObjectInCollection(EObject eObject, EReference reference, EObject referencedObject)` Removes an element from an object's many reference.
`static void` `destroyEObjectInResource(EObject referencedObject)` Removes an element from a resource.
`static java.util.Collection` `getCopyElements(java.util.Collection elements)` Removes from a collection of `elements` any elements that should not be copied.
`static EReference` `getPasteContainmentFeature(EObject parentEObject, EObject eObject, EReference originalReference)` Obtains the containment feature of a parent element into which a child should be pasted, that best matches the child's original containment feature.
`static boolean` `hasNameCollision(java.util.Collection list, EObject eObject)` Queries whether an object is nameable and have the same name (ignoring case) as any element in a `list`.
`static boolean` `hasNameCollision(EObject eObject1, EObject eObject2)` Queries whether two elements are both nameable and have the same name (ignoring case).
`static boolean` `isChild(EObject eParent, EObject eObject)` Queries whether the specified `eObject` is contained within another.
`static boolean` `isOkToAppendEObjectAt(EObject eObject, EReference reference, EObject referencedObject)` Queries whether a many reference may be appended with an new `EObject`.
`static boolean` `isOkToDestroyEObject(EObject eObject, EReference reference)` Queries whether a scalar reference may be cleared.
`static boolean` `isOkToDestroyEObjectInCollection(EObject eObject, EReference reference)` Queries whether a many reference may have a reference removed from it.
`static boolean` `isOkToSetEAttribute(EObject eObject, EAttribute attribute, java.lang.Object value)` Queries whether an attribute may be set to the specified new value.
`static boolean` `isOkToSetEList(EObject eObject, EReference reference)` Queries whether a many reference may be replaced with an entirely new list of `EObject`s.
`static boolean` `isOkToSetEObject(EObject eObject, EReference reference, EObject referencedObject)` Queries whether a scalar reference may be set to an new `EObject`.
`static void` `rename(java.util.Collection list, EObject eObject, java.lang.String prefix)` Given an object that has a name collision with one or more elements in a `list`, renames it to have a unique name.
`static EObject` `resolve(EObject proxy, java.util.Map idToEObjectMap)` Resolves a `proxy`, using the specified ID map.
`static EObject` `resolve(EObject proxy, XMLResource resource)` Resolves a `proxy`, using the specified resource.
`static void` `sendCreateEvent(EObject eObject)` Broadcasts a creatio notification for a new `EObject` via the appropriate clipboard support utility, if the metamodel support such notifications.
`static void` `sendCreateEvent(java.util.List eObjects)` Broadcasts creation notifications for a list of new `EObject`s via the appropriate clipboard support utility, if the metamodel support such notifications.
`static void` `setEAttribute(EObject eObject, EAttribute attribute, java.lang.Object value)` Replaces an object's attribute with an new value.
`static EObject` `setEObject(EObject eObject, EReference reference, EObject referencedObject)` Replaces an object's scalar reference with an new element.
`static java.util.List` `setEObjectList(EObject eObject, EReference reference, java.util.List referencedObjects)` Replaces an object's many reference with an entirely new list of references.

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

Field Detail

### NONE

    public static final int NONE

  Index in an array or list indicating absence of the element sought.

  See Also:
    Constant Field Values

Method Detail

### getCopyElements

    public static java.util.Collection getCopyElements(java.util.Collection elements)

  Removes from a collection of `elements` any elements that should not be copied. These are those that have containers that are already in the `elements` collection.

  Parameters:
    `elements` - the collection of elements to be whittled down to those that should be copied. Note that this collection is modified in place
  Returns:
    the `elements` collection, again

### setEObjectList

    public static java.util.List setEObjectList(EObject eObject,
                                                EReference reference,
                                                java.util.List referencedObjects)

  Replaces an object's many reference with an entirely new list of references. Does nothing if the `reference` specified is not settable.

  Parameters:
    `eObject` - the element owning the reference to be set
    `reference` - the many reference to be set
    `referencedObjects` - the new value of the reference; must be an `EList` of `EObject`s
  Returns:
    the `referencedObjects`
  See Also:
    `ClipboardSupportUtil.isOkToSetEList(EObject, EReference)`

### isOkToSetEList

    public static boolean isOkToSetEList(EObject eObject,
                                         EReference reference)

  Queries whether a many reference may be replaced with an entirely new list of `EObject`s.

  Parameters:
    `eObject` - the owner of the `reference`
    `reference` - a many reference to query whether it is settable
  Returns:
    `true` if the `reference` is changeable and is not derived; `false`, otherwise

### appendEObjectListAt

    public static java.util.List appendEObjectListAt(EObject eObject,
                                                     EReference reference,
                                                     java.util.List referencedObjects)

  Appends an object's many reference with a list of additional references.

  Parameters:
    `eObject` - the element owning the reference list to be appended
    `reference` - the many reference to be appended
    `referencedObjects` - `EObject`s to append to the list
  Returns:
    those of the `referencedObjects` that were successfully appended
  See Also:
    `ClipboardSupportUtil.appendEObjectAt(EObject, EReference, EObject)`

### appendEObjectAt

    public static EObject appendEObjectAt(EObject eObject,
                                          EReference reference,
                                          EObject referencedObject)

  Appends an object's many reference with an additional reference. Has no effect if this `reference` cannot be appended.

  Parameters:
    `eObject` - the element owning the reference list to be appended
    `reference` - the many reference to be appended
    `referencedObject` - an object to append to the list
  Returns:
    `referencedObject` if it was successfully appended to the reference; `null`, otherwise
  See Also:
    `ClipboardSupportUtil.appendEObjectAt(EObject, EReference, EObject)`, `ClipboardSupportUtil.isOkToAppendEObjectAt(EObject, EReference, EObject)`

### appendEObject

    public static EObject appendEObject(Resource resource,
                                        EObject referencedObject)

  Appends a resource's contents with an additional reference.

  Parameters:
    `resource` - the resource
    `referencedObject` - an object to append to the list
  Returns:
    `referencedObject` if it was successfully appended to the resource; `null`, otherwise

### setEObject

    public static EObject setEObject(EObject eObject,
                                     EReference reference,
                                     EObject referencedObject)

  Replaces an object's scalar reference with an new element. Does nothing if the `reference` specified is not settable.

  Parameters:
    `eObject` - the element owning the reference to be set
    `reference` - the scalar reference to be set
    `referencedObject` - the new value of the reference
  Returns:
    the `referencedObjects`
  See Also:
    `ClipboardSupportUtil.isOkToSetEObject(EObject, EReference, EObject)`

### setEAttribute

    public static void setEAttribute(EObject eObject,
                                     EAttribute attribute,
                                     java.lang.Object value)

  Replaces an object's attribute with an new value. Does nothing if the `attribute` specified is not settable.

  Parameters:
    `eObject` - the element owning the attribute to be set
    `attribute` - the attribute to be set
    `value` - the new value of the attribute
  See Also:
    `ClipboardSupportUtil.isOkToSetEAttribute(EObject, EAttribute, Object)`

### sendCreateEvent

    public static void sendCreateEvent(EObject eObject)

  Broadcasts a creatio notification for a new `EObject` via the appropriate clipboard support utility, if the metamodel support such notifications.

  Parameters:
    `eObject` - a newly created `EObject`
  See Also:
    `IClipboardSupport.sendCreateNotification(EObject)`

### sendCreateEvent

    public static void sendCreateEvent(java.util.List eObjects)

  Broadcasts creation notifications for a list of new `EObject`s via the appropriate clipboard support utility, if the metamodel support such notifications.

  Parameters:
    `eObjects` - a list of newly created `EObject`s
  See Also:
    `ClipboardSupportUtil.sendCreateEvent(EObject)`

### isOkToSetEAttribute

    public static boolean isOkToSetEAttribute(EObject eObject,
                                              EAttribute attribute,
                                              java.lang.Object value)

  Queries whether an attribute may be set to the specified new value.

  Parameters:
    `eObject` - the owner of the `attribute`
    `attribute` - an attribute to query whether it is settable
    `value` - the proposed new value of the `attribute`
  Returns:
    `true` if the `attribute` is changeable and the `value` is not `null`; `false`, otherwise

### destroyEObject

    public static void destroyEObject(EObject eObject,
                                      EReference reference)

  Clears an object's scalar reference. Has no effect if this `reference` cannot be cleared.

  Parameters:
    `eObject` - the element owning the reference to be cleared
    `reference` - the scalar reference to be cleared
  See Also:
    `ClipboardSupportUtil.isOkToDestroyEObject(EObject, EReference)`

### destroyEObjectInCollection

    public static void destroyEObjectInCollection(EObject eObject,
                                                  EReference reference,
                                                  EObject referencedObject)

  Removes an element from an object's many reference. Has no effect if this `reference` cannot be removed.

  Parameters:
    `eObject` - the element owning the reference list to be reduced
    `reference` - the many reference to be reduced
    `referencedObject` - an object to remove from the list
  See Also:
    `ClipboardSupportUtil.isOkToDestroyEObjectInCollection(EObject, EReference)`

### destroyEObjectInResource

    public static void destroyEObjectInResource(EObject referencedObject)

  Removes an element from a resource.

  Parameters:
    `referencedObject` - an object to remove from the resource

### isOkToAppendEObjectAt

    public static boolean isOkToAppendEObjectAt(EObject eObject,
                                                EReference reference,
                                                EObject referencedObject)

  Queries whether a many reference may be appended with an new `EObject`.

  Parameters:
    `eObject` - the owner of the `reference`
    `reference` - a many reference to query whether it is appendable
    `referencedObject` - an object that is proposed to be appended to the `reference`
  Returns:
    `true` if the `reference` is changeable and is not derived, and does not already contain the `referencedObject` or appending it would not violate the `reference`'s declared upper bound; `false`, otherwise

### isOkToSetEObject

    public static boolean isOkToSetEObject(EObject eObject,
                                           EReference reference,
                                           EObject referencedObject)

  Queries whether a scalar reference may be set to an new `EObject`.

  Parameters:
    `eObject` - the owner of the `reference`
    `reference` - a scalar reference to query whether it is settable
    `referencedObject` - an object that is proposed to be assigned to the `reference`
  Returns:
    `true` if the `reference` is changeable and is not derived, and does not already contain the `referencedObject` or the `referencedObject` is `null`; `false`, otherwise

### isOkToDestroyEObject

    public static boolean isOkToDestroyEObject(EObject eObject,
                                               EReference reference)

  Queries whether a scalar reference may be cleared.

  Parameters:
    `eObject` - the owner of the `reference`
    `reference` - a scalar reference to query whether it is clearable
  Returns:
    `true` if the `reference` is changeable and its value is not already `null`; `false`, otherwise

### isOkToDestroyEObjectInCollection

    public static boolean isOkToDestroyEObjectInCollection(EObject eObject,
                                                           EReference reference)

  Queries whether a many reference may have a reference removed from it.

  Parameters:
    `eObject` - the owner of the `reference`
    `reference` - a many reference to query whether it is removable
  Returns:
    `true` if the `reference` is changeable and is not derived, and removing an element would not violate its declared lower bound; `false`, otherwise

### isChild

    public static boolean isChild(EObject eParent,
                                  EObject eObject)

  Queries whether the specified `eObject` is contained within another. This differs from the `EcoreUtil.isAncestor(org.eclipse.emf.ecore.EObject, org.eclipse.emf.ecore.EObject)` method in checking for equality rather than identity.

  Parameters:
    `eParent` - an element
    `eObject` - an element to see whether it is contained in the `eParent`
  Returns:
    `true` if the `eObject` is contained within an element equal to the `eParent`; `false`, otherwise

### hasNameCollision

    public static boolean hasNameCollision(EObject eObject1,
                                           EObject eObject2)

  Queries whether two elements are both nameable and have the same name (ignoring case).

  Parameters:
    `eObject1` - an object
    `eObject2` - another object
  Returns:
    `true` if both objects are nameable and have the same name (ignoring case); `false`, otherwise
  See Also:
    `IClipboardSupport.isNameable(EObject)`

### hasNameCollision

    public static boolean hasNameCollision(java.util.Collection list,
                                           EObject eObject)

  Queries whether an object is nameable and have the same name (ignoring case) as any element in a `list`.

  Parameters:
    `list` - a ist of objects
    `eObject` - another object
  Returns:
    `true` if the `eObject`is nameable and has the same name (ignoring case) as any object in the `list`; `false`, otherwise
  See Also:
    `IClipboardSupport.isNameable(EObject)`

### rename

    public static void rename(java.util.Collection list,
                              EObject eObject,
                              java.lang.String prefix)

  Given an object that has a name collision with one or more elements in a `list`, renames it to have a unique name.

  Parameters:
    `list` - a list of objects
    `eObject` - another object whose name collides with the `list`
    `prefix` - the prefix to append; it will be modified by '_1', '_2', etc. as necessary
  See Also:
    `ClipboardSupportUtil.hasNameCollision(Collection, EObject)`

### containsAny

    public static boolean containsAny(java.util.Collection collection1,
                                      java.util.Collection collection2)

  Queries whether two collections intersect.

  Parameters:
    `collection1` - a collection
    `collection2` - another
  Returns:
    `true` if they have any elements in common; `false`, otherwise

### resolve

    public static EObject resolve(EObject proxy,
                                  java.util.Map idToEObjectMap)

  Resolves a `proxy`, using the specified ID map. If a proxy resolves to another proxy, then this procedure repeats until either a non-proxy is found or it is not resolved.

  Parameters:
    `proxy` - a proxy
    `idToEObjectMap` - a mapping of element ID strings to `EObject`s
  Returns:
    a resolved element, or a proxy if it could not be resolved. In either case, the result may be different than the original `proxy` (this is different from the behaviour of the `EcoreUtil.resolve(org.eclipse.emf.ecore.EObject, org.eclipse.emf.ecore.EObject)` method

### resolve

    public static EObject resolve(EObject proxy,
                                  XMLResource resource)

  Resolves a `proxy`, using the specified resource. If a proxy resolves to another proxy, then this procedure repeats until either a non-proxy is found or it is not resolved.

  Parameters:
    `proxy` - a proxy
    `resource` - the resource containing a mapping of element ID strings to `EObject`s
  Returns:
    a resolved element, or a proxy if it could not be resolved. In either case, the result may be different than the original `proxy` (this is different from the behaviour of the `EcoreUtil.resolve(org.eclipse.emf.ecore.EObject, org.eclipse.emf.ecore.EObject)` method

### getPasteContainmentFeature

    public static EReference getPasteContainmentFeature(EObject parentEObject,
                                                        EObject eObject,
                                                        EReference originalReference)

  Obtains the containment feature of a parent element into which a child should be pasted, that best matches the child's original containment feature.

  Parameters:
    `parentEObject` - the target element into which a child is to be pasted
    `eObject` - the child element to be pasted into the parent
    `originalReference` - the child's original containment reference
  Returns:
    the best-match containment reference, or `null` if child `eObject` simply cannot be contained by the `parentEObject`

Runtime

Guidelines for using Eclipse APIs.

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