001/*
002 *  Copyright 2010 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.repository.version;
017
018import java.util.Date;
019
020import org.ametys.plugins.repository.AmetysObject;
021import org.ametys.plugins.repository.AmetysRepositoryException;
022import org.ametys.plugins.repository.UnknownAmetysObjectException;
023
024/**
025 * {@link AmetysObject} that is versioned and knows about its revisions and labels.
026 */
027public interface VersionAwareAmetysObject extends AmetysObject
028{
029    /**
030     * List all revisions of this object. Revisions are ordered in chronological order.
031     * @return the list of revisions (can be empty, but not <code>null</code>)
032     * @throws AmetysRepositoryException if the revisions cannot be known.
033     */
034    public String[] getAllRevisions() throws AmetysRepositoryException;
035
036    /**
037     * List all labels that exist on this object, whatever the revision.
038     * @return the list of all labels (can be empty, but not <code>null</code>).
039     * @throws AmetysRepositoryException if the labels cannot be known.
040     */
041    public String[] getAllLabels() throws AmetysRepositoryException;
042
043    /**
044     * Get the revision of this object, if any.
045     * @return the revision or null if this is the latest.
046     * @throws AmetysRepositoryException if the revision cannot be known.
047     */
048    public String getRevision() throws AmetysRepositoryException;
049
050    /**
051     * Get the creation time of the current revision, if any.
052     * @return the revision creation time, or null if there's no current revision.
053     * @throws AmetysRepositoryException if an error occurs
054     */
055    public Date getRevisionTimestamp() throws AmetysRepositoryException;
056
057    /**
058     * Get the creation time of the given revision.
059     * @param revision the revision.
060     * @return the revision creation date.
061     * @throws UnknownAmetysObjectException if the given revision does not exist for this object.
062     * @throws AmetysRepositoryException if an error occurs
063     */
064    public Date getRevisionTimestamp(String revision) throws AmetysRepositoryException;
065
066    /**
067     * Get the labels for this object, in the current revision (a single revision can hold several labels).
068     * @return the list of labels for this revision (can be empty, but not <code>null</code>).
069     * @throws AmetysRepositoryException if the labels cannot be known.
070     */
071    public String[] getLabels() throws AmetysRepositoryException;
072
073    /**
074     * Get the labels for this object fot the given revision (a single revision can hold several labels).
075     * @param revision the revision
076     * @return the list of labels for this revision (can be empty, but not <code>null</code>).
077     * @throws UnknownAmetysObjectException if the given revision does not exist for this object.
078     * @throws AmetysRepositoryException if the labels cannot be known.
079     */
080    public String[] getLabels(String revision) throws UnknownAmetysObjectException, AmetysRepositoryException;
081    
082    /**
083     * Switch to the revision corresponding to the specified label.<br>
084     * All subsequent method calls on this {@link AmetysObject} will concern that version.
085     * @param label the label to switch to, or null to specify the current version
086     * @throws UnknownAmetysObjectException if the label does not correspond to any revision
087     * @throws AmetysRepositoryException if a problem occurs
088     */
089    public void switchToLabel(String label) throws UnknownAmetysObjectException, AmetysRepositoryException;
090
091    /**
092     * Switch to the revision corresponding to the specified revision.<br>
093     * All subsequent method calls on this {@link AmetysObject} will concern that version.
094     * @param revision the revision, or null to specify the current version
095     * @throws UnknownAmetysObjectException if the revision does not exist
096     * @throws AmetysRepositoryException if a problem occurs
097     */
098    public void switchToRevision(String revision) throws UnknownAmetysObjectException, AmetysRepositoryException;
099}