001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.fusesource.hawtdb.api;
018    
019    import java.nio.ByteBuffer;
020    
021    import org.fusesource.hawtbuf.Buffer;
022    
023    /**
024     * Implemented by objects which provides block io access to pages on file.
025     * 
026     * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
027     */
028    public interface Paged {
029    
030        /**
031         * @return An object which provides access to allocate/deallocate pages.
032         */
033        Allocator allocator();
034        
035        /**
036         * does the same as allocator().alloc(1)
037         * @return a newly allocated page location.
038         */
039        int alloc();
040    
041        /**
042         * does the same as allocator().free(page, 1)
043         */
044        void free(int page);
045    
046        enum SliceType {
047            READ, WRITE, READ_WRITE
048        }
049    
050        /**
051         * Provides direct access to the memory associated with a page. Specifying
052         * the correct mode argument is especially critical and the Paged resources
053         * is being accessed in a transaction context so that the transaction can
054         * maintain snapshot isolation.
055         * 
056         * @param mode
057         *            how will the buffer be used.
058         * @param pageId
059         *            the starting page of the buffer
060         * @param count
061         *            the number of pages to include in the buffer.
062         * @return
063         * @throws IOPagingException
064         */
065        public ByteBuffer slice(SliceType mode, int pageId, int count) throws IOPagingException;
066    
067        public void unslice(ByteBuffer buffer);
068    
069        /**
070         * Copies the contents of a page into the buffer space. The buffer offset
071         * will be updated to reflect the amount of data copied into the buffer.
072         * 
073         * @param pageId
074         * @param buffer
075         */
076        public void read(int pageId, Buffer buffer);
077    
078        /**
079         * Copies the buffer into the page. The buffer offset will be updated to
080         * reflect the amount of data copied to the page.
081         * 
082         * @param pageId
083         * @param buffer
084         */
085        public void write(int pageId, Buffer buffer);
086        
087        /**
088         * @return the maximum number of bytes that be read or written to a page.
089         */
090        int getPageSize();
091    
092        /**
093         * @return the number of pages that would be required to store the specified
094         *         number of bytes
095         */
096        int pages(int length);
097        
098        void flush();
099        
100        
101        /**
102         * Gets an object previously put at the given page.  The returned object SHOULD NEVER be mutated.
103         *  
104         * @param page
105         * @return
106         */
107        <T> T get(PagedAccessor<T> pagedAccessor, int page);
108        
109        /**
110         * Put an object at a given page.  The supplied object SHOULD NEVER be mutated 
111         * once it has been stored.
112         * 
113         * @param page
114         * @param value
115         */
116        <T> void put(PagedAccessor<T> pagedAccessor, int page, T value);
117        
118        /**
119         * Frees any pages associated with the value stored at the given page if any.  Does not free
120         * the page supplied.
121         *  
122         * @param page
123         * @return
124         */
125        <T> void clear(PagedAccessor<T> pagedAccessor, int page);
126    
127    }