View Javadoc
1   /*
2   Copyright (c) 2005 Health Market Science, Inc.
3   
4   Licensed under the Apache License, Version 2.0 (the "License");
5   you may not use this file except in compliance with the License.
6   You may obtain a copy of the License at
7   
8       http://www.apache.org/licenses/LICENSE-2.0
9   
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15  */
16  
17  package com.healthmarketscience.jackcess.impl;
18  
19  import java.io.Flushable;
20  import java.io.IOException;
21  import java.nio.ByteBuffer;
22  import java.nio.ByteOrder;
23  import java.nio.channels.Channel;
24  import java.nio.channels.FileChannel;
25  
26  
27  /**
28   * Reads and writes individual pages in a database file
29   * @author Tim McCune
30   */
31  public class PageChannel implements Channel, Flushable {
32    
33    static final int INVALID_PAGE_NUMBER = -1;
34  
35    static final ByteOrder DEFAULT_BYTE_ORDER = ByteOrder.LITTLE_ENDIAN;
36    
37    /** invalid page header, used when deallocating old pages.  data pages
38        generally have 4 interesting bytes at the beginning which we want to
39        reset. */
40    private static final byte[] INVALID_PAGE_BYTE_HEADER =
41      new byte[]{PageTypes.INVALID, (byte)0, (byte)0, (byte)0};
42    
43    /** Global usage map always lives on page 1 */
44    static final int PAGE_GLOBAL_USAGE_MAP = 1;
45    /** Global usage map always lives at row 0 */
46    static final int ROW_GLOBAL_USAGE_MAP = 0;
47    
48    /** Channel containing the database */
49    private final FileChannel _channel;
50    /** whether or not the _channel should be closed by this class */
51    private final boolean _closeChannel;
52    /** Format of the database in the channel */
53    private final JetFormat _format;
54    /** whether or not to force all writes to disk immediately */
55    private final  boolean _autoSync;
56    /** buffer used when deallocating old pages.  data pages generally have 4
57        interesting bytes at the beginning which we want to reset. */
58    private final ByteBuffer _invalidPageBytes =
59      ByteBuffer.wrap(INVALID_PAGE_BYTE_HEADER);
60    /** dummy buffer used when allocating new pages */
61    private final ByteBuffer _forceBytes = ByteBuffer.allocate(1);
62    /** Tracks free pages in the database. */
63    private UsageMap _globalUsageMap;
64    /** handler for the current database encoding type */
65    private CodecHandler _codecHandler = DefaultCodecProvider.DUMMY_HANDLER;
66    /** temp page buffer used when pages cannot be partially encoded */
67    private TempPageHolder _fullPageEncodeBufferH;
68    private TempBufferHolder _tempDecodeBufferH;
69    private int _writeCount;
70    
71    /**
72     * Only used by unit tests
73     */
74    protected PageChannel(boolean testing) {
75      if(!testing) {
76        throw new IllegalArgumentException();
77      }
78      _channel = null;
79      _closeChannel = false;
80      _format = JetFormat.VERSION_4;
81      _autoSync = false;
82    }
83  
84    /**
85     * @param channel Channel containing the database
86     * @param format Format of the database in the channel
87     */
88    public PageChannel(FileChannel channel, boolean closeChannel,
89                       JetFormat format, boolean autoSync)
90      throws IOException
91    {
92      _channel = channel;
93      _closeChannel = closeChannel;
94      _format = format;
95      _autoSync = autoSync;
96    }
97  
98    /**
99     * Does second-stage initialization, must be called after construction.
100    */
101   public void initialize(DatabaseImpl database, CodecProvider codecProvider)
102     throws IOException
103   {
104     // initialize page en/decoding support
105     _codecHandler = codecProvider.createHandler(this, database.getCharset());
106     if(!_codecHandler.canEncodePartialPage()) {
107       _fullPageEncodeBufferH =
108         TempPageHolder.newHolder(TempBufferHolder.Type.SOFT);
109     }
110     if(!_codecHandler.canDecodeInline()) {
111       _tempDecodeBufferH = TempBufferHolder.newHolder(
112           TempBufferHolder.Type.SOFT, true);
113     }
114 
115     // note the global usage map is a special map where any page outside of
116     // the current range is assumed to be "on"
117     _globalUsageMap = UsageMap.read(database, PAGE_GLOBAL_USAGE_MAP,
118                                     ROW_GLOBAL_USAGE_MAP, true);
119   }
120   
121   public JetFormat getFormat() {
122     return _format;
123   }
124 
125   public boolean isAutoSync() {
126     return _autoSync;
127   }
128 
129   /**
130    * Begins a "logical" write operation.  See {@link #finishWrite} for more
131    * details.
132    */
133   public void startWrite() {
134     ++_writeCount;
135   }
136 
137   /**
138    * Begins an exclusive "logical" write operation (throws an exception if
139    * another write operation is outstanding).  See {@link #finishWrite} for
140    * more details.
141    */
142   public void startExclusiveWrite() {
143     if(_writeCount != 0) {
144       throw new IllegalArgumentException(
145           "Another write operation is currently in progress");
146     }
147     startWrite();
148   }
149 
150   /**
151    * Completes a "logical" write operation.  This method should be called in
152    * finally block which wraps a logical write operation (which is preceded by
153    * a {@link #startWrite} call).  Logical write operations may be nested.  If
154    * the database is configured for "auto-sync", the channel will be flushed
155    * when the outermost operation is complete,
156    */
157   public void finishWrite() throws IOException {
158     assertWriting();
159     if((--_writeCount == 0) && _autoSync) {
160       flush();
161     }
162   }
163 
164   /**
165    * Returns {@code true} if a logical write operation is in progress, {@code
166    * false} otherwise.
167    */
168   public boolean isWriting() {
169     return(_writeCount > 0);
170   }
171 
172   /**
173    * Asserts that a write operation is in progress.
174    */
175   private void assertWriting() {
176     if(!isWriting()) {
177       throw new IllegalStateException("No write operation in progress");
178     }
179   }
180   
181   /**
182    * Returns the next page number based on the given file size.
183    */
184   private int getNextPageNumber(long size) {
185     return (int)(size / getFormat().PAGE_SIZE);
186   }
187 
188   /**
189    * Returns the offset for a page within the file.
190    */
191   private long getPageOffset(int pageNumber) {
192     return((long) pageNumber * (long) getFormat().PAGE_SIZE);
193   }
194   
195   /**
196    * Validates that the given pageNumber is valid for this database.
197    */
198   private void validatePageNumber(int pageNumber)
199     throws IOException
200   {
201     int nextPageNumber = getNextPageNumber(_channel.size());
202     if((pageNumber <= INVALID_PAGE_NUMBER) || (pageNumber >= nextPageNumber)) {
203       throw new IllegalStateException("invalid page number " + pageNumber);
204     }
205   }
206   
207   /**
208    * @param buffer Buffer to read the page into
209    * @param pageNumber Number of the page to read in (starting at 0)
210    */
211   public void readPage(ByteBuffer buffer, int pageNumber)
212     throws IOException
213   {
214     validatePageNumber(pageNumber);
215 
216     ByteBuffer inPage = buffer;
217     ByteBuffer outPage = buffer;
218     if((pageNumber != 0) && !_codecHandler.canDecodeInline()) {
219       inPage = _tempDecodeBufferH.getPageBuffer(this);
220       outPage.clear();
221     }
222 
223     inPage.clear();
224     int bytesRead = _channel.read(
225         inPage, (long) pageNumber * (long) getFormat().PAGE_SIZE);
226     inPage.flip();
227     if(bytesRead != getFormat().PAGE_SIZE) {
228       throw new IOException("Failed attempting to read " +
229                             getFormat().PAGE_SIZE + " bytes from page " +
230                             pageNumber + ", only read " + bytesRead);
231     }
232 
233     if(pageNumber == 0) {
234       // de-mask header (note, page 0 never has additional encoding)
235       applyHeaderMask(buffer);
236     } else {
237       _codecHandler.decodePage(inPage, outPage, pageNumber);
238     }
239   }
240   
241   /**
242    * Write a page to disk
243    * @param page Page to write
244    * @param pageNumber Page number to write the page to
245    */
246   public void writePage(ByteBuffer page, int pageNumber) throws IOException {
247     writePage(page, pageNumber, 0);
248   }
249   
250   /**
251    * Write a page (or part of a page) to disk
252    * @param page Page to write
253    * @param pageNumber Page number to write the page to
254    * @param pageOffset offset within the page at which to start writing the
255    *                   page data
256    */
257   public void writePage(ByteBuffer page, int pageNumber, int pageOffset)
258     throws IOException
259   {
260     assertWriting();
261     validatePageNumber(pageNumber);
262     
263     page.rewind().position(pageOffset);
264 
265     int writeLen = page.remaining();
266     if((writeLen + pageOffset) > getFormat().PAGE_SIZE) {
267       throw new IllegalArgumentException(
268           "Page buffer is too large, size " + (writeLen + pageOffset));
269     }
270     
271     ByteBuffer encodedPage = page;
272     if(pageNumber == 0) {
273       // re-mask header
274       applyHeaderMask(page);
275     } else {
276 
277       if(!_codecHandler.canEncodePartialPage()) {
278         if((pageOffset > 0) && (writeLen < getFormat().PAGE_SIZE)) {
279 
280           // current codec handler cannot encode part of a page, so need to
281           // copy the modified part into the current page contents in a temp
282           // buffer so that we can encode the entire page
283           ByteBuffer fullPage = _fullPageEncodeBufferH.setPage(
284               this, pageNumber);
285 
286           // copy the modified part to the full page
287           fullPage.position(pageOffset);
288           fullPage.put(page);
289           fullPage.rewind();
290 
291           // reset so we can write the whole page
292           page = fullPage;
293           pageOffset = 0;
294           writeLen = getFormat().PAGE_SIZE;
295 
296         } else {
297 
298           _fullPageEncodeBufferH.possiblyInvalidate(pageNumber, null);
299         }
300       }
301 
302       // re-encode page
303       encodedPage = _codecHandler.encodePage(page, pageNumber, pageOffset);
304 
305       // reset position/limit in case they were affected by encoding
306       encodedPage.position(pageOffset).limit(pageOffset + writeLen);
307     }
308 
309     try {
310       _channel.write(encodedPage, (getPageOffset(pageNumber) + pageOffset));
311     } finally {
312       if(pageNumber == 0) {
313         // de-mask header
314         applyHeaderMask(page);
315       }
316     }
317   }
318   
319   /**
320    * Allocates a new page in the database.  Data in the page is undefined
321    * until it is written in a call to {@link #writePage(ByteBuffer,int)}.
322    */
323   public int allocateNewPage() throws IOException {
324     assertWriting();
325 
326     // this will force the file to be extended with mostly undefined bytes
327     long size = _channel.size();
328     if(size >= getFormat().MAX_DATABASE_SIZE) {
329       throw new IOException("Database is at maximum size " +
330                             getFormat().MAX_DATABASE_SIZE);
331     }
332     if((size % getFormat().PAGE_SIZE) != 0L) {
333       throw new IOException("Database corrupted, file size " + size +
334                             " is not multiple of page size " +
335                             getFormat().PAGE_SIZE);
336     }
337     
338     _forceBytes.rewind();
339     
340     // push the buffer to the end of the page, so that a full page's worth of
341     // data is written
342     int pageOffset = (getFormat().PAGE_SIZE - _forceBytes.remaining());
343     long offset = size + pageOffset;
344     int pageNumber = getNextPageNumber(size);
345 
346     // since we are just allocating page space at this point and not writing
347     // meaningful data, we do _not_ encode the page.
348     _channel.write(_forceBytes, offset);
349 
350     _globalUsageMap.removePageNumber(pageNumber);
351     return pageNumber;
352   }
353 
354   /**
355    * Deallocate a previously used page in the database.
356    */
357   public void deallocatePage(int pageNumber) throws IOException {
358     assertWriting();
359 
360     validatePageNumber(pageNumber);
361     
362     // don't write the whole page, just wipe out the header (which should be
363     // enough to let us know if we accidentally try to use an invalid page)
364     _invalidPageBytes.rewind();
365     _channel.write(_invalidPageBytes, getPageOffset(pageNumber));
366     
367     _globalUsageMap.addPageNumber(pageNumber);  //force is done here
368   }
369   
370   /**
371    * @return A newly-allocated buffer that can be passed to readPage
372    */
373   public ByteBuffer createPageBuffer() {
374     return createBuffer(getFormat().PAGE_SIZE);
375   }
376 
377   /**
378    * @return A newly-allocated buffer of the given size and DEFAULT_BYTE_ORDER
379    *         byte order
380    */
381   public static ByteBuffer createBuffer(int size) {
382     return createBuffer(size, DEFAULT_BYTE_ORDER);
383   }
384   
385   /**
386    * @return A newly-allocated buffer of the given size and byte order
387    */
388   public static ByteBuffer createBuffer(int size, ByteOrder order) {
389     return ByteBuffer.allocate(size).order(order);
390   }
391   
392   public void flush() throws IOException {
393     _channel.force(true);
394   }
395   
396   public void close() throws IOException {
397     flush();
398     if(_closeChannel) {
399       _channel.close();
400     }
401   }
402   
403   public boolean isOpen() {
404     return _channel.isOpen();
405   }
406 
407   /**
408    * Applies the XOR mask to the database header in the given buffer.
409    */
410   private void applyHeaderMask(ByteBuffer buffer) {
411       // de/re-obfuscate the header
412       byte[] headerMask = _format.HEADER_MASK;
413       for(int idx = 0; idx < headerMask.length; ++idx) {
414         int pos = idx + _format.OFFSET_MASKED_HEADER;
415         byte b = (byte)(buffer.get(pos) ^ headerMask[idx]);
416         buffer.put(pos, b);
417       }
418   }
419   
420   /**
421    * @return a duplicate of the current buffer narrowed to the given position
422    *         and limit.  mark will be set at the current position.
423    */
424   public static ByteBuffer narrowBuffer(ByteBuffer buffer, int position,
425                                         int limit)
426   {
427     return (ByteBuffer)buffer.duplicate()
428       .order(buffer.order())
429       .clear()
430       .limit(limit)
431       .position(position)
432       .mark();
433   }
434 
435   /**
436    * Returns a ByteBuffer wrapping the given bytes and configured with the
437    * default byte order.
438    */
439   public static ByteBuffer wrap(byte[] bytes) {
440     return ByteBuffer.wrap(bytes).order(DEFAULT_BYTE_ORDER);
441   }
442 }