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 }