View Javadoc

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 org.apache.directory.server.core.cursor.Cursor;
24  
25  
26  /**
27   * An optional search interface supported by TaggableChangeLogStores.  This 
28   * interface enables the:
29   * 
30   * <ul>
31   *   <li>lookup of tags by revision</li>
32   *   <li>finding all tags</li>
33   *   <li>finding tags before or after a revision</li>
34   *   <li>finding tags in some revision range</li>
35   * </ul>
36   * 
37   * While investigating these interface methods keep in mind that only one 
38   * tag can exist on a revision.  Unlike subversion which allows multiple 
39   * tags on a revision we only allow at most one: more than one is pointless.
40   * 
41   * Date wise searches for tags are not present within this interface since 
42   * they should be used in conjunction with the ChangeLogSearchEngine which
43   * is by default supported by TaggableSearchableChangeLogStores.  The 
44   * ChangeLogSearchEngine can find revisions based on time descriptors and
45   * returned revisions can be checked for the presence of tags using this
46   * interface.  The whole point to enabling both search engines in a single
47   * interfaces is because if you can search for tags you should be able to 
48   * search for revisions: however the converse may not be the case.
49   * 
50   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
51   * @version $Rev$, $Date$
52   */
53  public interface TagSearchEngine
54  {
55      /**
56       * Gets the tag for a specific snapshot if that snapshot exists. 
57       *
58       * @param revision the revision number to use to check for a snapshot
59       * @return the snapshot at the revision if one exists, otherwise null
60       * @throws Exception if there is a problem accessing the store
61       */
62      Tag lookup( long revision ) throws Exception;
63      
64      /**
65       * Checks to see if a snapshot exists for a specific revision. 
66       *
67       * @param revision the revision number to use to check for a snapshot
68       * @return true if a snapshot exists at the revision, false otherwise
69       * @throws Exception if there is a problem accessing the store
70       */
71      boolean has( long revision ) throws Exception;
72  
73  
74      // -----------------------------------------------------------------------
75      // Tag Search Operations
76      // -----------------------------------------------------------------------
77  
78      
79      /**
80       * Finds all the snapshot tags taken since revision 0 until the current 
81       * revision.
82       *
83       * @param order the revision order in which to return snapshot tags 
84       * @return a cursor containing the tags of all snapshots taken since revision 1
85       * @throws Exception if there is a problem accessing the store
86       */
87      Cursor<Tag> find( RevisionOrder order ) throws Exception;
88      
89      /**
90       * Finds all the snapshot tags taken before a specific revision.  If a tag 
91       * exists at the revision parameter it will be returned as well.
92       *
93       * @param revision the revision number to get snapshots before 
94       * @param order the revision order in which to return snapshot tags 
95       * @return an enumeration over the tags of all snapshots taken before a revision inclusive
96       * @throws Exception if there is a problem accessing the store
97       * @throws IllegalArgumentException if the revision is greater than the current revision
98       * or less than 0.
99       */
100     Cursor<Tag> findBefore( long revision, RevisionOrder order ) throws Exception;
101     
102     /**
103      * Finds all the snapshot tags taken after a specific revision.  If a tag 
104      * exists at the revision parameter it will be returned as well.
105      *
106      * @param revision the revision number to get snapshots after
107      * @param order the revision order in which to return snapshot tags 
108      * @return an enumeration over the tags of all snapshots taken after a revision inclusive
109      * @throws Exception if there is a problem accessing the store
110      * @throws IllegalArgumentException if the revision is greater than the current revision
111      * or less than 0.
112      */
113     Cursor<Tag> findAfter( long revision, RevisionOrder order ) throws Exception;
114     
115     /**
116      * Enumerates over the tags of all snapshots taken between a specific revision 
117      * range inclusive.  The first revision parameter should be less than or equal 
118      * to the second revision parameter.
119      *
120      * @param startRevision the revision to start on inclusive
121      * @param endRevision the revision to end on inclusive
122      * @param order the revision order in which to return snapshot tags
123      * @return enumeration over all the snapshots taken in a revision range inclusive
124      * @throws Exception if there is a problem accessing the store
125      * @throws IllegalArgumentException if the revision range is not constructed properly
126      * or if either revision number is greater than the current revision or less than 0.
127      */
128     Cursor<Tag> find( long startRevision, long endRevision, RevisionOrder order ) 
129         throws Exception;
130 }