eap.freeciv
Class SimpleField

java.lang.Object
  extended byeap.freeciv.Field
      extended byeap.freeciv.SimpleField
Direct Known Subclasses:
BitStringField, BooleanField, CityMapField, SignedIntField, StringField, TechListField, UnsignedIntField, WorkListField

public abstract class SimpleField
extends Field

Represents a field with a name and a single value. Note that "single value" means that its value is represented by a single object in a packet, so it includes things like a WorkList, where several values are encoded in a single object. This is an abstract class which handles a number of general properties of fields, but does not understand the actual data format.

A field may be optional, meaning it should be written only if it is defined in the packet, and it should be read only if there are bytes remaining in the packet.

A field may be present only if a given condition is met. The definition of this condition is a bit nebulous - so the best way to understand it would be to read the source code for testCondition(Packet). I think there is only one field in all of freeciv which uses this.

A field may have a scale factor. Numerical valued fields should multiply the raw value by this scale factor.


Constructor Summary
protected SimpleField()
          Create a new simple field.
 
Method Summary
 void addIndex(int index)
          Adds the given index in brackets to the end of the name of this field.
 String getname()
          Returns the name of this field.
 int getSize(Packet packet)
          Returns the size of this field.
abstract  int getValueSize(Packet packet)
          Returns the size of the data in this field.
 boolean isOptional()
          Indicates whether this field is optional.
 boolean isSet(Packet packet)
          Returns true if the packet has a value with the same name as this field.
 void read(Packet packet, PacketSource source)
          Read the value from the packet if it is present.
protected abstract  void readValue(Packet packet, PacketSource source)
          Read the data in this field from the packet.
 void removeIndex()
          Reverse the effects of the last call to addIndex(int)
 void setCondition(String condition)
          Set a string describing a condition for whether this field should appear in the packet.
 void setName(String name)
          Set the name of this field.
 void setOptional(boolean optional)
          Set whether this field is optional
 void setScale(double scale)
          Set the scale factor for this packet.
protected  boolean testCondition(Packet packet)
          Evaluate a test condition to see if a packets contains this field.
 void write(Packet packet, OutputStream out)
          Write this field if it is present in the packet.
protected abstract  void writeValue(Object value, OutputStream out)
          Write the data in this field.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SimpleField

protected SimpleField()
Create a new simple field. Initializes the scale to 1.0, the condition to none, and set the field as required.

Method Detail

setName

public void setName(String name)
Set the name of this field. This names is used as the keyword for accessing the data in a packet.


getname

public String getname()
Returns the name of this field.


addIndex

public void addIndex(int index)
Adds the given index in brackets to the end of the name of this field. This is used by arrays.

Specified by:
addIndex in class Field
See Also:
Field.addIndex(int)

removeIndex

public void removeIndex()
Description copied from class: Field
Reverse the effects of the last call to Field.addIndex(int)

Specified by:
removeIndex in class Field

isSet

public boolean isSet(Packet packet)
Returns true if the packet has a value with the same name as this field.

Specified by:
isSet in class Field

setOptional

public void setOptional(boolean optional)
Set whether this field is optional


isOptional

public boolean isOptional()
Indicates whether this field is optional.


setCondition

public void setCondition(String condition)
Set a string describing a condition for whether this field should appear in the packet.

See Also:
testCondition(Packet)

setScale

public void setScale(double scale)
Set the scale factor for this packet. Numerical-valued subclasses should multiply raw values by this scale factor.


readValue

protected abstract void readValue(Packet packet,
                                  PacketSource source)
                           throws IOException
Read the data in this field from the packet. The read(eap.freeciv.Packet, eap.freeciv.PacketSource) method determines whether this field should appear in the packet and then calls this method to read the actual data.

Throws:
IOException

writeValue

protected abstract void writeValue(Object value,
                                   OutputStream out)
                            throws IOException
Write the data in this field. The write(eap.freeciv.Packet, java.io.OutputStream) method determines whether this field should appear in the packet and then calls this method to write the actual data.

Throws:
IOException

getValueSize

public abstract int getValueSize(Packet packet)
Returns the size of the data in this field. The getSize(Packet) method determines whether the packet contains this field and then calls this method to return its size.


read

public final void read(Packet packet,
                       PacketSource source)
                throws IOException
Read the value from the packet if it is present. Subclasses should override readValue(Packet, PacketSource) to specify how the data are encoded.

Specified by:
read in class Field
Throws:
IOException

write

public final void write(Packet packet,
                        OutputStream out)
                 throws IOException
Write this field if it is present in the packet. Subclasses should override writeValue(Object, OutputStream) to specify how the data are encoded.

Specified by:
write in class Field
Throws:
IOException

testCondition

protected boolean testCondition(Packet packet)
                         throws IOException
Evaluate a test condition to see if a packets contains this field. This is rarely used.

Throws:
IOException

getSize

public final int getSize(Packet packet)
Returns the size of this field. If the field is not included in the packet, then this method returns zero. Otherwise it calls getValueSize(Packet) to determine the size.

Specified by:
getSize in class Field