New Jide License
[indepmod/experimental.git] / IndependentModeler / src / cz / cvut / promod / services / projectService / ProjectControlService.java
blob9542124a2b81e24080dac368953305168ff96878
1 package cz.cvut.promod.services.projectService;
3 import cz.cvut.promod.services.projectService.treeProjectNode.ProjectRoot;
4 import cz.cvut.promod.services.projectService.treeProjectNode.ProjectDiagram;
5 import cz.cvut.promod.services.projectService.treeProjectNode.listener.ProjectDiagramListener;
6 import cz.cvut.promod.services.projectService.results.AddProjectItemResult;
7 import cz.cvut.promod.services.projectService.results.LoadProjectResult;
8 import cz.cvut.promod.services.projectService.results.SaveProjectResult;
10 import javax.swing.tree.*;
11 import java.util.List;
12 import java.io.File;
14 /**
15 * ProMod, master thesis project
16 * User: Petr Zverina, petr.zverina@gmail.com
17 * Date: 17:48:28, 10.10.2009
19 public interface ProjectControlService extends ProjectService{
21 /**
22 * Returns the model used by the project navigation tree.
24 * One is supposed to avoid using this model. Use other methods to changes tree state!
26 * @return project navigation tree model
28 public DefaultTreeModel getProjectTreeModel();
30 /**
31 * Set the required item in the project navigation tree.
33 * @param treePath is the tree path to be selected in the project navigation tree
35 public void setSelectedItem(final TreePath treePath);
37 /**
38 * Adds new project item to the project navigation tree. Do not store anything on the file system (for this use
39 * synchronization).
41 * Be careful that project name can have any project name (not null or empty), but some illegal
42 * names wont be possible to save to the file system during synchronization.
44 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils to check correctness of name
46 * @param projectRoot is the project root of the project that is supposed to be added to the project navigation
47 * tree. The display name cannot be null, an empty string and cannot contain any disallowed symbols.
49 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more info about disallowed symbols
51 * @param select if true, the newly added project item (project) will be selected in project tree navigation
53 * @return an object of AddProjectItemResult representing result of the operation
55 * @see cz.cvut.promod.services.projectService.results.AddProjectItemResult for more detail info about the result
56 * @see cz.cvut.promod.services.projectService.results.AddProjectItemStatus for more details about relevant error
57 * message
59 public AddProjectItemResult addProject(final ProjectRoot projectRoot, final boolean select);
62 /**
63 * Adds a new subfolder with given name to the required tree path in the project navigation tree.
64 * The required tree path has to be a valid tree in the project navigation tree and the last path
65 * component is supposed to be a project container (project root or a subfolder). One can never add
66 * subfolder under a diagram node.
68 * @param subFolderName is the name for the new subfolder, cannot by nullary or an empty string. It cannot contains
69 * any disallowed symbols as well.
71 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about disallowed symbols
73 * @param parentTreePath is the tree path to the parent node, under that is the the new subfolder supposed to
74 * be added. Has to be valid.
76 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about path validity
78 * @param select if true, the newly added subfolder node will be selected in project tree navigation
80 * @return an object of AddProjectItemResult representing result of the operation
82 * @see cz.cvut.promod.services.projectService.results.AddProjectItemResult for more detail info about the result
83 * @see cz.cvut.promod.services.projectService.results.AddProjectItemStatus for more details about relevant error
84 * message
86 public AddProjectItemResult addSubFolder(final String subFolderName,
87 final TreePath parentTreePath,
88 final boolean select);
90 /**
91 * Adds a new subfolder with given name to the tree path of the closest project container in the project
92 * navigation tree.
94 * @param subFolderName is the name for the new subfolder, cannot by nullary or an empty string. It cannot contains
95 * any disallowed symbols as well.
97 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about disallowed symbols
99 * @param select if true, the newly added subfolder node will be selected in project tree navigation
101 * @return an object of AddProjectItemResult representing result of the operation
103 * @see cz.cvut.promod.services.projectService.results.AddProjectItemResult for more detail info about the result
104 * @see cz.cvut.promod.services.projectService.results.AddProjectItemStatus for more details about relevant error
105 * message
107 public AddProjectItemResult addSubFolder(final String subFolderName, final boolean select);
110 * Adds a new project diagram under specified parent node to the project navigation tree. One cannot save
111 * 2 diagrams with the same name and the same notation under one parent node.
113 * Note: It is possible to insert more than just one diagram having the same name under one parent node
114 * in the project navigation tree, but each of these diagrams has to be of a different notation
116 * @param projectDiagram is the project diagram that is supposed to be inserted to the project navigation tree. The
117 * name cannot contain any disallowed symbols.
119 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about disallowed symbols
121 * @param parentTreePath is the path to the parent node, under that is the project diagram supposed to be inserted.
122 * The tree path has to be valid and the last path component has to be a project container (project root or
123 * subfolder)
125 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about path validity
127 * @param select if true, the newly added diagram node will be selected in project tree navigation
129 * @return an object of AddProjectItemResult representing result of the operation
131 * @see cz.cvut.promod.services.projectService.results.AddProjectItemResult for more detail info about the result
132 * @see cz.cvut.promod.services.projectService.results.AddProjectItemStatus for more details about relevant error
133 * message
135 public AddProjectItemResult addDiagram(final ProjectDiagram projectDiagram,
136 final TreePath parentTreePath,
137 final boolean select);
140 * Adds a new project diagram to the tree path of the closest project container in the project
141 * navigation tree.
143 * Note: It is possible to insert more than just one diagram having the same name under one parent node
144 * in the project navigation tree, but each of these diagrams has to be of a different notation
146 * @param projectDiagram is the project diagram that is supposed to be inserted to the project navigation tree. The
147 * name cannot contain any disallowed symbols.
149 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about disallowed symbols
151 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about path validity
153 * @param select if true, the newly added diagram node will be selected in project tree navigation
155 * @return an object of AddProjectItemResult representing result of the operation
157 * @see cz.cvut.promod.services.projectService.results.AddProjectItemResult for more detail info about the result
158 * @see cz.cvut.promod.services.projectService.results.AddProjectItemStatus for more details about relevant error
159 * message
161 public AddProjectItemResult addDiagram(final ProjectDiagram projectDiagram,
162 final boolean select);
165 * Removes project item specified by the argument from the project navigation tree.
167 * If the project item that is supposed to be deleted is currently selected or it's any child,
168 * then the parent of this item will selected automatically.
170 * If the item to be deleted is or contains some project diagrams, then REMOVE event of this items
171 * is automatically dispatched.
173 * The project diagram is automatically removed.
175 * @param treePath specifies the project item, that is supposed to be removed
177 * @return file system path to the item, that was deleted, null if any error occurs
179 public String removeProjectItem(final TreePath treePath);
182 * Synchronization from the project navigation tree to the file system.
184 * It is possible to run this sync only from EventDispatcherThread.
186 * @param treePath is the tree path to the root of the sub-tree that is supposed to be synchronized.
187 * If the last path component's user's object is any instance if ProjectDiagram, the synchronization is
188 * performed only on this diagram. If the last path component's user object is any implementation of
189 * ProjectContainer interface than this node is taken as the root of the sub-tree where will be
190 * synchronization performed.
192 * @param addProjectItems indicates whether new items are supposed to be created on the file system if there are missing
193 * @param overwriteProjectItems indicates whether diagrams that already exists on the file system are supposed to be overwritten
194 * @param deleteProjectItems indicates whether no project items (files or diagrams) are supposed to be deleted from file system
195 * one should be very careful when using this flag, because all deletion are un-doable.
196 * @param cancelable if true, the the synchronization can be canceled by the user
197 * @return true if no error has occurred during synchronization, false otherwise
199 public boolean synchronize(final TreePath treePath,
200 final boolean addProjectItems,
201 final boolean overwriteProjectItems,
202 final boolean deleteProjectItems,
203 final boolean cancelable);
206 * Synchronization from the file system to the project navigation.
208 * It is possible to run this sync only from EventDispatcherThread.
210 * @param projectFile is the actual project file of the project, the placement of the project file is the
211 * file system location from where the synchronization starts (can be specify by the path offset)
212 * @param pathOffset is the specification of a particular directory extending the project file location from where
213 * the synchronization supposed to start. E.g. the project file location is D:\Project\MyProject.pmp. The path
214 * offset is overview/diagrams. So the synchronization will start from the location D:\Project\overview\diagrams.
215 * @param addProjectItems indicates whether new items are supposed to be created in the project navigation if there are missing
216 * @param overwriteProjectItems indicates whether diagrams that already exists in the project navigation are supposed to be overwritten
217 * @param deleteProjectItems indicates whether no project items are supposed to be deleted from the project navigation during synchronization
218 * @param cancelable if true, the the synchronization can be canceled by the user
219 * @return true if no error has occurred during synchronization, false otherwise
221 public boolean synchronize(final File projectFile,
222 final List<String> pathOffset,
223 final boolean addProjectItems,
224 final boolean overwriteProjectItems,
225 final boolean deleteProjectItems,
226 final boolean cancelable);
229 * Save the project root represented by the tree path to the project root.
230 * This method automatically overwrites the old file, if any exists. One should always use
231 * something like new File(<path to project file>).exists() to be sure. If the required
232 * directory structure doesn't exist then this structure is automatically created for you.
234 * Note, that this method uses a static method of ProjectFileSave class
236 * @see cz.cvut.promod.services.projectService.localIO.ProjectFileSaver to save the project with formatting
237 * enabled. One can use this static method straight instead of using this method. Then, you can let the
238 * saver omit the formatting to lower RAM consumption and increase performance.
240 * @param projectTreePath is the tree path to the project root in project navigation tree. The tree path has to be
241 * valid and tha last path component has to be a valid project root
243 * @see cz.cvut.promod.services.projectService.utils.ProjectServiceUtils for more details about tree path validity
245 * @return a value defined by the SaveProjectResult enumeration
247 * @see cz.cvut.promod.services.projectService.results.SaveProjectResult for more details about return values
248 * and it's conditions
250 public SaveProjectResult saveProject(final TreePath projectTreePath);
254 * Loads the project diagram and returns and object of LoadProjectResult class.
256 * @see cz.cvut.promod.services.projectService.results.LoadProjectResult
258 * @param projectFile is the file specifynig the ProMod project file
260 * @return an object of LoadProjectResult class holding the project root and other info
262 public LoadProjectResult loadProject(final File projectFile);
265 * Switch one project diagram for another. All listeners that have been registered with the old project diagram
266 * will be registered with the new diagram diagram.
268 * If any of the project diagrams is null then this method will have no effect.
270 * @param oldProjectDiagram is the old project diagram
271 * @param newProjectDiagram is the new project diagram
273 public void switchChangePublisher(final ProjectDiagram oldProjectDiagram, final ProjectDiagram newProjectDiagram);
276 * Switch one project diagram listener for another.
278 * If any of the project diagram listeners is null then this method will have no effect.
280 * @param oldProjectDiagramListener is the old project diagram listener
281 * @param newProjectDiagramListener is the new project diagram listener
283 public void switchChangeListener(final ProjectDiagramListener oldProjectDiagramListener, final ProjectDiagramListener newProjectDiagramListener);