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 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 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 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 */ SourceChannel(SelectorProvider provider)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 */ validOps()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 */ SinkChannel(SelectorProvider provider)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 */ validOps()116 public final int validOps() { 117 return SelectionKey.OP_WRITE; 118 } 119 120 } 121 122 /** 123 * Initializes a new instance of this class. 124 */ Pipe()125 protected Pipe() { } 126 127 /** 128 * Returns this pipe's source channel. 129 * 130 * @return This pipe's source channel 131 */ source()132 public abstract SourceChannel source(); 133 134 /** 135 * Returns this pipe's sink channel. 136 * 137 * @return This pipe's sink channel 138 */ sink()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 */ open()154 public static Pipe open() throws IOException { 155 return SelectorProvider.provider().openPipe(); 156 } 157 158 } 159