/******************************************************************************
 * Copyright (c) 2002, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    IBM Corporation - initial API and implementation 
 ****************************************************************************/

package org.eclipse.gmf.runtime.emf.clipboard.core;

import java.util.Collection;
import java.util.Map;
import java.util.Set;

import org.eclipse.emf.ecore.EClass;
import org.eclipse.emf.ecore.EObject;
import org.eclipse.emf.ecore.EReference;
import org.eclipse.emf.ecore.EStructuralFeature;
import org.eclipse.emf.ecore.xmi.XMLResource;


/**
 * An interface to be implemented by EMF metamodel providers to inject
 * metamodel-specific semantics into copy/paste operations.
 * Basically it has hints (e.g., what to do when pasted elements collide, what
 * related elements should always be copied together, etc.) that helps the
 * framework to make decisions.  For maximal flexibility, it is even possible
 * to override the paste operstion altogether.
 * <p>
 * This interface is intended to be implemented by plug-ins on the
 * <tt>clipboardSupport</tt> extension point.
 * See the {@link AbstractClipboardSupport} for a convenient superclass for
 * your implementation.
 * </p>
 * 
 * @see AbstractClipboardSupport
 * 
 * @author Yasser Lulu
 */
public interface IClipboardSupport {

    /**
     * Queries what to do when a paste collision occurs on instances of a
     * particular metaclass.
     * 
     * @param eClass the metaclass in question
     * @return one of the enumerated paste actions
     */
    PasteAction getPasteCollisionAction(EClass eClass);

    /**
     * Queries whether a feature supports a particular paste option.
     * 
     * @param context and object being copied or pasted
     * @param eStructuralFeature a feature of the <code>contextEObject</code>
     * @param pasteOption the paste option to query
     * 
     * @return boolean whether the paste option is supported on this feature
     */
    boolean hasPasteOption(EObject context,
            EStructuralFeature eStructuralFeature, PasteOption pasteOption);

    /**
     * Queries whether a reference needs to be copied even though the referenced
     * element was not specifically included in the copy request.  It is
     * recommended, though not required, that in general:
     * <ul>
     *   <li>containment references should always be copied</li>
     *   <li>transient or derived references should not be copied</li>
     * </ul>
     * 
     * @param context an object being copied that owns the reference
     * @param eReference the reference being to query
     * @param value the object(s) referenced by the <code>eReference</code>.
     *     It is either an {@link EObject} or a collection of
     *     <code>EObject</code>s, according to the multiplicity of the reference
     * 
     * @return boolean whether the <code>value</code> must also be copied
     */
    boolean isCopyAlways(EObject context, EReference eReference, Object value);

    /**
     * Queries whether it is necessary to completely override the default paste
     * behaviour for pasting the specified (contained) child object into its
     * parent.
     * 
     * @param parentElement the target element into which a child is to be pasted
     * @param childEObject the child element to be pasted
     * 
     * @return boolean <code>true</code> if we want to completely override the
     *     paste operation for this child; <code>false</code>, otherwise
     */
    boolean shouldOverrideChildPasteOperation(EObject parentElement,
            EObject childEObject);

    /**
     * Queries whether it is necessary to completely override the default copy
     * behaviour for copying the specified objects.
     * 
     * @param eObjects a collection of {@link EObject}s to be pasted
     * @param hintMap the copy hints provided by the client of the
     *     current copy operation
     * 
     * @return boolean <code>true</code> if we want to completely override the
     *     copy operation for these objects; <code>false</code>, otherwise
     */

    boolean shouldOverrideCopyOperation(Collection eObjects, Map hintMap);

    /**
     * Obtains an override for the specified paste operation.  This method is
     * called immediately after
     * {@link #shouldOverrideChildPasteOperation(EObject, EObject)}, and then
     * only if the latter returned <code>true</code>.
     * 
     * @param overriddenChildPasteOperation the paste operation to override
     * @return the overriding paste operation, or <code>null</code> if it is not
     *      appropriate to override (only in the case that
     *      <code>shouldOverrideChildPasteOperation()</code> was <code>false</code>)
     * 
     * @see #shouldOverrideChildPasteOperation(EObject, EObject)
     */
    OverridePasteChildOperation getOverrideChildPasteOperation(
            PasteChildOperation overriddenChildPasteOperation);

    /**
     * Obtains an override for the specified copy operation.  This method is
     * called immediately after
     * {@link #shouldOverrideCopyOperation(Collection, Map)}, and then
     * only if the latter returned <code>true</code>.
     * 
     * @param overriddenCopyOperation the copy operation to override
     * @return the overriding copy operation, or <code>null</code> if it is not
     *      appropriate to override (only in the case that
     *      <code>shouldOverrideCopyOperation()</code> was <code>false</code>)
     * 
     * @see #shouldOverrideChildPasteOperation(EObject, EObject)
     */
    OverrideCopyOperation getOverrideCopyOperation(
            CopyOperation overriddenCopyOperation);

    /**
     * Queries whether any of a set of {@link EObject}s, or any objects
     * contained in their sub-trees,
     * should be excluded altogether from the copy operation.  These objects
     * will not be copied.  It is up to the receiver to explicitly search the
     * <code>eObjects</code> recursively for exclusions.
     * 
     * @param eObjects the objects considered for copying
     * @return collection of object that we should not copy, or empty if none
     */
    Collection getExcludedCopyObjects(Set eObjects);
    
    /**
     * Obtains the resource containing an <code>eObject</code> or, if the
     * <code>eObject</code> is to be copied but is not attached to a resource,
     * the resource containing some related element that the detached
     * <code>eObject</code> would otherwise have been in.
     * 
     * @param eObject the object for which we need the associated resource
     * @return the containing resource or, if the <code>eObject</code> is
     *     detached, some resource from which it is reachable via some
     *     other attached object
     */
    XMLResource getResource(EObject eObject);
    
    /**
     * Queries whether an <code>eObject</code> should have a reference to the
     * corresponding original element save along with a record of the original
     * containment feature.  All original top-level copy objects must have
     * this information saved.  As for their children (recursively), it is
     * optional.
     * 
     * @param eObject the eObject to query whether the containment feature
     *     should be saved
     * @return whether that feature information should be saved
     */
    boolean shouldSaveContainmentFeature(EObject eObject);
    
    /**
     *Performs what is necessary by the target paste model for the newly pasted elements
     *This because we disable the semantic procedures, and they used to handle migration
     *of profiles. now this function will end up doing that.
     * 
     * @param pastedEObjects the pasted objects to process     
     */
    void performPostPasteProcessing(Set pastedEObjects);
    
    /**
     * Queries whether an <code>eObject</code>'s metamodel supports the concept
     * of "naming" the <code>eObject</code>.  The "name" of an element may be
     * assigned to copies with an adornment (e.g., "Copy of " as done by a
     * certain well-known file system).
     * 
     * @param eObject an <code>EObject</code>
     * @return whether the <code>eObject</code> supports a "name" of some kind
     * 
     * @see #getName(EObject)
     * @see #setName(EObject, String)
     */
    boolean isNameable(EObject eObject);
    
    /**
     * Obtains the "name" of an element, if the metamodel supports the
     * concept of naming elements and this <code>eObject</code> has a name.
     * 
     * @param eObject an element
     * @return the element's "name" if it has any, or <code>null</code> if not
     * 
     * @see #isNameable(EObject)
     */
    String getName(EObject eObject);
    
    /**
     * Sets the "name" of an element, if the metamodel supports the
     * concept of naming elements and this <code>eObject</code> is nameable.
     * 
     * @param eObject an element
     * @param name the element's new "name", or <code>null</code> to clear it
     * 
     * @throws IllegalArgumentException if the <code>eObject</code> is not
     *      nameable
     * 
     * @see #isNameable(EObject)
     */
    void setName(EObject eObject, String name);
    
    /**
     * Destroys an <code>eObject</code>, to ensure that it no longer exists in
     * its containing resource.  At a minimum, this method must remove the
     * <code>eObject</code> from its container.  It may also do more, such as
     * cleaning up references to the <code>eObject</code>.
     * 
     * @param eObject the object to be destroyed
     */
    void destroy(EObject eObject);
    
    /**
     * Sends a notification that an <code>eObject</code> was created in its
     * host editing domain.  This is an optional operation, for those
     * applications that support the "create" notification type that is
     * currently deprecated in EMF.
     * 
     * @param eObject an object newly created in the editing domain
     */
    void sendCreateNotification(EObject eObject);

	/**
	 * Queries whether an object can contain an object of a given type
	 * in a specified containment reference.  The containment conditions
	 * may be stricter than merely conformance to the declared type of the
	 * containment reference.
	 * 
	 * @param container a prospective containing object
	 * @param reference the containment reference to check
	 * @param containedType the type of the prospective contained object
	 * 
	 * @return <code>true</code> if an element of the specified type is
	 *     permitted to be contained as indicated; <code>false</code>, otherwise
	 */
	boolean canContain(EObject container, EReference reference, EClass containedType);
}