001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.directory.server.core.api.changelog; 021 022 023import java.util.List; 024 025import org.apache.directory.api.ldap.model.exception.LdapException; 026import org.apache.directory.api.ldap.model.ldif.LdifEntry; 027import org.apache.directory.server.core.api.DirectoryService; 028import org.apache.directory.server.core.api.LdapPrincipal; 029 030 031/** 032 * A facade for the change log subsystem. It exposes the functionality 033 * needed to interact with the facility to query for changes, take snapshots, 034 * and revert the server to an earlier revision. 035 * 036 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 037 */ 038public interface ChangeLog 039{ 040 /** 041 * Checks whether or not the change log has been enabled to track changes. 042 * 043 * @return true if the change log is tracking changes, false otherwise 044 */ 045 boolean isEnabled(); 046 047 048 /** 049 * Enable or disable the ChangeLog service 050 * @param enabled true to enable the service, flase to disable it 051 */ 052 void setEnabled( boolean enabled ); 053 054 055 /** 056 * @return The underlying storage 057 */ 058 ChangeLogStore getChangeLogStore(); 059 060 061 /** 062 * Set the underlying storage 063 * @param store The storage 064 */ 065 void setChangeLogStore( ChangeLogStore store ); 066 067 068 /** 069 * Gets the current revision for the server. 070 * 071 * @return the current revision 072 * @throws LdapException if there is a problem accessing this information 073 */ 074 long getCurrentRevision() throws LdapException; 075 076 077 /** 078 * Records a change as a forward LDIF, a reverse change to revert the change and 079 * the authorized principal triggering the revertable change event. 080 * 081 * @param principal the authorized LDAP principal triggering the change 082 * @param forward LDIF of the change going to the next state 083 * @param reverse LDIF (anti-operation): the change required to revert this change 084 * @return the new revision reached after having applied the forward LDIF 085 * @throws LdapException if there are problems logging the change 086 */ 087 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws LdapException; 088 089 090 /** 091 * Records a change as a forward LDIF, some reverse changes to revert the change and 092 * the authorized principal triggering the revertable change event. 093 * 094 * @param principal the authorized LDAP principal triggering the change 095 * @param forward LDIF of the change going to the next state 096 * @param reverses LDIF (anti-operation): the changes required to revert this change 097 * @return the new revision reached after having applied the forward LDIF 098 * @throws LdapException if there are problems logging the change 099 */ 100 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws LdapException; 101 102 103 /** 104 * Returns whether or not this ChangeLogService supports searching for changes. 105 * 106 * @return true if log searching is supported, false otherwise 107 */ 108 boolean isLogSearchSupported(); 109 110 111 /** 112 * Returns whether or not this ChangeLogService supports searching for snapshot tags. 113 * 114 * @return true if snapshot tag searching is supported, false otherwise 115 */ 116 boolean isTagSearchSupported(); 117 118 119 /** 120 * Returns whether or not this ChangeLogService stores snapshot tags. 121 * 122 * @return true if this ChangeLogService supports tag storage, false otherwise 123 */ 124 boolean isTagStorageSupported(); 125 126 127 /** 128 * Gets the change log query engine which would be used to ask questions 129 * about what changed, when, how and by whom. It may not be supported by 130 * all implementations. Some implementations may simply log changes without 131 * direct access to those changes from within the server. 132 * 133 * @return the change log query engine 134 * @throws UnsupportedOperationException if the change log is not searchable 135 */ 136 ChangeLogSearchEngine getChangeLogSearchEngine(); 137 138 139 /** 140 * Gets the tag search engine used to query the snapshots taken. If this ChangeLogService 141 * does not support a taggable and searchable store then an UnsupportedOperationException 142 * will result. 143 * 144 * @return the snapshot query engine for this store 145 * @throws UnsupportedOperationException if the tag searching is not supported 146 */ 147 TagSearchEngine getTagSearchEngine(); 148 149 150 /** 151 * Creates a tag for a snapshot of the server in a specific state at a revision. 152 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it 153 * does not then it's up to callers to track this tag since it will not be stored 154 * by this service. 155 * 156 * @param revision the revision to tag the snapshot 157 * @return the Tag associated with the revision 158 * @throws Exception if there is a problem taking a tag 159 * @throws IllegalArgumentException if the revision is out of range (less than 0 160 * and greater than the current revision) 161 */ 162 Tag tag( long revision ) throws Exception; 163 164 165 /** 166 * Creates a tag for a snapshot of the server in a specific state at a revision. 167 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it 168 * does not then it's up to callers to track this tag since it will not be stored 169 * by this service. 170 * 171 * @param revision the revision to tag the snapshot 172 * @param description some information about what the snapshot tag represents 173 * @return the Tag associated with the revision 174 * @throws Exception if there is a problem taking a tag 175 * @throws IllegalArgumentException if the revision is out of range (less than 0 176 * and greater than the current revision) 177 */ 178 Tag tag( long revision, String description ) throws Exception; 179 180 181 /** 182 * Creates a snapshot of the server at the current revision. 183 * 184 * @param description some information about what the snapshot tag represents 185 * @return the revision at which the tag is created 186 * @throws Exception if there is a problem taking a tag 187 */ 188 Tag tag( String description ) throws Exception; 189 190 191 /** 192 * Creates a snapshot of the server at the current revision. 193 * 194 * @return the revision at which the tag is created 195 * @throws Exception if there is a problem taking a tag 196 */ 197 Tag tag() throws Exception; 198 199 200 /** 201 * @return The latest tag 202 * @throws LdapException if there is a problem taking the latest tag 203 */ 204 Tag getLatest() throws LdapException; 205 206 207 /** 208 * Initialize the ChangeLog system. 209 * 210 * @param service The associated DirectoryService 211 * @throws LdapException If the initialization failed 212 */ 213 void init( DirectoryService service ) throws LdapException; 214 215 216 /** 217 * Flush the changes to disk 218 * @throws LdapException If the flush failed 219 */ 220 void sync() throws LdapException; 221 222 223 /** 224 * Destroy the changeLog 225 * 226 * @throws LdapException If the destroy failed 227 */ 228 void destroy() throws LdapException; 229 230 231 /** 232 * Exposes the contents of ChangeLog to clients if set to true. Default setting is false. 233 * 234 * @param exposed true to expose the contents, false to not expose. 235 */ 236 void setExposed( boolean exposed ); 237 238 239 /** 240 * @return true if the changeLog system is visible by clients 241 */ 242 boolean isExposed(); 243 244 245 /** 246 * The prefix of the partition. Default value is <i>ou=changelog</i>. 247 * 248 * @param suffix suffix value to be set for the changelog partition 249 */ 250 void setPartitionSuffix( String suffix ); 251 252 253 /** 254 * The name of the revisions container under the partition. Default value is ou=revisions 255 * 256 * @param revContainerName the name of the revisions container 257 */ 258 void setRevisionsContainerName( String revContainerName ); 259 260 261 /** 262 * The name of the tags container under the partition. Default value is ou=tags 263 * 264 * @param tagContainerName the name of the revisions container 265 */ 266 void setTagsContainerName( String tagContainerName ); 267}