001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 * 
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 * 
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017package org.apache.logging.log4j.core.util;
018
019import java.io.Serializable;
020import java.io.Writer;
021
022/**
023 * {@link Writer} implementation that outputs to a {@link StringBuilder}.
024 * <p>
025 * <strong>NOTE:</strong> This implementation, as an alternative to
026 * <code>java.io.StringWriter</code>, provides an <i>un-synchronized</i>
027 * (i.e. for use in a single thread) implementation for better performance.
028 * For safe usage with multiple {@link Thread}s then
029 * <code>java.io.StringWriter</code> should be used.
030 * 
031 * <h3>History</h3>
032 * <ol>
033 * <li>Copied from Apache Commons IO revision 1681000.</li>
034 * <li>Pick up Javadoc updates from revision 1722253.</li>
035 * <ol>
036 */
037public class StringBuilderWriter extends Writer implements Serializable {
038
039    private static final long serialVersionUID = -146927496096066153L;
040    private final StringBuilder builder;
041
042    /**
043     * Constructs a new {@link StringBuilder} instance with default capacity.
044     */
045    public StringBuilderWriter() {
046        this.builder = new StringBuilder();
047    }
048
049    /**
050     * Constructs a new {@link StringBuilder} instance with the specified capacity.
051     *
052     * @param capacity The initial capacity of the underlying {@link StringBuilder}
053     */
054    public StringBuilderWriter(final int capacity) {
055        this.builder = new StringBuilder(capacity);
056    }
057
058    /**
059     * Constructs a new instance with the specified {@link StringBuilder}.
060     * 
061     * <p>If {@code builder} is null a new instance with default capacity will be created.</p>
062     *
063     * @param builder The String builder. May be null.
064     */
065    public StringBuilderWriter(final StringBuilder builder) {
066        this.builder = builder != null ? builder : new StringBuilder();
067    }
068
069    /**
070     * Appends a single character to this Writer.
071     *
072     * @param value The character to append
073     * @return This writer instance
074     */
075    @Override
076    public Writer append(final char value) {
077        builder.append(value);
078        return this;
079    }
080
081    /**
082     * Appends a character sequence to this Writer.
083     *
084     * @param value The character to append
085     * @return This writer instance
086     */
087    @Override
088    public Writer append(final CharSequence value) {
089        builder.append(value);
090        return this;
091    }
092
093    /**
094     * Appends a portion of a character sequence to the {@link StringBuilder}.
095     *
096     * @param value The character to append
097     * @param start The index of the first character
098     * @param end The index of the last character + 1
099     * @return This writer instance
100     */
101    @Override
102    public Writer append(final CharSequence value, final int start, final int end) {
103        builder.append(value, start, end);
104        return this;
105    }
106
107    /**
108     * Closing this writer has no effect. 
109     */
110    @Override
111    public void close() {
112        // no-op
113    }
114
115    /**
116     * Flushing this writer has no effect. 
117     */
118    @Override
119    public void flush() {
120        // no-op
121    }
122
123
124    /**
125     * Writes a String to the {@link StringBuilder}.
126     * 
127     * @param value The value to write
128     */
129    @Override
130    public void write(final String value) {
131        if (value != null) {
132            builder.append(value);
133        }
134    }
135
136    /**
137     * Writes a portion of a character array to the {@link StringBuilder}.
138     *
139     * @param value The value to write
140     * @param offset The index of the first character
141     * @param length The number of characters to write
142     */
143    @Override
144    public void write(final char[] value, final int offset, final int length) {
145        if (value != null) {
146            builder.append(value, offset, length);
147        }
148    }
149
150    /**
151     * Returns the underlying builder.
152     *
153     * @return The underlying builder
154     */
155    public StringBuilder getBuilder() {
156        return builder;
157    }
158
159    /**
160     * Returns {@link StringBuilder#toString()}.
161     *
162     * @return The contents of the String builder.
163     */
164    @Override
165    public String toString() {
166        return builder.toString();
167    }
168}