WritableByteChannel


1   /*
2    * @(#)WritableByteChannel.java 1.15 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.nio.channels;
9   
10  import java.io.IOException  ;
11  import java.nio.ByteBuffer  ;
12  
13  
14  /**
15   * A channel that can write bytes.
16   *
17   * <p> Only one write operation upon a writable channel may be in progress at
18   * any given time.  If one thread initiates a write operation upon a channel
19   * then any other thread that attempts to initiate another write operation will
20   * block until the first operation is complete.  Whether or not other kinds of
21   * I/O operations may proceed concurrently with a write operation depends upon
22   * the type of the channel. </p>
23   *
24   *
25   * @author Mark Reinhold
26   * @author JSR-51 Expert Group
27   * @version 1.15, 03/12/19
28   * @since 1.4
29   */
30  
31  public interface WritableByteChannel
32      extends Channel  
33  {
34  
35      /**
36       * Writes a sequence of bytes to this channel from the given buffer.
37       *
38       * <p> An attempt is made to write up to <i>r</i> bytes to the channel,
39       * where <i>r</i> is the number of bytes remaining in the buffer, that is,
40       * <tt>dst.remaining()</tt>, at the moment this method is invoked.
41       *
42       * <p> Suppose that a byte sequence of length <i>n</i> is written, where
43       * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
44       * This byte sequence will be transferred from the buffer starting at index
45       * <i>p</i>, where <i>p</i> is the buffer's position at the moment this
46       * method is invoked; the index of the last byte written will be
47       * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>.
48       * Upon return the buffer's position will be equal to
49       * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
50       *
51       * <p> Unless otherwise specified, a write operation will return only after
52       * writing all of the <i>r</i> requested bytes.  Some types of channels,
53       * depending upon their state, may write only some of the bytes or possibly
54       * none at all.  A socket channel in non-blocking mode, for example, cannot
55       * write any more bytes than are free in the socket's output buffer.
56       *
57       * <p> This method may be invoked at any time.  If another thread has
58       * already initiated a write operation upon this channel, however, then an
59       * invocation of this method will block until the first operation is
60       * complete. </p>
61       *
62       * @param  src
63       *         The buffer from which bytes are to be retrieved
64       *
65       * @return The number of bytes written, possibly zero
66       *
67       * @throws  NonWritableChannelException
68       *          If this channel was not opened for writing
69       *
70       * @throws  ClosedChannelException
71       *          If this channel is closed
72       *
73       * @throws  AsynchronousCloseException
74       *          If another thread closes this channel
75       *          while the write operation is in progress
76       *
77       * @throws  ClosedByInterruptException
78       *          If another thread interrupts the current thread
79       *          while the write operation is in progress, thereby
80       *          closing the channel and setting the current thread's
81       *          interrupt status
82       *
83       * @throws  IOException
84       *          If some other I/O error occurs
85       */
86      public int write(ByteBuffer   src) throws IOException  ;
87  
88  }
89
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags