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