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.commons.io.output; 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 * {@link java.io.StringWriter}, 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 * {@link java.io.StringWriter} should be used. 030 * </p> 031 * <h2>Deprecating Serialization</h2> 032 * <p> 033 * <em>Serialization is deprecated and will be removed in 3.0.</em> 034 * </p> 035 * @since 2.0 036 */ 037public class StringBuilderWriter extends Writer implements Serializable { 038 039 private static final long serialVersionUID = -146927496096066153L; 040 041 /** The append target. */ 042 private final StringBuilder builder; 043 044 /** 045 * Constructs a new {@link StringBuilder} instance with default capacity. 046 */ 047 public StringBuilderWriter() { 048 this.builder = new StringBuilder(); 049 } 050 051 /** 052 * Constructs a new {@link StringBuilder} instance with the specified capacity. 053 * 054 * @param capacity The initial capacity of the underlying {@link StringBuilder} 055 */ 056 public StringBuilderWriter(final int capacity) { 057 this.builder = new StringBuilder(capacity); 058 } 059 060 /** 061 * Constructs a new instance with the specified {@link StringBuilder}. 062 * 063 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 064 * 065 * @param builder The String builder. May be null. 066 */ 067 public StringBuilderWriter(final StringBuilder builder) { 068 this.builder = builder != null ? builder : new StringBuilder(); 069 } 070 071 /** 072 * Appends a single character to this Writer. 073 * 074 * @param value The character to append 075 * @return This writer instance 076 */ 077 @Override 078 public Writer append(final char value) { 079 builder.append(value); 080 return this; 081 } 082 083 /** 084 * Appends a character sequence to this Writer. 085 * 086 * @param value The character to append 087 * @return This writer instance 088 */ 089 @Override 090 public Writer append(final CharSequence value) { 091 builder.append(value); 092 return this; 093 } 094 095 /** 096 * Appends a portion of a character sequence to the {@link StringBuilder}. 097 * 098 * @param value The character to append 099 * @param start The index of the first character 100 * @param end The index of the last character + 1 101 * @return This writer instance 102 */ 103 @Override 104 public Writer append(final CharSequence value, final int start, final int end) { 105 builder.append(value, start, end); 106 return this; 107 } 108 109 /** 110 * Closing this writer has no effect. 111 */ 112 @Override 113 public void close() { 114 // no-op 115 } 116 117 /** 118 * Flushing this writer has no effect. 119 */ 120 @Override 121 public void flush() { 122 // no-op 123 } 124 125 /** 126 * Gets the underlying builder. 127 * 128 * @return The underlying builder 129 */ 130 public StringBuilder getBuilder() { 131 return builder; 132 } 133 134 /** 135 * Returns {@link StringBuilder#toString()}. 136 * 137 * @return The contents of the String builder. 138 */ 139 @Override 140 public String toString() { 141 return builder.toString(); 142 } 143 144 /** 145 * Writes a portion of a character array to the {@link StringBuilder}. 146 * 147 * @param value The value to write 148 * @param offset The index of the first character 149 * @param length The number of characters to write 150 */ 151 @Override 152 public void write(final char[] value, final int offset, final int length) { 153 if (value != null) { 154 builder.append(value, offset, length); 155 } 156 } 157 158 /** 159 * Writes a String to the {@link StringBuilder}. 160 * 161 * @param value The value to write 162 */ 163 @Override 164 public void write(final String value) { 165 if (value != null) { 166 builder.append(value); 167 } 168 } 169}