directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: r583879 - /directory/apacheds/branches/bigbang/core/src/main/java/org/apache/directory/server/core/changelog/
Date Thu, 11 Oct 2007 16:56:43 GMT
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;
 }



Mime
View raw message