bundles/org.simantics.g2d/src/org/simantics/g2d/diagram/DiagramMutator.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.g2d.diagram;
  13
  14 import org.simantics.g2d.element.ElementClass;
  15 import org.simantics.g2d.element.IElement;
  16
  17 /**
  18  * An interface that is used for writing diagram modifications into the
  19  * back-end. It is basically a queue of ordered modifications. Performing these
  20  * modifications will cause back-end data model listeners to fire, making it
  21  * possible for the back-end => diagram synchronizer to keep the visual
  22  * appearance up-to-date with the data model.
  23  *
  24  * <p>
  25  * To guarantee proper synchronization between back-end data model tracking and
  26  * back-end mutation, methods of this class should only be invoked within
  27  * diagram write transactions. See
  28  * {@link DiagramUtils#inDiagramTransaction(IDiagram, org.simantics.g2d.diagram.handler.TransactionContext.TransactionType, Runnable)}
  29  * and
  30  * {@link DiagramUtils#mutateDiagram(IDiagram, org.simantics.utils.datastructures.Callback)}.
  31  *
  32  * @author Antti Villberg
  33  * @author Tuukka Lehtonen
  34  *
  35  * @deprecated will be completely removed asap, do not use this, just write the
  36  *             data directly into the database.
  37  */
  38 @Deprecated
  39 public interface DiagramMutator {
  40
  41     /**
  42      * Creates a modification that forces the hints of the specified element to
  43      * be synchronized with the back-end.
  44      *
  45      * @param element
  46      */
  47     void synchronizeHintsToBackend(IElement element);
  48
  49     void modifyTransform(IElement element);
  50
  51     IElement newElement(ElementClass clazz);
  52
  53     /**
  54      * Set the Z-Order of the specified element.
  55      *
  56      * @param element
  57      * @param position
  58      */
  59     void synchronizeElementOrder();
  60
  61     /**
  62      * Retrieve objects bound using {@link #register(IElement, Object)}. These
  63      * bindings will only stay alive until either {@link #clear()} or
  64      * {@link #commit()} is invoked.
  65      *
  66      * @param <T>
  67      * @param element
  68      * @return
  69      */
  70     <T> T backendObject(IElement element);
  71
  72     /**
  73      * For registering an element <-> back-end object binding which will be kept
  74      * until either {@link #clear()} or {@link #commit()} is invoked.
  75      * {@link #backendObject(IElement)} can be to retrieve the objects based on
  76      * these bindings which is necessary in cases where the write-back process
  77      * produces new back-end resources that are needed by modifications that are
  78      * performed later.
  79      *
  80      * @param element
  81      * @param object
  82      */
  83     void register(IElement element, Object object);
  84
  85     /**
  86      * Commits all changes that have been queue into the mutator since the
  87      * previous {@link #commit()} or {@link #clear()} invocation. A successful
  88      * commit will empty the mutator into a state which is essentially the same
  89      * as after invoking {@link #clear()}.
  90      */
  91     void commit();
  92
  93     /**
  94      * Discard any changes that have been queued in the mutator by invocations
  95      * to any modifying methods. After this the queue will be empty. Can be
  96      * invoked at any time.
  97      */
  98     void clear();
  99
 100 }