home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / net / SocketOptions.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  7.7 KB  |  224 lines
  1. /*
  2.  * @(#)SocketOptions.java    1.7 98/03/18
  3.  *
  4.  * Copyright 1996, 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.net;
  16.  
  17. /**
  18.  * Interface of methods to get/set socket options.  This interface is
  19.  * implemented by: <B>SocketImpl</B> and  <B>DatagramSocketImpl</B>.  
  20.  * Subclasses of these should override the methods
  21.  * of this interface in order to support their own options.
  22.  * <P>
  23.  * The methods and constants which specify options in this interface are
  24.  * for implementation only.  If you're not subclassing SocketImpl or
  25.  * DatagramSocketImpl, <B>you won't use these directly.</B> There are
  26.  * type-safe methods to get/set each of these options in Socket, ServerSocket, 
  27.  * DatagramSocket and MulticastSocket.
  28.  * <P>
  29.  * A subset of the standard BSD-style socket options are supported in the
  30.  * JDK base classes, <B>PlainSocketImpl</B> and <B>PlainDatagramSocketImpl</B>.  
  31.  * A brief description of each and their use is provided.
  32.  * <P>
  33.  * @version 1.7, 03/18/98
  34.  * @author David Brown
  35.  */
  36.  
  37.  
  38. interface SocketOptions {
  39.  
  40.     /**
  41.      * Enable/disable the option specified by <I>optID</I>.  If the option
  42.      * is to be enabled, and it takes an option-specific "value",  this is 
  43.      * passed in <I>value</I>.  The actual type of value is option-specific,
  44.      * and it is an error to pass something that isn't of the expected type:
  45.      * <BR><PRE>
  46.      * SocketImpl s;
  47.      * ...
  48.      * s.setOption(SO_LINGER, new Integer(10)); 
  49.      *    // OK - set SO_LINGER w/ timeout of 10 sec.
  50.      * s.setOption(SO_LINGER, new Double(10)); 
  51.      *    // ERROR - expects java.lang.Integer
  52.      *</PRE>
  53.      * If the requested option is binary, it can be set using this method by
  54.      * a java.lang.Boolean:
  55.      * <BR><PRE>
  56.      * s.setOption(TCP_NODELAY, new Boolean(true)); 
  57.      *    // OK - enables TCP_NODELAY, a binary option
  58.      * </PRE>
  59.      * <BR>
  60.      * Any option can be disabled using this method with a Boolean(false):
  61.      * <BR><PRE>
  62.      * s.setOption(TCP_NODELAY, new Boolean(false)); 
  63.      *    // OK - disables TCP_NODELAY
  64.      * s.setOption(SO_LINGER, new Boolean(false)); 
  65.      *    // OK - disables SO_LINGER
  66.      * </PRE>
  67.      * <BR>
  68.      * For an option that requires a particular parameter, 
  69.      * setting its value to anything other than 
  70.      * <I>Boolean(false)</I> implicitly enables it.
  71.      * <BR>
  72.      * Throws SocketException if the option is unrecognized, 
  73.      * the socket is closed, or some low-level error occurred 
  74.      * <BR>
  75.      * @param optID identifies the option 
  76.      * @param value the parameter of the socket option
  77.      * @throws SocketException if the option is unrecognized, 
  78.      * the socket is closed, or some low-level error occurred 
  79.      */
  80.  
  81.     public void 
  82.     setOption(int optID, Object value) throws SocketException;
  83.  
  84.     /**
  85.      * Fetch the value of an option.  
  86.      * Binary options will return java.lang.Boolean(true) 
  87.      * if enabled, java.lang.Boolean(false) if disabled, e.g.:
  88.      * <BR><PRE>
  89.      * SocketImpl s;
  90.      * ...
  91.      * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
  92.      * if (noDelay.booleanValue()) {
  93.      *     // true if TCP_NODELAY is enabled...
  94.      * ...
  95.      * }
  96.      * </PRE>
  97.      * <P>
  98.      * For options that take a particular type as a parameter,
  99.      * getOption(int) will return the paramter's value, else
  100.      * it will return java.lang.Boolean(false):
  101.      * <PRE>
  102.      * Object o = s.getOption(SO_LINGER);
  103.      * if (o instanceof Integer) {
  104.      *     System.out.print("Linger time is " + ((Integer)o).intValue());
  105.      * } else {
  106.      *   // the true type of o is java.lang.Boolean(false);
  107.      * }
  108.      * </PRE>
  109.      *
  110.      * @throws SocketException if the socket is closed
  111.      * @throws SocketException if <I>optID</I> is unknown along the
  112.      *         protocol stack (including the SocketImpl)
  113.      */
  114.       
  115.     public Object getOption(int optID) throws SocketException;
  116.  
  117.     /**
  118.      * The java-supported BSD-style options.
  119.      */
  120.  
  121.     /**
  122.      * Disable Nagle's algorithm for this connection.  Written data
  123.      * to the network is not buffered pending acknowledgement of
  124.      * previously written data.  
  125.      *<P>
  126.      * Valid for TCP only: SocketImpl.
  127.      * <P>
  128.      * @see Socket#setTcpNoDelay
  129.      * @see Socket#getTcpNoDelay
  130.      */
  131.  
  132.     public final static int TCP_NODELAY = 0x0001;
  133.  
  134.     /**
  135.      * Fetch the local address binding of a socket (this option cannot
  136.      * be "set" only "gotten", since sockets are bound at creation time,
  137.      * and so the locally bound address cannot be changed).  The default local
  138.      * address of a socket is INADDR_ANY, meaning any local address on a
  139.      * multi-homed host.  A multi-homed host can use this option to accept
  140.      * connections to only one of its addresses (in the case of a 
  141.      * ServerSocket or DatagramSocket), or to specify its return address 
  142.      * to the peer (for a Socket or DatagramSocket).  The parameter of 
  143.      * this option is an InetAddress.
  144.      * <P>
  145.      * This option <B>must</B> be specified in the constructor.
  146.      * <P>
  147.      * Valid for: SocketImpl, DatagramSocketImpl
  148.      * <P>
  149.      * @see Socket#getLocalAddress
  150.      * @see Server#getLocalAddress
  151.      * @see DatagramSocket#getLocalAddress
  152.      */
  153.  
  154.     public final static int SO_BINDADDR = 0x000F;
  155.  
  156.     /** Sets SO_REUSEADDR for a socket.  This is used only for MulticastSockets
  157.      * in java, and it is set by default for MulticastSockets.
  158.      * <P>
  159.      * Valid for: DatagramSocketImpl
  160.      */
  161.  
  162.     public final static int SO_REUSEADDR = 0x04;
  163.  
  164.     /** Set which outgoing interface on which to send multicast packets.  
  165.      * Useful on hosts with multiple network interfaces, where applications
  166.      * want to use other than the system default.  Takes/returns an InetAddress.
  167.      * <P>
  168.      * Valid for Multicast: DatagramSocketImpl
  169.      * <P>
  170.      * @see MulticastSocket#setInterface
  171.      * @see MulitcastSocket#getInterface
  172.      */
  173.      
  174.     public final static int IP_MULTICAST_IF = 0x10;
  175.  
  176.     /**
  177.      * Specify a linger-on-close timeout.  This option disables/enables 
  178.      * immediate return from a <B>close()</B> of a TCP Socket.  Enabling 
  179.      * this option with a non-zero Integer <I>timeout</I> means that a 
  180.      * <B>close()</B> will block pending the transmission and acknowledgement
  181.      * of all data written to the peer, at which point the socket is closed
  182.      * <I>gracefully</I>.  Upon reaching the linger timeout, the socket is
  183.      * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a 
  184.      * timeout of zero does a forceful close immediately.
  185.      * <P>
  186.      * <B>Note:</B>The actual implementation of SO_LINGER in the OS varies 
  187.      * across platforms.
  188.      * <P>
  189.      * Valid only for TCP: SocketImpl
  190.      * <P>
  191.      * @see Socket#setSoLinger
  192.      * @see Socket#getSoLinger
  193.      */
  194.  
  195.     public final static int SO_LINGER = 0x0080;
  196.  
  197.     /** Set a timeout on blocking Socket operations:
  198.      * <PRE>
  199.      * ServerSocket.accept();
  200.      * SocketInputStream.read();
  201.      * DatagramSocket.receive();
  202.      * </PRE>
  203.      * <P>
  204.      * The option must be set prior to entering a blocking operation to take effect.
  205.      * If the timeout expires and the operation would continue to block,
  206.      * <B>java.io.InterruptedIOException</B> is raised.  The Socket is not closed
  207.      * in this case.
  208.      * <P>
  209.      * Valid for all sockets: SocketImpl, DatagramSocketImpl
  210.      * <P>
  211.      * @see Socket#setSoTimeout
  212.      * @see ServerSocket#setSoTimeout
  213.      * @see DatagramSocket#setSoTimeout
  214.      */
  215.  
  216.     public final static int SO_TIMEOUT = 0x1006;
  217. }
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.