home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / MulticastSocket.java < prev    next >
Text File  |  1998-09-22  |  8KB  |  231 lines
  1. /*
  2.  * @(#)MulticastSocket.java    1.19 98/07/01
  3.  *
  4.  * Copyright 1995-1998 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. import java.io.IOException;
  18. import java.io.InterruptedIOException;
  19.  
  20. /**
  21.  * The multicast datagram socket class is useful for sending
  22.  * and receiving IP multicast packets.  A MulticastSocket is
  23.  * a (UDP) DatagramSocket, with additional capabilities for
  24.  * joining "groups" of other multicast hosts on the internet.
  25.  * <P>
  26.  * A multicast group is specified by a class D IP address, those
  27.  * in the range <CODE>224.0.0.1</CODE> to <CODE>239.255.255.255</CODE>, 
  28.  * inclusive, and by a standard UDP port number.  One would join a 
  29.  * multicast group by first creating a MulticastSocket with the desired
  30.  * port, then invoking the <CODE>joinGroup(InetAddress groupAddr)</CODE>
  31.  * method:
  32.  * <PRE>
  33.  * // join a Multicast group and send the group salutations
  34.  * ...
  35.  * byte[] msg = {'H', 'e', 'l', 'l', 'o'};
  36.  * InetAddress group = InetAddress.getByName("228.5.6.7");
  37.  * MulticastSocket s = new MulticastSocket(6789);
  38.  * s.joinGroup(group);
  39.  * DatagramPacket hi = new DatagramPacket(msg, msg.length,
  40.  *                             group, 6789);
  41.  * s.send(hi);
  42.  * // get their responses! 
  43.  * byte[] buf = new byte[1000];
  44.  * DatagramPacket recv = new DatagramPacket(buf, buf.length);
  45.  * s.receive(recv);
  46.  * ...
  47.  * // OK, I'm done talking - leave the group...
  48.  * s.leaveGroup(group);
  49.  * </PRE>
  50.  * 
  51.  * When one sends a message to a multicast group, <B>all</B> subscribing
  52.  * recipients to that host and port receive the message (within the
  53.  * time-to-live range of the packet, see below).  The socket needn't
  54.  * be a member of the multicast group to send messages to it.
  55.  * <P>
  56.  * When a socket subscribes to a multicast group/port, it receives
  57.  * datagrams sent by other hosts to the group/port, as do all other
  58.  * members of the group and port.  A socket relinquishes membership
  59.  * in a group by the leaveGroup(InetAddress addr) method.  <B> 
  60.  * Multiple MulticastSocket's</B> may subscribe to a multicast group
  61.  * and port concurrently, and they will all receive group datagrams.
  62.  * <P>
  63.  * Currently applets are not allowed ot use multicast sockets.
  64.  *
  65.  * @author Pavani Diwanji
  66.  * @since  JDK1.1
  67.  */
  68. public
  69. class MulticastSocket extends DatagramSocket {
  70.     /**
  71.      * Create a multicast socket.
  72.      * @since   JDK1.1
  73.      */
  74.     public MulticastSocket() throws IOException {
  75.     super();
  76.     }
  77.  
  78.     /**
  79.      * Create a multicast socket and bind it to a specific port.
  80.      * @param local port to use
  81.      * @since   JDK1.1
  82.      */
  83.     public MulticastSocket(int port) throws IOException {
  84.     super(port);
  85.     }
  86.  
  87.     /* do the work of creating a vanilla multicast socket.  It is
  88.      * important that the signature of this method not change,
  89.      * even though it is package-private, since it is overrides a
  90.      * method from DatagramSocket, which must not set SO_REUSEADDR.
  91.      */
  92.     void create(int port, InetAddress ignore) throws SocketException {
  93.     SecurityManager security = System.getSecurityManager();
  94.     if (security != null) {
  95.         security.checkListen(port);
  96.     }
  97.     try {
  98.         this.impl = (DatagramSocketImpl) implClass.newInstance();
  99.     } catch (Exception e) {
  100.         throw new SocketException("can't instantiate DatagramSocketImpl" + e.toString());
  101.     }
  102.     impl.create();
  103.     impl.setOption(SocketOptions.SO_REUSEADDR, new Integer(-1));
  104.     impl.bind(port, InetAddress.anyLocalAddress);
  105.     }
  106.     
  107.     /**
  108.      * Set the default time-to-live for multicast packets sent out
  109.      * on this socket.  The TTL sets the IP time-to-live for
  110.      * <code>DatagramPackets</code> sent to a MulticastGroup, which
  111.      * specifies how many "hops" that the packet will be forwarded
  112.      * on the network before it expires.
  113.      * <P>
  114.      * The ttl is an <b>unsigned</b> 8-bit quantity, and so <B>must</B> be
  115.      * in the range <code> 0 < ttl <= 0xFF </code>.
  116.      * @param ttl the time-to-live
  117.      * @since   JDK1.1
  118.      */
  119.     public void setTTL(byte ttl) throws IOException {
  120.     impl.setTTL(ttl);
  121.     }
  122.  
  123.     /**
  124.      * Get the default time-to-live for multicast packets sent out
  125.      * on the socket.
  126.      * @since   JDK1.1
  127.      */
  128.     public byte getTTL() throws IOException {
  129.     return impl.getTTL();
  130.     }
  131.  
  132.     /**
  133.      * Joins a multicast group.
  134.      * @param mcastaddr is the multicast address to join 
  135.      * @exception IOException is raised if there is an error joining
  136.      * or when address is not a multicast address.
  137.      * @since   JDK1.1
  138.      */
  139.     public void joinGroup(InetAddress mcastaddr) throws IOException {
  140.  
  141.     SecurityManager security = System.getSecurityManager();
  142.     if (security != null) {
  143.         security.checkMulticast(mcastaddr);
  144.     }
  145.     impl.join(mcastaddr);
  146.     }
  147.  
  148.     /**
  149.      * Leave a multicast group.
  150.      * @param mcastaddr is the multicast address to leave
  151.      * @exception IOException is raised if there is an error leaving
  152.      * or when address is not a multicast address.
  153.      * @since   JDK1.1
  154.      */
  155.     public void leaveGroup(InetAddress mcastaddr) throws IOException {
  156.  
  157.     SecurityManager security = System.getSecurityManager();
  158.     if (security != null) {
  159.         security.checkMulticast(mcastaddr);
  160.     }
  161.     impl.leave(mcastaddr);
  162.     }
  163.  
  164.     /**
  165.      * Set the outgoing network interface for multicast packets on this
  166.      * socket, to other than the system default.  Useful for multihomed
  167.      * hosts.
  168.      * @since   JDK1.1
  169.      */
  170.     public void setInterface(InetAddress inf) throws SocketException {
  171.     impl.setOption(SocketOptions.IP_MULTICAST_IF, inf);
  172.     }
  173.     
  174.     /**
  175.      * Retrieve the address of the network interface used for
  176.      * multicast packets.
  177.      * @since   JDK1.1
  178.      */
  179.     public InetAddress getInterface() throws SocketException {
  180.     return (InetAddress) impl.getOption(SocketOptions.IP_MULTICAST_IF);
  181.     }
  182.     
  183.     /**
  184.      * Sends a datagram packet to the destination, with a TTL (time-
  185.      * to-live) other than the default for the socket.  This method
  186.      * need only be used in instances where a particular TTL is desired;
  187.      * otherwise it is preferable to set a TTL once on the socket, and
  188.      * use that default TTL for all packets.  This method does <B>not
  189.      * </B> alter the default TTL for the socket.
  190.      * @param p    is the packet to be sent. The packet should contain
  191.      * the destination multicast ip address and the data to be sent.
  192.      * One does not need to be the member of the group to send
  193.      * packets to a destination multicast address.
  194.      * @param ttl optional time to live for multicast packet.
  195.      * default ttl is 1.
  196.      * @exception IOException is raised if an error occurs i.e
  197.      * error while setting ttl.
  198.      * @see DatagramSocket#send
  199.      * @see DatagramSocket#receive
  200.      * @since   JDK1.1
  201.      */
  202.     public synchronized void send(DatagramPacket p, byte ttl)
  203.      throws IOException {
  204.  
  205.         // Security manager makes sure that the multicast address is
  206.     // is allowed one and that the ttl used is less
  207.     // than the allowed maxttl.
  208.     SecurityManager security = System.getSecurityManager();
  209.     if (security != null) {
  210.         if (p.getAddress().isMulticastAddress()) {
  211.         security.checkMulticast(p.getAddress(), ttl);
  212.         } else {
  213.         security.checkConnect(p.getAddress().getHostAddress(), p.getPort());
  214.         }
  215.     }
  216.  
  217.     byte dttl = getTTL();
  218.     
  219.     if (ttl != dttl) {
  220.     // set the ttl
  221.         impl.setTTL(ttl);
  222.     }
  223.     // call the datagram method to send
  224.     impl.send(p);
  225.     // set it back to default
  226.     if (ttl != dttl) {
  227.         impl.setTTL(dttl);
  228.     } 
  229.     }  
  230. }
  231.