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