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  ;
20  import java.util.Collection  ;
21  import java.util.Map  ;
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   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  <String  , Serializable  > 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  <Version> createVersion(
99              NodeRef nodeRef, 
100             Map  <String  , Serializable  > 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  <Version> createVersion(
117             Collection  <NodeRef> nodeRefs, 
118             Map  <String  , Serializable  > 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags