1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2000,2008 Oracle. All rights reserved. 5 * 6 * $Id: TupleBase.java,v 12.6 2008/01/08 20:58:36 bostic Exp $ 7 */ 8 9package com.sleepycat.bind.tuple; 10 11import com.sleepycat.db.DatabaseEntry; 12 13/** 14 * A base class for tuple bindings and tuple key creators that provides control 15 * over the allocation of the output buffer. 16 * 17 * <p>Tuple bindings and key creators append data to a {@link TupleOutput} 18 * instance, which is also a {@link com.sleepycat.util.FastOutputStream} 19 * instance. This object has a byte array buffer that is resized when it is 20 * full. The reallocation of this buffer can be a performance factor for 21 * some applications using large objects. To manage this issue, the {@link 22 * #setTupleBufferSize} method may be used to control the initial size of the 23 * buffer, and the {@link #getTupleOutput} method may be overridden by 24 * subclasses to take over creation of the TupleOutput object.</p> 25 */ 26public class TupleBase { 27 28 private int outputBufferSize; 29 30 /** 31 * Initializes the initial output buffer size to zero. 32 * 33 * <p>Unless {@link #setTupleBufferSize} is called, the default {@link 34 * com.sleepycat.util.FastOutputStream#DEFAULT_INIT_SIZE} size will be 35 * used.</p> 36 */ 37 public TupleBase() { 38 outputBufferSize = 0; 39 } 40 41 /** 42 * Sets the initial byte size of the output buffer that is allocated by the 43 * default implementation of {@link #getTupleOutput}. 44 * 45 * <p>If this property is zero (the default), the default {@link 46 * com.sleepycat.util.FastOutputStream#DEFAULT_INIT_SIZE} size is used.</p> 47 * 48 * @param byteSize the initial byte size of the output buffer, or zero to 49 * use the default size. 50 */ 51 public void setTupleBufferSize(int byteSize) { 52 outputBufferSize = byteSize; 53 } 54 55 /** 56 * Returns the initial byte size of the output buffer. 57 * 58 * @return the initial byte size of the output buffer. 59 * 60 * @see #setTupleBufferSize 61 */ 62 public int getTupleBufferSize() { 63 return outputBufferSize; 64 } 65 66 /** 67 * Returns an empty TupleOutput instance that will be used by the tuple 68 * binding or key creator. 69 * 70 * <p>The default implementation of this method creates a new TupleOutput 71 * with an initial buffer size that can be changed using the {@link 72 * #setTupleBufferSize} method.</p> 73 * 74 * <p>This method may be overridden to return a TupleOutput instance. For 75 * example, an instance per thread could be created and returned by this 76 * method. If a TupleOutput instance is reused, be sure to call its 77 * {@link com.sleepycat.util.FastOutputStream#reset} method before each 78 * use.</p> 79 * 80 * @param object is the object to be written to the tuple output, and may 81 * be used by subclasses to determine the size of the output buffer. 82 * 83 * @return an empty TupleOutput instance. 84 * 85 * @see #setTupleBufferSize 86 */ 87 protected TupleOutput getTupleOutput(Object object) { 88 int byteSize = getTupleBufferSize(); 89 if (byteSize != 0) { 90 return new TupleOutput(new byte[byteSize]); 91 } else { 92 return new TupleOutput(); 93 } 94 } 95 96 /** 97 * Utility method to set the data in a entry buffer to the data in a tuple 98 * output object. 99 * 100 * @param output is the source tuple output object. 101 * 102 * @param entry is the destination entry buffer. 103 */ 104 public static void outputToEntry(TupleOutput output, DatabaseEntry entry) { 105 106 entry.setData(output.getBufferBytes(), output.getBufferOffset(), 107 output.getBufferLength()); 108 } 109 110 /** 111 * Utility method to set the data in a entry buffer to the data in a tuple 112 * input object. 113 * 114 * @param input is the source tuple input object. 115 * 116 * @param entry is the destination entry buffer. 117 */ 118 public static void inputToEntry(TupleInput input, DatabaseEntry entry) { 119 120 entry.setData(input.getBufferBytes(), input.getBufferOffset(), 121 input.getBufferLength()); 122 } 123 124 /** 125 * Utility method to create a new tuple input object for reading the data 126 * from a given buffer. If an existing input is reused, it is reset before 127 * returning it. 128 * 129 * @param entry is the source entry buffer. 130 * 131 * @return the new tuple input object. 132 */ 133 public static TupleInput entryToInput(DatabaseEntry entry) { 134 135 return new TupleInput(entry.getData(), entry.getOffset(), 136 entry.getSize()); 137 } 138 139 /** 140 * Utility method for use by bindings to create a tuple output object. 141 * 142 * @return a new tuple output object. 143 * 144 * @deprecated replaced by {@link #getTupleOutput} 145 */ 146 public static TupleOutput newOutput() { 147 148 return new TupleOutput(); 149 } 150 151 /** 152 * Utility method for use by bindings to create a tuple output object 153 * with a specific starting size. 154 * 155 * @return a new tuple output object. 156 * 157 * @deprecated replaced by {@link #getTupleOutput} 158 */ 159 public static TupleOutput newOutput(byte[] buffer) { 160 161 return new TupleOutput(buffer); 162 } 163} 164