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