View Javadoc

1   /*
2    * Copyright 2004 Charles Blaxland
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package mnemosyne.core;
17  
18  
19  /***
20   * Interface for managing versions of a persistent object. Every persistent object
21   * instance has its own version manager.
22   *
23   * @version $Id: VersionCollection.java,v 1.1.1.1 2004/08/07 06:41:15 charlesblaxland Exp $
24   */
25  public interface VersionCollection
26  {
27      /***
28       * Returns the object as it appeared at the given version. Persistent objects
29       * do not necessarily have an instance for *every* version that is created. Only
30       * objects that actually changed in a particular version have instances that exactly
31       * match that version.
32       * <p/>
33       * If there is no version that matches exactly the version specified, then
34       * the last version previous to that is returned. This will be the
35       * version in which the object was last modified, or the version as at system
36       * startup if there have been no modifications.
37       *
38       * If there is no valid version found, a runtime exception is raised.
39       *
40       * @param versionToGet The version of the object to retrieve.
41       * @return The version of the object at the given version.
42       */
43      public Object retrieveVersion(Version versionToGet);
44  
45      /***
46       * Sets the value of this object at the given version.  If there is a current
47       * value of the object at the given version, it is replaced.  If there is no
48       * version of the object at the given version, a runtime exception is
49       * raised.
50       *
51       * @param version
52       * @param obj
53       */
54      public void replaceVersion(Version version, Object obj);
55  
56      /***
57       * Adds a new version of the object.  If there is a current value of the object
58       * at the given version, or if the given version is less than the latest version,
59       * a runtime exception is generated.
60       *
61       * @param version
62       * @param obj
63       */
64      public void addVersion(Version version, Object obj);
65  
66      /***
67       * Removes the given version of the object.  This is typically called by
68       * the version garbage collector to remove versions that are no longer being
69       * referenced by any threads.
70       * <p/>
71       * If the given version does not exist, no action is taken.
72       *
73       * @param version The version of the object to remove.
74       */
75      public void removeVersion(Version version);
76  
77      /***
78       * Returns the number of items in this collection.
79       * @return
80       */
81      public int size();
82  }