KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > alfresco > service > cmr > repository > NodeService


1 /*
2  * Copyright (C) 2005 Alfresco, Inc.
3  *
4  * Licensed under the Mozilla Public License version 1.1
5  * with a permitted attribution clause. You may obtain a
6  * copy of the License at
7  *
8  * http://www.alfresco.org/legal/license.txt
9  *
10  * Unless required by applicable law or agreed to in writing,
11  * software distributed under the License is distributed on an
12  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13  * either express or implied. See the License for the specific
14  * language governing permissions and limitations under the
15  * License.
16  */
17 package org.alfresco.service.cmr.repository;
18
19 import java.io.Serializable JavaDoc;
20 import java.util.List JavaDoc;
21 import java.util.Map JavaDoc;
22 import java.util.Set JavaDoc;
23
24 import org.alfresco.service.cmr.dictionary.InvalidAspectException;
25 import org.alfresco.service.cmr.dictionary.InvalidTypeException;
26 import org.alfresco.service.namespace.QName;
27 import org.alfresco.service.namespace.QNamePattern;
28
29 /**
30  * Interface for public and internal <b>node</b> and <b>store</b> operations.
31  *
32  * @author Derek Hulley
33  */
34 public interface NodeService
35 {
36     /**
37      * Gets a list of all available node store references
38      *
39      * @return Returns a list of store references
40      */
41     public List JavaDoc<StoreRef> getStores();
42     
43     /**
44      * Create a new store for the given protocol and identifier. The implementation
45      * may create the store in any number of locations, including a database or
46      * Subversion.
47      *
48      * @param protocol the implementation protocol
49      * @param identifier the protocol-specific identifier
50      * @return Returns a reference to the store
51      * @throws StoreExistsException
52      */
53     public StoreRef createStore(String JavaDoc protocol, String JavaDoc identifier) throws StoreExistsException;
54     
55     /**
56      * @param storeRef a reference to the store to look for
57      * @return Returns true if the store exists, otherwise false
58      */
59     public boolean exists(StoreRef storeRef);
60     
61     /**
62      * @param nodeRef a reference to the node to look for
63      * @return Returns true if the node exists, otherwise false
64      */
65     public boolean exists(NodeRef nodeRef);
66     
67     /**
68      * Gets the ID of the last transaction that caused the node to change. This includes
69      * deletions, so it is possible that the node being referenced no longer exists.
70      * If the node never existed, then null is returned.
71      *
72      * @param nodeRef a reference to a current or previously existing node
73      * @return Returns the status of the node, or null if the node never existed
74      */
75     public NodeRef.Status getNodeStatus(NodeRef nodeRef);
76     
77     /**
78      * @param storeRef a reference to an existing store
79      * @return Returns a reference to the root node of the store
80      * @throws InvalidStoreRefException if the store could not be found
81      */
82     public NodeRef getRootNode(StoreRef storeRef) throws InvalidStoreRefException;
83
84     /**
85      * @see #createNode(NodeRef, QName, QName, QName, Map)
86      */
87     public ChildAssociationRef createNode(
88             NodeRef parentRef,
89             QName assocTypeQName,
90             QName assocQName,
91             QName nodeTypeQName)
92             throws InvalidNodeRefException, InvalidTypeException;
93     
94     /**
95      * Creates a new, non-abstract, real node as a primary child of the given parent node.
96      *
97      * @param parentRef the parent node
98      * @param assocTypeQName the type of the association to create. This is used
99      * for verification against the data dictionary.
100      * @param assocQName the qualified name of the association
101      * @param nodeTypeQName a reference to the node type
102      * @param properties optional map of properties to keyed by their qualified names
103      * @return Returns a reference to the newly created child association
104      * @throws InvalidNodeRefException if the parent reference is invalid
105      * @throws InvalidTypeException if the node type reference is not recognised
106      *
107      * @see org.alfresco.service.cmr.dictionary.DictionaryService
108      */
109     public ChildAssociationRef createNode(
110             NodeRef parentRef,
111             QName assocTypeQName,
112             QName assocQName,
113             QName nodeTypeQName,
114             Map JavaDoc<QName, Serializable JavaDoc> properties)
115             throws InvalidNodeRefException, InvalidTypeException;
116     
117     /**
118      * Moves the primary location of the given node.
119      * <p>
120      * This involves changing the node's primary parent and possibly the name of the
121      * association referencing it.
122      *
123      * @param nodeToMoveRef the node to move
124      * @param newParentRef the new parent of the moved node
125      * @param assocTypeQName the type of the association to create. This is used
126      * for verification against the data dictionary.
127      * @param assocQName the qualified name of the new child association
128      * @return Returns a reference to the newly created child association
129      * @throws InvalidNodeRefException if either the parent node or move node reference is invalid
130      * @throws CyclicChildRelationshipException if the child partakes in a cyclic relationship after the add
131      *
132      * @see #getPrimaryParent(NodeRef)
133      */
134     public ChildAssociationRef moveNode(
135             NodeRef nodeToMoveRef,
136             NodeRef newParentRef,
137             QName assocTypeQName,
138             QName assocQName)
139             throws InvalidNodeRefException;
140     
141     /**
142      * Set the ordering index of the child association. This affects the ordering of
143      * of the return values of methods that return a set of children or child
144      * associations.
145      *
146      * @param childAssocRef the child association that must be moved in the order
147      * @param index an arbibrary index that will affect the return order
148      *
149      * @see #getChildAssocs(NodeRef)
150      * @see #getChildAssocs(NodeRef, QNamePattern, QNamePattern)
151      * @see ChildAssociationRef#getNthSibling()
152      */
153     public void setChildAssociationIndex(
154             ChildAssociationRef childAssocRef,
155             int index)
156             throws InvalidChildAssociationRefException;
157     
158     /**
159      * @param nodeRef
160      * @return Returns the type name
161      * @throws InvalidNodeRefException if the node could not be found
162      *
163      * @see org.alfresco.service.cmr.dictionary.DictionaryService
164      */
165     public QName getType(NodeRef nodeRef) throws InvalidNodeRefException;
166     
167     /**
168      * Re-sets the type of the node. Can be called in order specialise a node to a sub-type.
169      *
170      * This should be used with caution since calling it changes the type of the node and thus
171      * implies a different set of aspects, properties and associations. It is the calling codes
172      * responsibility to ensure that the node is in a approriate state after changing the type.
173      *
174      * @param nodeRef the node reference
175      * @param typeQName the type QName
176      *
177      * @since 1.1
178      */
179     public void setType(NodeRef nodeRef, QName typeQName) throws InvalidNodeRefException;
180     
181     /**
182      * Applies an aspect to the given node. After this method has been called,
183      * the node with have all the aspect-related properties present
184      *
185      * @param nodeRef
186      * @param aspectTypeQName the aspect to apply to the node
187      * @param aspectProperties a minimum of the mandatory properties required for
188      * the aspect
189      * @throws InvalidNodeRefException
190      * @throws InvalidAspectException if the class reference is not to a valid aspect
191      *
192      * @see org.alfresco.service.cmr.dictionary.DictionaryService#getAspect(QName)
193      * @see org.alfresco.service.cmr.dictionary.ClassDefinition#getProperties()
194      */
195     public void addAspect(
196             NodeRef nodeRef,
197             QName aspectTypeQName,
198             Map JavaDoc<QName, Serializable JavaDoc> aspectProperties)
199             throws InvalidNodeRefException, InvalidAspectException;
200     
201     /**
202      * Remove an aspect and all related properties from a node
203      *
204      * @param nodeRef
205      * @param aspectTypeQName the type of aspect to remove
206      * @throws InvalidNodeRefException if the node could not be found
207      * @throws InvalidAspectException if the the aspect is unknown or if the
208      * aspect is mandatory for the <b>class</b> of the <b>node</b>
209      */
210     public void removeAspect(NodeRef nodeRef, QName aspectTypeQName)
211             throws InvalidNodeRefException, InvalidAspectException;
212     
213     /**
214      * Determines if a given aspect is present on a node. Aspects may only be
215      * removed if they are <b>NOT</b> mandatory.
216      *
217      * @param nodeRef
218      * @param aspectRef
219      * @return Returns true if the aspect has been applied to the given node,
220      * otherwise false
221      * @throws InvalidNodeRefException if the node could not be found
222      * @throws InvalidAspectException if the aspect reference is invalid
223      */
224     public boolean hasAspect(NodeRef nodeRef, QName aspectRef)
225             throws InvalidNodeRefException, InvalidAspectException;
226     
227     /**
228      * @param nodeRef
229      * @return Returns a set of all aspects applied to the node, including mandatory
230      * aspects
231      * @throws InvalidNodeRefException if the node could not be found
232      */
233     public Set JavaDoc<QName> getAspects(NodeRef nodeRef) throws InvalidNodeRefException;
234     
235     /**
236      * Deletes the given node.
237      * <p>
238      * All associations (both children and regular node associations)
239      * will be deleted, and where the given node is the primary parent,
240      * the children will also be cascade deleted.
241      *
242      * @param nodeRef reference to a node within a store
243      * @throws InvalidNodeRefException if the reference given is invalid
244      */
245     public void deleteNode(NodeRef nodeRef) throws InvalidNodeRefException;
246     
247     /**
248      * Makes a parent-child association between the given nodes. Both nodes must belong to the same store.
249      * <p>
250      *
251      *
252      * @param parentRef
253      * @param childRef
254      * @param assocTypeQName the qualified name of the association type as defined in the datadictionary
255      * @param qname the qualified name of the association
256      * @return Returns a reference to the newly created child association
257      * @throws InvalidNodeRefException if the parent or child nodes could not be found
258      * @throws CyclicChildRelationshipException if the child partakes in a cyclic relationship after the add
259      */
260     public ChildAssociationRef addChild(
261             NodeRef parentRef,
262             NodeRef childRef,
263             QName assocTypeQName,
264             QName qname) throws InvalidNodeRefException;
265     
266     /**
267      * Severs all parent-child relationships between two nodes.
268      * <p>
269      * The child node will be cascade deleted if one of the associations was the
270      * primary association, i.e. the one with which the child node was created.
271      *
272      * @param parentRef the parent end of the association
273      * @param childRef the child end of the association
274      * @return Returns a collection of deleted entities - both associations and node references.
275      * @throws InvalidNodeRefException if the parent or child nodes could not be found
276      */
277     public void removeChild(NodeRef parentRef, NodeRef childRef) throws InvalidNodeRefException;
278
279     /**
280      * @param nodeRef
281      * @return Returns all properties keyed by their qualified name
282      * @throws InvalidNodeRefException if the node could not be found
283      */
284     public Map JavaDoc<QName, Serializable JavaDoc> getProperties(NodeRef nodeRef) throws InvalidNodeRefException;
285     
286     /**
287      * @param nodeRef
288      * @param qname the qualified name of the property
289      * @return Returns the value of the property, or null if not yet set
290      * @throws InvalidNodeRefException if the node could not be found
291      */
292     public Serializable JavaDoc getProperty(NodeRef nodeRef, QName qname) throws InvalidNodeRefException;
293     
294     /**
295      * Set the values of all properties to be an <code>Serializable</code> instances.
296      * The properties given must still fulfill the requirements of the class and
297      * aspects relevant to the node.
298      * <p>
299      * <b>NOTE:</b> Null values <u>are</u> allowed.
300      *
301      * @param nodeRef
302      * @param properties all the properties of the node keyed by their qualified names
303      * @throws InvalidNodeRefException if the node could not be found
304      */
305     public void setProperties(NodeRef nodeRef, Map JavaDoc<QName, Serializable JavaDoc> properties) throws InvalidNodeRefException;
306     
307     /**
308      * Sets the value of a property to be any <code>Serializable</code> instance.
309      * To remove a property value, use {@link #getProperties(NodeRef)}, remove the
310      * value and call {@link #setProperties(NodeRef, Map<QName,Serializable>)}.
311      * <p>
312      * <b>NOTE:</b> Null values <u>are</u> allowed.
313      *
314      * @param nodeRef
315      * @param qname the fully qualified name of the property
316      * @param propertyValue the value of the property - never null
317      * @throws InvalidNodeRefException if the node could not be found
318      */
319     public void setProperty(NodeRef nodeRef, QName qname, Serializable JavaDoc value) throws InvalidNodeRefException;
320     
321     /**
322      * @param nodeRef the child node
323      * @return Returns a list of all parent-child associations that exist where the given
324      * node is the child
325      * @throws InvalidNodeRefException if the node could not be found
326      *
327      * @see #getParentAssocs(NodeRef, QNamePattern, QNamePattern)
328      */
329     public List JavaDoc<ChildAssociationRef> getParentAssocs(NodeRef nodeRef) throws InvalidNodeRefException;
330     
331     /**
332      * Gets all parent associations where the pattern of the association qualified
333      * name is a match
334      * <p>
335      * The resultant list is ordered by (a) explicit index and (b) association creation time.
336      *
337      * @param nodeRef the child node
338      * @param typeQNamePattern the pattern that the type qualified name of the association must match
339      * @param qnamePattern the pattern that the qnames of the assocs must match
340      * @return Returns a list of all parent-child associations that exist where the given
341      * node is the child
342      * @throws InvalidNodeRefException if the node could not be found
343      *
344      * @see ChildAssociationRef#getNthSibling()
345      * @see #setChildAssociationIndex(ChildAssociationRef, int)
346      * @see QName
347      * @see org.alfresco.service.namespace.RegexQNamePattern#MATCH_ALL
348      */
349     public List JavaDoc<ChildAssociationRef> getParentAssocs(NodeRef nodeRef, QNamePattern typeQNamePattern, QNamePattern qnamePattern)
350             throws InvalidNodeRefException;
351     
352     /**
353      * Get all child associations of the given node.
354      * <p>
355      * The resultant list is ordered by (a) explicit index and (b) association creation time.
356      *
357      * @param nodeRef the parent node - usually a <b>container</b>
358      * @return Returns a collection of <code>ChildAssocRef</code> instances. If the
359      * node is not a <b>container</b> then the result will be empty.
360      * @throws InvalidNodeRefException if the node could not be found
361      *
362      * @see #getChildAssocs(NodeRef, QNamePattern, QNamePattern)
363      * @see #setChildAssociationIndex(ChildAssociationRef, int)
364      * @see ChildAssociationRef#getNthSibling()
365      */
366     public List JavaDoc<ChildAssociationRef> getChildAssocs(NodeRef nodeRef) throws InvalidNodeRefException;
367     
368     /**
369      * Gets all child associations where the pattern of the association qualified
370      * name is a match.
371      *
372      * @param nodeRef the parent node - usually a <b>container</b>
373      * @param typeQNamePattern the pattern that the type qualified name of the association must match
374      * @param qnamePattern the pattern that the qnames of the assocs must match
375      * @return Returns a list of <code>ChildAssocRef</code> instances. If the
376      * node is not a <b>container</b> then the result will be empty.
377      * @throws InvalidNodeRefException if the node could not be found
378      *
379      * @see QName
380      * @see org.alfresco.service.namespace.RegexQNamePattern#MATCH_ALL
381      */
382     public List JavaDoc<ChildAssociationRef> getChildAssocs(
383             NodeRef nodeRef,
384             QNamePattern typeQNamePattern,
385             QNamePattern qnamePattern)
386             throws InvalidNodeRefException;
387     
388     /**
389      * Fetches the primary parent-child relationship.
390      * <p>
391      * For a root node, the parent node reference will be null.
392      *
393      * @param nodeRef
394      * @return Returns the primary parent-child association of the node
395      * @throws InvalidNodeRefException if the node could not be found
396      */
397     public ChildAssociationRef getPrimaryParent(NodeRef nodeRef) throws InvalidNodeRefException;
398     
399     /**
400      *
401      * @param sourceRef a reference to a <b>real</b> node
402      * @param targetRef a reference to a node
403      * @param assocTypeQName the qualified name of the association type
404      * @return Returns a reference to the new association
405      * @throws InvalidNodeRefException if either of the nodes could not be found
406      * @throws AssociationExistsException
407      */
408     public AssociationRef createAssociation(NodeRef sourceRef, NodeRef targetRef, QName assocTypeQName)
409             throws InvalidNodeRefException, AssociationExistsException;
410     
411     /**
412      *
413      * @param sourceRef the associaton source node
414      * @param targetRef the association target node
415      * @param assocTypeQName the qualified name of the association type
416      * @throws InvalidNodeRefException if either of the nodes could not be found
417      */
418     public void removeAssociation(NodeRef sourceRef, NodeRef targetRef, QName assocTypeQName)
419             throws InvalidNodeRefException;
420     
421     /**
422      * Fetches all associations <i>from</i> the given source where the associations'
423      * qualified names match the pattern provided.
424      *
425      * @param sourceRef the association source
426      * @param qnamePattern the association qname pattern to match against
427      * @return Returns a list of <code>NodeAssocRef</code> instances for which the
428      * given node is a source
429      * @throws InvalidNodeRefException if the source node could not be found
430      *
431      * @see QName
432      * @see org.alfresco.service.namespace.RegexQNamePattern#MATCH_ALL
433      */
434     public List JavaDoc<AssociationRef> getTargetAssocs(NodeRef sourceRef, QNamePattern qnamePattern)
435             throws InvalidNodeRefException;
436     
437     /**
438      * Fetches all associations <i>to</i> the given target where the associations'
439      * qualified names match the pattern provided.
440      *
441      * @param targetRef the association target
442      * @param qnamePattern the association qname pattern to match against
443      * @return Returns a list of <code>NodeAssocRef</code> instances for which the
444      * given node is a target
445      * @throws InvalidNodeRefException
446      *
447      * @see QName
448      * @see org.alfresco.service.namespace.RegexQNamePattern#MATCH_ALL
449      */
450     public List JavaDoc<AssociationRef> getSourceAssocs(NodeRef targetRef, QNamePattern qnamePattern)
451             throws InvalidNodeRefException;
452     
453     /**
454      * The root node has an entry in the path(s) returned. For this reason, there
455      * will always be <b>at least one</b> path element in the returned path(s).
456      * The first element will have a null parent reference and qname.
457      *
458      * @param nodeRef
459      * @return Returns the path to the node along the primary node path
460      * @throws InvalidNodeRefException if the node could not be found
461      *
462      * @see #getPaths(NodeRef, boolean)
463      */
464     public Path getPath(NodeRef nodeRef) throws InvalidNodeRefException;
465     
466     /**
467      * The root node has an entry in the path(s) returned. For this reason, there
468      * will always be <b>at least one</b> path element in the returned path(s).
469      * The first element will have a null parent reference and qname.
470      *
471      * @param nodeRef
472      * @param primaryOnly true if only the primary path must be retrieved. If true, the
473      * result will have exactly one entry.
474      * @return Returns a List of all possible paths to the given node
475      * @throws InvalidNodeRefException if the node could not be found
476      */
477     public List JavaDoc<Path> getPaths(NodeRef nodeRef, boolean primaryOnly) throws InvalidNodeRefException;
478 }
479
Popular Tags