1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * 19 */ 20 package org.apache.directory.server.core.changelog; 21 22 23 import java.util.List; 24 25 import org.apache.directory.server.core.DirectoryService; 26 import org.apache.directory.server.core.authn.LdapPrincipal; 27 import org.apache.directory.shared.ldap.ldif.LdifEntry; 28 29 30 /** 31 * A facade for the change log subsystem. It exposes the functionality 32 * needed to interact with the facility to query for changes, take snapshots, 33 * and revert the server to an earlier revision. 34 * 35 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 36 * @version $Rev$, $Date$ 37 */ 38 public interface ChangeLog 39 { 40 /** 41 * Checks whether or not the change log has been enabled to track changes. 42 * 43 * @return true if the change log is tracking changes, false otherwise 44 */ 45 boolean isEnabled(); 46 47 48 void setEnabled( boolean enabled ); 49 50 51 ChangeLogStore getChangeLogStore(); 52 53 54 void setChangeLogStore( ChangeLogStore store ); 55 56 57 /** 58 * Gets the current revision for the server. 59 * 60 * @return the current revision 61 * @throws Exception if there is a problem accessing this information 62 */ 63 long getCurrentRevision() throws Exception; 64 65 66 /** 67 * Records a change as a forward LDIF, a reverse change to revert the change and 68 * the authorized principal triggering the revertable change event. 69 * 70 * @param principal the authorized LDAP principal triggering the change 71 * @param forward LDIF of the change going to the next state 72 * @param reverse LDIF (anti-operation): the change required to revert this change 73 * @return the new revision reached after having applied the forward LDIF 74 * @throws Exception if there are problems logging the change 75 */ 76 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception; 77 78 79 /** 80 * Records a change as a forward LDIF, some reverse changes to revert the change and 81 * the authorized principal triggering the revertable change event. 82 * 83 * @param principal the authorized LDAP principal triggering the change 84 * @param forward LDIF of the change going to the next state 85 * @param reverses LDIF (anti-operation): the changes required to revert this change 86 * @return the new revision reached after having applied the forward LDIF 87 * @throws Exception if there are problems logging the change 88 */ 89 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception; 90 91 92 /** 93 * Returns whether or not this ChangeLogService supports searching for changes. 94 * 95 * @return true if log searching is supported, false otherwise 96 */ 97 boolean isLogSearchSupported(); 98 99 100 /** 101 * Returns whether or not this ChangeLogService supports searching for snapshot tags. 102 * 103 * @return true if snapshot tag searching is supported, false otherwise 104 */ 105 boolean isTagSearchSupported(); 106 107 108 /** 109 * Returns whether or not this ChangeLogService stores snapshot tags. 110 * 111 * @return true if this ChangeLogService supports tag storage, false otherwise 112 */ 113 boolean isTagStorageSupported(); 114 115 116 /** 117 * Gets the change log query engine which would be used to ask questions 118 * about what changed, when, how and by whom. It may not be supported by 119 * all implementations. Some implementations may simply log changes without 120 * direct access to those changes from within the server. 121 * 122 * @return the change log query engine 123 * @throws UnsupportedOperationException if the change log is not searchable 124 */ 125 ChangeLogSearchEngine getChangeLogSearchEngine(); 126 127 128 /** 129 * Gets the tag search engine used to query the snapshots taken. If this ChangeLogService 130 * does not support a taggable and searchable store then an UnsupportedOperationException 131 * will result. 132 * 133 * @return the snapshot query engine for this store 134 * @throws UnsupportedOperationException if the tag searching is not supported 135 */ 136 TagSearchEngine getTagSearchEngine(); 137 138 139 /** 140 * Creates a tag for a snapshot of the server in a specific state at a revision. 141 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it 142 * does not then it's up to callers to track this tag since it will not be stored 143 * by this service. 144 * 145 * @param revision the revision to tag the snapshot 146 * @return the Tag associated with the revision 147 * @throws Exception if there is a problem taking a tag 148 * @throws IllegalArgumentException if the revision is out of range (less than 0 149 * and greater than the current revision) 150 */ 151 Tag tag( long revision ) throws Exception; 152 153 154 /** 155 * Creates a tag for a snapshot of the server in a specific state at a revision. 156 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it 157 * does not then it's up to callers to track this tag since it will not be stored 158 * by this service. 159 * 160 * @param revision the revision to tag the snapshot 161 * @param description some information about what the snapshot tag represents 162 * @return the Tag associated with the revision 163 * @throws Exception if there is a problem taking a tag 164 * @throws IllegalArgumentException if the revision is out of range (less than 0 165 * and greater than the current revision) 166 */ 167 Tag tag( long revision, String description ) throws Exception; 168 169 170 /** 171 * Creates a snapshot of the server at the current revision. 172 * 173 * @param description some information about what the snapshot tag represents 174 * @return the revision at which the tag is created 175 * @throws Exception if there is a problem taking a tag 176 */ 177 Tag tag( String description ) throws Exception; 178 179 180 /** 181 * Creates a snapshot of the server at the current revision. 182 * 183 * @return the revision at which the tag is created 184 * @throws Exception if there is a problem taking a tag 185 */ 186 Tag tag() throws Exception; 187 188 Tag getLatest() throws Exception; 189 190 void init( DirectoryService service ) throws Exception; 191 192 void sync() throws Exception; 193 194 void destroy() throws Exception; 195 196 /** 197 * Exposes the contents of ChangeLog to clients if set to true. Default setting is false. 198 * 199 * @param exposeChangeLog true to expose the contents, false to not expose. 200 */ 201 void setExposeChangeLog( boolean exposeChangeLog ); 202 203 boolean isExposeChangeLog(); 204 205 /** 206 * The prefix of the partition. Default value is <i>ou=changelog</i>. 207 * 208 * @param suffix suffix value to be set for the changelog partition 209 */ 210 void setPartitionSuffix( String suffix ); 211 212 /** 213 * The name of the revisions container under the partition. Default value is ou=revisions 214 * 215 * @param revContainerName the name of the revisions container 216 */ 217 void setRevisionsContainerName( String revContainerName ); 218 219 /** 220 * The name of the tags container under the partition. Default value is ou=tags 221 * 222 * @param tagContainerName the name of the revisions container 223 */ 224 void setTagsContainerName( String tagContainerName ); 225 }