com.limegroup.gnutella.messages
Class Message

java.lang.Object
  extended bycom.limegroup.gnutella.messages.Message
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable
Direct Known Subclasses:
PingReply, PingRequest, PushRequest, QueryReply, QueryRequest, RouteTableMessage, VendorMessage

public abstract class Message
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable

A Gnutella message (packet). This class is abstract; subclasses implement specific messages such as search requests.

All messages have message IDs, function IDs, TTLs, hops taken, and data length. Messages come in two flavors: requests (ping, search) and replies (pong, search results). Message are mostly immutable; only the TTL, hops, and priority field can be changed.

See Also:
Serialized Form

Field Summary
static byte F_PING
           
static byte F_PING_REPLY
           
static byte F_PUSH
           
static byte F_QUERY
           
static byte F_QUERY_REPLY
           
static byte F_ROUTE_TABLE_UPDATE
           
static byte F_VENDOR_MESSAGE
           
static byte F_VENDOR_MESSAGE_STABLE
           
static int N_MULTICAST
           
static int N_TCP
           
static int N_UDP
           
static int N_UNKNOWN
           
protected static boolean RECORD_STATS
          Constant for whether or not to record stats.
static byte SOFT_MAX
          Cached soft max ttl -- if the TTL+hops is greater than SOFT_MAX, the TTL is set to SOFT_MAX-hops.
 
Constructor Summary
protected Message(byte[] guid, byte func, byte ttl, byte hops, int length)
          Same as above, but caller specifies TTL and number of hops.
protected Message(byte[] guid, byte func, byte ttl, byte hops, int length, int network)
          Same as above, but caller specifies the network.
protected Message(byte func, byte ttl, int length)
           
 
Method Summary
 int compareTo(java.lang.Object message)
          Returns a negative value if this is of lesser priority than message, positive value if of higher priority, or zero if of same priority.
 long getCreationTime()
          Returns the system time (i.e., the result of System.currentTimeMillis()) this was instantiated.
 byte getFunc()
           
 byte[] getGUID()
           
 byte getHops()
           
 int getLength()
          Returns the length of this' payload, in bytes.
 int getNetwork()
           
 int getPriority()
          Returns this user-defined priority.
 int getTotalLength()
          Returns the total length of this, in bytes
 byte getTTL()
           
 byte hop()
           
 boolean isMulticast()
           
 boolean isTCP()
           
 boolean isUDP()
           
 boolean isUnknownNetwork()
           
static byte[] makeGuid()
          Same as GUID.makeGUID.
static Message read(java.io.InputStream in)
          Reads a Gnutella message from the specified input stream.
static Message read(java.io.InputStream in, byte softMax)
           
static Message read(java.io.InputStream in, byte[] buf, byte softMax)
           
static Message read(java.io.InputStream in, byte[] buf, int network, byte softMax)
           
static Message read(java.io.InputStream in, int network)
           
protected  byte[] readNullTerminatedBytes(java.io.InputStream is)
           
abstract  void recordDrop()
          Records the dropping of this message in statistics.
protected  void repOk()
          Rep.
protected  void setGUID(GUID guid)
          Sets the guid for this message.
 void setHops(byte hops)
          If the hops is less than zero, throws IllegalArgumentException.
 void setPriority(int priority)
          Set this user-defined priority for flow-control purposes.
 void setTTL(byte ttl)
          If ttl is less than zero, throws IllegalArgumentException.
abstract  Message stripExtendedPayload()
          Returns a message identical to this but without any extended (typically GGEP) data.
 java.lang.String toString()
           
protected  void updateLength(int l)
          Updates length of this' payload, in bytes.
 void write(java.io.OutputStream out)
           
protected  boolean writeGemExtension(java.io.OutputStream os, boolean addPrefixDelimiter, byte[] extBytes)
           
protected  boolean writeGemExtension(java.io.OutputStream os, boolean addPrefixDelimiter, java.lang.String ext)
           
protected  boolean writeGemExtensions(java.io.OutputStream os, boolean addPrefixDelimiter, java.util.Iterator iter)
           
protected abstract  void writePayload(java.io.OutputStream out)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

F_PING

public static final byte F_PING
See Also:
Constant Field Values

F_PING_REPLY

public static final byte F_PING_REPLY
See Also:
Constant Field Values

F_PUSH

public static final byte F_PUSH
See Also:
Constant Field Values

F_QUERY

public static final byte F_QUERY
See Also:
Constant Field Values

F_QUERY_REPLY

public static final byte F_QUERY_REPLY
See Also:
Constant Field Values

F_ROUTE_TABLE_UPDATE

public static final byte F_ROUTE_TABLE_UPDATE
See Also:
Constant Field Values

F_VENDOR_MESSAGE

public static final byte F_VENDOR_MESSAGE
See Also:
Constant Field Values

F_VENDOR_MESSAGE_STABLE

public static final byte F_VENDOR_MESSAGE_STABLE
See Also:
Constant Field Values

N_UNKNOWN

public static final int N_UNKNOWN
See Also:
Constant Field Values

N_TCP

public static final int N_TCP
See Also:
Constant Field Values

N_UDP

public static final int N_UDP
See Also:
Constant Field Values

N_MULTICAST

public static final int N_MULTICAST
See Also:
Constant Field Values

SOFT_MAX

public static final byte SOFT_MAX
Cached soft max ttl -- if the TTL+hops is greater than SOFT_MAX, the TTL is set to SOFT_MAX-hops.


RECORD_STATS

protected static final boolean RECORD_STATS
Constant for whether or not to record stats.

Constructor Detail

Message

protected Message(byte func,
                  byte ttl,
                  int length)

Message

protected Message(byte[] guid,
                  byte func,
                  byte ttl,
                  byte hops,
                  int length)
Same as above, but caller specifies TTL and number of hops. This is used when reading packets off network.


Message

protected Message(byte[] guid,
                  byte func,
                  byte ttl,
                  byte hops,
                  int length,
                  int network)
Same as above, but caller specifies the network. This is used when reading packets off network.

Method Detail

makeGuid

public static byte[] makeGuid()
Same as GUID.makeGUID. This exists for backwards compatibility.


repOk

protected void repOk()
Rep. invariant


read

public static Message read(java.io.InputStream in)
                    throws BadPacketException,
                           java.io.IOException
Reads a Gnutella message from the specified input stream. The returned message can be any one of the recognized Gnutella message, such as queries, query hits, pings, pongs, etc.

Parameters:
in - the InputStream instance containing message data
Returns:
a new Gnutella message instance
Throws:
BadPacketException - if the message is not considered valid for any reason
IOException - if there is any IO problem reading the message
BadPacketException
java.io.IOException

read

public static Message read(java.io.InputStream in,
                           byte softMax)
                    throws BadPacketException,
                           java.io.IOException
Throws:
BadPacketException
java.io.IOException

read

public static Message read(java.io.InputStream in,
                           int network)
                    throws BadPacketException,
                           java.io.IOException
Throws:
BadPacketException
java.io.IOException

read

public static Message read(java.io.InputStream in,
                           byte[] buf,
                           byte softMax)
                    throws BadPacketException,
                           java.io.IOException
Throws:
BadPacketException
java.io.IOException

read

public static Message read(java.io.InputStream in,
                           byte[] buf,
                           int network,
                           byte softMax)
                    throws BadPacketException,
                           java.io.IOException
Parameters:
network - the network this was received from.
Throws:
BadPacketException
java.io.IOException

write

public void write(java.io.OutputStream out)
           throws java.io.IOException
Throws:
java.io.IOException

writePayload

protected abstract void writePayload(java.io.OutputStream out)
                              throws java.io.IOException
Throws:
java.io.IOException

writeGemExtension

protected boolean writeGemExtension(java.io.OutputStream os,
                                    boolean addPrefixDelimiter,
                                    byte[] extBytes)
                             throws java.io.IOException
Throws:
java.io.IOException

writeGemExtension

protected boolean writeGemExtension(java.io.OutputStream os,
                                    boolean addPrefixDelimiter,
                                    java.lang.String ext)
                             throws java.io.IOException
Throws:
java.io.IOException

writeGemExtensions

protected boolean writeGemExtensions(java.io.OutputStream os,
                                     boolean addPrefixDelimiter,
                                     java.util.Iterator iter)
                              throws java.io.IOException
Throws:
java.io.IOException

readNullTerminatedBytes

protected byte[] readNullTerminatedBytes(java.io.InputStream is)
                                  throws java.io.IOException
Throws:
java.io.IOException

getNetwork

public int getNetwork()

isMulticast

public boolean isMulticast()

isUDP

public boolean isUDP()

isTCP

public boolean isTCP()

isUnknownNetwork

public boolean isUnknownNetwork()

getGUID

public byte[] getGUID()

getFunc

public byte getFunc()

getTTL

public byte getTTL()

setTTL

public void setTTL(byte ttl)
            throws java.lang.IllegalArgumentException
If ttl is less than zero, throws IllegalArgumentException. Otherwise sets this TTL to the given value. This is useful when you want certain messages to travel less than others.

Throws:
java.lang.IllegalArgumentException

setGUID

protected void setGUID(GUID guid)
Sets the guid for this message. Is needed, when we want to cache query replies or other messages, and change the GUID as per the request

Parameters:
guid - The guid to be set

setHops

public void setHops(byte hops)
             throws java.lang.IllegalArgumentException
If the hops is less than zero, throws IllegalArgumentException. Otherwise sets this hops to the given value. This is useful when you want certain messages to look as if they've travelled further.

Throws:
java.lang.IllegalArgumentException

getHops

public byte getHops()

getLength

public int getLength()
Returns the length of this' payload, in bytes.


updateLength

protected void updateLength(int l)
Updates length of this' payload, in bytes.


getTotalLength

public int getTotalLength()
Returns the total length of this, in bytes


hop

public byte hop()

getCreationTime

public long getCreationTime()
Returns the system time (i.e., the result of System.currentTimeMillis()) this was instantiated.


getPriority

public int getPriority()
Returns this user-defined priority. Lower values are higher priority.


setPriority

public void setPriority(int priority)
Set this user-defined priority for flow-control purposes. Lower values are higher priority.


stripExtendedPayload

public abstract Message stripExtendedPayload()
Returns a message identical to this but without any extended (typically GGEP) data. Since Message's are mostly immutable, the returned message may alias parts of this; in fact the returned message could even be this. The caveat is that the hops and TTL field of Message can be mutated for efficiency reasons. Hence you must not call hop() on either this or the returned value. Typically this is not a problem, as hop() is called before forwarding/broadcasting a message.

Returns:
an instance of this without any dangerous extended payload

compareTo

public int compareTo(java.lang.Object message)
Returns a negative value if this is of lesser priority than message, positive value if of higher priority, or zero if of same priority. Remember that lower priority numbers mean HIGHER priority.

Specified by:
compareTo in interface java.lang.Comparable
Throws:
java.lang.ClassCastException - message not an instance of Message

toString

public java.lang.String toString()

recordDrop

public abstract void recordDrop()
Records the dropping of this message in statistics.