bundles/org.simantics.g2d/src/org/simantics/g2d/diagram/DiagramMutator.java

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