001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
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 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.versioning;
020
021import java.io.Serializable;
022import java.util.List;
023import java.util.Map;
024
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.VersioningOption;
027import org.nuxeo.ecm.core.model.Document;
028
029/**
030 * The versioning service holds the versioning policy used to define what happens to a document's version when it is
031 * created, saved, checked in, checked out or restored, and what version increment options (none, minor, major) are made
032 * available to the user.
033 *
034 * @since 5.4
035 */
036public interface VersioningService {
037
038    /** Document property in which the major version is stored. */
039    String MAJOR_VERSION_PROP = "uid:major_version";
040
041    /** Document property in which the minor version is stored. */
042    String MINOR_VERSION_PROP = "uid:minor_version";
043
044    /**
045     * Context data that can be used to skip versioning on document creation, in case the supplied version is enough.
046     */
047    String SKIP_VERSIONING = "SKIP_VERSIONING";
048
049    /**
050     * Context data to provide a user-level choice to the versioning policy. Value is a {@link VersioningOption}.
051     */
052    String VERSIONING_OPTION = "VersioningOption";
053
054    /**
055     * Context data to disable auto-checkout of checked-in documents at pre-save time. This option should only be used
056     * when updating a facet that's considered pure metadata and holds information about the document but external to
057     * it. Value is a {@link Boolean}.
058     *
059     * @since 5.7, 5.6.0-HF09
060     */
061    String DISABLE_AUTO_CHECKOUT = "DisableAutoCheckOut";
062
063    /**
064     * Context data to provide a checkin comment for operations that potentially check in (save, publish, checkin).
065     */
066    String CHECKIN_COMMENT = "CheckinComment";
067
068    /**
069     * Gets the version label to display for a given document.
070     *
071     * @param doc the document
072     * @return the version label, like {@code "2.1"}
073     */
074    String getVersionLabel(DocumentModel doc);
075
076    /**
077     * Checks what options are available on a document at save time.
078     *
079     * @param doc the document
080     * @return the options, the first being the default
081     */
082    List<VersioningOption> getSaveOptions(DocumentModel doc);
083
084    /**
085     * Applies versioning after document creation.
086     *
087     * @param doc the document
088     * @param context map event info
089     */
090    void doPostCreate(Document doc, Map<String, Serializable> options);
091
092    /**
093     * Checks if {@link #doPreSave} will do a checkout when called with the same arguments.
094     * <p>
095     * Needed to be able to send "about to checkin" events.
096     *
097     * @param doc the document
098     * @param isDirty {@code true} if there is actual data to save
099     * @param option an option chosen by the user or framework
100     * @param options map event info and options
101     * @return {@code true} if {@link #doPreSave} will do a checkout
102     */
103    boolean isPreSaveDoingCheckOut(Document doc, boolean isDirty, VersioningOption option,
104            Map<String, Serializable> options);
105
106    /**
107     * Applies versioning options before document save.
108     *
109     * @param doc the document
110     * @param isDirty {@code true} if there is actual data to save
111     * @param option an option chosen by the user or framework
112     * @param checkinComment a checkin comment
113     * @param context map event info
114     * @return the validated option (to use in doPostSave)
115     */
116    VersioningOption doPreSave(Document doc, boolean isDirty, VersioningOption option, String checkinComment,
117            Map<String, Serializable> options);
118
119    /**
120     * Checks if {@link #doPostSave} will do a checkin when called with the same arguments.
121     *
122     * @param doc the document
123     * @param option an option chosen by the user or framework
124     * @param options map event info
125     * @return {@code true} if {@link #doPostSave} will do a checkin
126     */
127    boolean isPostSaveDoingCheckIn(Document doc, VersioningOption option, Map<String, Serializable> options);
128
129    /**
130     * Applies versioning options after document save. If a new version is checked in during the operation, the document
131     * for this version is returned to the caller.
132     *
133     * @param doc the document
134     * @param option an option chosen by the user or framework
135     * @param checkinComment a checkin comment
136     * @param context map event info
137     * @return checkedInDocument or null
138     */
139    Document doPostSave(Document doc, VersioningOption option, String checkinComment,
140            Map<String, Serializable> options);
141
142    /**
143     * Applies version increment option and does a checkin.
144     *
145     * @param doc the document
146     * @param option an option chosen by the user or framework
147     * @param checkinComment a checkin comment
148     * @return the version
149     */
150    Document doCheckIn(Document doc, VersioningOption option, String checkinComment);
151
152    /**
153     * Apply modifications after doing a checkout.
154     *
155     * @param doc the document
156     */
157    void doCheckOut(Document doc);
158
159}