2 * Copyright (c) 2001-2007 Sun Microsystems, Inc. All rights reserved.
4 * The Sun Project JXTA(TM) Software License
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
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.
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.
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.
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.
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.
41 * JXTA is a registered trademark of Sun Microsystems, Inc. in the United
42 * States and other countries.
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.
48 * ====================================================================
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.
54 * This license is based on the BSD license adopted by the Apache Foundation.
57 package net.jxta.endpoint;
60 import java.io.IOException;
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.
68 * <p/>MessageSenders additionally describe themselves in terms of their
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>
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
86 public interface MessageSender extends MessageTransport {
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.
94 * <p/>The public address may also be for a different message transport.
96 * @return an EndpointAddress containing the public address for this
99 public EndpointAddress getPublicAddress();
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.
106 * @return {@code true} if the Message Transport is connection oriented.
108 public boolean isConnectionOriented();
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
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}.
120 * @return <tt>true</tt> if the protocol can be used by the EndpointRouter
122 public boolean allowsRouting();
125 * Return a {@link Messenger} for sending messages to the specified
126 * destination {@link EndpointAddress}.
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.
134 public Messenger getMessenger(EndpointAddress dest, Object hint);
137 * Returns {@code true} if the specified destination address is reachable
138 * via this Message Transport otherwise returns {@code false}.
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.
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}.
149 public boolean ping(EndpointAddress addr);