001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.server.xdbm;
021    
022    
023    /**
024     * A master table used to store indexible entries.
025     *
026     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
027     * @version $Rev: 661851 $
028     */
029    public interface MasterTable<E> extends Table<Long, E>
030    {
031        /** the base name for the db file for this table */
032        String DBF = "master";
033    
034        /** the sequence key - stores last sequence value in the admin table */
035        String SEQPROP_KEY = "__sequence__";
036    
037    
038        /**
039         * Gets an entry from this MasterTable.
040         *
041         * @param id the BigInteger id of the entry to retrieve.
042         * @return the entry with operational attributes and all.
043         * @throws Exception if there is a read error on the underlying Db.
044         */
045        E get( Long id ) throws Exception;
046    
047    
048        /**
049         * Puts an entry into this MasterTable with a specified unique id.  Used
050         * both to create new entries and update existing ones.
051         *
052         * @param entry the entry to add
053         * @param id unique identifier of the entry to put
054         * @throws Exception if there is a write error on the underlying Db.
055         */
056        void put( Long id, E entry ) throws Exception;
057    
058    
059        /**
060         * Deletes a entry from this MasterTable at an index specified by id.
061         *
062         * @param id unique identifier of the entry to delete
063         * @return the deleted entry
064         * @throws Exception if there is a write error on the underlying Db
065         */
066        void delete( Long id ) throws Exception;
067    
068    
069        /**
070         * Gets the value of the id sequence from this MasterTable's sequence
071         * without affecting the value.
072         *
073         * @throws Exception if the admin table storing sequences cannot be read
074         */
075        Long getCurrentId() throws Exception;
076    
077    
078        /**
079         * Gets the next value from the sequence of this MasterTable.  This has
080         * the side-effect of incrementing the sequence values perminantly.
081         *
082         * @return the current value of this MasterTable's sequence incremented
083         * by one
084         * @throws Exception on failure to update the id sequence
085         */
086        Long getNextId() throws Exception;
087    
088    
089        /**
090         * Gets a persistant property associated with this MasterTable.
091         *
092         * @param property the key of the property to get the value of
093         * @return the value of the property
094         * @throws Exception on failure to read the property
095         */
096        String getProperty( String property ) throws Exception;
097    
098    
099        /**
100         * Sets a persistant property associated with this MasterTable.
101         *
102         * @param property the key of the property to set the value of
103         * @param value the value of the property
104         * @throws Exception on failure to write the property
105         */
106        void setProperty( String property, String value ) throws Exception;
107    }