| /* |
| * 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.partition.impl.btree; |
| |
| |
| import javax.naming.NamingEnumeration; |
| import javax.naming.NamingException; |
| |
| |
| /** |
| * A wrapper interface around a BTree (that does not support duplicate keys) which |
| * transparently enables duplicate keys and translates underlying exceptions to |
| * NamingExceptions. |
| * |
| * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> |
| * @version $Rev$ |
| */ |
| public interface Table |
| { |
| /** |
| * Gets the comparator used by this Table: may be null if this Table was |
| * not initialized with one. |
| * |
| * @return the final comparator instance or null if this Table was not |
| * created with one. |
| */ |
| TupleComparator getComparator(); |
| |
| |
| /** |
| * Gets the data renderer used by this Table to display or log records keys |
| * and values. |
| * |
| * @return the renderer used |
| */ |
| TupleRenderer getRenderer(); |
| |
| |
| /** |
| * Sets the data renderer to by used by this Table to display or log record |
| * keys and values. |
| * |
| * @param renderer the DataRenderer instance to used as the renderer. |
| */ |
| void setRenderer( TupleRenderer renderer ); |
| |
| |
| /** |
| * Gets the name of this Table. |
| * |
| * @return the name |
| */ |
| String getName(); |
| |
| |
| /** |
| * Checks to see if this Table has enabled the use of duplicate keys. |
| * |
| * @return true if duplicate keys are enabled, false otherwise. |
| */ |
| boolean isDupsEnabled(); |
| |
| |
| /** |
| * Checks to see if this Table has enabled sorting on the values of |
| * duplicate keys. |
| * |
| * @return true if duplicate key values are sorted, false otherwise. |
| */ |
| boolean isSortedDupsEnabled(); |
| |
| |
| // ------------------------------------------------------------------------ |
| // Simple Table Key/Value Assertions |
| // ------------------------------------------------------------------------ |
| |
| |
| /** |
| * Checks to see if this table has a key: same as a get call with a check to |
| * see if the returned value is null or not. |
| * |
| * @param key the Object of the key to check for |
| * @return true if the key exists, false otherwise. |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| boolean has( Object key ) throws NamingException; |
| |
| |
| /** |
| * Checks to see if this table has a key with a specific value. |
| * |
| * @param key the key Object to check for |
| * @param value the value Object to check for |
| * @return true if a record with the key and value exists, false otherwise. |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| boolean has( Object key, Object value ) throws NamingException; |
| |
| |
| /** |
| * Checks to see if this table has a record with a key greater/less than or |
| * equal to the key argument. The key argument need not exist for this |
| * call to return true. The underlying database must be a BTree because |
| * this method depends on the use of sorted keys. |
| * |
| * @param key the key Object to compare keys to |
| * @param isGreaterThan boolean for greater than or less then comparison |
| * @return true if a record with a key greater/less than the key argument |
| * exists, false otherwise |
| * @throws NamingException if there is a failure to read the underlying Db, |
| * or if the underlying Db is not a Btree. |
| */ |
| boolean has( Object key, boolean isGreaterThan ) throws NamingException; |
| |
| |
| /** |
| * Checks to see if this table has a record with a key equal to the |
| * argument key with a value greater/less than or equal to the value |
| * argument provided. The key argument <strong>MUST</strong> exist for |
| * this call to return true and the underlying Db must be a Btree that |
| * allows for sorted duplicate values. The entire basis to this method |
| * depends on the fact that duplicate key values are sorted according to |
| * a valid value comparator function. |
| * |
| * If the table does not support duplicates then an |
| * UnsupportedOperationException is thrown. |
| * |
| * @param key the key Object |
| * @param val the value Object to compare values to |
| * @param isGreaterThan boolean for greater than or less then comparison |
| * @return true if a record with a key greater/less than the key argument |
| * exists, false otherwise |
| * @throws NamingException if there is a failure to read the underlying Db |
| * or if the underlying Db is not of the Btree type that allows sorted |
| * duplicate values. |
| */ |
| boolean has( Object key, Object val, boolean isGreaterThan ) throws NamingException; |
| |
| |
| // ------------------------------------------------------------------------ |
| // Table Value Accessors/Mutators |
| // ------------------------------------------------------------------------ |
| |
| /** |
| * Gets the value of a record by key if the key exists. If this Table |
| * allows duplicate keys then the first key will be returned. If this |
| * Table is also a Btree that first key will be the smallest key in the |
| * Table as specificed by this Table's comparator or the default berkeley |
| * bytewise lexical comparator. |
| * |
| * @param key the key of the record |
| * @return the value of the record with key if key exists or null if |
| * no such record exists. |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| Object get( Object key ) throws NamingException; |
| |
| |
| /** |
| * Puts a record into this Table. |
| * |
| * @param key the key of the record |
| * @param value the value of the record. |
| * @return the last value present for key or null if this the key did not |
| * exist before. |
| * @throws NamingException if there is a failure to read or write to |
| * the underlying Db |
| */ |
| Object put( Object key, Object value ) throws NamingException; |
| |
| |
| /** |
| * Efficiently puts a set of values into the Table. If the Table does not |
| * support duplicate keys then only the first key within the enumeration is |
| * added. If there are more elements left after this single addition an |
| * UnsupportedOperationException is thrown. Nothing is added if the table |
| * does not support duplicates and there is more than one element in the |
| * enumeration. |
| * |
| * @param key the key to use for the values |
| * @param values the values supplied as an enumeration |
| * @throws NamingException if something goes wrong |
| */ |
| Object put( Object key, NamingEnumeration<? extends Object> values ) throws NamingException; |
| |
| |
| /** |
| * Removes all records with key from this Table. |
| * |
| * @param key the key of the records to remove |
| * @throws NamingException if there is a failure to read or write to |
| * the underlying Db |
| */ |
| Object remove( Object key ) throws NamingException; |
| |
| |
| /** |
| * Removes a single specific record with key and value from this Table. |
| * |
| * @param key the key of the record to remove |
| * @param value the value of the record to remove |
| * @throws NamingException if there is a failure to read or write to |
| * the underlying Db |
| */ |
| Object remove( Object key, Object value ) throws NamingException; |
| |
| |
| /** |
| * Removes a set of values with the same key from this Table. If this |
| * table does not allow duplicates the method will attempt to remove the |
| * first value in the enumeration if one exists. If there is more than one |
| * value within the enumeration after the first drop an |
| * UnsupportedOperationException is thrown. Nothing is removed if there is |
| * more than one element on the enumeration and the table does not support |
| * duplicates. |
| * |
| * @param key the key of the records to remove |
| * @return the first value removed |
| * @throws NamingException if there is a failure to read or write to |
| * the underlying Db |
| */ |
| Object remove( Object key, NamingEnumeration<? extends Object> values ) throws NamingException; |
| |
| |
| /** |
| * Sets a enumeration to the first record in the Table with a key value of |
| * key and enables single next steps across all duplicate records with |
| * this key. This enumeration will only iterate over duplicates of the key. |
| * Unlike listTuples(Object) which returns Tuples from the enumerations |
| * this just returns the values of the key. |
| * |
| * @param key the key to iterate over |
| * @throws NamingException if the underlying browser could not be set |
| */ |
| NamingEnumeration<Object> listValues( Object key ) throws NamingException; |
| |
| |
| // ------------------------------------------------------------------------ |
| // listTuples overloads |
| // ------------------------------------------------------------------------ |
| |
| |
| /** |
| * Sets a cursor to the first record in the Table and enables single |
| * next steps across all records. |
| * |
| * @throws NamingException if the underlying cursor could not be set. |
| */ |
| NamingEnumeration<Tuple> listTuples() throws NamingException; |
| |
| |
| /** |
| * Sets a cursor to the first record in the Table with a key value of |
| * key and enables single next steps across all duplicate records with |
| * this key. This cursor will only iterate over duplicates of the key. |
| * |
| * @param key the key to iterate over |
| * @throws NamingException if the underlying cursor could not be set |
| */ |
| NamingEnumeration<Tuple> listTuples( Object key ) throws NamingException; |
| |
| |
| /** |
| * Sets a cursor to the first record in the Table with a key value |
| * greater/less than or equal to key and enables single next steps across |
| * all records with key values equal to or less/greater than key. |
| * |
| * @param key the key to use to position this cursor to record with a key |
| * greater/less than or equal to it |
| * @param isGreaterThan if true the cursor iterates up over ascending keys |
| * greater than or equal to the key argument, but if false this cursor |
| * iterates down over descending keys less than or equal to key argument |
| * @throws NamingException if the underlying cursor could not be set |
| */ |
| NamingEnumeration<Tuple> listTuples( Object key, boolean isGreaterThan ) throws NamingException; |
| |
| |
| /** |
| * Sets a cursor to the first record in the Table with a key equal to |
| * the key argument whose value is greater/less than or equal to val and |
| * enables single next steps across all records with key equal to key. |
| * Hence this cursor will only iterate over duplicate keys where values are |
| * less than or greater than or equal to val. |
| * |
| * If the table does not support duplicates then an |
| * UnsupportedOperationException is thrown. |
| * |
| * @param key the key to use to position this cursor to record with a key |
| * equal to it. |
| * @param val the value to use to position this cursor to record with a |
| * value greater/less than or equal to it. |
| * @param isGreaterThan if true the cursor iterates up over ascending |
| * values greater than or equal to the val argument, but if false this |
| * cursor iterates down over descending values less than or equal to val |
| * argument starting from the largest value going down |
| * @throws NamingException if the underlying cursor could not be set or |
| * this method is called over a cursor on a table that does not have sorted |
| * duplicates enabled. |
| */ |
| NamingEnumeration<Tuple> listTuples( Object key, Object val, boolean isGreaterThan ) throws NamingException; |
| |
| |
| // ------------------------------------------------------------------------ |
| // Table Record Count Methods |
| // ------------------------------------------------------------------------ |
| |
| /** |
| * Gets the count of the number of records in this Table. |
| * |
| * @return the number of records |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| int count() throws NamingException; |
| |
| |
| /** |
| * Gets the count of the number of records in this Table with a specific |
| * key: returns the number of duplicates for a key. |
| * |
| * @param key the Object key to count. |
| * @return the number of duplicate records for a key. |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| int count( Object key ) throws NamingException; |
| |
| |
| /** |
| * Returns the number of records greater than or less than a key value. The |
| * key need not exist for this call to return a non-zero value. |
| * |
| * @param key the Object key to count. |
| * @param isGreaterThan boolean set to true to count for greater than and |
| * equal to record keys, or false for less than or equal to keys. |
| * @return the number of keys greater or less than key. |
| * @throws NamingException if there is a failure to read the underlying Db |
| */ |
| int count( Object key, boolean isGreaterThan ) throws NamingException; |
| |
| |
| /** |
| * Closes the underlying Db of this Table. |
| * |
| * @throws NamingException on any failures |
| */ |
| void close() throws NamingException; |
| } |