You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ak...@apache.org on 2007/10/11 18:56:43 UTC
svn commit: r583879 -
/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/
Author: akarasulu
Date: Thu Oct 11 09:56:42 2007
New Revision: 583879
URL: http://svn.apache.org/viewvc?rev=583879&view=rev
Log:
changes to changelog interfaces ...
o added more javadocs and clarified semantics
o filled in the facade for the ChangeLogService
o cleaned up other javadocs
Modified:
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogEvent.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogSearchEngine.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogService.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogStore.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/Tag.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TagSearchEngine.java
directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TaggableChangeLogStore.java
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogEvent.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogEvent.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogEvent.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogEvent.java Thu Oct 11 09:56:42 2007
@@ -45,16 +45,17 @@
/**
* Creates a new instance of ChangeLogEvent.
*
- * @param the revision for the change
+ * @param revision the revision number for the change
* @param committer the authorized user which triggered the change
* @param forwardLdif the LDIF representing the change forward in time
* @param reverseLdif an LDIF which reverts the change going reverse in time to an earlier revision
+ * @param zuluTime the timestamp for when the change occurred in generalizedTime format
*/
- public ChangeLogEvent( long commitId, String zuluTime, LdapPrincipal committer,
+ public ChangeLogEvent( long revision, String zuluTime, LdapPrincipal committer,
Entry forwardLdif, Entry reverseLdif )
{
this.zuluTime = zuluTime;
- this.revision = commitId;
+ this.revision = revision;
this.forwardLdif = forwardLdif;
this.reverseLdif = reverseLdif;
this.committer = committer;
@@ -82,13 +83,15 @@
/**
* @return the committer
*/
- public LdapPrincipal getCommitter()
+ public LdapPrincipal getCommitterPrincipal()
{
return committer;
}
/**
+ * Gets the revision of this event.
+ *
* @return the revision
*/
public long getRevision()
@@ -98,7 +101,9 @@
/**
- * @return the zuluTime
+ * Gets the generalizedTime when this event occured.
+ *
+ * @return the zuluTime when this event occured
*/
public String getZuluTime()
{
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogSearchEngine.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogSearchEngine.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogSearchEngine.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogSearchEngine.java Thu Oct 11 09:56:42 2007
@@ -76,6 +76,8 @@
* @param revision to get a ChangeLogEvent for
* @return the ChangeLogEvent associated with the revision
* @throws NamingException if there are failures accessing the store
+ * @throws IllegalArgumentException if the revision is out of range (less than 0
+ * and greater than the current revision)
*/
ChangeLogEvent lookup( long revision ) throws NamingException;
@@ -97,6 +99,8 @@
* @param order the order in which to return ChangeLogEvents (ordered by revision number)
* @return an enumeration of all the ChangeLogEvents before and including some revision
* @throws NamingException if there are failures accessing the store
+ * @throws IllegalArgumentException if the revision is out of range (less than 0
+ * and greater than the current revision)
*/
NamingEnumeration<ChangeLogEvent> findBefore( long revision, RevisionOrder order ) throws NamingException;
@@ -108,6 +112,8 @@
* @param order the order in which to return ChangeLogEvents (ordered by revision number)
* @return an enumeration of all the ChangeLogEvents after and including the revision
* @throws NamingException if there are failures accessing the store
+ * @throws IllegalArgumentException if the revision is out of range (less than 0
+ * and greater than the current revision)
*/
NamingEnumeration<ChangeLogEvent> findAfter( long revision, RevisionOrder order ) throws NamingException;
@@ -120,6 +126,8 @@
* @param order the order in which to return ChangeLogEvents (ordered by revision number)
* @return an enumeration of all the ChangeLogEvents within some revision range inclusive
* @throws NamingException if there are failures accessing the store
+ * @throws IllegalArgumentException if the start and end revisions are out of range
+ * (less than 0 and greater than the current revision), or if startRevision > endRevision
*/
NamingEnumeration<ChangeLogEvent> find( long startRevision, long endRevision, RevisionOrder order )
throws NamingException;
@@ -218,7 +226,7 @@
* <li>scope (specialized) </li>
* </ul>
*
- * @param objectClass the objectClass definition for the entries to search changes for
+ * @param filter the filter to use for finding the change
* @param order the order in which to return ChangeLogEvents (ordered by revision number)
* @return the set of ChangeLogEvents on entries of a particular objectClass
* @throws NamingException if there are failures accessing the store
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogService.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogService.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogService.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogService.java Thu Oct 11 09:56:42 2007
@@ -20,13 +20,106 @@
package org.apache.directory.server.core.changelog;
+import javax.naming.NamingException;
+
+
/**
- * TODO ChangeLogService.
+ * 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>
* @version $Rev$, $Date$
*/
public interface ChangeLogService
{
+ /**
+ * Gets the current revision for the server.
+ *
+ * @return the current revision
+ * @throws NamingException if there is a problem accessing this information
+ */
+ long getCurrentRevision() throws NamingException;
+
+ /**
+ * 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 NamingException 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 NamingException;
+
+ /**
+ * Creates a snapshot of the server at the current revision.
+ *
+ * @return the revision at which the tag is created
+ * @throws NamingException if there is a problem taking a tag
+ */
+ Tag tag() throws NamingException;
+ /**
+ * Reverts the server's state to an earlier revision. Note that the revsion number
+ * still increases to revert back even though the state reverted to is the same.
+ * Note that implementations may lock the server from making changes or searching
+ * the directory until this operation has completed.
+ *
+ * @param revision the revision number to revert to
+ * @return the new revision reached by applying all changes needed to revert to the
+ * original state
+ * @throws NamingException if there are problems reverting back to the earlier state
+ * @throws IllegalArgumentException if the revision provided is greater than the current
+ * revision or less than 0
+ * @throws UnsupportedOperationException if this feature is not supported by the
+ * change log
+ */
+ long revert( long revision ) throws NamingException;
}
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogStore.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogStore.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogStore.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/ChangeLogStore.java Thu Oct 11 09:56:42 2007
@@ -19,6 +19,7 @@
*/
package org.apache.directory.server.core.changelog;
+
import javax.naming.NamingException;
import org.apache.directory.server.core.authn.LdapPrincipal;
@@ -35,7 +36,7 @@
public interface ChangeLogStore
{
/**
- * Get's the current revision of the server (a.k.a. the HEAD revision).
+ * Gets the current revision of the server (a.k.a. the HEAD revision).
*
* @return the current revision of the server
*/
@@ -49,7 +50,7 @@
* @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 commit id or revision representing the change within the log
- * @throws NamingException
+ * @throws NamingException if there are problems logging the change
*/
long log( LdapPrincipal principal, Entry forward, Entry reverse ) throws NamingException;
}
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/Tag.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/Tag.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/Tag.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/Tag.java Thu Oct 11 09:56:42 2007
@@ -31,7 +31,7 @@
{
/*
* TODO should we have date in which tag was taken
- * TODO should we have the date of the revision
+ * TODO should we have the date of the revision that was tagged
*/
private final long revision;
private final String description;
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TagSearchEngine.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TagSearchEngine.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TagSearchEngine.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TagSearchEngine.java Thu Oct 11 09:56:42 2007
@@ -53,12 +53,6 @@
*/
public interface TagSearchEngine
{
-
- // -----------------------------------------------------------------------
- // Tag Lookup Operations
- // -----------------------------------------------------------------------
-
-
/**
* Gets the tag for a specific snapshot if that snapshot exists.
*
@@ -101,6 +95,8 @@
* @param order the revision order in which to return snapshot tags
* @return an enumeration over the tags of all snapshots taken before a revision inclusive
* @throws NamingException if there is a problem accessing the store
+ * @throws IllegalArgumentException if the revision is greater than the current revision
+ * or less than 0.
*/
NamingEnumeration<Tag> findBefore( long revision, RevisionOrder order ) throws NamingException;
@@ -112,6 +108,8 @@
* @param order the revision order in which to return snapshot tags
* @return an enumeration over the tags of all snapshots taken after a revision inclusive
* @throws NamingException if there is a problem accessing the store
+ * @throws IllegalArgumentException if the revision is greater than the current revision
+ * or less than 0.
*/
NamingEnumeration<Tag> findAfter( long revision, RevisionOrder order ) throws NamingException;
@@ -120,9 +118,13 @@
* range inclusive. The first revision parameter should be less than or equal
* to the second revision parameter.
*
- * @param order the revision order in which to return snapshot tags
+ * @param startRevision the revision to start on inclusive
+ * @param endRevision the revision to end on inclusive
+ * @param order the revision order in which to return snapshot tags
* @return enumeration over all the snapshots taken in a revision range inclusive
* @throws NamingException if there is a problem accessing the store
+ * @throws IllegalArgumentException if the revision range is not constructed properly
+ * or if either revision number is greater than the current revision or less than 0.
*/
NamingEnumeration<Tag> find( long startRevision, long endRevision, RevisionOrder order )
throws NamingException;
Modified: directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TaggableChangeLogStore.java
URL: http://svn.apache.org/viewvc/directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TaggableChangeLogStore.java?rev=583879&r1=583878&r2=583879&view=diff
==============================================================================
--- directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TaggableChangeLogStore.java (original)
+++ directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/TaggableChangeLogStore.java Thu Oct 11 09:56:42 2007
@@ -35,8 +35,10 @@
/**
* Creates a tag for a snapshot of the server in a specific state at a revision.
*
- * @param the revision to tag the snapshot
- * @throws NamingException
+ * @param revision the revision to tag the snapshot
+ * @throws NamingException if there is a problem taking a tag, or if
+ * the revision does not exist
+ * @return the Tag associated with the revision
*/
Tag tag( long revision ) throws NamingException;
@@ -44,7 +46,7 @@
* Creates a snapshot of the server at the current revision.
*
* @return the revision at which the tag is created
- * @throws NamingException
+ * @throws NamingException if there is a problem taking a tag
*/
Tag tag() throws NamingException;
}