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