eap.freeciv
Class PacketBroker

java.lang.Object
  extended byeap.freeciv.PacketBroker

public class PacketBroker
extends Object

Generates PacketStructure objects, by reading XML configuration files.

Right now I'm too lazy to describe the XML format tags in detail. Hopefully they are easy to figure out by looking at some examples in eap/freeciv/config. I created the XML files by writing a perl script to parse the freeciv packets.c and packets.h files and output a best-guess at the XML. That handled maybe 90% of the tedium. I then cleaned things up by hand - mosly for arrays and optional fields. So far I have only done this for freeciv 1.13.0, since that is the version I have installed on my machine.

There is one configuration file listing the ID and name for each packet. Freeciv uses the same format for different types of packets, so this list also gives the format name. This file must be called "list.xml"

The format for each packet is described in a file with the packet format name, with ".xml" appended. Most fields are simple integers or strings. There are special cases like arrays, where a set of fields are read multiple times, or bit fields where a single byte encodes up to 8 boolean values. If there is enough interest, I will need to document the XML carefully - and write a DTD for it.

The idea behind this class is to separate the internal representation of the packet structure from the config files. That way the internal representation can be omtimized for reading large numbers of the same kind of packet. Also, this makes it relatively easy to support other kinds of configuration files. I believe this is the only class which requires java 1.4 because of the XML processing stuff. That could be one reason to replace it with something else. Or it could be a good reason to upgrade to the latest runtime environment.


Constructor Summary
PacketBroker()
          Create a new packet broker which will look for the configuration files in a default location.
PacketBroker(String config)
          Create a new packet broker which will read the configuration from the given directory.
 
Method Summary
 String getName(int id)
          Returns the packet name (not the format name) for a given ID.
 PacketStructure getStructure(int id)
          Returns the structure for a given Packet ID.
protected  PacketStructure getStructure(String structure_name)
          Return the structure corresponding to a given structure name.
 BinaryField parseBinaryField(Element element)
          Return a Field object for an XML element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PacketBroker

public PacketBroker()
             throws ParserConfigurationException,
                    SAXException,
                    IOException
Create a new packet broker which will look for the configuration files in a default location. Currently the default is "eap/freeciv/config/1.13".


PacketBroker

public PacketBroker(String config)
             throws ParserConfigurationException,
                    SAXException,
                    IOException
Create a new packet broker which will read the configuration from the given directory. This class uses its ClassLoader to find the config files, so the directory name should conform to the rules of ClassLoader.getResource(String), i.e. a "/" separated path relative to the CLASSPATH. Typically the configuration directory will be under eap/freeciv/config, but it could be anywhere. Note that the configuration files can be in a jar and/or server over a network with an applet's bytecode.

Method Detail

getStructure

protected PacketStructure getStructure(String structure_name)
                                throws SAXException,
                                       IOException
Return the structure corresponding to a given structure name. Note that this is different from the packet name, since freeciv uses the same format for different packet types. This method is mostly for internal use.

Throws:
SAXException
IOException

getStructure

public PacketStructure getStructure(int id)
                             throws IOException
Returns the structure for a given Packet ID. The ID is the number encoded in the third byte of the packet header. Note this method can return the same PacketStructure each time it is called with the same ID. In fact that's the whole idea of separating the structure from the storage, so that we can read the configuration once and cache the structures.

Throws:
IOException

getName

public String getName(int id)
               throws IOException
Returns the packet name (not the format name) for a given ID.

Throws:
IOException

parseBinaryField

public BinaryField parseBinaryField(Element element)
                             throws IOException
Return a Field object for an XML element.

Throws:
IOException