001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package java.nio.channels;
018:
019: import java.io.IOException;
020: import java.nio.ByteBuffer;
021:
022: /**
023: * The interface to channels that can write a set of buffers in a single
024: * operation.
025: * <p>
026: * The corresponding interface for reads is called
027: * <code>ScatteringByteChannel</code>.
028: */
029: public interface GatheringByteChannel extends WritableByteChannel {
030:
031: /**
032: * Writes bytes from all the given buffers to the channel.
033: * <p>
034: * This method is equivalent to:
035: *
036: * <pre>
037: * write(buffers, 0, buffers.length);
038: * </pre>
039: *
040: * </p>
041: *
042: * @param buffers
043: * the buffers containing bytes to be written.
044: * @return the number of bytes actually written.
045: * @throws ClosedChannelException
046: * if the channel is closed.
047: * @throws NonWritableChannelException
048: * if the channel is open, but not in a mode that permits
049: * writing.
050: * @throws ClosedByInterruptException
051: * if the thread is interrupted in its IO operation by another
052: * thread closing the channel.
053: * @throws AsynchronousCloseException
054: * if the write is interrupted by another thread sending an
055: * explicit interrupt.
056: * @throws IOException
057: * if some other type of exception occurs. Details are in the
058: * message.
059: */
060: public long write(ByteBuffer[] buffers) throws IOException;
061:
062: /**
063: * Writes a subset of the given bytes from the buffers to the channel.
064: * <p>
065: * This method attempts to write all of the <code>remaining()</code> bytes
066: * from <code>length</code> byte buffers, in order, starting at
067: * <code>buffers[offset]</code>. The number of bytes actually written is
068: * returned.
069: * </p>
070: * <p>
071: * If a write operation is in progress, subsequent threads will block until
072: * the write is completed, and will then contend for the ability to write.
073: * </p>
074: *
075: * @param buffers
076: * the array of byte buffers containing the source of remaining
077: * bytes that will be attempted to be written.
078: * @param offset
079: * the index of the first buffer to write.
080: * @param length
081: * the number of buffers to write.
082: * @return the number of bytes actually written.
083: * @throws IndexOutOfBoundsException
084: * if offset < 0 or > buffers.length; or length < 0 or >
085: * buffers.length - offset.
086: * @throws NonWritableChannelException
087: * if the channel was not opened for writing.
088: * @throws ClosedChannelException
089: * the channel is currently closed.
090: * @throws AsynchronousCloseException
091: * the channel was closed by another thread while the write was
092: * underway.
093: * @throws ClosedByInterruptException
094: * the thread was interrupted by another thread while the write
095: * was underway.
096: * @throws IOException
097: * if some other type of exception occurs. Details are in the
098: * message.
099: */
100: public long write(ByteBuffer[] buffers, int offset, int length)
101: throws IOException;
102: }
|