KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > alfresco > service > cmr > version > VersionService


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.version;
18
19 import java.io.Serializable JavaDoc;
20 import java.util.Collection JavaDoc;
21 import java.util.Map JavaDoc;
22
23 import org.alfresco.service.cmr.repository.AspectMissingException;
24 import org.alfresco.service.cmr.repository.NodeRef;
25 import org.alfresco.service.cmr.repository.StoreRef;
26 import org.alfresco.service.namespace.QName;
27
28 /**
29  * Interface for public and internal version operations.
30  *
31  * @author Roy Wetherall
32  */

33 public interface VersionService
34 {
35     /**
36      * The version store protocol label, used in store references
37      */

38     public static final String JavaDoc VERSION_STORE_PROTOCOL = "versionStore";
39     
40     /**
41      * Gets the reference to the version store
42      *
43      * @return reference to the version store
44      */

45     public StoreRef getVersionStoreReference();
46     
47     /**
48      * Creates a new version based on the referenced node.
49      * <p>
50      * If the node has not previously been versioned then a version history and
51      * initial version will be created.
52      * <p>
53      * If the node referenced does not or can not have the version aspect
54      * applied to it then an exception will be raised.
55      * <p>
56      * The version properties are sotred as version meta-data against the newly
57      * created version.
58      *
59      * @param nodeRef a node reference
60      * @param versionProperties the version properties that are stored with the newly created
61      * version
62      * @return the created version object
63      * @throws ReservedVersionNameException
64      * thrown if a reserved property name is used int he version properties
65      * provided
66      * @throws AspectMissingException
67      * thrown if the version aspect is missing
68      */

69     public Version createVersion(
70             NodeRef nodeRef,
71             Map JavaDoc<String JavaDoc, Serializable JavaDoc> versionProperties)
72             throws ReservedVersionNameException, AspectMissingException;
73
74     /**
75      * Creates a new version based on the referenced node.
76      * <p>
77      * If the node has not previously been versioned then a version history and
78      * initial version will be created.
79      * <p>
80      * If the node referenced does not or can not have the version aspect
81      * applied to it then an exception will be raised.
82      * <p>
83      * The version properties are sotred as version meta-data against the newly
84      * created version.
85      *
86      * @param nodeRef a node reference
87      * @param versionProperties the version properties that are stored with the newly created
88      * version
89      * @param versionChildren if true then the children of the referenced node are also
90      * versioned, false otherwise
91      * @return the created version object(s)
92      * @throws ReservedVersionNameException
93      * thrown if a reserved property name is used int he version properties
94      * provided
95      * @throws AspectMissingException
96      * thrown if the version aspect is missing
97      */

98     public Collection JavaDoc<Version> createVersion(
99             NodeRef nodeRef,
100             Map JavaDoc<String JavaDoc, Serializable JavaDoc> versionProperties,
101             boolean versionChildren)
102             throws ReservedVersionNameException, AspectMissingException;
103
104     /**
105      * Creates new versions based on the list of node references provided.
106      *
107      * @param nodeRefs a list of node references
108      * @param versionProperties version property values
109      * @return a collection of newly created versions
110      * @throws ReservedVersionNameException
111      * thrown if a reserved property name is used int he version properties
112      * provided
113      * @throws AspectMissingException
114      * thrown if the version aspect is missing
115      */

116     public Collection JavaDoc<Version> createVersion(
117             Collection JavaDoc<NodeRef> nodeRefs,
118             Map JavaDoc<String JavaDoc, Serializable JavaDoc> versionProperties)
119             throws ReservedVersionNameException, AspectMissingException;
120
121     /**
122      * Gets the version history information for a node.
123      * <p>
124      * If the node has not been versioned then null is returned.
125      * <p>
126      * If the node referenced does not or can not have the version aspect
127      * applied to it then an exception will be raised.
128      *
129      * @param nodeRef a node reference
130      * @return the version history information
131      * @throws AspectMissingException
132      * thrown if the version aspect is missing
133      */

134     public VersionHistory getVersionHistory(NodeRef nodeRef)
135         throws AspectMissingException;
136     
137     /**
138      * Gets the version object for the current version of the node reference
139      * passed.
140      * <p>
141      * Returns null if the node is not versionable or has not been versioned.
142      * @param nodeRef the node reference
143      * @return the version object for the current version
144      */

145     public Version getCurrentVersion(NodeRef nodeRef);
146     
147     /**
148      * The node reference will be reverted to the current version.
149      * <p>
150      * A deep revert will be performed.
151      *
152      * @see VersionService#revert(NodeRef, Version, boolean)
153      *
154      * @param nodeRef the node reference
155      */

156     public void revert(NodeRef nodeRef);
157     
158     /**
159      * The node reference will be reverted to the current version.
160      *
161      * @see VersionService#revert(NodeRef, Version, boolean)
162      *
163      * @param nodeRef the node reference
164      * @param deep true if a deep revert is to be performed, flase otherwise
165      */

166     public void revert(NodeRef nodeRef, boolean deep);
167     
168     /**
169      * A deep revert will take place by default.
170      *
171      * @see VersionService#revert(NodeRef, Version, boolean)
172      *
173      * @param nodeRef the node reference
174      * @param version the version to revert to
175      */

176     public void revert(NodeRef nodeRef, Version version);
177     
178     /**
179      * Revert the state of the node to the specified version.
180      * <p>
181      * Any changes made to the node will be lost and the state of the node will reflect
182      * that of the version specified.
183      * <p>
184      * The version label property on the node reference will remain unchanged.
185      * <p>
186      * If the node is further versioned then the new version will be created at the head of
187      * the version history graph. A branch will not be created.
188      * <p>
189      * If a deep revert is to be performed then any child nodes that are no longer present will
190      * be deep restored (if appropriate) otherwise child associations to deleted, versioned nodes
191      * will not be restored.
192      *
193      * @param nodeRef the node reference
194      * @param version the version to revert to
195      * @param deep true is a deep revert is to be performed, false otherwise.
196      */

197     public void revert(NodeRef nodeRef, Version version, boolean deep);
198     
199     /**
200      * By default a deep restore is performed.
201      *
202      * @see org.alfresco.service.cmr.version.VersionService#restore(NodeRef, NodeRef, QName, QName, boolean)
203      *
204      * @param nodeRef the node reference to a node that no longer exists in the store
205      * @param parentNodeRef the new parent of the restored node
206      * @param assocTypeQName the assoc type qname
207      * @param assocQName the assoc qname
208      * @return the newly restored node reference
209      */

210     public NodeRef restore(
211             NodeRef nodeRef,
212             NodeRef parentNodeRef,
213             QName assocTypeQName,
214             QName assocQName);
215     
216     /**
217      * Restores a node not currenlty present in the store, but that has a version
218      * history.
219      * <p>
220      * The restored node will be at the head (most resent version).
221      * <p>
222      * Resoration will fail if there is no version history for the specified node id in
223      * the specified store.
224      * <p>
225      * If the node already exists in the store then an exception will be raised.
226      * <p>
227      * Once the node is restored it is reverted to the head version in the appropriate
228      * version history tree. If deep is set to true then this will be a deep revert, false
229      * otherwise.
230      *
231      * @param nodeRef the node reference to a node that no longer exists in
232      * the store
233      * @param parentNodeRef the new parent of the resotred node
234      * @param assocTypeQName the assoc type qname
235      * @param assocQName the assoc qname
236      * @param deep true is a deep revert shoudl be performed once the node has been
237      * restored, false otherwise
238      * @return the newly restored node reference
239      */

240     public NodeRef restore(
241             NodeRef nodeRef,
242             NodeRef parentNodeRef,
243             QName assocTypeQName,
244             QName assocQName,
245             boolean deep);
246     
247     /**
248      * Delete the version history associated with a node reference.
249      * <p>
250      * This operation is perminant, all versions in the version history are
251      * deleted and cannot be retrieved.
252      * <p>
253      * The current version label for the node reference is reset and any subsequent versions
254      * of the node will result in a new version history being created.
255      *
256      * @param nodeRef the node reference
257      * @throws AspectMissingException thrown if the version aspect is missing
258      */

259     public void deleteVersionHistory(NodeRef nodeRef)
260         throws AspectMissingException;
261 }
262
Popular Tags