com.limegroup.gnutella.messages
Class QueryRequest

java.lang.Object
  extended bycom.limegroup.gnutella.messages.Message
      extended bycom.limegroup.gnutella.messages.QueryRequest
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable

public class QueryRequest
extends Message
implements java.io.Serializable

This class creates Gnutella query messages, either from scratch, or from data read from the network. Queries can contain query strings, XML query strings, URNs, etc. The minimum speed field is now used for bit flags to indicate such things as the firewalled status of the querier.

This class also has factory constructors for requeries originated from this LimeWire. These requeries have specially marked GUIDs that allow us to identify them as requeries.

See Also:
Serialized Form

Field Summary
static int SPECIAL_FIREWALL_MASK
           
static int SPECIAL_MINSPEED_MASK
           
static int SPECIAL_OUTOFBAND_MASK
           
static int SPECIAL_XML_MASK
           
 
Fields inherited from class com.limegroup.gnutella.messages.Message
F_PING, F_PING_REPLY, F_PUSH, F_QUERY, F_QUERY_REPLY, F_ROUTE_TABLE_UPDATE, F_VENDOR_MESSAGE, F_VENDOR_MESSAGE_STABLE, N_MULTICAST, N_TCP, N_UDP, N_UNKNOWN, RECORD_STATS, SOFT_MAX
 
Constructor Summary
QueryRequest(byte[] guid, byte ttl, java.lang.String query, java.lang.String richQuery, java.util.Set requestedUrnTypes, java.util.Set queryUrns, QueryKey queryKey, boolean isFirewalled, int network, boolean canReceiveOutOfBandReplies)
          Builds a new query from scratch but you can flag it as a Requery, if needed.
 
Method Summary
static QueryRequest createBrowseHostQuery()
          Creates a new specialized QueryRequest instance for browse host queries so that FileManager can understand them.
static QueryRequest createMulticastQuery(QueryRequest qr)
          Creates a new QueryRequest instance for multicast queries.
static QueryRequest createNetworkQuery(byte[] guid, byte ttl, byte hops, byte[] payload, int network)
          Creates a new query from the network.
static QueryRequest createNonFirewalledQuery(java.lang.String query, byte ttl)
          Specialized constructor used to create a query without the firewalled bit set.
static QueryRequest createOutOfBandQuery(java.lang.String query, byte[] ip, int port)
           
static QueryRequest createQuery(byte[] guid, java.lang.String query, java.lang.String xmlQuery)
          Creates a new query with the specified guid, query string, and xml query string.
static QueryRequest createQuery(QueryRequest qr, byte ttl)
          Creates a new query from the existing query with the specified ttl.
static QueryRequest createQuery(java.util.Set urnTypeSet, java.util.Set urnSet)
          Creates a new query for the specified UrnType set and URN set.
static QueryRequest createQuery(java.lang.String query)
          Creates a new query for the specified file name, with no XML.
static QueryRequest createQuery(java.lang.String query, byte ttl)
          Creates a new query for the specified file name, with no XML.
static QueryRequest createQuery(java.lang.String query, java.lang.String xmlQuery)
          Creates a new query for the specified file name, with no XML.
static QueryRequest createQuery(URN sha1)
          Creates a new query for the specified SHA1 value.
static QueryRequest createQuery(URN sha1, java.lang.String filename)
          Creates a new query for the specified SHA1 value with file name thrown in for good measure (or at least until \ works as a query).
static QueryRequest createQueryKeyQuery(QueryRequest qr, QueryKey key)
          Creates a new QueryRequest that is a copy of the input query, except that it includes the specified query key.
static QueryRequest createQueryKeyQuery(java.lang.String query, QueryKey key)
          Creates a new query with the specified query key for use in GUESS-style UDP queries.
static QueryRequest createRequery(java.lang.String query)
          Creates a requery for when we don't know the hash of the file -- we don't know the hash.
static QueryRequest createRequery(URN sha1)
          Creates a new requery for the specified SHA1 value.
static QueryRequest createRequery(URN sha1, byte ttl)
          Creates a new requery for the specified SHA1 value and the specified firewall boolean.
static QueryRequest createRequery(URN sha1, java.lang.String filename)
          Creates a new requery for the specified SHA1 value with file name thrown in for good measure (or at least until \ works as a query).
 boolean desiresOutOfBandReplies()
          Returns true if the query source can accept out-of-band replies.
 boolean desiresXMLResponses()
          Returns true if the query source desires Lime meta-data in responses.
 boolean equals(java.lang.Object o)
           
 int getMinSpeed()
          Note: the minimum speed can be represented as a 2-byte unsigned number, but Java shorts are signed.
 byte[] getPayload()
          Accessor fot the payload of the query hit.
 java.lang.String getQuery()
          Returns the query string of this message.
 QueryKey getQueryKey()
          Returns the QueryKey associated with this Request.
 java.util.Set getQueryUrns()
          Returns the Set of URN instances for this query.
 java.lang.String getReplyAddress()
          Returns the address to send a out-of-band reply to.
 int getReplyPort()
          Returns the port to send a out-of-band reply to.
 java.util.Set getRequestedUrnTypes()
          Returns the Set of URN types requested for this query.
 LimeXMLDocument getRichQuery()
          Returns the rich query LimeXMLDocument.
 int hashCode()
           
 boolean hasQueryUrns()
          Returns whether or not this query contains URNs.
 boolean isFirewalledSource()
          Returns true if the query source is a firewalled servent.
 boolean isLimeRequery()
          Accessor for whether or not this is a requery from a LimeWire.
static byte[] newQueryGUID(boolean isRequery)
          Returns a new GUID appropriate for query requests.
 void recordDrop()
          Records the dropping of this message in statistics.
 Message stripExtendedPayload()
          Returns this, because it's always safe to send big queries.
 java.lang.String toString()
           
protected  void writePayload(java.io.OutputStream out)
           
 
Methods inherited from class com.limegroup.gnutella.messages.Message
compareTo, getCreationTime, getFunc, getGUID, getHops, getLength, getNetwork, getPriority, getTotalLength, getTTL, hop, isMulticast, isTCP, isUDP, isUnknownNetwork, makeGuid, read, read, read, read, read, readNullTerminatedBytes, repOk, setGUID, setHops, setPriority, setTTL, updateLength, write, writeGemExtension, writeGemExtension, writeGemExtensions
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SPECIAL_MINSPEED_MASK

public static final int SPECIAL_MINSPEED_MASK
See Also:
Constant Field Values

SPECIAL_FIREWALL_MASK

public static final int SPECIAL_FIREWALL_MASK
See Also:
Constant Field Values

SPECIAL_XML_MASK

public static final int SPECIAL_XML_MASK
See Also:
Constant Field Values

SPECIAL_OUTOFBAND_MASK

public static final int SPECIAL_OUTOFBAND_MASK
See Also:
Constant Field Values
Constructor Detail

QueryRequest

public QueryRequest(byte[] guid,
                    byte ttl,
                    java.lang.String query,
                    java.lang.String richQuery,
                    java.util.Set requestedUrnTypes,
                    java.util.Set queryUrns,
                    QueryKey queryKey,
                    boolean isFirewalled,
                    int network,
                    boolean canReceiveOutOfBandReplies)
Builds a new query from scratch but you can flag it as a Requery, if needed. If you need to make a query that accepts out-of-band results, be sure to set the guid correctly (see GUID.makeAddressEncodedGUI) and set canReceiveOutOfBandReplies .

Parameters:
requestedUrnTypes - Set of UrnType instances requested for this query, which may be empty or null if no types were requested
queryUrns - Set of URN instances requested for this query, which may be empty or null if no URNs were requested
Throws:
IllegalArgumentException - if the query string, the xml query string, and the urns are all empty
Method Detail

createRequery

public static QueryRequest createRequery(URN sha1)
Creates a new requery for the specified SHA1 value.

Parameters:
sha1 - the URN of the file to search for
Returns:
a new QueryRequest for the specified SHA1 value
Throws:
NullPointerException - if the sha1 argument is null

createQuery

public static QueryRequest createQuery(URN sha1)
Creates a new query for the specified SHA1 value.

Parameters:
sha1 - the URN of the file to search for
Returns:
a new QueryRequest for the specified SHA1 value
Throws:
NullPointerException - if the sha1 argument is null

createRequery

public static QueryRequest createRequery(URN sha1,
                                         java.lang.String filename)
Creates a new requery for the specified SHA1 value with file name thrown in for good measure (or at least until \ works as a query).

Parameters:
sha1 - the URN of the file to search for
Returns:
a new QueryRequest for the specified SHA1 value
Throws:
NullPointerException - if the sha1 argument is null

createQuery

public static QueryRequest createQuery(URN sha1,
                                       java.lang.String filename)
Creates a new query for the specified SHA1 value with file name thrown in for good measure (or at least until \ works as a query).

Parameters:
sha1 - the URN of the file to search for
Returns:
a new QueryRequest for the specified SHA1 value
Throws:
NullPointerException - if the sha1 argument is null

createRequery

public static QueryRequest createRequery(URN sha1,
                                         byte ttl)
Creates a new requery for the specified SHA1 value and the specified firewall boolean.

Parameters:
sha1 - the URN of the file to search for
ttl - the time to live (ttl) of the query
Returns:
a new QueryRequest for the specified SHA1 value
Throws:
NullPointerException - if the sha1 argument is null
IllegalArgumentException - if the ttl value is negative or greater than the maximum allowed value

createQuery

public static QueryRequest createQuery(java.util.Set urnTypeSet,
                                       java.util.Set urnSet)
Creates a new query for the specified UrnType set and URN set.

Parameters:
urnTypeSet - the Set of UrnTypes to request.
urnSet - the Set of URNss to request.
Returns:
a new QueryRequest for the specied UrnTypes and URNs
Throws:
NullPointerException - if either sets are null.

createRequery

public static QueryRequest createRequery(java.lang.String query)
Creates a requery for when we don't know the hash of the file -- we don't know the hash.

Parameters:
query - the query string
Returns:
a new QueryRequest for the specified query
Throws:
NullPointerException - if the query argument is null
IllegalArgumentException - if the query argument is zero-length (empty)

createQuery

public static QueryRequest createQuery(java.lang.String query)
Creates a new query for the specified file name, with no XML.

Parameters:
query - the file name to search for
Returns:
a new QueryRequest for the specified query
Throws:
NullPointerException - if the query argument is null
IllegalArgumentException - if the query argument is zero-length (empty)

createOutOfBandQuery

public static QueryRequest createOutOfBandQuery(java.lang.String query,
                                                byte[] ip,
                                                int port)

createQuery

public static QueryRequest createQuery(java.lang.String query,
                                       java.lang.String xmlQuery)
Creates a new query for the specified file name, with no XML.

Parameters:
query - the file name to search for
Returns:
a new QueryRequest for the specified query
Throws:
NullPointerException - if the query argument is null or if the xmlQuery argument is null
IllegalArgumentException - if the query argument and the xml query are both zero-length (empty)

createQuery

public static QueryRequest createQuery(java.lang.String query,
                                       byte ttl)
Creates a new query for the specified file name, with no XML.

Parameters:
query - the file name to search for
ttl - the time to live (ttl) of the query
Returns:
a new QueryRequest for the specified query and ttl
Throws:
NullPointerException - if the query argument is null
IllegalArgumentException - if the query argument is zero-length (empty)
IllegalArgumentException - if the ttl value is negative or greater than the maximum allowed value

createQuery

public static QueryRequest createQuery(byte[] guid,
                                       java.lang.String query,
                                       java.lang.String xmlQuery)
Creates a new query with the specified guid, query string, and xml query string.

Parameters:
guid - the message GUID for the query
query - the query string
xmlQuery - the xml query string
Returns:
a new QueryRequest for the specified query, xml query, and guid
Throws:
NullPointerException - if the query argument is null, if the xmlQuery argument is null, or if the guid argument is null
IllegalArgumentException - if the guid length is not 16, if both the query strings are empty, or if the XML does not appear to be valid

createQuery

public static QueryRequest createQuery(QueryRequest qr,
                                       byte ttl)
Creates a new query from the existing query with the specified ttl.

Parameters:
qr - the QueryRequest to copy
ttl - the new ttl
Returns:
a new QueryRequest with the specified ttl

createQueryKeyQuery

public static QueryRequest createQueryKeyQuery(java.lang.String query,
                                               QueryKey key)
Creates a new query with the specified query key for use in GUESS-style UDP queries.

Parameters:
query - the query string
key - the query key
Returns:
a new QueryRequest instance with the specified query string and query key
Throws:
NullPointerException - if the query argument is null or if the key argument is null
IllegalArgumentException - if the query argument is zero-length (empty)

createMulticastQuery

public static QueryRequest createMulticastQuery(QueryRequest qr)
Creates a new QueryRequest instance for multicast queries. This is necessary due to the unique properties of multicast queries, such as the firewalled bit not being set regardless of whether or not the node is truly firewalled/NATted to the world outside the subnet.

Parameters:
qr - the QueryRequest instance containing all the data necessary to create a multicast query
Returns:
a new QueryRequest instance with bits set for multicast -- a min speed bit in particular
Throws:
NullPointerException - if the qr argument is null

createQueryKeyQuery

public static QueryRequest createQueryKeyQuery(QueryRequest qr,
                                               QueryKey key)
Creates a new QueryRequest that is a copy of the input query, except that it includes the specified query key.

Parameters:
qr - the QueryRequest to use
key - the QueryKey to add
Returns:
a new QueryRequest from the specified query and key

createBrowseHostQuery

public static QueryRequest createBrowseHostQuery()
Creates a new specialized QueryRequest instance for browse host queries so that FileManager can understand them.

Returns:
a new QueryRequest for browse host queries

createNonFirewalledQuery

public static QueryRequest createNonFirewalledQuery(java.lang.String query,
                                                    byte ttl)
Specialized constructor used to create a query without the firewalled bit set. This should primarily be used for testing.

Parameters:
query - the query string
Returns:
a new QueryRequest with the specified query string and without the firewalled bit set

createNetworkQuery

public static QueryRequest createNetworkQuery(byte[] guid,
                                              byte ttl,
                                              byte hops,
                                              byte[] payload,
                                              int network)
                                       throws BadPacketException
Creates a new query from the network.

Parameters:
guid - the GUID of the query
ttl - the time to live of the query
hops - the hops of the query
payload - the query payload
Returns:
a new QueryRequest instance from the specified data
Throws:
BadPacketException

newQueryGUID

public static byte[] newQueryGUID(boolean isRequery)
Returns a new GUID appropriate for query requests. If isRequery, the GUID query is marked.


writePayload

protected void writePayload(java.io.OutputStream out)
                     throws java.io.IOException
Specified by:
writePayload in class Message
Throws:
java.io.IOException

getPayload

public byte[] getPayload()
Accessor fot the payload of the query hit.

Returns:
the query hit payload

getQuery

public java.lang.String getQuery()
Returns the query string of this message.

The caller should not call the getBytes() method on the returned value, as this seems to cause problems on the Japanese Macintosh. If you need the raw bytes of the query string, call getQueryByteAt(int).


getRichQuery

public LimeXMLDocument getRichQuery()
Returns the rich query LimeXMLDocument.

Returns:
the rich query LimeXMLDocument

getRequestedUrnTypes

public java.util.Set getRequestedUrnTypes()
Returns the Set of URN types requested for this query.

Returns:
the Set of UrnType instances requested for this query, which may be empty (not null) if no types were requested

getQueryUrns

public java.util.Set getQueryUrns()
Returns the Set of URN instances for this query.

Returns:
the Set of URN instances for this query, which may be empty (not null) if no URNs were requested

hasQueryUrns

public boolean hasQueryUrns()
Returns whether or not this query contains URNs.

Returns:
true if this query contains URNs, false otherwise

getMinSpeed

public int getMinSpeed()
Note: the minimum speed can be represented as a 2-byte unsigned number, but Java shorts are signed. Hence we must use an int. The value returned is always smaller than 2^16.


isFirewalledSource

public boolean isFirewalledSource()
Returns true if the query source is a firewalled servent.


desiresXMLResponses

public boolean desiresXMLResponses()
Returns true if the query source desires Lime meta-data in responses.


desiresOutOfBandReplies

public boolean desiresOutOfBandReplies()
Returns true if the query source can accept out-of-band replies. Use getReplyAddress() and getReplyPort() if this is true to know where to it. Always send XML if you are sending an out-of-band reply.


getReplyAddress

public java.lang.String getReplyAddress()
Returns the address to send a out-of-band reply to. Only useful when desiresOutOfBandReplies() == true.


getReplyPort

public int getReplyPort()
Returns the port to send a out-of-band reply to. Only useful when desiresOutOfBandReplies() == true.


isLimeRequery

public boolean isLimeRequery()
Accessor for whether or not this is a requery from a LimeWire.

Returns:
true if it is an automated requery from a LimeWire, otherwise false

getQueryKey

public QueryKey getQueryKey()
Returns the QueryKey associated with this Request. May very well be null. Usually only UDP QueryRequests will have non-null QueryKeys.


recordDrop

public void recordDrop()
Description copied from class: Message
Records the dropping of this message in statistics.

Specified by:
recordDrop in class Message

stripExtendedPayload

public Message stripExtendedPayload()
Returns this, because it's always safe to send big queries.

Specified by:
stripExtendedPayload in class Message
Returns:
an instance of this without any dangerous extended payload

hashCode

public int hashCode()

equals

public boolean equals(java.lang.Object o)

toString

public java.lang.String toString()
Overrides:
toString in class Message