/*
* (C) Copyright 2006-2017 Nuxeo (http://nuxeo.com/) and others.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Contributors:
* Florent Guillaume
*/
package org.nuxeo.ecm.core.versioning;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import org.nuxeo.ecm.core.api.DocumentModel;
import org.nuxeo.ecm.core.api.VersioningOption;
import org.nuxeo.ecm.core.model.Document;
/**
* The versioning service holds the versioning policy used to define what happens to a document's version when it is
* created, saved, checked in, checked out or restored, and what version increment options (none, minor, major) are made
* available to the user.
*
* @since 5.4
*/
public interface VersioningService {
/** Document property in which the major version is stored. */
String MAJOR_VERSION_PROP = "uid:major_version";
/** Document property in which the minor version is stored. */
String MINOR_VERSION_PROP = "uid:minor_version";
/**
* Context data that can be used to skip versioning on document creation, in case the supplied version is enough.
*/
String SKIP_VERSIONING = "SKIP_VERSIONING";
/**
* Context data to provide a user-level choice to the versioning policy. Value is a {@link VersioningOption}.
*/
String VERSIONING_OPTION = "VersioningOption";
/**
* Context data to disable auto-checkout of checked-in documents at pre-save time. This option should only be used
* when updating a facet that's considered pure metadata and holds information about the document but external to
* it. Value is a {@link Boolean}.
*
* @since 5.7, 5.6.0-HF09
*/
String DISABLE_AUTO_CHECKOUT = "DisableAutoCheckOut";
/**
* Context data to provide a checkin comment for operations that potentially check in (save, publish, checkin).
*/
String CHECKIN_COMMENT = "CheckinComment";
/**
* Gets the version label to display for a given document.
*
* @param doc the document
* @return the version label, like {@code "2.1"}
*/
String getVersionLabel(DocumentModel doc);
/**
* Checks what options are available on a document at save time.
*
* @param doc the document
* @return the options, the first being the default
*/
List<VersioningOption> getSaveOptions(DocumentModel doc);
/**
* Applies versioning after document creation.
*
* @param doc the document
* @param options map event info
*/
void doPostCreate(Document doc, Map<String, Serializable> options);
/**
* Checks if {@link #doPreSave} will do a checkout when called with the same arguments.
* <p>
* Needed to be able to send "about to checkin" events.
*
* @param doc the document
* @param isDirty {@code true} if there is actual data to save
* @param option an option chosen by the user or framework
* @param options map event info and options
* @return {@code true} if {@link #doPreSave} will do a checkout
*/
boolean isPreSaveDoingCheckOut(Document doc, boolean isDirty, VersioningOption option,
Map<String, Serializable> options);
/**
* Applies versioning options before document save.
*
* @param doc the document
* @param isDirty {@code true} if there is actual data to save
* @param option an option chosen by the user or framework
* @param checkinComment a checkin comment
* @param options map event info
* @return the validated option (to use in doPostSave)
*/
VersioningOption doPreSave(Document doc, boolean isDirty, VersioningOption option, String checkinComment,
Map<String, Serializable> options);
/**
* Checks if {@link #doPostSave} will do a checkin when called with the same arguments.
*
* @param doc the document
* @param option an option chosen by the user or framework
* @param options map event info
* @return {@code true} if {@link #doPostSave} will do a checkin
*/
boolean isPostSaveDoingCheckIn(Document doc, VersioningOption option, Map<String, Serializable> options);
/**
* Applies versioning options after document save. If a new version is checked in during the operation, the document
* for this version is returned to the caller.
*
* @param doc the document
* @param option an option chosen by the user or framework
* @param checkinComment a checkin comment
* @param options map event info
* @return checkedInDocument or null
*/
Document doPostSave(Document doc, VersioningOption option, String checkinComment,
Map<String, Serializable> options);
/**
* Applies version increment option and does a checkin.
*
* @param doc the document
* @param option an option chosen by the user or framework
* @param checkinComment a checkin comment
* @return the version
*/
Document doCheckIn(Document doc, VersioningOption option, String checkinComment);
/**
* Apply modifications after doing a checkout.
*
* @param doc the document
*/
void doCheckOut(Document doc);
/**
* Does automatic versioning if a policy exists for the current input context. Currently automatic versioning is
* either before or after document update, never both.
*
* @param before the flag to trigger a before or after automatic versioning (used to retrieve the right policy)
* @since 9.1
*/
void doAutomaticVersioning(DocumentModel previousDocument, DocumentModel currentDocument, boolean before);
}