sjero.net Git - linphone/blob - p2pproxy/dependencies-src/jxse-src-2.5/api/src/net/jxta/endpoint/MessageSender.java

   1 /*
   2  * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
   3  *
   4  *  The Sun Project JXTA(TM) Software License
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are met:
   8  *
   9  *  1. Redistributions of source code must retain the above copyright notice,
  10  *     this list of conditions and the following disclaimer.
  11  *
  12  *  2. Redistributions in binary form must reproduce the above copyright notice,
  13  *     this list of conditions and the following disclaimer in the documentation
  14  *     and/or other materials provided with the distribution.
  15  *
  16  *  3. The end-user documentation included with the redistribution, if any, must
  17  *     include the following acknowledgment: "This product includes software
  18  *     developed by Sun Microsystems, Inc. for JXTA(TM) technology."
  19  *     Alternately, this acknowledgment may appear in the software itself, if
  20  *     and wherever such third-party acknowledgments normally appear.
  21  *
  22  *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
  23  *     not be used to endorse or promote products derived from this software
  24  *     without prior written permission. For written permission, please contact
  25  *     Project JXTA at http://www.jxta.org.
  26  *
  27  *  5. Products derived from this software may not be called "JXTA", nor may
  28  *     "JXTA" appear in their name, without prior written permission of Sun.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
  31  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  32  *  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
  33  *  MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  34  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  36  *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  37  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  38  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  39  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  *
  41  *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United
  42  *  States and other countries.
  43  *
  44  *  Please see the license information page at :
  45  *  <http://www.jxta.org/project/www/license.html> for instructions on use of
  46  *  the license in source files.
  47  *
  48  *  ====================================================================
  49  *
  50  *  This software consists of voluntary contributions made by many individuals
  51  *  on behalf of Project JXTA. For more information on Project JXTA, please see
  52  *  http://www.jxta.org.
  53  *
  54  *  This license is based on the BSD license adopted by the Apache Foundation.
  55  */
  56
  57 package net.jxta.endpoint;
  58
  59
  60 import java.io.IOException;
  61
  62
  63 /**
  64  *  A MessageSender is a MessageTransport that is able to send messages to
  65  *  remote peers using some protocol. MessageSenders provide facilities for
  66  *  sending point-to-point (unicast) messages.
  67  *
  68  *  <p/>MessageSenders additionally describe themselves in terms of their
  69  *  abilities.
  70  *  <dl>
  71  *  <dt>{@link #isConnectionOriented()}</dt><dd>Indicates that the
  72  *  Message Transport can provide efficient transport of a series of messages to
  73  *  the same destination</dd>
  74  *  <dt>{link@ #allowRouting()}</dt><dd>Indicates that the Message Transport
  75  *  can be used in the routing of messages to destinations which are not
  76  *  directly reachable via this transport.</dd>
  77  *  </dl>
  78  *
  79  *  @see net.jxta.endpoint.MessageTransport
  80  *  @see net.jxta.endpoint.Message
  81  *  @see net.jxta.endpoint.Messenger
  82  *  @see net.jxta.endpoint.EndpointService
  83  *  @see net.jxta.endpoint.MessageReceiver
  84  *  @see net.jxta.endpoint.MessagePropagater
  85  */
  86 public interface MessageSender extends MessageTransport {
  87
  88     /**
  89      *  Returns the {@link EndpointAddress} which will be used as the source
  90      *  address for all messages sent by this message sender. This is the
  91      *  "preferred" address to which replies should be sent. This address is not
  92      *  necessarily the best or only address by which the peer may be reached.
  93      *
  94      *  <p/>The public address may also be for a different message transport.
  95      *
  96      *  @return an EndpointAddress containing the public address for this
  97      *  message receiver.
  98      */
  99     public EndpointAddress getPublicAddress();
 100
 101     /**
 102      *  Returns {@code true} if the Message Transport is connection oriented
 103      *  (like TCP/IP). Indicates that the Message Transport can provide
 104      *  efficient transport of a series of messages to the same destination.
 105      *
 106      *  @return {@code true} if the Message Transport is connection oriented.
 107      */
 108     public boolean isConnectionOriented();
 109
 110     /**
 111      *  Returns true if the Message Transport can be used by the EndpointRouter.
 112      *  Indicates that the Message Transport can be used in the routing of
 113      *  messages to destinations which are not directly reachable via this
 114      *  transport.
 115      *
 116      *  <p/>More specifically, this Message Transport will be used to route
 117      *  messages who's final destination is <b>not</b> one of the endpoint
 118      *  addresses available from {@code getReachableEndpointAddresses}.
 119      *
 120      * @return <tt>true</tt> if the protocol can be used by the EndpointRouter
 121      */
 122     public boolean allowsRouting();
 123
 124     /**
 125      *  Return a {@link Messenger} for sending messages to the specified
 126      *  destination {@link EndpointAddress}.
 127      *
 128      @param dest The destination address for which a messenger is requested.
 129      *  @param hint An optional hint for the transport to use when creating the
 130      *  messenger. The format of the hint is specific to each Message Transport
 131      *  and may be {@code null} if no hint is provided.
 132      *  @return a Messenger or {@code null} if the destination is not reachable.
 133      */
 134     public Messenger getMessenger(EndpointAddress dest, Object hint);
 135
 136     /**
 137      *  Returns {@code true} if the specified destination address is reachable
 138      *  via this Message Transport otherwise returns {@code false}.
 139      *
 140      *  @deprecated This operation is often very expensive and usually
 141      *  duplicates the work of {@link #getMessenger}. If you want to determine
 142      *  the reachability of a destination, get a Messenger to the destination.
 143      *
 144      *  @param addr Address to ping
 145      *  @return {@code true} if the specified destination address is reachable
 146      *  via this Message Transport otherwise returns {@code false}.
 147      */
 148     @Deprecated
 149     public boolean ping(EndpointAddress addr);
 150 }