| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| */ |
| package org.apache.directory.server.core.api.changelog; |
| |
| |
| import java.util.List; |
| |
| import org.apache.directory.api.ldap.model.exception.LdapException; |
| import org.apache.directory.api.ldap.model.ldif.LdifEntry; |
| import org.apache.directory.server.core.api.DirectoryService; |
| import org.apache.directory.server.core.api.LdapPrincipal; |
| |
| |
| /** |
| * A facade for the change log subsystem. It exposes the functionality |
| * needed to interact with the facility to query for changes, take snapshots, |
| * and revert the server to an earlier revision. |
| * |
| * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> |
| */ |
| public interface ChangeLog |
| { |
| /** |
| * Checks whether or not the change log has been enabled to track changes. |
| * |
| * @return true if the change log is tracking changes, false otherwise |
| */ |
| boolean isEnabled(); |
| |
| |
| /** |
| * Enable or disable the ChangeLog service |
| * @param enabled true to enable the service, flase to disable it |
| */ |
| void setEnabled( boolean enabled ); |
| |
| |
| /** |
| * @return The underlying storage |
| */ |
| ChangeLogStore getChangeLogStore(); |
| |
| |
| /** |
| * Set the underlying storage |
| * @param store The storage |
| */ |
| void setChangeLogStore( ChangeLogStore store ); |
| |
| |
| /** |
| * Gets the current revision for the server. |
| * |
| * @return the current revision |
| * @throws Exception if there is a problem accessing this information |
| */ |
| long getCurrentRevision() throws LdapException; |
| |
| |
| /** |
| * Records a change as a forward LDIF, a reverse change to revert the change and |
| * the authorized principal triggering the revertable change event. |
| * |
| * @param principal the authorized LDAP principal triggering the change |
| * @param forward LDIF of the change going to the next state |
| * @param reverse LDIF (anti-operation): the change required to revert this change |
| * @return the new revision reached after having applied the forward LDIF |
| * @throws Exception if there are problems logging the change |
| */ |
| ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws LdapException; |
| |
| |
| /** |
| * Records a change as a forward LDIF, some reverse changes to revert the change and |
| * the authorized principal triggering the revertable change event. |
| * |
| * @param principal the authorized LDAP principal triggering the change |
| * @param forward LDIF of the change going to the next state |
| * @param reverses LDIF (anti-operation): the changes required to revert this change |
| * @return the new revision reached after having applied the forward LDIF |
| * @throws Exception if there are problems logging the change |
| */ |
| ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws LdapException; |
| |
| |
| /** |
| * Returns whether or not this ChangeLogService supports searching for changes. |
| * |
| * @return true if log searching is supported, false otherwise |
| */ |
| boolean isLogSearchSupported(); |
| |
| |
| /** |
| * Returns whether or not this ChangeLogService supports searching for snapshot tags. |
| * |
| * @return true if snapshot tag searching is supported, false otherwise |
| */ |
| boolean isTagSearchSupported(); |
| |
| |
| /** |
| * Returns whether or not this ChangeLogService stores snapshot tags. |
| * |
| * @return true if this ChangeLogService supports tag storage, false otherwise |
| */ |
| boolean isTagStorageSupported(); |
| |
| |
| /** |
| * Gets the change log query engine which would be used to ask questions |
| * about what changed, when, how and by whom. It may not be supported by |
| * all implementations. Some implementations may simply log changes without |
| * direct access to those changes from within the server. |
| * |
| * @return the change log query engine |
| * @throws UnsupportedOperationException if the change log is not searchable |
| */ |
| ChangeLogSearchEngine getChangeLogSearchEngine(); |
| |
| |
| /** |
| * Gets the tag search engine used to query the snapshots taken. If this ChangeLogService |
| * does not support a taggable and searchable store then an UnsupportedOperationException |
| * will result. |
| * |
| * @return the snapshot query engine for this store |
| * @throws UnsupportedOperationException if the tag searching is not supported |
| */ |
| TagSearchEngine getTagSearchEngine(); |
| |
| |
| /** |
| * Creates a tag for a snapshot of the server in a specific state at a revision. |
| * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it |
| * does not then it's up to callers to track this tag since it will not be stored |
| * by this service. |
| * |
| * @param revision the revision to tag the snapshot |
| * @return the Tag associated with the revision |
| * @throws Exception if there is a problem taking a tag |
| * @throws IllegalArgumentException if the revision is out of range (less than 0 |
| * and greater than the current revision) |
| */ |
| Tag tag( long revision ) throws Exception; |
| |
| |
| /** |
| * Creates a tag for a snapshot of the server in a specific state at a revision. |
| * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it |
| * does not then it's up to callers to track this tag since it will not be stored |
| * by this service. |
| * |
| * @param revision the revision to tag the snapshot |
| * @param description some information about what the snapshot tag represents |
| * @return the Tag associated with the revision |
| * @throws Exception if there is a problem taking a tag |
| * @throws IllegalArgumentException if the revision is out of range (less than 0 |
| * and greater than the current revision) |
| */ |
| Tag tag( long revision, String description ) throws Exception; |
| |
| |
| /** |
| * Creates a snapshot of the server at the current revision. |
| * |
| * @param description some information about what the snapshot tag represents |
| * @return the revision at which the tag is created |
| * @throws Exception if there is a problem taking a tag |
| */ |
| Tag tag( String description ) throws Exception; |
| |
| |
| /** |
| * Creates a snapshot of the server at the current revision. |
| * |
| * @return the revision at which the tag is created |
| * @throws Exception if there is a problem taking a tag |
| */ |
| Tag tag() throws Exception; |
| |
| |
| /** |
| * @return The latest tag |
| * @throws Exception if there is a problem taking the latest tag |
| */ |
| Tag getLatest() throws LdapException; |
| |
| |
| /** |
| * Initialize the ChangeLog system. |
| * |
| * @param service The associated DirectoryService |
| * @throws Exception |
| */ |
| void init( DirectoryService service ) throws Exception; |
| |
| |
| /** |
| * Flush the changes to disk |
| * @throws Exception If the flush failed |
| */ |
| void sync() throws Exception; |
| |
| |
| /** |
| * Destroy the changeLog |
| * @throws Exception |
| */ |
| void destroy() throws Exception; |
| |
| |
| /** |
| * Exposes the contents of ChangeLog to clients if set to true. Default setting is false. |
| * |
| * @param exposed true to expose the contents, false to not expose. |
| */ |
| void setExposed( boolean exposed ); |
| |
| |
| /** |
| * @return true if the changeLog system is visible by clients |
| */ |
| boolean isExposed(); |
| |
| |
| /** |
| * The prefix of the partition. Default value is <i>ou=changelog</i>. |
| * |
| * @param suffix suffix value to be set for the changelog partition |
| */ |
| void setPartitionSuffix( String suffix ); |
| |
| |
| /** |
| * The name of the revisions container under the partition. Default value is ou=revisions |
| * |
| * @param revContainerName the name of the revisions container |
| */ |
| void setRevisionsContainerName( String revContainerName ); |
| |
| |
| /** |
| * The name of the tags container under the partition. Default value is ou=tags |
| * |
| * @param tagContainerName the name of the revisions container |
| */ |
| void setTagsContainerName( String tagContainerName ); |
| } |