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 */ 020 package org.apache.directory.server.core.changelog; 021 022 023 import java.util.List; 024 025 import org.apache.directory.server.core.LdapPrincipal; 026 import org.apache.directory.server.core.DirectoryService; 027 import org.apache.directory.shared.ldap.cursor.Cursor; 028 import org.apache.directory.shared.ldap.ldif.LdifEntry; 029 030 031 032 /** 033 * A store for change events on the directory which exposes methods for 034 * managing, querying and in general performing legal operations on the log. 035 * 036 * @org.apache.xbean.XBean 037 * 038 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 039 * @version $Rev$, $Date$ 040 */ 041 public interface ChangeLogStore 042 { 043 /** 044 * Initialize the store. 045 * 046 * @param service The associated DirectoryService 047 * @throws Exception If the initialization failed 048 */ 049 void init( DirectoryService service ) throws Exception; 050 051 052 /** 053 * Write the changes on disk 054 * 055 * @throws Exception If the write failed 056 */ 057 void sync() throws Exception; 058 059 060 /** 061 * Destroy the logs. 062 * 063 * @throws Exception If we can't destroy the logs 064 */ 065 void destroy() throws Exception; 066 067 068 /** 069 * Gets the current revision of the server (a.k.a. the HEAD revision). 070 * 071 * @return the current revision of the server 072 */ 073 long getCurrentRevision(); 074 075 076 /** 077 * Records a change as a forward LDIF, a reverse change to revert the change and 078 * the authorized principal triggering the revertable change event. 079 * 080 * @param principal the authorized LDAP principal triggering the change 081 * @param forward LDIF of the change going to the next state 082 * @param reverse LDIF (anti-operation): the change required to revert this change 083 * @return the new revision reached after having applied the forward LDIF 084 * @throws Exception if there are problems logging the change 085 */ 086 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception; 087 088 089 /** 090 * Records a change as a forward LDIF, some reverse changes to revert the change and 091 * the authorized principal triggering the revertable change event. 092 * 093 * @param principal the authorized LDAP principal triggering the change 094 * @param forward LDIF of the change going to the next state 095 * @param reverses LDIF (anti-operation): the changes required to revert this change 096 * @return the new revision reached after having applied the forward LDIF 097 * @throws Exception if there are problems logging the change 098 */ 099 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception; 100 101 102 /** 103 * Looks up the ChangeLogEvent for a revision. 104 * 105 * @param revision to get a ChangeLogEvent for 106 * @return the ChangeLogEvent associated with the revision 107 * @throws Exception if there are failures accessing the store 108 * @throws IllegalArgumentException if the revision is out of range (less than 0 109 * and greater than the current revision) 110 */ 111 ChangeLogEvent lookup( long revision ) throws Exception; 112 113 114 /** 115 * Gets a Cursor over all the ChangeLogEvents within the system since 116 * revision 0. 117 * 118 * This method should exhibit isolation characteristics: meaning if the 119 * request is initiated at revision 100, then any subsequent log entries 120 * increasing the revision should not be seen. 121 * 122 * @return a Cursor over all the ChangeLogEvents 123 * @throws Exception if there are failures accessing the store 124 */ 125 Cursor<ChangeLogEvent> find() throws Exception; 126 127 128 /** 129 * Gets a Cursor over the ChangeLogEvents that occurred before a revision 130 * exclusive. 131 * 132 * @param revision the revision number to get the ChangeLogEvents before 133 * @return a Cursor over the ChangeLogEvents before a revision 134 * @throws Exception if there are failures accessing the store 135 * @throws IllegalArgumentException if the revision is out of range (less than 0 136 * and greater than the current revision) 137 */ 138 Cursor<ChangeLogEvent> findBefore( long revision ) throws Exception; 139 140 141 /** 142 * Finds the ChangeLogEvents that occurred after a revision exclusive. 143 * 144 * This method should exhibit isolation characteristics: meaning if the request is 145 * initiated at revision 100 then any subsequent log entries increasing the revision 146 * should not be seen. 147 * 148 * @param revision the revision number to get the ChangeLogEvents after 149 * @return a Cursor of all the ChangeLogEvents after and including the revision 150 * @throws Exception if there are failures accessing the store 151 * @throws IllegalArgumentException if the revision is out of range (less than 0 152 * and greater than the current revision) 153 */ 154 Cursor<ChangeLogEvent> findAfter( long revision ) throws Exception; 155 156 157 /** 158 * Finds the ChangeLogEvents that occurred between a revision range inclusive. 159 * 160 * @param startRevision the revision number to start getting the ChangeLogEvents above 161 * @param endRevision the revision number to start getting the ChangeLogEvents below 162 * @return an enumeration of all the ChangeLogEvents within some revision range inclusive 163 * @throws Exception if there are failures accessing the store 164 * @throws IllegalArgumentException if the start and end revisions are out of range 165 * (less than 0 and greater than the current revision), or if startRevision > endRevision 166 */ 167 Cursor<ChangeLogEvent> find( long startRevision, long endRevision ) throws Exception; 168 }