View Javadoc
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  
26  package java.nio.channels;
27  
28  import java.io.IOException;
29  import 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 source channel in exactlyAthe 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  
52  public abstract class Pipe {
53  
54      /**
55       * A channel representing the readable end of a {@link Pipe}.
56       *
57       * @since 1.4
58       */
59      public static abstract 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 static abstract 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 }