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
18package java.io;
19
20/**
21 * Wraps an existing {@link Writer} and performs some transformation on the
22 * output data while it is being written. Transformations can be anything from a
23 * simple byte-wise filtering output data to an on-the-fly compression or
24 * decompression of the underlying writer. Writers that wrap another writer and
25 * provide some additional functionality on top of it usually inherit from this
26 * class.
27 *
28 * @see FilterReader
29 */
30public abstract class FilterWriter extends Writer {
31
32    /**
33     * The Writer being filtered.
34     */
35    protected Writer out;
36
37    /**
38     * Constructs a new FilterWriter on the Writer {@code out}. All writes are
39     * now filtered through this writer.
40     *
41     * @param out
42     *            the target Writer to filter writes on.
43     */
44    protected FilterWriter(Writer out) {
45        super(out);
46        this.out = out;
47    }
48
49    /**
50     * Closes this writer. This implementation closes the target writer.
51     *
52     * @throws IOException
53     *             if an error occurs attempting to close this writer.
54     */
55    @Override
56    public void close() throws IOException {
57        synchronized (lock) {
58            out.close();
59        }
60    }
61
62    /**
63     * Flushes this writer to ensure all pending data is sent out to the target
64     * writer. This implementation flushes the target writer.
65     *
66     * @throws IOException
67     *             if an error occurs attempting to flush this writer.
68     */
69    @Override
70    public void flush() throws IOException {
71        synchronized (lock) {
72            out.flush();
73        }
74    }
75
76    /**
77     * Writes {@code count} characters from the char array {@code buffer}
78     * starting at position {@code offset} to the target writer.
79     *
80     * @param buffer
81     *            the buffer to write.
82     * @param offset
83     *            the index of the first character in {@code buffer} to write.
84     * @param count
85     *            the number of characters in {@code buffer} to write.
86     * @throws IOException
87     *             if an error occurs while writing to this writer.
88     */
89    @Override
90    public void write(char[] buffer, int offset, int count) throws IOException {
91        synchronized (lock) {
92            out.write(buffer, offset, count);
93        }
94    }
95
96    /**
97     * Writes the specified character {@code oneChar} to the target writer. Only the
98     * two least significant bytes of the integer {@code oneChar} are written.
99     *
100     * @param oneChar
101     *            the char to write to the target writer.
102     * @throws IOException
103     *             if an error occurs while writing to this writer.
104     */
105    @Override
106    public void write(int oneChar) throws IOException {
107        synchronized (lock) {
108            out.write(oneChar);
109        }
110    }
111
112    /**
113     * Writes {@code count} characters from the string {@code str} starting at
114     * position {@code index} to this writer. This implementation writes
115     * {@code str} to the target writer.
116     *
117     * @param str
118     *            the string to be written.
119     * @param offset
120     *            the index of the first character in {@code str} to write.
121     * @param count
122     *            the number of chars in {@code str} to write.
123     * @throws IOException
124     *             if an error occurs while writing to this writer.
125     */
126    @Override
127    public void write(String str, int offset, int count) throws IOException {
128        synchronized (lock) {
129            out.write(str, offset, count);
130        }
131    }
132}
133