View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.io.output;
18  
19  import java.io.Serializable;
20  import java.io.StringWriter;
21  import java.io.Writer;
22  
23  /**
24   * {@link Writer} implementation that outputs to a {@link StringBuilder}.
25   * <p>
26   * <strong>NOTE:</strong> This implementation, as an alternative to {@link StringWriter}, provides an <em>un-synchronized</em> implementation for better
27   * performance for use in a single thread. For safe usage with multiple {@link Thread}s, a {@link StringWriter} should be used.
28   * </p>
29   * <h2>Deprecating Serialization</h2>
30   * <p>
31   * <em>Serialization is deprecated and will be removed in 3.0.</em>
32   * </p>
33   *
34   * @since 2.0
35   */
36  public class StringBuilderWriter extends Writer implements Serializable {
37  
38      private static final long serialVersionUID = -146927496096066153L;
39  
40      /** The append target. */
41      private final StringBuilder builder;
42  
43      /**
44       * Constructs a new {@link StringBuilder} instance with default capacity.
45       */
46      public StringBuilderWriter() {
47          this.builder = new StringBuilder();
48      }
49  
50      /**
51       * Constructs a new {@link StringBuilder} instance with the specified capacity.
52       *
53       * @param capacity The initial capacity of the underlying {@link StringBuilder}
54       */
55      public StringBuilderWriter(final int capacity) {
56          this.builder = new StringBuilder(capacity);
57      }
58  
59      /**
60       * Constructs a new instance with the specified {@link StringBuilder}.
61       *
62       * <p>If {@code builder} is null a new instance with default capacity will be created.</p>
63       *
64       * @param builder The String builder. May be null.
65       */
66      public StringBuilderWriter(final StringBuilder builder) {
67          this.builder = builder != null ? builder : new StringBuilder();
68      }
69  
70      /**
71       * Appends a single character to this Writer.
72       *
73       * @param value The character to append
74       * @return This writer instance
75       */
76      @Override
77      public Writer append(final char value) {
78          builder.append(value);
79          return this;
80      }
81  
82      /**
83       * Appends a character sequence to this Writer.
84       *
85       * @param value The character to append
86       * @return This writer instance
87       */
88      @Override
89      public Writer append(final CharSequence value) {
90          builder.append(value);
91          return this;
92      }
93  
94      /**
95       * Appends a portion of a character sequence to the {@link StringBuilder}.
96       *
97       * @param value The character to append
98       * @param start The index of the first character
99       * @param end The index of the last character + 1
100      * @return This writer instance
101      */
102     @Override
103     public Writer append(final CharSequence value, final int start, final int end) {
104         builder.append(value, start, end);
105         return this;
106     }
107 
108     /**
109      * Closing this writer has no effect.
110      */
111     @Override
112     public void close() {
113         // no-op
114     }
115 
116     /**
117      * Flushing this writer has no effect.
118      */
119     @Override
120     public void flush() {
121         // no-op
122     }
123 
124     /**
125      * Gets the underlying builder.
126      *
127      * @return The underlying builder
128      */
129     public StringBuilder getBuilder() {
130         return builder;
131     }
132 
133     /**
134      * Returns {@link StringBuilder#toString()}.
135      *
136      * @return The contents of the String builder.
137      */
138     @Override
139     public String toString() {
140         return builder.toString();
141     }
142 
143     /**
144      * Writes a portion of a character array to the {@link StringBuilder}.
145      *
146      * @param value The value to write
147      * @param offset The index of the first character
148      * @param length The number of characters to write
149      */
150     @Override
151     public void write(final char[] value, final int offset, final int length) {
152         if (value != null) {
153             builder.append(value, offset, length);
154         }
155     }
156 
157     /**
158      * Writes a String to the {@link StringBuilder}.
159      *
160      * @param value The value to write
161      */
162     @Override
163     public void write(final String value) {
164         if (value != null) {
165             builder.append(value);
166         }
167     }
168 }