1 /*
2 * This file is a part of CAST project.
3 * (c) Copyright 2007, AGH University of Science & Technology
4 * https://caribou.iisg.agh.edu.pl/trac/cast
5 *
6 * Licensed under the Eclipse Public License, Version 1.0 (the "License").
7 * You may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 * http://www.eclipse.org/legal/epl-v10.html
10 */
11 /*
12 * File: IDiagram.java
13 * Created: 2007-00-00
14 * Author: fox, tmilos
15 * $Id: IDiagram.java 2817 2009-05-05 13:17:57Z tmilos $
16 */
17
18 package pl.edu.agh.cast.model.visual.backward;
19
20 import java.io.Serializable;
21 import java.util.Collection;
22 import java.util.Date;
23 import java.util.List;
24 import java.util.Map;
25
26 import org.eclipse.core.resources.IFile;
27 import org.eclipse.core.runtime.IProgressMonitor;
28
29 import pl.edu.agh.cast.data.model.property.IPropertyChangeProvider;
30 import pl.edu.agh.cast.model.attributes.AttributeMergePolicy;
31 import pl.edu.agh.cast.model.attributes.NodeAttributeManager;
32 import pl.edu.agh.cast.model.base.IDataProvider;
33 import pl.edu.agh.cast.model.base.IDataSet;
34 import pl.edu.agh.cast.model.base.IEntity;
35 import pl.edu.agh.cast.model.base.IRelation;
36
37 /**
38 * Interface of a diagram which consists of {@link Node}s and {@link Connection}s.
39 *
40 * @author AGH CAST Team
41 */
42 public interface IDiagram extends Serializable, IPropertyChangeProvider, AttributeValueContainer, IDataProvider {
43
44 /**
45 * Returns a collection of all diagram {@link Node}s.
46 *
47 * @return collection of {@link Node}s
48 */
49 public Collection<Node> getNodes();
50
51 /**
52 * Returns a collection of {@link Connection}s.
53 *
54 * This can throw {@link UnsupportedOperationException} if diagram does not have information about single
55 * connections.
56 *
57 * @return collection of {@link Connection}s
58 */
59 public Collection<Connection> getConnections();
60
61 /**
62 * Returns diagram settings.
63 *
64 * @return diagram settings
65 */
66 public IDiagramSettings getSettings();
67
68 /**
69 * Sets diagram settings.
70 *
71 * @param settings
72 * diagram settings
73 */
74 public void setSettings(IDiagramSettings settings);
75
76 /**
77 * Return file in which this diagram is stored.
78 *
79 * @return the file containing this diagram
80 */
81 public IFile getFile();
82
83 /**
84 * Set the file in which this diagram is stored.
85 *
86 * @param file
87 * the file to store the diagram in
88 */
89 public void setFile(IFile file);
90
91 /**
92 * Returns the display name of the diagram.
93 *
94 * @return the name of the diagram
95 */
96 public String getDisplayName();
97
98 /**
99 * Sets the display name of the diagram.
100 *
101 * @param name
102 * the name of the diagram
103 */
104 public void setDisplayName(String name);
105
106 /**
107 * Returns statistics for current diagram.
108 *
109 * @return statistics for current diagram
110 * @deprecated Use the {@link #getStatistics(IProgressMonitor)} version with progress reporting
111 */
112 @Deprecated
113 public List<Statistic> getStatistics();
114
115 /**
116 * Returns statistics for current diagram. Uses {@link IProgressMonitor}.
117 *
118 * @param monitor
119 * non-null progress monitor
120 * @return statistics for current diagram
121 */
122 public List<Statistic> getStatistics(IProgressMonitor monitor);
123
124 /**
125 * Returns the {@link NodeAttributeManager} of this diagram.
126 *
127 * @return {@link NodeAttributeManager} of this diagram
128 */
129 public NodeAttributeManager getNodeAttributeManager();
130
131 /**
132 * Returns the {@link Node} with given id.
133 *
134 * @param nodeId
135 * id of the node to find
136 * @return node with given id
137 */
138 public Node findNode(String nodeId);
139
140 /**
141 * Returns the {@link Connection} matching given criteria.
142 *
143 * @param sourceNodeId
144 * id of the connection source node
145 * @param targetNodeId
146 * id of the connection target node
147 * @param date
148 * date of the connection
149 * @return connection matching given criteria
150 */
151 public Connection findConnection(String sourceNodeId, String targetNodeId, Date date);
152
153 /**
154 * Adds a {@link Node} to the model.
155 *
156 * @param node
157 * the node to add
158 * @return the node that was actually added to the diagram (useful for undo)
159 */
160 public Node addNode(Node node);
161
162 /**
163 * Adds {@link Node}s to the model.
164 *
165 * @param nodes
166 * collection of nodes to add
167 * @return collection of nodes that were actually added to the diagram (doesn't include nodes already present in the
168 * diagram); this information can be used to undo the adding operation
169 */
170 public Collection<Node> addNodes(Collection<Node> nodes);
171
172 /**
173 * Adds a {@link Connection} to the diagram.
174 *
175 * @param c
176 * connection to add
177 * @return non-null, added connection
178 */
179 public Connection addConnection(Connection c);
180
181 /**
182 * Adds multiple {@link Connection}s. Calls {@link #addConnection}.
183 *
184 * @param connections
185 * collection of connections to add
186 */
187 public void addConnections(Collection<Connection> connections);
188
189 /**
190 * Removes a {@link Node} from the diagram. Node must have been created by this diagram's factory (i.e. must be a
191 * diagram's node).
192 *
193 * @param node
194 * the node to remove
195 * @throws IllegalArgumentException
196 * if node is not a child of the diagram
197 */
198 public void removeNode(Node node);
199
200 /**
201 * Removes {@link Node}s from the model. Nodes must have been created by this diagram's factory (i.e. must be
202 * diagram's nodes).
203 *
204 * @param nodes
205 * collection of nodes to remove
206 * @throws IllegalArgumentException
207 * if any of the nodes is not a child of the diagram
208 */
209 public void removeNodes(Collection<Node> nodes);
210
211 /**
212 * Removes a {@link Connection} from the model. Connection must have been created by this diagram's factory (i.e.
213 * must be a diagram's connection).
214 *
215 * @param connection
216 * connection to add
217 * @throws IllegalArgumentException
218 * if connection is not a child of the diagram
219 */
220 public void removeConnection(Connection connection);
221
222 /**
223 * Removes selection in diagram edit part.
224 */
225 public void deselect();
226
227 /**
228 * Returns all model data (packaged as one {@link IDataSet}) kept in the diagram.
229 *
230 * @return {@link IDataSet} containing diagram model data
231 */
232 public IDataSet getDomainModel();
233
234 /**
235 * Finds {@link IRelation} for given connection.
236 *
237 * @param connection
238 * the connection which was made of the relation
239 * @return the relation which was the base for given connection
240 */
241 public IRelation findRelation(Connection connection);
242
243 /**
244 * Adds attributes from a collection of entities to the diagram with join on entity and node IDs. For details see
245 * {@link #addAttributesFromEntities(Collection, Map, String, String, String)}
246 *
247 * @param entities
248 * collection of entities to add attributes from
249 * @param attributes
250 * collection of attributes from <code>entities</code> that should be added to nodes
251 * @param mergePolicies
252 * map of {@link AttributeMergePolicy} policies
253 * @param nodeType
254 * type of nodes that the attributes should be added to, if <code>null</code> then all types are taken
255 * into account
256 * @param monitor
257 * progress monitor for this task, if <code>null</code> then
258 * {@link org.eclipse.core.runtime.NullProgressMonitor} is used
259 */
260 public void addAttributesFromEntities(Collection<IEntity> entities, Collection<String> attributes,
261 Map<String, AttributeMergePolicy> mergePolicies, String nodeType, IProgressMonitor monitor);
262
263 /**
264 * Adds attributes from a collection of entities to the diagram. The join between the entities and nodes is
265 * performed on the <code>sourceJoinAttribute</code> of <code>entities</code> and <code>targetJoinAttribute</code>
266 * of diagram nodes.
267 *
268 * For each {@link Node} <code>node</code> of type <code>nodeType</code> from the current {@link Diagram}, if there
269 * is an <code>entity</code> (of type {@link IEntity}) such that:
270 *
271 * <pre>
272 * node.getAttributeValue(targetJoinAttribute).equals(entity.getAttribute(sourceJoinAttribute));
273 * </pre>
274 *
275 * then the attributes from the <code>entity</code> are added to the <code>node</code>.
276 *
277 * The <code>sourceJoinAttribute</code> entity attribute should be unique across the <code>entities</code>
278 * collection, in order for the results to be deterministic.
279 *
280 * In order to resolve conflicts where the same attribute is present in both <code>entity</code> and
281 * <code>node</code>, instances {@link AttributeMergePolicy} can be used. These policies should be supplied in a map
282 * with entity attribute IDs as keys. A <code>null</code> key defines the default policy, otherwise
283 * {@link AttributeMergePolicy#MERGE_POLICY_ALWAYS_SECOND} is used.
284 *
285 * @param entities
286 * collection of entities to add attributes from
287 * @param attributes
288 * collection of attributes from <code>entities</code> that should be added to nodes
289 * @param mergePolicies
290 * map of {@link AttributeMergePolicy} policies
291 * @param nodeType
292 * type of nodes that the attributes should be added to, if <code>null</code> then all types are taken
293 * into account
294 * @param sourceJoinAttribute
295 * id of the entity attribute to join on
296 * @param targetJoinAttribute
297 * id of the node attribute to join on
298 * @param monitor
299 * progress monitor for this task, if <code>null</code> then
300 * {@link org.eclipse.core.runtime.NullProgressMonitor} is used
301 */
302 public void addAttributesFromEntities(Collection<IEntity> entities, Collection<String> attributes,
303 Map<String, AttributeMergePolicy> mergePolicies, String nodeType, String sourceJoinAttribute,
304 String targetJoinAttribute, IProgressMonitor monitor);
305
306 /**
307 * Checks if the nodes of this diagram may be enhanced with attributes of entities from another {@link IDataSet}.
308 * For details see {@link #addAttributesFromEntities(Collection, Collection, Map, String, String, String)} .
309 *
310 * @return whether this diagram may be enhanced
311 */
312 public boolean isEnhancable();
313
314 /**
315 * Suppresses all events fired by this diagram.
316 *
317 * @param newSuppressEvents
318 * new value of suppression flag
319 */
320 public void setSuppressEvents(boolean newSuppressEvents);
321
322 }