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
20import org.apache.harmony.luni.util.Msg;
21
22/**
23 * Places information on a communications pipe. When two threads want to pass
24 * data back and forth, one creates a piped output stream and the other one
25 * creates a piped input stream.
26 *
27 * @see PipedInputStream
28 *
29 * @since Android 1.0
30 */
31public class PipedOutputStream extends OutputStream {
32
33    /**
34     * The destination PipedInputStream
35     */
36    private PipedInputStream dest;
37
38    /**
39     * Constructs a new unconnected {@code PipedOutputStream}. The resulting
40     * stream must be connected to a {@link PipedInputStream} before data can be
41     * written to it.
42     *
43     * @since Android 1.0
44     */
45    public PipedOutputStream() {
46        super();
47    }
48
49    /**
50     * Constructs a new {@code PipedOutputStream} connected to the
51     * {@link PipedInputStream} {@code dest}. Any data written to this stream
52     * can be read from the target stream.
53     *
54     * @param dest
55     *            the piped input stream to connect to.
56     * @throws IOException
57     *             if this stream or {@code dest} are already connected.
58     * @since Android 1.0
59     */
60    public PipedOutputStream(PipedInputStream dest) throws IOException {
61        super();
62        connect(dest);
63    }
64
65    /**
66     * Closes this stream. If this stream is connected to an input stream, the
67     * input stream is closed and the pipe is disconnected.
68     *
69     * @throws IOException
70     *             if an error occurs while closing this stream.
71     * @since Android 1.0
72     */
73    @Override
74    public void close() throws IOException {
75        // Is the pipe connected?
76        if (dest != null) {
77            dest.done();
78            dest = null;
79        }
80    }
81
82    /**
83     * Connects this stream to a {@link PipedInputStream}. Any data written to
84     * this output stream becomes readable in the input stream.
85     *
86     * @param stream
87     *            the destination input stream.
88     * @throws IOException
89     *             if either stream is already connected.
90     * @since Android 1.0
91     */
92    public void connect(PipedInputStream stream) throws IOException {
93        if (null == stream) {
94            throw new NullPointerException();
95        }
96        if (this.dest != null) {
97            throw new IOException(Msg.getString("K0079")); //$NON-NLS-1$
98        }
99        synchronized (stream) {
100            if (stream.isConnected) {
101                throw new IOException(Msg.getString("K007a")); //$NON-NLS-1$
102            }
103            stream.buffer = new byte[PipedInputStream.PIPE_SIZE];
104            stream.isConnected = true;
105            this.dest = stream;
106        }
107    }
108
109    /**
110     * Notifies the readers of this {@link PipedInputStream} that bytes can be
111     * read. This method does nothing if this stream is not connected.
112     *
113     * @throws IOException
114     *             if an I/O error occurs while flushing this stream.
115     * @since Android 1.0
116     */
117    @Override
118    public void flush() throws IOException {
119        if (dest != null) {
120            synchronized (dest) {
121                dest.notifyAll();
122            }
123        }
124    }
125
126    /**
127     * Writes {@code count} bytes from the byte array {@code buffer} starting at
128     * {@code offset} to this stream. The written data can then be read from the
129     * connected input stream.
130     * <p>
131     * Separate threads should be used to write to a {@code PipedOutputStream}
132     * and to read from the connected {@link PipedInputStream}. If the same
133     * thread is used, a deadlock may occur.
134     * </p>
135     *
136     * @param buffer
137     *            the buffer to write.
138     * @param offset
139     *            the index of the first byte in {@code buffer} to write.
140     * @param count
141     *            the number of bytes from {@code buffer} to write to this
142     *            stream.
143     * @throws IndexOutOfBoundsException
144     *             if {@code offset < 0} or {@code count < 0}, or if {@code
145     *             offset + count} is bigger than the length of {@code buffer}.
146     * @throws InterruptedIOException
147     *             if the pipe is full and the current thread is interrupted
148     *             waiting for space to write data. This case is not currently
149     *             handled correctly.
150     * @throws IOException
151     *             if this stream is not connected, if the target stream is
152     *             closed or if the thread reading from the target stream is no
153     *             longer alive. This case is currently not handled correctly.
154     * @since Android 1.0
155     */
156    @Override
157    public void write(byte[] buffer, int offset, int count) throws IOException {
158        // BEGIN android-note
159        // changed array notation to be consistent with the rest of harmony
160        // END android-note
161        if (dest == null) {
162            // K007b=Pipe Not Connected
163            throw new IOException(Msg.getString("K007b")); //$NON-NLS-1$
164        }
165        super.write(buffer, offset, count);
166    }
167
168    /**
169     * Writes a single byte to this stream. Only the least significant byte of
170     * the integer {@code oneByte} is written. The written byte can then be read
171     * from the connected input stream.
172     * <p>
173     * Separate threads should be used to write to a {@code PipedOutputStream}
174     * and to read from the connected {@link PipedInputStream}. If the same
175     * thread is used, a deadlock may occur.
176     * </p>
177     *
178     * @param oneByte
179     *            the byte to write.
180     * @throws InterruptedIOException
181     *             if the pipe is full and the current thread is interrupted
182     *             waiting for space to write data. This case is not currently
183     *             handled correctly.
184     * @throws IOException
185     *             if this stream is not connected, if the target stream is
186     *             closed or if the thread reading from the target stream is no
187     *             longer alive. This case is currently not handled correctly.
188     * @since Android 1.0
189     */
190    @Override
191    public void write(int oneByte) throws IOException {
192        if (dest == null) {
193            throw new IOException(Msg.getString("K007b")); //$NON-NLS-1$
194        }
195        dest.receive(oneByte);
196    }
197}
198