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.mavibot.btree;
21  
22  
23  import java.io.IOException;
24  
25  import org.apache.directory.mavibot.btree.exception.EndOfFileExceededException;
26  
27  
28  /**
29   * A Cursor is used to fetch elements in a BTree and is returned by the
30   * @see BTree#browse method. The cursor <strng>must</strong> be closed
31   * when the user is done with it.
32   * <p>
33   *
34   * @param <K> The type for the Key
35   * @param <V> The type for the stored value
36   * 
37   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
38   */
39  public interface TupleCursor<K, V> extends Cursor<K>
40  {
41      /**
42       * Tells if the cursor can return a next element
43       * 
44       * @return true if there are some more elements
45       * @throws IOException 
46       * @throws EndOfFileExceededException 
47       */
48      public boolean hasNext() throws EndOfFileExceededException, IOException;
49  
50      /**
51       * Find the next key/value
52       * 
53       * @return A Tuple containing the found key and value
54       * @throws IOException 
55       * @throws EndOfFileExceededException 
56       */
57      Tuple<K, V> next() throws EndOfFileExceededException, IOException;
58  
59  
60      /**
61       * Tells if the cursor can return a previous element
62       * 
63       * @return true if there are some more elements
64       * @throws IOException 
65       * @throws EndOfFileExceededException 
66       */
67      public boolean hasPrev() throws EndOfFileExceededException, IOException;
68      
69      
70      /**
71       * Find the previous key/value
72       * 
73       * @return A Tuple containing the found key and value
74       * @throws IOException 
75       * @throws EndOfFileExceededException 
76       */
77      Tuple<K, V> prev() throws EndOfFileExceededException, IOException;
78  
79  
80      /**
81       * Get the current revision
82       * 
83       * @return The revision this cursor is based on
84       */
85      long getRevision();
86  
87  
88      /**
89       * Get the creation date
90       * @return The creation date for this cursor
91       */
92      long getCreationDate();
93  
94  
95      /**
96       * Tells if the cursor can return a next key
97       * 
98       * @return true if there are some more keys
99       * @throws IOException 
100      * @throws EndOfFileExceededException 
101      */
102     public boolean hasNextKey() throws EndOfFileExceededException, IOException;
103     
104     
105     /**
106      * Get the next non-duplicate key.
107      * If the BTree contains :
108      * 
109      *  <ul>
110      *    <li><1,0></li>
111      *    <li><1,1></li>
112      *    <li><1,2></li>
113      *    <li><2,0></li>
114      *    <li><2,1></li>
115      *  </ul>
116      *   
117      *  and cursor is present at <1,1> then the returned tuple will be <2,0> (not <1,2>)
118      *  
119      * @return A Tuple containing the found key and value
120      * @throws EndOfFileExceededException
121      * @throws IOException
122      */
123     Tuple<K, V> nextKey() throws EndOfFileExceededException, IOException;
124 
125 
126     /**
127      * Tells if the cursor can return a previous key
128      * 
129      * @return true if there are some more keys
130      * @throws IOException 
131      * @throws EndOfFileExceededException 
132      */
133     public boolean hasPrevKey() throws EndOfFileExceededException, IOException;
134 
135     
136     /**
137      * Get the previous non-duplicate key.
138      * If the BTree contains :
139      * 
140      *  <ul>
141      *    <li><1,0></li>
142      *    <li><1,1></li>
143      *    <li><1,2></li>
144      *    <li><2,0></li>
145      *    <li><2,1></li>
146      *  </ul>
147      *   
148      *  and cursor is present at <2,1> then the returned tuple will be <1,0> (not <2,0>)
149      *  
150      * @return A Tuple containing the found key and value
151      * @throws EndOfFileExceededException
152      * @throws IOException
153      */
154     Tuple<K, V> prevKey() throws EndOfFileExceededException, IOException;
155     
156     
157     /**
158      * Change the position in the current cursor before the first key
159      */
160     void beforeFirst() throws IOException;
161     
162     
163     /**
164      * Change the position in the current cursor to set it after the last key
165      */
166     void afterLast() throws IOException;
167 }