bundles/org.simantics.diagram/src/org/simantics/diagram/synchronization/CopyAdvisor.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.diagram.synchronization;
  13
  14 import java.util.EnumSet;
  15 import java.util.Map;
  16
  17 import org.simantics.g2d.diagram.IDiagram;
  18
  19 /**
  20  * A CopyAdvisor is used to abstractly evaluate whether a source object can be
  21  * copied and for performing the actual copy operation. CopyAdvisor is a part of
  22  * the Simantics diagram to backend (graph) synchronization framework.
  23  *
  24  * <p>
  25  * The {@link #canCopy(ISynchronizationContext, Object)} method returns an
  26  * evaluation of what can be regarding copying of the specified source object.
  27  * The type of the source object depends on the backend just like the contents
  28  * of the received {@link ISynchronizationContext}.
  29  *
  30  * <p>
  31  * CopyAdvisor is currently used with {@link IDiagram} to describe how copying
  32  * happens within a diagram (or diagram type).
  33  *
  34  * @author Tuukka Lehtonen
  35  */
  36 public interface CopyAdvisor {
  37
  38     public enum Evaluation {
  39         SUPPORTED,
  40         NOT_SUPPORTED,
  41         DENIED,
  42     }
  43
  44     EnumSet<Evaluation> SUPPORTED  = EnumSet.of(Evaluation.SUPPORTED);
  45     EnumSet<Evaluation> DENIED     = EnumSet.of(Evaluation.DENIED);
  46     EnumSet<Evaluation> NOT_DENIED = EnumSet.complementOf(DENIED);
  47
  48     /**
  49      * @param context a context for the synchronization operation
  50      * @param source
  51      * @param sourceContainer
  52      * @param targetContainer
  53      * @return evaluation of the possibilities of copying the source object
  54      */
  55     Evaluation canCopy(ISynchronizationContext context, Object source, Object sourceContainer, Object targetContainer);
  56
  57     /**
  58      * @param context a context for the synchronization operation
  59      * @param source
  60      * @param sourceContainer
  61      * @param targetContainer
  62      * @return copied backend object or <code>null</code> if the specified
  63      *         source object is not supported
  64      * @throws SynchronizationException if copying is denied for the source
  65      *         object
  66      */
  67     Object copy(ISynchronizationContext context, Object source, Object sourceContainer, Object targetContainer);
  68
  69     /**
  70      * @param context a context for the synchronization operation
  71      * @param source
  72      * @param sourceContainer
  73      * @param targetContainer
  74      * @param map a map for storing the correspondences between original and
  75      *        copied objects. This is used to output data from the copy process.
  76      * @return copied backend object or <code>null</code> if the specified
  77      *         source object is not supported
  78      * @throws SynchronizationException if copying is denied for the source
  79      *         object
  80      */
  81     Object copy(ISynchronizationContext context, Object source, Object sourceContainer, Object targetContainer,
  82             Map<Object, Object> map);
  83
  84     /**
  85      * @param context
  86      * @param source
  87      * @param sourceContainer
  88      * @param targetContainer
  89      * @return any non-null object if successful, <code>null</code> if couldn't
  90      *         cut
  91      * @throws SynchronizationException if cut fails
  92      */
  93     Object cut(ISynchronizationContext context, Object source, Object sourceContainer, Object targetContainer);
  94
  95     /**
  96      * Invoked when either a copy or cut operation has been finished.
  97      *
  98      * @param context
  99      * @throws SynchronizationException if onFinish fails
 100      */
 101     void onFinish(ISynchronizationContext context);
 102
 103 }