1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: SerialBase.java,v 12.6 2008/01/08 20:58:35 bostic Exp $
7 */
8
9package com.sleepycat.bind.serial;
10
11import com.sleepycat.util.FastOutputStream;
12
13/**
14 * A base class for serial bindings creators that provides control over the
15 * allocation of the output buffer.
16 *
17 * <p>Serial bindings append data to a {@link FastOutputStream} instance.  This
18 * object has a byte array buffer that is resized when it is full.  The
19 * reallocation of this buffer can be a performance factor for some
20 * applications using large objects.  To manage this issue, the {@link
21 * #setSerialBufferSize} method may be used to control the initial size of the
22 * buffer, and the {@link #getSerialOutput} method may be overridden by
23 * subclasses to take over creation of the FastOutputStream object.</p>
24 */
25public class SerialBase {
26
27    private int outputBufferSize;
28
29    /**
30     * Initializes the initial output buffer size to zero.
31     *
32     * <p>Unless {@link #setSerialBufferSize} is called, the default {@link
33     * FastOutputStream#DEFAULT_INIT_SIZE} size will be used.</p>
34     */
35    public SerialBase() {
36        outputBufferSize = 0;
37    }
38
39    /**
40     * Sets the initial byte size of the output buffer that is allocated by the
41     * default implementation of {@link #getSerialOutput}.
42     *
43     * <p>If this property is zero (the default), the default {@link
44     * FastOutputStream#DEFAULT_INIT_SIZE} size is used.</p>
45     *
46     * @param byteSize the initial byte size of the output buffer, or zero to
47     * use the default size.
48     */
49    public void setSerialBufferSize(int byteSize) {
50        outputBufferSize = byteSize;
51    }
52
53    /**
54     * Returns the initial byte size of the output buffer.
55     *
56     * @return the initial byte size of the output buffer.
57     *
58     * @see #setSerialBufferSize
59     */
60    public int getSerialBufferSize() {
61        return outputBufferSize;
62    }
63
64    /**
65     * Returns an empty SerialOutput instance that will be used by the serial
66     * binding or key creator.
67     *
68     * <p>The default implementation of this method creates a new SerialOutput
69     * with an initial buffer size that can be changed using the {@link
70     * #setSerialBufferSize} method.</p>
71     *
72     * <p>This method may be overridden to return a FastOutputStream instance.
73     * For example, an instance per thread could be created and returned by
74     * this method.  If a FastOutputStream instance is reused, be sure to call
75     * its {@link FastOutputStream#reset} method before each use.</p>
76     *
77     * @param object is the object to be written to the serial output, and may
78     * be used by subclasses to determine the size of the output buffer.
79     *
80     * @return an empty FastOutputStream instance.
81     *
82     * @see #setSerialBufferSize
83     */
84    protected FastOutputStream getSerialOutput(Object object) {
85        int byteSize = getSerialBufferSize();
86        if (byteSize != 0) {
87            return new FastOutputStream(byteSize);
88        } else {
89            return new FastOutputStream();
90        }
91    }
92}
93