eap.freeciv
Class Packet

java.lang.Object
  extended byeap.freeciv.Packet

public class Packet
extends Object

Acts as a repository for packet data.

There are two ways to decode packet data. You can either handle the packet strucure at compile time (i.e. write a different object for each packet type), or you can do it at runtime, with a general way of holding data and describing its structure. You can read this structure from a configuration file when you need it.

The compile-time method runs faster and requires less memory, but the executable size is larger. With the Runtime method, you can do things like loop over all the fields in a packet and print their names and values. Furthermore, the compile-time method can be tedious to code, and prone to error. However you can overcome this by writing a code generator, which reads configuration files and outputs source code for each packet.

The Freeciv C code uses the compile-time method (without a code generator). I chose to use the runtime method, since modern computers have plenty of speed and memory. Also, with Java if you wanted it to run fast you would have written it in C++, so you might as well optimize your code for elegance and maintainability. Plus, in Java it's good to keep your executables small, in case you want to use it as an applet. Lots of people still get their internet over the phone.

So this class is just a repository for the data in a packet as a set of key - value pairs. It knows nothing about how the values are arranged or encoded in the data stream. That is all handled by the PacketStructure class. Note this means there are no restrictions on the data you can store in a packet. However when you write the packet you will have trouble if the required fields are undefined or have improper values. The structure will ignore any data fields it doesn't know about.


Constructor Summary
Packet(String name, int id, PacketStructure structure)
          Create a new packet with a given name, ID number and internal structure.
 
Method Summary
 void deleteValue(String name)
          Removes the named value from the packet.
 void dump()
          Prints a description of the packet to System.out.
 void dump(PrintStream out)
          Prints a description of the packet to the given PrintWriter.
 int getID()
          Returns the integer ID code for this packet.
 String getName()
          Returns the name of the packet.
 Object getValue(String name)
          Returns the value of the named field in the packet.
 boolean hasValue(String name)
          Returns true if the named value has been set in this packet.
 int intValue(String name)
          Return the value of a field as an integer.
 void readBody(PacketSource source)
          Sets the fields in this packet by reading them from the given PacketSource.
 void setValue(String name, Object value)
          Set the value of a named field in the packet.
 String toString()
          returns a string representing the name and ID number of this packet.
 void write(OutputStream out)
          Write the header and contents of this packet to an output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Packet

public Packet(String name,
              int id,
              PacketStructure structure)
Create a new packet with a given name, ID number and internal structure.

Method Detail

getName

public String getName()
Returns the name of the packet. Each packet type has a name associated with it. The name is set in the constructor, but in practice, the names are taken from the packet_type enum in common/packets.h with the "PACKET_" prefix removed. Note that size the packet ID numbers are subject to change from one version of freeciv to the next, so it is better to identity packets types by their name than by their integer code.


setValue

public void setValue(String name,
                     Object value)
Set the value of a named field in the packet. The values are usually encoded as Number or String objects, though some fields have special types.


getValue

public Object getValue(String name)
Returns the value of the named field in the packet.


intValue

public int intValue(String name)
Return the value of a field as an integer. This is a convenience method which casts the field as a Number and then calls intValue().

Throws:
ClassCastException - if the field is not a number
NullPointerException - if the value is undefined.

hasValue

public boolean hasValue(String name)
Returns true if the named value has been set in this packet. Note that it will still return true if the value has been set to null.


deleteValue

public void deleteValue(String name)
Removes the named value from the packet.


getID

public int getID()
Returns the integer ID code for this packet. For a given version of freeciv there is a one-to-one correspondence between the ID and the packet name. However, the IDs are more likely to change from one verison to the next than the names.


readBody

public void readBody(PacketSource source)
              throws IOException
Sets the fields in this packet by reading them from the given PacketSource. This method just calls the read method of this packet's structure. It clears any values stored in the packet before reading the new ones. Also, this method assumes that the packet header has already been read. The typical proceedure is to read the header, use that information to create the packet, and then read its body. All this is usually handled by a PacketSource.

Throws:
IOException

write

public void write(OutputStream out)
           throws IOException
Write the header and contents of this packet to an output stream.

Throws:
IOException

dump

public void dump()
Prints a description of the packet to System.out.


dump

public void dump(PrintStream out)
Prints a description of the packet to the given PrintWriter. Typically this is System.out or System.err. It first gives the name and ID of the packet and then an alphabetic list of all the fields in the packet and their values. This method is useful for debugging.


toString

public String toString()
returns a string representing the name and ID number of this packet.