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.util.List;
020    
021    
022    /**
023     * Encodes objects to a page file and decodes them from a page file.
024     * 
025     * @author <a href="http://hiramchirino.com">Hiram Chirino</a>
026     * @param <T>
027     */
028    public interface PagedAccessor<T> {
029        
030        /**
031         * Store a value at the specified page.
032         * 
033         * Object encoding will be deferred as long as possible.  This allows multiple updates
034         * the the same page to avoid paying the cost of multiple encoding passes.  Only when
035         * the value is evicted from the cache or the page file is flushed, will the encoding
036         * take place.
037         * 
038         * Since the deferred encoding is no longer taking place in the context of a transaction,
039         * there are several restrictions of what pages the Marshaler can update so that transaction
040         * isolation is not violated:
041         * <ul> 
042         * <li>It can update the specified page<li>
043         * <li>It can allocate new pages and update or free those pages</li>
044         * </ul>
045         * 
046         * @param paged
047         * @param page
048         * @param value
049         * @return a list of any pages allocated by the method.
050         */
051        List<Integer> store(Paged paged, int page, T value);
052        
053        /**
054         * Load a value from a specified page.  It should not attempt do any
055         * update operations against the {@link Paged} object.
056         * 
057         * @param paged
058         * @param page
059         * @return
060         */
061        T load(Paged paged, int page);
062        
063        /**
064         * Returns a list of the pages linked to the specified page.
065         * 
066         * @param paged
067         * @param page
068         */
069        List<Integer> pagesLinked(Paged paged, int page);
070    }