001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.version;
005:
006: import javax.jcr.*;
007:
008: /**
009: * A <code>VersionHistory</code> object wraps an <code>nt:versionHistory</code>
010: * node. It provides convenient access to version history information.
011: */
012: public interface VersionHistory extends Node {
013:
014: /**
015: * Returns the identifier of the versionable node for which this is the version history.
016: *
017: * @deprecated As of JCR 2.0, {@link #getVersionableIdentifier} should
018: * be used instead.
019: *
020: * @return the identifier of the versionable node for which this is the version history.
021: * @throws RepositoryException if an error occurs.
022: */
023: public String getVersionableUUID() throws RepositoryException;
024:
025: /**
026: * Returns the identifier of the versionable node for which this is the version history.
027: *
028: * @return the identifier of the versionable node for which this is the version history.
029: * @throws RepositoryException if an error occurs.
030: * @since JCR 2.0
031: */
032: public String getVersionableIdentifier() throws RepositoryException;
033:
034: /**
035: * Returns the root version of this version history.
036: *
037: * @return a <code>Version</code> object.
038: * @throws RepositoryException if an error occurs.
039: */
040: public Version getRootVersion() throws RepositoryException;
041:
042: /**
043: * Returns an iterator over all the versions within this version history.
044: * The order of the returned objects will not necessarily correspond to the
045: * order of versions in terms of the successor relation. To traverse the
046: * version graph one must traverse the <code>jcr:successor REFERENCE</code>
047: * properties starting with the root version. A version history will always
048: * have at least one version, the root version. Therefore, this method will
049: * always return an iterator of at least size 1.
050: *
051: * @return a <code>VersionIterator</code> object.
052: * @throws RepositoryException if an error occurs.
053: */
054: public VersionIterator getAllVersions() throws RepositoryException;
055:
056: /**
057: * Returns an iterator over all the frozen nodes of all the versions of
058: * this version history. Under simple versioning the order of the returned
059: * nodes will be the order of their creation. Under full versioning the
060: * order is implementation-dependent.
061: *
062: * @return a <code>NodeIterator</code> object.
063: * @throws RepositoryException if an error occurs.
064: * @since JCR 2.0
065: */
066: public NodeIterator getAllFrozenNodes() throws RepositoryException;
067:
068: /**
069: * Retrieves a particular version from this version history by version name.
070: * <p/>
071: * Throws a <code>VersionException</code> if the specified version is not in
072: * this version history.
073: *
074: * @param versionName a version name
075: * @return a <code>Version</code> object.
076: * @throws VersionException if the specified version is not in this version history.
077: * @throws RepositoryException if an error occurs.
078: */
079: public Version getVersion(String versionName)
080: throws VersionException, RepositoryException;
081:
082: /**
083: * Retrieves a particular version from this version history by version label.
084: * <p/>
085: * Throws a <code>VersionException</code> if the specified <code>label</code> is not in
086: * this version history.
087: *
088: * @param label a version label
089: * @return a <code>Version</code> object.
090: * @throws VersionException if the specified <code>label</code> is not in this version history.
091: * @throws RepositoryException if an error occurs.
092: */
093: public Version getVersionByLabel(String label)
094: throws RepositoryException;
095:
096: /**
097: * Adds the specified label to the specified version. This corresponds to
098: * adding a reference property with a name specified by the <code>label</code>
099: * parameter to the <code>jcr:versionLabels</code> subnode of the
100: * <code>nt:versionHistory</code> node. The reference property points to the
101: * <code>nt:version</code> node that represents the specified version.
102: * <p/>
103: * Note that this change is made immediately; there is no need to call <code>save</code>.
104: * In fact, since the the version storage is read-only with respect to normal repository
105: * methods, <code>save</code> does not even function in this context.
106: * <p/>
107: * Within a particular version history, a given label may appear a maximum of once.
108: * If the specified label is already assigned to a version in this history and
109: * <code>moveLabel</code> is <code>true</code> then the label is removed from its
110: * current location and added to the version with the specified <code>versionName</code>.
111: * If <code>moveLabel</code> is <code>false</code>, then an attempt to add a label that
112: * already exists in this version history will throw a <code>LabelExistVersionException</code>.
113: * <p/>
114: * A <code>VersionException</code> is thrown if the named version is not in this
115: * <code>VersionHistory</code> or if it is the root version (<code>jcr:rootVersion</code>)
116: * or if the <code>label</code> specified is not a valid JCR <code>NAME</code>.
117: * @param versionName the name of the version to which the label is to be added.
118: * @param label the label to be added.
119: * @param moveLabel if <code>true</code>, then if <code>label</code> is already assigned to a version in
120: * this version history, it is moved to the new version specified; if <code>false</code>, then attempting
121: * to assign an already used label will throw a <code>VersionException</code>.
122: * @throws LabelExistsVersionException if <code>moveLabel</code> is <code>false</code>,
123: * and an attempt is made to add a label that already exists in this version history
124: * @throws VersionException if an attempt is made to add an existing label to a version history
125: * and <code>moveLabel</code> is <code>false</code> or if the specifed version does not exist in
126: * this version history or if the specified version is the root version (<code>jcr:rootVersion</code>).
127: * @throws RepositoryException if another error occurs.
128: */
129: public void addVersionLabel(String versionName, String label,
130: boolean moveLabel) throws LabelExistsVersionException,
131: VersionException, RepositoryException;
132:
133: /**
134: * Removes the specified label from among the labels of this version history.
135: * This corresponds to removing a property from the <code>jcr:versionLabels</code>
136: * child node of the <code>nt:versionHistory</code> node that represents this version
137: * history.
138: * <p/>
139: * Note that this change is made immediately; there is no need to call <code>save</code>.
140: * In fact, since the the version storage is read-only with respect to normal repository
141: * methods, <code>save</code> does not even function in this context.
142: * <p/>
143: * If a label is specified that does not exist in this version history,
144: * a <code>VersionException</code> is thrown.
145: *
146: * @param label a version label
147: * @throws VersionException if the name labvel does not exist in this version history.
148: * @throws RepositoryException if another error occurs.
149: */
150: public void removeVersionLabel(String label)
151: throws VersionException, RepositoryException;
152:
153: /**
154: * Returns <code>true</code> if any version in the history has the given <code>label</code>.
155: *
156: * @param label a version label
157: * @return a <code>boolean</code>.
158: * @throws RepositoryException if an error occurs.
159: */
160: public boolean hasVersionLabel(String label)
161: throws RepositoryException;
162:
163: /**
164: * Returns true if the given version has the given <code>label</code>.
165: * @param version a Version object
166: * @param label a version label
167: * @return a <code>boolean</code>.
168: * @throws VersionException if the specified <code>version</code> is not of this version history.
169: * @throws RepositoryException if another error occurs.
170: */
171: public boolean hasVersionLabel(Version version, String label)
172: throws VersionException, RepositoryException;
173:
174: /**
175: * Returns all version labels of the history or an empty array if there are none.
176: *
177: * @return a <code>String</code> array containing all the labels of the version history.
178: * @throws RepositoryException if an error occurs.
179: */
180: public String[] getVersionLabels() throws RepositoryException;
181:
182: /**
183: * Returns all version labels of the given <code>version</code> - empty array if none.
184: * Throws a <code>VersionException</code> if the specified <code>version</code> is not
185: * in this version history.
186: * @param version a Version object
187: * @return a <code>String</code> array containing all the labels of the given version
188: * @throws VersionException if the specified <code>version</code> is not in this version history.
189: * @throws RepositoryException if another error occurs.
190: */
191: public String[] getVersionLabels(Version version)
192: throws VersionException, RepositoryException;
193:
194: /**
195: * Removes the named version from this version history and automatically
196: * repairs the version graph. If the version to be removed is <code>V</code>, <code>V</code>'s
197: * predecessor set is <code>P</code> and <code>V</code>'s successor set is <code>S</code>, then
198: * the version graph is repaired s follows:
199: * <ul>
200: * <li>For each member of <code>P</code>, remove the reference to <code>V</code> from its
201: * successor list and add references to each member of <code>S</code>.
202: * <li>For each member of <code>S</code>, remove the reference to <code>V</code> from its
203: * predecessor list and add references to each member of <code>P</code>.
204: * </ul>
205: * Note that this change is made immediately; there is no need to call <code>save</code>.
206: * In fact, since the the version storage is read-only with respect to normal repository
207: * methods, <code>save</code> does not even function in this context.
208: * <p/>
209: * A <code>ReferentialIntegrityException</code> will be thrown if the specified version is
210: * currently the target of a <code>REFERENCE</code> property elsewhere in the repository
211: * (not just in this workspace) and the current <code>Session</code> has read access to
212: * that <code>REFERENCE</code> property.
213: * <p/>
214: * An <code>AccessDeniedException</code> will be thrown if the current <code>Session</code>
215: * does not have permission to remove the specified version or if the specified version is
216: * currently the target of a <code>REFERENCE</code> property elsewhere in the repository
217: * (not just in this workspace) and the current <code>Session</code> does not have read
218: * access to that <code>REFERENCE</code> property.
219: * <p/>
220: * Throws an <code>UnsupportedRepositoryOperationException</code> if this operation is
221: * not supported by the implementation.
222: * <p/>
223: * Throws a <code>VersionException</code> if the named version is not in this <code>VersionHistory</code>.
224: *
225: * @param versionName the name of a version in this version history.
226: * @throws ReferentialIntegrityException if the specified version is currently the target of a
227: * <code>REFERENCE</code> property elsewhere in the repository (not necessarily in this workspace)
228: * and the current <code>Session</code> has read access to that <code>REFERENCE</code> property.
229: * @throws AccessDeniedException if the current Session does not have permission to remove the
230: * specified version or if the specified version is currently the target of a <code>REFERENCE</code>
231: * property elsewhere in the repository (not just in this workspace) and the current <code>Session</code>
232: * does not have read access to that <code>REFERENCE</code> property.
233: * @throws UnsupportedRepositoryOperationException if this operation is not supported by the implementation.
234: * @throws VersionException if the named version is not in this version history.
235: * @throws RepositoryException if another error occurs.
236: */
237: public void removeVersion(String versionName)
238: throws ReferentialIntegrityException,
239: AccessDeniedException,
240: UnsupportedRepositoryOperationException, VersionException,
241: RepositoryException;
242: }
|