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