eap.freeciv
Class Field

java.lang.Object
  extended byeap.freeciv.Field
Direct Known Subclasses:
ArrayField, BinaryField, BitField, SimpleField

public abstract class Field
extends Object

Represents a generic field in a packet structure. All of the methods in this class are abstract, since subclasses can implement very different functionality.


Constructor Summary
Field()
           
 
Method Summary
abstract  void addIndex(int index)
          Alter the way this field references its data, so as to append an index.
abstract  int getSize(Packet packet)
          Returns the size of this field in bytes, given the values stored in a paket.
abstract  boolean isSet(Packet packet)
          Returns true if the value(s) for this field are set in the given packet
abstract  void read(Packet packet, PacketSource source)
          Read the field from the given source and write its contents to the given packet.
abstract  void removeIndex()
          Reverse the effects of the last call to addIndex(int)
abstract  void write(Packet packet, OutputStream out)
          Write this field to the given stream, taking values from the given packet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Field

public Field()
Method Detail

read

public abstract void read(Packet packet,
                          PacketSource source)
                   throws IOException
Read the field from the given source and write its contents to the given packet. Remember that a packet is just a storage repository and a structure (composed of fields) describes how the packet is serialized.

Throws:
IOException

write

public abstract void write(Packet packet,
                           OutputStream out)
                    throws IOException
Write this field to the given stream, taking values from the given packet.

Throws:
IOException

getSize

public abstract int getSize(Packet packet)
Returns the size of this field in bytes, given the values stored in a paket. Many fields have a fixed size, but some do not and need to reference the packet data.


addIndex

public abstract void addIndex(int index)
Alter the way this field references its data, so as to append an index. Exactly how this is done depends on the subclass. The index can later be removed with removeIndex(). Multiple calls to this method are cumulative - i.e. a field can have multiple indices.

This is used by arrays. The typical procedure is to iterate over array elements, set the index in each component field, perform some operation, and then remove the index. The nice thing about this way of doing things is that an array can contain any type of field, including other arrays. The drawback is that you have to be very careful that the indices always get removed after use. Otherwise the structure could get into an invalid state. A related problem is that it violates the rule that packet structures are reusable, since two separate threads could be trying to add indices to the same field at the same time. So far this hasn't been a problem, since the indices stay on the field for a very short time. Also, in practice one thread handles client to server trafic and the other handles server to client trafic, and these generally use different packet types. Initially I set the index in the packet, but I ripped that out because it set the array for all fields. But to be thread safe I would have to go back to something like that, but specific to one keyword.

See Also:
ArrayField

removeIndex

public abstract void removeIndex()
Reverse the effects of the last call to addIndex(int)


isSet

public abstract boolean isSet(Packet packet)
Returns true if the value(s) for this field are set in the given packet