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.directory.api.util;
018
019
020import java.io.Writer;
021
022
023/**
024 * {@link Writer} implementation that outputs to a {@link StringBuilder}.
025 * <p>
026 * <strong>NOTE:</strong> This implementation, as an alternative to
027 * <code>java.io.StringWriter</code>, provides an <i>un-synchronized</i>
028 * (i.e. for use in a single thread) implementation for better performance.
029 * For safe usage with multiple {@link Thread}s then
030 * <code>java.io.StringWriter</code> should be used.
031 *
032 * @version $Id: StringBuilderWriter.java 1415850 2012-11-30 20:51:39Z ggregory $
033 * @since 2.0
034 */
035public class StringBuilderWriter extends Writer
036{
037
038    private final StringBuilder builder;
039
040
041    /**
042     * Construct a new {@link StringBuilder} instance with default capacity.
043     */
044    public StringBuilderWriter()
045    {
046        builder = new StringBuilder();
047    }
048
049
050    /**
051     * Construct a new {@link StringBuilder} instance with the specified capacity.
052     *
053     * @param capacity The initial capacity of the underlying {@link StringBuilder}
054     */
055    public StringBuilderWriter( int capacity )
056    {
057        builder = new StringBuilder( capacity );
058    }
059
060
061    /**
062     * Construct a new instance with the specified {@link StringBuilder}.
063     *
064     * @param builder The String builder
065     */
066    public StringBuilderWriter( StringBuilder builder )
067    {
068        this.builder = builder != null ? builder : new StringBuilder();
069    }
070
071
072    /**
073     * Append a single character to this Writer.
074     *
075     * @param value The character to append
076     * @return This writer instance
077     */
078    @Override
079    public Writer append( char value )
080    {
081        builder.append( value );
082        
083        return this;
084    }
085
086
087    /**
088     * Append a character sequence to this Writer.
089     *
090     * @param value The character to append
091     * @return This writer instance
092     */
093    @Override
094    public Writer append( CharSequence value )
095    {
096        builder.append( value );
097        
098        return this;
099    }
100
101
102    /**
103     * Append a portion of a character sequence to the {@link StringBuilder}.
104     *
105     * @param value The character to append
106     * @param start The index of the first character
107     * @param end The index of the last character + 1
108     * @return This writer instance
109     */
110    @Override
111    public Writer append( CharSequence value, int start, int end )
112    {
113        builder.append( value, start, end );
114        
115        return this;
116    }
117
118
119    /**
120     * Closing this writer has no effect. 
121     */
122    @Override
123    public void close()
124    {
125    }
126
127
128    /**
129     * Flushing this writer has no effect. 
130     */
131    @Override
132    public void flush()
133    {
134    }
135
136
137    /**
138     * Write a String to the {@link StringBuilder}.
139     * 
140     * @param value The value to write
141     */
142    @Override
143    public void write( String value )
144    {
145        if ( value != null )
146        {
147            builder.append( value );
148        }
149    }
150
151
152    /**
153     * Write a portion of a character array to the {@link StringBuilder}.
154     *
155     * @param value The value to write
156     * @param offset The index of the first character
157     * @param length The number of characters to write
158     */
159    @Override
160    public void write( char[] value, int offset, int length )
161    {
162        if ( value != null )
163        {
164            builder.append( value, offset, length );
165        }
166    }
167
168
169    /**
170     * Return the underlying builder.
171     *
172     * @return The underlying builder
173     */
174    public StringBuilder getBuilder()
175    {
176        return builder;
177    }
178
179
180    /**
181     * Returns {@link StringBuilder#toString()}.
182     *
183     * @return The contents of the String builder.
184     */
185    @Override
186    public String toString()
187    {
188        return builder.toString();
189    }
190}