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}