Pipe.java revision 12745:f068a4ffddd2 
1/*
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.nio.channels;
27
28import java.io.IOException;
29import java.nio.channels.spi.*;
30
31
32/**
33 * A pair of channels that implements a unidirectional pipe.
34 *
35 * <p> A pipe consists of a pair of channels: A writable {@link
36 * Pipe.SinkChannel sink} channel and a readable {@link Pipe.SourceChannel source}
37 * channel.  Once some bytes are written to the sink channel they can be read
38 * from the source channel in exactly the order in which they were written.
39 *
40 * <p> Whether or not a thread writing bytes to a pipe will block until another
41 * thread reads those bytes, or some previously-written bytes, from the pipe is
42 * system-dependent and therefore unspecified.  Many pipe implementations will
43 * buffer up to a certain number of bytes between the sink and source channels,
44 * but such buffering should not be assumed.  </p>
45 *
46 *
47 * @author Mark Reinhold
48 * @author JSR-51 Expert Group
49 * @since 1.4
50 */
51
52public abstract class Pipe {
53
54    /**
55     * A channel representing the readable end of a {@link Pipe}.
56     *
57     * @since 1.4
58     */
59    public abstract static class SourceChannel
60        extends AbstractSelectableChannel
61        implements ReadableByteChannel, ScatteringByteChannel
62    {
63        /**
64         * Constructs a new instance of this class.
65         *
66         * @param  provider
67         *         The selector provider
68         */
69        protected SourceChannel(SelectorProvider provider) {
70            super(provider);
71        }
72
73        /**
74         * Returns an operation set identifying this channel's supported
75         * operations.
76         *
77         * <p> Pipe-source channels only support reading, so this method
78         * returns {@link SelectionKey#OP_READ}.  </p>
79         *
80         * @return  The valid-operation set
81         */
82        public final int validOps() {
83            return SelectionKey.OP_READ;
84        }
85
86    }
87
88    /**
89     * A channel representing the writable end of a {@link Pipe}.
90     *
91     * @since 1.4
92     */
93    public abstract static class SinkChannel
94        extends AbstractSelectableChannel
95        implements WritableByteChannel, GatheringByteChannel
96    {
97        /**
98         * Initializes a new instance of this class.
99         *
100         * @param  provider
101         *         The selector provider
102         */
103        protected SinkChannel(SelectorProvider provider) {
104            super(provider);
105        }
106
107        /**
108         * Returns an operation set identifying this channel's supported
109         * operations.
110         *
111         * <p> Pipe-sink channels only support writing, so this method returns
112         * {@link SelectionKey#OP_WRITE}.  </p>
113         *
114         * @return  The valid-operation set
115         */
116        public final int validOps() {
117            return SelectionKey.OP_WRITE;
118        }
119
120    }
121
122    /**
123     * Initializes a new instance of this class.
124     */
125    protected Pipe() { }
126
127    /**
128     * Returns this pipe's source channel.
129     *
130     * @return  This pipe's source channel
131     */
132    public abstract SourceChannel source();
133
134    /**
135     * Returns this pipe's sink channel.
136     *
137     * @return  This pipe's sink channel
138     */
139    public abstract SinkChannel sink();
140
141    /**
142     * Opens a pipe.
143     *
144     * <p> The new pipe is created by invoking the {@link
145     * java.nio.channels.spi.SelectorProvider#openPipe openPipe} method of the
146     * system-wide default {@link java.nio.channels.spi.SelectorProvider}
147     * object.  </p>
148     *
149     * @return  A new pipe
150     *
151     * @throws  IOException
152     *          If an I/O error occurs
153     */
154    public static Pipe open() throws IOException {
155        return SelectorProvider.provider().openPipe();
156    }
157
158}
159