001: /***************************************************************
002: * This file is part of the [fleXive](R) project.
003: *
004: * Copyright (c) 1999-2008
005: * UCS - unique computing solutions gmbh (http://www.ucs.at)
006: * All rights reserved
007: *
008: * The [fleXive](R) project is free software; you can redistribute
009: * it and/or modify it under the terms of the GNU General Public
010: * License as published by the Free Software Foundation;
011: * either version 2 of the License, or (at your option) any
012: * later version.
013: *
014: * The GNU General Public License can be found at
015: * http://www.gnu.org/copyleft/gpl.html.
016: * A copy is found in the textfile GPL.txt and important notices to the
017: * license from the author are found in LICENSE.txt distributed with
018: * these libraries.
019: *
020: * This library is distributed in the hope that it will be useful,
021: * but WITHOUT ANY WARRANTY; without even the implied warranty of
022: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
023: * GNU General Public License for more details.
024: *
025: * For further information about UCS - unique computing solutions gmbh,
026: * please see the company website: http://www.ucs.at
027: *
028: * For further information about [fleXive](R), please see the
029: * project website: http://www.flexive.org
030: *
031: *
032: * This copyright notice MUST APPEAR in all copies of the file!
033: ***************************************************************/package com.flexive.shared.interfaces;
034:
035: import com.flexive.shared.FxLanguage;
036: import com.flexive.shared.content.FxPK;
037: import com.flexive.shared.exceptions.FxApplicationException;
038: import com.flexive.shared.tree.FxTreeMode;
039: import com.flexive.shared.tree.FxTreeNode;
040: import com.flexive.shared.tree.FxTreeNodeEdit;
041: import com.flexive.shared.value.FxReference;
042:
043: import javax.ejb.Remote;
044: import java.util.List;
045:
046: /**
047: * Tree Interface
048: *
049: * @author Gregor Schober (gregor.schober@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
050: */
051: @Remote
052: public interface TreeEngine {
053:
054: //----------------------
055: //- Create/Update/Remove
056: //----------------------
057:
058: /**
059: * Create a new or save an existing node
060: *
061: * @param node the node to save
062: * @return id of the saved node
063: * @throws FxApplicationException on errors
064: */
065: long save(FxTreeNodeEdit node) throws FxApplicationException;
066:
067: /**
068: * Remove a node and optionally its children.
069: * Referenced content content will only be removed if removedReferencedContent is set to true and the referenced
070: * content is not referenced elsewhere.
071: * The only exception is if the referenced content is of type FOLDER, then the folder is removed if it is not referenced
072: * from anywhere else.
073: *
074: * @param node the node to removed
075: * @param removeReferencedContent remove referenced content
076: * @param removeChildren remove children as well?
077: * @throws FxApplicationException on errors
078: */
079: void remove(FxTreeNode node, boolean removeReferencedContent,
080: boolean removeChildren) throws FxApplicationException;
081:
082: /**
083: * Create a tree folders of the given path relative to the parent node, creating all folders
084: * stored in <code>path</code> if they dont exist (similar to {@link java.io.File#mkdirs()}).
085: *
086: * @param mode operate on live or edit tree?
087: * @param parentNodeId the parent node to create the path from
088: * @param position desired position (will be applied to all "folders" hence in most cases only min or max values
089: * make sense)
090: * @param path the path to be created, e.g. "/my/virtual/folder"
091: * @return the node id's of the created path
092: * @throws FxApplicationException on errors
093: */
094: long[] createNodes(FxTreeMode mode, long parentNodeId,
095: int position, String path) throws FxApplicationException;
096:
097: /**
098: * Clears the requested tree and creates a new root node
099: *
100: * @param mode the tree to clear
101: * @throws FxApplicationException on errors
102: */
103: void clear(FxTreeMode mode) throws FxApplicationException;
104:
105: /**
106: * Moves a node to the specified parent and the specified position.
107: *
108: * @param mode tree mode to use (Live or Edit tree)
109: * @param nodeId the node to move
110: * @param destinationId the new parent
111: * @param newPosition the new position in the new parents children
112: * @throws FxApplicationException on errors
113: */
114: void move(FxTreeMode mode, long nodeId, long destinationId,
115: int newPosition) throws FxApplicationException;
116:
117: /**
118: * Copies a node to the specified parent and the specified position.
119: *
120: * @param mode tree mode to use (Live or Edit tree)
121: * @param source the parent id of the structure to copy
122: * @param destination the destination node
123: * @param destinationPosition the position in the destination node's children @return the (root-)id the copy
124: * @return the id of the new node (the "copy")
125: * @throws FxApplicationException on errors
126: */
127: long copy(FxTreeMode mode, long source, long destination,
128: int destinationPosition) throws FxApplicationException;
129:
130: /**
131: * Sets the template of the node.
132: *
133: * @param mode tree mode to use (Live or Edit tree)
134: * @param nodeId the node id
135: * @param template the tamplate, or null for no template
136: */
137: void setTemplate(FxTreeMode mode, long nodeId, String template);
138:
139: /**
140: * Activates a node - copying it from the "Edit" to the "Live" tree
141: *
142: * @param mode tree mode (currently onld Edit supported)
143: * @param nodeId the node to activate
144: * @param includeChildren if true all children of the node are activated as well
145: * @throws FxApplicationException on errors
146: */
147: void activate(FxTreeMode mode, long nodeId, boolean includeChildren)
148: throws FxApplicationException;
149:
150: //----------------------
151: //- Read/Load
152: //----------------------
153:
154: /**
155: * Returns true if a node with the specified id exists.
156: *
157: * @param mode tree mode to use (Live or Edit tree)
158: * @param id the id to check for
159: * @return true if the node exists
160: * @throws FxApplicationException on errors
161: */
162: boolean exist(FxTreeMode mode, long id)
163: throws FxApplicationException;
164:
165: /**
166: * Returns the informations for a single node
167: *
168: * @param mode tree mode to use (Live or Edit tree)
169: * @param id the id of the node to get
170: * @return the node information, or null if the node does not exist
171: * @throws FxApplicationException on errors
172: */
173: FxTreeNode getNode(FxTreeMode mode, long id)
174: throws FxApplicationException;
175:
176: /**
177: * Retrieves a (sub)tree, starting from the given node.
178: * Loading a tree with all data takes a lot of time hence the position of the nodes is not initialized and
179: * the labels are only loaded in the language set as default for the calling user.
180: * Incase the position or (detailed) label is needed the node can be reloaded using <code>getNode()</code>
181: *
182: * @param mode tree mode to use (Live or Edit tree)
183: * @param nodeId the nod to start from
184: * @param depth the maximum depth to read
185: * @return the (sub)tree
186: * @throws FxApplicationException on errors
187: */
188: FxTreeNode getTree(FxTreeMode mode, long nodeId, int depth)
189: throws FxApplicationException;
190:
191: /**
192: * Returns all the templates to use for this node ordered by relevance.
193: *
194: * @param mode tree mode to use (Live or Edit tree)
195: * @param id the id to get the templates for
196: * @return the templates, or null if the node does not exist
197: */
198: String[] getTemplates(FxTreeMode mode, long id);
199:
200: //----------------------
201: //- Finders/Search
202: //----------------------
203:
204: /**
205: * Find a (direct) child with the given name under the node <code>nodeId</code>.
206: *
207: * @param mode tree mode to use (Live or Edit tree)
208: * @param nodeId the parent node ID
209: * @param name name of the requested node @return the tree node
210: * @return the selected node. If no node was found, a runtime exception is thrown.
211: * @throws FxApplicationException on errors
212: */
213: FxTreeNode findChild(FxTreeMode mode, long nodeId, String name)
214: throws FxApplicationException;
215:
216: /**
217: * Find a (direct) child with the given reference ID under the node <code>nodeId</code>.
218: *
219: * @param mode tree mode to use (Live or Edit tree)
220: * @param nodeId the parent node ID
221: * @param referenceId the reference ID
222: * @return the selected node. If no node was found, a runtime exception is thrown.
223: * @throws FxApplicationException on errors
224: */
225: FxTreeNode findChild(FxTreeMode mode, long nodeId, long referenceId)
226: throws FxApplicationException;
227:
228: /**
229: * Find a (direct) child with the given PK under the node <code>nodeId</code>.
230: *
231: * @param mode tree mode to use (Live or Edit tree)
232: * @param nodeId the parent node ID
233: * @param pk the reference
234: * @return the selected node. If no node was found, a runtime exception is thrown.
235: * @throws FxApplicationException on errors
236: */
237: FxTreeNode findChild(FxTreeMode mode, long nodeId, FxPK pk)
238: throws FxApplicationException;
239:
240: /**
241: * Find a (direct) child with the given reference under the node <code>nodeId</code>.
242: *
243: * @param mode tree mode to use (Live or Edit tree)
244: * @param nodeId the parent node ID
245: * @param reference the reference
246: * @return the selected node. If no node was found, a runtime exception is thrown.
247: * @throws FxApplicationException on errors
248: */
249: FxTreeNode findChild(FxTreeMode mode, long nodeId,
250: FxReference reference) throws FxApplicationException;
251:
252: /**
253: * Returns all nodes that match the given reference.
254: *
255: * @param mode tree mode to use (Live or Edit tree)
256: * @param reference the reference
257: * @return the matching nodes
258: * @throws FxApplicationException on errors
259: */
260: List<FxTreeNode> getNodesWithReference(FxTreeMode mode,
261: long reference) throws FxApplicationException;
262:
263: /**
264: * Returns the node id specified by a path.
265: *
266: * @param mode tree mode to use (Live or Edit tree)
267: * @param path the path - eg '/nodeA/nodeB', the virtual root '/Root' node must not be included,
268: * and the path has to start with a '/'.
269: * @return the node id, or -1 if the path does not exist
270: * @throws FxApplicationException on errors
271: */
272: long getIdByPath(FxTreeMode mode, String path)
273: throws FxApplicationException;
274:
275: /**
276: * Returns the node id specified by a FQN path thats starts from the given node.
277: *
278: * @param mode tree mode to use (Live or Edit tree)
279: * @param startNode the root node.
280: * @param path the path - eg '/nodeA/nodeB', the virtual root '/Root' node must not be included,
281: * and the path has to start with a '/'.
282: * @return the node id, or -1 if the path does not exist
283: * @throws FxApplicationException on errors
284: */
285: long getIdByFQNPath(FxTreeMode mode, long startNode, String path)
286: throws FxApplicationException;
287:
288: /**
289: * Returns the node id specified by a label path thats starts from the given node.
290: *
291: * @param mode tree mode to use (Live or Edit tree)
292: * @param startNode the root node.
293: * @param path the path - eg '/nodeA/nodeB', the virtual root '/Root' node must not be included,
294: * and the path has to start with a '/'.
295: * @return the node id, or -1 if the path does not exist
296: * @throws FxApplicationException on errors
297: */
298: long getIdByLabelPath(FxTreeMode mode, long startNode, String path)
299: throws FxApplicationException;
300:
301: /**
302: * Returns the path for a specified id.
303: *
304: * @param mode tree mode to use (Live or Edit tree)
305: * @param nodeId the node id to get the path for
306: * @return the node id, or -1 if the path does not exist
307: * @throws FxApplicationException on errors
308: */
309: String getPathById(FxTreeMode mode, long nodeId)
310: throws FxApplicationException;
311:
312: /**
313: * Returns all ids from the given node up to the root.
314: *
315: * @param mode tree mode to use (Live or Edit tree)
316: * @param nodeId the id to start with
317: * @return the id chain, or null if the node does not exist
318: * @throws FxApplicationException on errors
319: */
320: long[] getIdChain(FxTreeMode mode, long nodeId)
321: throws FxApplicationException;
322:
323: /**
324: * Returns all ids from the root up to the given node.
325: *
326: * @param mode tree mode to use (Live or Edit tree)
327: * @param id the id to start with
328: * @return the id chain, or null if the node does not exist
329: */
330: long[] getReverseIdChain(FxTreeMode mode, long id);
331:
332: /**
333: * Returns a list of paths made up of FQN's for the given id's
334: * The root node will be excluded.
335: * <p/>
336: * Example: input id's = [12,4]<br>
337: * Result: ["/Node1/Node12","/Node1/Node4"]
338: *
339: * @param mode tree mode to use (Live or Edit tree)
340: * @param ids the id's of the nodes to get the path to the root node for
341: * @return a list with all paths made up of FQN's
342: * @throws FxApplicationException on errors
343: */
344: List<String> getPaths(FxTreeMode mode, long... ids)
345: throws FxApplicationException;
346:
347: /**
348: * Returns a list of paths made up of Caption's for the given id's.
349: * If there is no caption propery found in the instance, the FQN will be used.
350: * The root node will be excluded. The language is the calling users preferred language.
351: * <p/>
352: * Example: input ids = [12,4]<br>
353: * Result: ["/DescriptionForNode1/DescriptionForNode12","/DescriptionForNode1/DescriptionForNode4"]
354: *
355: * @param mode tree mode to use (Live or Edit tree)
356: * @param ids the id's of the nodes to get the path to the root node for
357: * @return a list with all paths made up of Caption's
358: * @throws FxApplicationException on errors
359: */
360: List<String> getLabels(FxTreeMode mode, long... ids)
361: throws FxApplicationException;
362:
363: /**
364: * Returns a list of paths made up of Caption's for the given id's.
365: * If there is no caption propery found in the instance, the FQN will be used.
366: * The root node will be excluded.
367: * <p/>
368: * Example: input ids = [12,4]<br>
369: * Result: ["/DescriptionForNode1/DescriptionForNode12","/DescriptionForNode1/DescriptionForNode4"]
370: *
371: * @param mode tree mode to use (Live or Edit tree)
372: * @param lang desired result language
373: * @param ids the id's of the nodes to get the path to the root node for
374: * @return a list with all paths made up of Caption's
375: * @throws FxApplicationException on errors
376: */
377: List<String> getLabels(FxTreeMode mode, FxLanguage lang,
378: long... ids) throws FxApplicationException;
379:
380: //----------------------
381: //- Internal/Lifecycle
382: //----------------------
383:
384: /**
385: * Populate the tree with test data
386: *
387: * @param mode tree mode
388: * @throws FxApplicationException on errors
389: */
390: void populate(FxTreeMode mode) throws FxApplicationException;
391: }
|