com.limegroup.gnutella
Class Response

java.lang.Object
  extended bycom.limegroup.gnutella.Response

public class Response
extends java.lang.Object

A single result from a query reply message. (In hindsight, "Result" would have been a better name.) Besides basic file information, responses can include metadata, which is actually stored query reply's QHD. Metadata comes in two formats: raw strings or parsed LimeXMLDocument.

Response was originally intended to be immutable, but it currently includes mutator methods for metadata; these will be removed in the future.


Constructor Summary
Response(FileDesc fd)
          Constructs a new Response instance from the data in the specified FileDesc.
Response(long index, long size, java.lang.String name)
          Creates a fresh new response.
Response(long index, long size, java.lang.String name, LimeXMLDocument doc)
          Creates a new response with parsed metadata.
Response(long index, long size, java.lang.String name, java.lang.String metadata)
          Creates a new response with raw unparsed metadata.
 
Method Summary
static Response createFromStream(java.io.InputStream is)
          Factory method for instantiating individual responses from an InputStream instance.
 boolean equals(java.lang.Object o)
          Overrides equals to check that these two responses are equal.
 LimeXMLDocument getDocument()
          Returns this' metadata as a parsed XML document
 long getIndex()
          Returns the index for the file stored in this Response instance.
 int getLength()
           
 java.util.Set getLocations()
          Returns an immutabe Set of Endpoint that contain the same file described in this Response.
 byte[] getMetaBytes()
          Returns a copy of the array of bytes for the meta-data for this Response instance.
 int getMetaBytesSize()
          Accessor fot the length of the array of bytes that stores the meta- data.
 java.lang.String getMetadata()
          Returns the string of meta-data for this Response instance.
 java.lang.String getName()
          Returns the name of the file for this response.
 byte[] getNameBytes()
          Returns a copy of the array of bytes for the file name for this Response instance.
 int getNameBytesSize()
          Returns the size of the name in bytes (not the whole response) In the constructor we create the nameBytes array once which is the representation of the name in bytes.
 long getSize()
          Returns the size of the file for this Response instance (in bytes).
 java.util.Set getUrns()
          Returns an immutable Set of URN instances for this Response.
 int hashCode()
           
 void setDocument(LimeXMLDocument doc)
          Sets this' metadata.
 RemoteFileDesc toRemoteFileDesc(HostData data)
          Returns this Response as a RemoteFileDesc.
 java.lang.String toString()
          Overrides Object.toString to print out a more informative message.
 int writeToArray(byte[] array, int i)
          Write the response data to the given byte array, as if inside a QueryReply.
 void writeToStream(java.io.OutputStream os)
          Like writeToArray(), but writes to an OutputStream.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Response

public Response(long index,
                long size,
                java.lang.String name)
Creates a fresh new response.


Response

public Response(long index,
                long size,
                java.lang.String name,
                LimeXMLDocument doc)
Creates a new response with parsed metadata. Typically this is used to respond to query requests.

Parameters:
doc - the metadata to include

Response

public Response(long index,
                long size,
                java.lang.String name,
                java.lang.String metadata)
Creates a new response with raw unparsed metadata. Typically this is used when reading replies from the network.

Parameters:
metadata - a string of metadata, typically XML

Response

public Response(FileDesc fd)
Constructs a new Response instance from the data in the specified FileDesc.

Parameters:
fd - the FileDesc containing the data to construct this Response -- must not be null
Method Detail

createFromStream

public static Response createFromStream(java.io.InputStream is)
                                 throws java.io.IOException
Factory method for instantiating individual responses from an InputStream instance.

Parameters:
is - the InputStream to read from
Throws:
IOException - if there are any problems reading from or writing to the stream
java.io.IOException

writeToArray

public int writeToArray(byte[] array,
                        int i)
Write the response data to the given byte array, as if inside a QueryReply.


writeToStream

public void writeToStream(java.io.OutputStream os)
                   throws java.io.IOException
Like writeToArray(), but writes to an OutputStream.

Throws:
java.io.IOException

setDocument

public void setDocument(LimeXMLDocument doc)
Sets this' metadata. Added to faciliatate setting audio metadata for responses generated from ordinary searches. Typically this should only be called if no metadata was passed to this' constructor.


getLength

public int getLength()

getIndex

public long getIndex()
Returns the index for the file stored in this Response instance.

Returns:
the index for the file stored in this Response instance

getSize

public long getSize()
Returns the size of the file for this Response instance (in bytes).

Returns:
the size of the file for this Response instance (in bytes)

getNameBytesSize

public int getNameBytesSize()
Returns the size of the name in bytes (not the whole response) In the constructor we create the nameBytes array once which is the representation of the name in bytes.

storing the nameBytes is an optimization beacuse we do not want to call getBytes() on the name string every time we need the byte representation or the number of bytes in the name.


getMetaBytesSize

public int getMetaBytesSize()
Accessor fot the length of the array of bytes that stores the meta- data.

Returns:
the length of the array of bytes that stores the meta-data

getNameBytes

public byte[] getNameBytes()
Returns a copy of the array of bytes for the file name for this Response instance.

Returns:
a copy of the array of bytes for the file name for this Response instance

getMetaBytes

public byte[] getMetaBytes()
Returns a copy of the array of bytes for the meta-data for this Response instance.

Returns:
a copy of the array of bytes for the meta-data

getName

public java.lang.String getName()
Returns the name of the file for this response. This is guaranteed to be non-null, but it could be the empty string.

Returns:
the name of the file for this response

getMetadata

public java.lang.String getMetadata()
Returns the string of meta-data for this Response instance.

Returns:
the string of meta-data for this Response instance, which is guaranteed to be non-null, but which can be the empty string

getDocument

public LimeXMLDocument getDocument()
Returns this' metadata as a parsed XML document

Returns:
the metadata, or null if none exists or the metadata couldn't be parsed

getUrns

public java.util.Set getUrns()
Returns an immutable Set of URN instances for this Response.

Returns:
an immutable Set of URN instances for this Response, guaranteed to be non-null, although the set could be empty

getLocations

public java.util.Set getLocations()
Returns an immutabe Set of Endpoint that contain the same file described in this Response.

Returns:
an immutabe Set of Endpoint that contain the same file described in this Response, guaranteed to be non-null, although the set could be empty

toRemoteFileDesc

public RemoteFileDesc toRemoteFileDesc(HostData data)
Returns this Response as a RemoteFileDesc.


equals

public boolean equals(java.lang.Object o)
Overrides equals to check that these two responses are equal. Raw extension bytes are not checked, because they may be extensions that do not change equality, such as otherLocations.


hashCode

public int hashCode()

toString

public java.lang.String toString()
Overrides Object.toString to print out a more informative message.