001: /*-
002: * See the file LICENSE for redistribution information.
003: *
004: * Copyright (c) 2000,2008 Oracle. All rights reserved.
005: *
006: * $Id: TupleBase.java,v 1.5.2.2 2008/01/07 15:14:06 cwl Exp $
007: */
008:
009: package com.sleepycat.bind.tuple;
010:
011: import com.sleepycat.je.DatabaseEntry;
012:
013: /**
014: * A base class for tuple bindings and tuple key creators that provides control
015: * over the allocation of the output buffer.
016: *
017: * <p>Tuple bindings and key creators append data to a {@link TupleOutput}
018: * instance, which is also a {@link com.sleepycat.util.FastOutputStream}
019: * instance. This object has a byte array buffer that is resized when it is
020: * full. The reallocation of this buffer can be a performance factor for
021: * some applications using large objects. To manage this issue, the {@link
022: * #setTupleBufferSize} method may be used to control the initial size of the
023: * buffer, and the {@link #getTupleOutput} method may be overridden by
024: * subclasses to take over creation of the TupleOutput object.</p>
025: */
026: public class TupleBase {
027:
028: private int outputBufferSize;
029:
030: /**
031: * Initializes the initial output buffer size to zero.
032: *
033: * <p>Unless {@link #setTupleBufferSize} is called, the default {@link
034: * com.sleepycat.util.FastOutputStream#DEFAULT_INIT_SIZE} size will be
035: * used.</p>
036: */
037: public TupleBase() {
038: outputBufferSize = 0;
039: }
040:
041: /**
042: * Sets the initial byte size of the output buffer that is allocated by the
043: * default implementation of {@link #getTupleOutput}.
044: *
045: * <p>If this property is zero (the default), the default {@link
046: * com.sleepycat.util.FastOutputStream#DEFAULT_INIT_SIZE} size is used.</p>
047: *
048: * @param byteSize the initial byte size of the output buffer, or zero to
049: * use the default size.
050: */
051: public void setTupleBufferSize(int byteSize) {
052: outputBufferSize = byteSize;
053: }
054:
055: /**
056: * Returns the initial byte size of the output buffer.
057: *
058: * @return the initial byte size of the output buffer.
059: *
060: * @see #setTupleBufferSize
061: */
062: public int getTupleBufferSize() {
063: return outputBufferSize;
064: }
065:
066: /**
067: * Returns an empty TupleOutput instance that will be used by the tuple
068: * binding or key creator.
069: *
070: * <p>The default implementation of this method creates a new TupleOutput
071: * with an initial buffer size that can be changed using the {@link
072: * #setTupleBufferSize} method.</p>
073: *
074: * <p>This method may be overridden to return a TupleOutput instance. For
075: * example, an instance per thread could be created and returned by this
076: * method. If a TupleOutput instance is reused, be sure to call its
077: * {@link com.sleepycat.util.FastOutputStream#reset} method before each
078: * use.</p>
079: *
080: * @param object is the object to be written to the tuple output, and may
081: * be used by subclasses to determine the size of the output buffer.
082: *
083: * @return an empty TupleOutput instance.
084: *
085: * @see #setTupleBufferSize
086: */
087: protected TupleOutput getTupleOutput(Object object) {
088: int byteSize = getTupleBufferSize();
089: if (byteSize != 0) {
090: return new TupleOutput(new byte[byteSize]);
091: } else {
092: return new TupleOutput();
093: }
094: }
095:
096: /**
097: * Utility method to set the data in a entry buffer to the data in a tuple
098: * output object.
099: *
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,
105: DatabaseEntry entry) {
106:
107: entry.setData(output.getBufferBytes(),
108: output.getBufferOffset(), output.getBufferLength());
109: }
110:
111: /**
112: * Utility method to set the data in a entry buffer to the data in a tuple
113: * input object.
114: *
115: * @param input is the source tuple input object.
116: *
117: * @param entry is the destination entry buffer.
118: */
119: public static void inputToEntry(TupleInput input,
120: DatabaseEntry entry) {
121:
122: entry.setData(input.getBufferBytes(), input.getBufferOffset(),
123: input.getBufferLength());
124: }
125:
126: /**
127: * Utility method to create a new tuple input object for reading the data
128: * from a given buffer. If an existing input is reused, it is reset before
129: * returning it.
130: *
131: * @param entry is the source entry buffer.
132: *
133: * @return the new tuple input object.
134: */
135: public static TupleInput entryToInput(DatabaseEntry entry) {
136:
137: return new TupleInput(entry.getData(), entry.getOffset(), entry
138: .getSize());
139: }
140:
141: /**
142: * Utility method for use by bindings to create a tuple output object.
143: *
144: * @return a new tuple output object.
145: *
146: * @deprecated replaced by {@link #getTupleOutput}
147: */
148: public static TupleOutput newOutput() {
149:
150: return new TupleOutput();
151: }
152:
153: /**
154: * Utility method for use by bindings to create a tuple output object
155: * with a specific starting size.
156: *
157: * @return a new tuple output object.
158: *
159: * @deprecated replaced by {@link #getTupleOutput}
160: */
161: public static TupleOutput newOutput(byte[] buffer) {
162:
163: return new TupleOutput(buffer);
164: }
165: }
|