Package net.sf.freecol.common.io

Class FreeColXMLReader

java.lang.Object

javax.xml.stream.util.StreamReaderDelegate

net.sf.freecol.common.io.FreeColXMLReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, javax.xml.stream.XMLStreamConstants, javax.xml.stream.XMLStreamReader

public class FreeColXMLReader
extends javax.xml.stream.util.StreamReaderDelegate
implements java.io.Closeable

A wrapper for XMLStreamReader and potentially an underlying stream. Adds on many useful utilities for reading XML and FreeCol values.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FreeColXMLReader.ReadScope

Field Summary

Fields

Modifier and Type	Field	Description
private java.io.InputStream	inputStream	The stream to read from.
private static java.util.logging.Logger	logger
private FreeColXMLReader.ReadScope	readScope	The read scope to apply.
private static java.util.Map<java.lang.Integer,java.lang.String>	tagStrings	Map for the XMLStreamConstants.
private boolean	tracing	Trace all reads?
private java.util.Map<java.lang.String,FreeColObject>	uninterned	A cache of uninterned objects.

Fields inherited from interface javax.xml.stream.XMLStreamConstants

ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT

Constructor Summary

Constructors

Constructor	Description
FreeColXMLReader(java.io.BufferedInputStream bis)	Creates a new FreeColXMLReader.
FreeColXMLReader(java.io.File file)	Creates a new FreeColXMLReader.
FreeColXMLReader(java.io.InputStream inputStream)	Creates a new FreeColXMLReader.
FreeColXMLReader(java.io.Reader reader)	Creates a new FreeColXMLReader.

Method Summary

Modifier and Type	Method	Description
boolean	atTag(java.lang.String tag)	Is the stream at the given tag?
void	close()	Closes both the XMLStreamReader and the underlying stream if any.
void	closeTag(java.lang.String tag)	Close the current tag, checking that it did indeed close correctly.
void	closeTag(java.lang.String tag, java.lang.String... others)	Close the current tag, but accept some alternative elements first.
<T extends FreeColObject> T	copy(Game game, java.lang.Class<T> returnClass)	Copy a FreeColObject by serializing it and reading back the result with a non-interning stream.
java.lang.String	currentTag()	Extract the current tag and its attributes from an input stream.
void	expectTag(java.lang.String tag)	Expect a particular tag.
<T extends AIObject> T	findAIObject(AIMain aiMain, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue, boolean required)	Find a FreeCol AI object from an attribute in a stream.
<T extends FreeColGameObject> T	findFreeColGameObject(Game game, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue, boolean required)	Find a FreeColGameObject of a given class from a stream attribute.
java.util.Map<java.lang.String,java.lang.String>	getAllAttributes()	Get a map of all attributes present.
java.util.Map<java.lang.String,java.lang.String>	getArrayAttributeMap()	Get a map of the array attributes.
boolean	getAttribute(java.lang.String attributeName, boolean defaultValue)	Gets a boolean from an attribute in a stream.
float	getAttribute(java.lang.String attributeName, float defaultValue)	Gets a float from an attribute in a stream.
int	getAttribute(java.lang.String attributeName, int defaultValue)	Gets an int from an attribute in a stream.
long	getAttribute(java.lang.String attributeName, long defaultValue)	Gets a long from an attribute in a stream.
<T extends java.lang.Enum<T>> T	getAttribute(java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue)	Gets an enum from an attribute in a stream.
java.lang.String	getAttribute(java.lang.String attributeName, java.lang.String defaultValue)	Gets a string from an attribute in a stream.
<T extends FreeColObject> T	getAttribute(Game game, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue)	Gets a FreeCol object from an attribute in a stream.
<T extends AIObject> T	getAttribute(AIMain aiMain, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue)	Get a FreeCol AI object from an attribute in a stream.
java.util.Map<java.lang.String,java.lang.String>	getAttributeMap(java.lang.String... attributes)	Get a map of attributes.
Location	getLocationAttribute(Game game, java.lang.String attributeName, boolean make)	Find a new location from a stream attribute.
FreeColXMLReader.ReadScope	getReadScope()	Get the read scope.
<T extends FreeColSpecObjectType> T	getType(Specification spec, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue)	Get a FreeColSpecObjectType by identifier from a stream from a specification.
boolean	hasAttribute(java.lang.String attributeName)	Is there an attribute present in the stream?
private <T extends FreeColObject> T	internedRead(Game game, java.lang.Class<T> returnClass)	Do a normal interning read of a FreeColObject.
private FreeColObject	lookup(Game game, java.lang.String id)	Look up an identifier in an enclosing game.
<T extends FreeColObject> T	lookup(Game game, java.lang.String id, java.lang.Class<T> returnClass)	Look up an identifier in an enclosing game.
<T extends AIObject> T	makeAIObject(AIMain aiMain, java.lang.String attributeName, java.lang.Class<T> returnClass, T defaultValue, boolean required)	Either get an existing AIObject from a stream attribute or create it if it does not exist.
<T extends FreeColObject> T	makeFreeColObject(Game game, java.lang.String attributeName, java.lang.Class<T> returnClass, boolean required)	Either get an existing FreeColObject from a stream attribute or create it if it does not exist.
boolean	moreTags()	Check if there are more tags in the current element.
private static javax.xml.stream.XMLInputFactory	newXMLInputFactory()	Create a new XMLInputFactory.
int	nextTag()
int	readAttributeValues(java.util.Map<java.lang.String,java.lang.String> map, java.lang.String attr)	Fill in the identifier values supplied in a map.
<T extends FreeColObject> T	readFreeColObject(Game game)	Read a FreeColObject from a stream.
<T extends FreeColObject> T	readFreeColObject(Game game, java.lang.Class<T> returnClass)	Reads a FreeColObject from a stream.
java.lang.String	readId()	Reads the identifier attribute.
<T extends FreeColSpecObjectType> java.util.List<T>	readList(Specification spec, java.lang.String tag, java.lang.Class<T> type)	Reads an XML-representation of a list of FreeColSpecObjectTypes.
FreeColXMLReader.ReadScope	replaceScope(FreeColXMLReader.ReadScope newReadScope)	Replace a the scope.
FreeColXMLReader	setReadScope(FreeColXMLReader.ReadScope readScope)	Set the read scope.
FreeColXMLReader	setTracing(boolean tracing)	Set the tracing state.
boolean	shouldClearContainers()	Should the game object type being read clear its containers before reading the child elements? Usually true, but not if the type is extending another one.
boolean	shouldIntern()	Should reads from this stream intern their objects into the enclosing game?
void	swallowTag(java.lang.String tag)	Swallow a tag, ignoring anything read until the tag closes.
void	unexpectedTag(java.lang.String context)	Standardized way to throw a parsing exception with a bit of context.
private <T extends FreeColObject> T	uninternedRead(Game game, java.lang.Class<T> returnClass)	Do a special non-interning read of a FreeColObject.

Methods inherited from class javax.xml.stream.util.StreamReaderDelegate

getAttributeCount, getAttributeLocalName, getAttributeName, getAttributeNamespace, getAttributePrefix, getAttributeType, getAttributeValue, getAttributeValue, getCharacterEncodingScheme, getElementText, getEncoding, getEventType, getLocalName, getLocation, getName, getNamespaceContext, getNamespaceCount, getNamespacePrefix, getNamespaceURI, getNamespaceURI, getNamespaceURI, getParent, getPIData, getPITarget, getPrefix, getProperty, getText, getTextCharacters, getTextCharacters, getTextLength, getTextStart, getVersion, hasName, hasNext, hasText, isAttributeSpecified, isCharacters, isEndElement, isStandalone, isStartElement, isWhiteSpace, next, require, setParent, standaloneSet

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

private static final java.util.logging.Logger logger

tagStrings

private static final java.util.Map<java.lang.Integer,java.lang.String> tagStrings

Map for the XMLStreamConstants.

tracing

private boolean tracing

Trace all reads?

inputStream

private java.io.InputStream inputStream

The stream to read from.

readScope

private FreeColXMLReader.ReadScope readScope

The read scope to apply.

uninterned

private java.util.Map<java.lang.String,FreeColObject> uninterned

A cache of uninterned objects. Uninterned reads add to this list so that they can refer to sub-objects correctly. However there is no obvious place to clear this cache, so we do that in replaceScope as you can not expect to reference the same object across scopes.

Constructor Detail

FreeColXMLReader

public FreeColXMLReader(java.io.BufferedInputStream bis)
                 throws javax.xml.stream.XMLStreamException

Creates a new FreeColXMLReader.

Parameters:

bis - The BufferedInputStream to create an FreeColXMLReader for.

Throws:

javax.xml.stream.XMLStreamException - can be thrown while creating the reader.

FreeColXMLReader

public FreeColXMLReader(java.io.InputStream inputStream)
                 throws javax.xml.stream.XMLStreamException

Creates a new FreeColXMLReader.

Parameters:

inputStream - The InputStream to create an FreeColXMLReader for.

Throws:

javax.xml.stream.XMLStreamException - can be thrown while creating the reader.

FreeColXMLReader

public FreeColXMLReader(java.io.File file)
                 throws java.io.IOException,
                        javax.xml.stream.XMLStreamException

Creates a new FreeColXMLReader.

Parameters:

file - The File to create an FreeColXMLReader for.

Throws:

java.io.IOException - if the file is missing.

javax.xml.stream.XMLStreamException - can be thrown while creating the reader.

FreeColXMLReader

public FreeColXMLReader(java.io.Reader reader)
                 throws javax.xml.stream.XMLStreamException

Creates a new FreeColXMLReader.

Parameters:

reader - A Reader to create an FreeColXMLReader for.

Throws:

javax.xml.stream.XMLStreamException - if thrown while creating the reader.

Method Detail

newXMLInputFactory

private static javax.xml.stream.XMLInputFactory newXMLInputFactory()

Create a new XMLInputFactory. Respond to CVE 2018-1000825.

Returns:

A new XMLInputFactory.

setTracing

public FreeColXMLReader setTracing(boolean tracing)

Set the tracing state.

Parameters:

tracing - The new tracing state.

Returns:

This reader.

shouldIntern

public boolean shouldIntern()

Should reads from this stream intern their objects into the enclosing game?

Returns:

True if this is an interning stream.

getReadScope

public FreeColXMLReader.ReadScope getReadScope()

Get the read scope.

Returns:

The ReadScope.

setReadScope

public FreeColXMLReader setReadScope(FreeColXMLReader.ReadScope readScope)

Set the read scope.

Parameters:

readScope - The new ReadScope.

Returns:

This reader.

replaceScope

public FreeColXMLReader.ReadScope replaceScope(FreeColXMLReader.ReadScope newReadScope)

Replace a the scope.

Parameters:

newReadScope - The ReadScope to push.

Returns:

The previous ReadScope.

lookup

private FreeColObject lookup(Game game,
                             java.lang.String id)

Look up an identifier in an enclosing game. If not interning prefer an non-interned result.

Parameters:

game - The Game to consult.

id - The object identifier.

Returns:

The FreeColObject found, or null if none.

lookup

public <T extends FreeColObject> T lookup(Game game,
                                          java.lang.String id,
                                          java.lang.Class<T> returnClass)
                                   throws javax.xml.stream.XMLStreamException

Look up an identifier in an enclosing game. This is public to allow the special fixup in Game.readChildren.

Type Parameters:

T - The expected object class type.

Parameters:

game - The Game to consult.

id - The object identifier.

returnClass - The class of the return value.

Returns:

The FreeColObject found, or null if none.

Throws:

javax.xml.stream.XMLStreamException - if the return class does not match.

close

public void close()

Closes both the XMLStreamReader and the underlying stream if any. Implements interface Closeable.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface javax.xml.stream.XMLStreamReader

Overrides:

close in class javax.xml.stream.util.StreamReaderDelegate

readId

public java.lang.String readId()

Reads the identifier attribute. When all the compatibility code is obsolete, remove this routine and replace its uses with just: getAttribute(in, ID_ATTRIBUTE_TAG, (String)null) or equivalent.

Returns:

The identifier found, or null if none present.

nextTag

public int nextTag()
            throws javax.xml.stream.XMLStreamException

Specified by:

nextTag in interface javax.xml.stream.XMLStreamReader

Overrides:

nextTag in class javax.xml.stream.util.StreamReaderDelegate

Throws:

javax.xml.stream.XMLStreamException

atTag

public boolean atTag(java.lang.String tag)

Is the stream at the given tag?

Parameters:

tag - The tag to test.

Returns:

True if at the given tag.

expectTag

public void expectTag(java.lang.String tag)
               throws javax.xml.stream.XMLStreamException

Expect a particular tag.

Parameters:

tag - The expected tag name.

Throws:

javax.xml.stream.XMLStreamException - if the expected tag is not found.

moreTags

public boolean moreTags()
                 throws javax.xml.stream.XMLStreamException

Check if there are more tags in the current element.

Returns:

True if the stream has not reached the end of the current element.

Throws:

javax.xml.stream.XMLStreamException - if there is an error with the stream.

closeTag

public void closeTag(java.lang.String tag)
              throws javax.xml.stream.XMLStreamException

Close the current tag, checking that it did indeed close correctly.

Parameters:

tag - The expected tag name.

Throws:

javax.xml.stream.XMLStreamException - if a closing tag is not found.

closeTag

public void closeTag(java.lang.String tag,
                     java.lang.String... others)
              throws javax.xml.stream.XMLStreamException

Close the current tag, but accept some alternative elements first.

Parameters:

tag - The expected tag to close.

others - Alternate elements to accept.

Throws:

javax.xml.stream.XMLStreamException - if a closing tag is not found.

swallowTag

public void swallowTag(java.lang.String tag)
                throws javax.xml.stream.XMLStreamException

Swallow a tag, ignoring anything read until the tag closes.

Parameters:

tag - The tag to swallow.

Throws:

javax.xml.stream.XMLStreamException - if a there is an error with the stream.

currentTag

public java.lang.String currentTag()

Extract the current tag and its attributes from an input stream. Useful for error messages.

Returns:

A simple display of the stream state.

unexpectedTag

public void unexpectedTag(java.lang.String context)
                   throws javax.xml.stream.XMLStreamException

Standardized way to throw a parsing exception with a bit of context.

Parameters:

context - A context string.

Throws:

javax.xml.stream.XMLStreamException - is always thrown.

hasAttribute

public boolean hasAttribute(java.lang.String attributeName)

Is there an attribute present in the stream?

Parameters:

attributeName - An attribute name

Returns:

True if the attribute is present.

getAttribute

public boolean getAttribute(java.lang.String attributeName,
                            boolean defaultValue)

Gets a boolean from an attribute in a stream.

Parameters:

attributeName - The attribute name.

defaultValue - The default value.

Returns:

The boolean attribute value, or the default value if none found.

getAttribute

public float getAttribute(java.lang.String attributeName,
                          float defaultValue)

Gets a float from an attribute in a stream.

Parameters:

attributeName - The attribute name.

defaultValue - The default value.

Returns:

The float attribute value, or the default value if none found.

getAttribute

public int getAttribute(java.lang.String attributeName,
                        int defaultValue)

Gets an int from an attribute in a stream.

Parameters:

attributeName - The attribute name.

defaultValue - The default value.

Returns:

The int attribute value, or the default value if none found.

getAttribute

public long getAttribute(java.lang.String attributeName,
                         long defaultValue)

Gets a long from an attribute in a stream.

Parameters:

attributeName - The attribute name.

defaultValue - The default value.

Returns:

The long attribute value, or the default value if none found.

getAttribute

public java.lang.String getAttribute(java.lang.String attributeName,
                                     java.lang.String defaultValue)

Gets a string from an attribute in a stream.

Parameters:

attributeName - The attribute name.

defaultValue - The default value.

Returns:

The string attribute value, or the default value if none found.

getAttribute

public <T extends java.lang.Enum<T>> T getAttribute(java.lang.String attributeName,
                                                    java.lang.Class<T> returnClass,
                                                    T defaultValue)

Gets an enum from an attribute in a stream.

Type Parameters:

T - The expected enum type.

Parameters:

attributeName - The attribute name.

returnClass - The class of the return value.

defaultValue - The default value.

Returns:

The enum attribute value, or the default value if none found.

getAttribute

public <T extends FreeColObject> T getAttribute(Game game,
                                                java.lang.String attributeName,
                                                java.lang.Class<T> returnClass,
                                                T defaultValue)
                                         throws javax.xml.stream.XMLStreamException

Gets a FreeCol object from an attribute in a stream.

Type Parameters:

T - The expected attribute type.

Parameters:

game - The Game to look in.

attributeName - The attribute name.

returnClass - The FreeColObject type to expect.

defaultValue - The default value.

Returns:

The FreeColObject found, or the default value if not.

Throws:

javax.xml.stream.XMLStreamException - if the wrong class was passed.

getAttribute

public <T extends AIObject> T getAttribute(AIMain aiMain,
                                           java.lang.String attributeName,
                                           java.lang.Class<T> returnClass,
                                           T defaultValue)

Get a FreeCol AI object from an attribute in a stream.

Type Parameters:

T - The expected attribute type.

Parameters:

aiMain - The AIMain that contains the object.

attributeName - The attribute name.

returnClass - The AIObject type to expect.

defaultValue - The default value.

Returns:

The AIObject found, or the default value if not.

getLocationAttribute

public Location getLocationAttribute(Game game,
                                     java.lang.String attributeName,
                                     boolean make)
                              throws javax.xml.stream.XMLStreamException

Find a new location from a stream attribute. This is necessary because Location is an interface.

Parameters:

game - The Game to look in.

attributeName - The attribute to check.

make - If true, try to make the location if it is not found.

Returns:

The Location found.

Throws:

javax.xml.stream.XMLStreamException - if a problem was encountered during parsing.

getAttributeMap

public java.util.Map<java.lang.String,java.lang.String> getAttributeMap(java.lang.String... attributes)

Get a map of attributes.

Parameters:

attributes - The list of attributes to look up.

Returns:

A map of attributes.

getArrayAttributeMap

public java.util.Map<java.lang.String,java.lang.String> getArrayAttributeMap()

Get a map of the array attributes.

Returns:

A map of array attributes.

getAllAttributes

public java.util.Map<java.lang.String,java.lang.String> getAllAttributes()

Get a map of all attributes present.

Returns:

A map of all the attributes.

readList

public <T extends FreeColSpecObjectType> java.util.List<T> readList(Specification spec,
                                                                    java.lang.String tag,
                                                                    java.lang.Class<T> type)
                                                             throws javax.xml.stream.XMLStreamException

Reads an XML-representation of a list of FreeColSpecObjectTypes.

Type Parameters:

T - The list member type.

Parameters:

tag - The tag for the list.

spec - The Specification to find items in.

type - The type of the items to be added. The type must exist in the supplied specification.

Returns:

The list.

Throws:

javax.xml.stream.XMLStreamException - if a problem was encountered during parsing.

findFreeColGameObject

public <T extends FreeColGameObject> T findFreeColGameObject(Game game,
                                                             java.lang.String attributeName,
                                                             java.lang.Class<T> returnClass,
                                                             T defaultValue,
                                                             boolean required)
                                                      throws javax.xml.stream.XMLStreamException

Find a FreeColGameObject of a given class from a stream attribute. Use this routine when the object is optionally already be present in the game.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

attributeName - The attribute name.

returnClass - The class to expect.

defaultValue - A default value to return if not found.

required - If true a null result should throw an exception.

Returns:

The FreeColGameObject found, or the default value if not found.

Throws:

javax.xml.stream.XMLStreamException - if the attribute is missing.

makeFreeColObject

public <T extends FreeColObject> T makeFreeColObject(Game game,
                                                     java.lang.String attributeName,
                                                     java.lang.Class<T> returnClass,
                                                     boolean required)
                                              throws javax.xml.stream.XMLStreamException

Either get an existing FreeColObject from a stream attribute or create it if it does not exist. Use this routine when the object may not necessarily already be present in the game, but is expected to be defined eventually.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

attributeName - The required attribute name.

returnClass - The class of object.

required - If true a null result should throw an exception.

Returns:

The FreeColObject found or made, or null if the attribute was not present.

Throws:

javax.xml.stream.XMLStreamException - if a problem was encountered during parsing.

internedRead

private <T extends FreeColObject> T internedRead(Game game,
                                                 java.lang.Class<T> returnClass)
                                          throws javax.xml.stream.XMLStreamException

Do a normal interning read of a FreeColObject.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

returnClass - The class to expect.

Returns:

The FreeColObject found, or null there was no ID_ATTRIBUTE_TAG present.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

uninternedRead

private <T extends FreeColObject> T uninternedRead(Game game,
                                                   java.lang.Class<T> returnClass)
                                            throws javax.xml.stream.XMLStreamException

Do a special non-interning read of a FreeColObject.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

returnClass - The class to expect.

Returns:

The FreeColObject found, or null there was no ID_ATTRIBUTE_TAG present.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

readFreeColObject

public <T extends FreeColObject> T readFreeColObject(Game game,
                                                     java.lang.Class<T> returnClass)
                                              throws javax.xml.stream.XMLStreamException

Reads a FreeColObject from a stream. Expects the object to be identified by the standard ID_ATTRIBUTE_TAG. Use this routine when the object may or may not have been referenced and created-by-id in this game, but this is the point where it is authoritatively defined.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

returnClass - The class to expect.

Returns:

The FreeColObject found, or null there was no ID_ATTRIBUTE_TAG present.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

readFreeColObject

public <T extends FreeColObject> T readFreeColObject(Game game)
                                              throws javax.xml.stream.XMLStreamException

Read a FreeColObject from a stream.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

Returns:

The FreeColObject found.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

findAIObject

public <T extends AIObject> T findAIObject(AIMain aiMain,
                                           java.lang.String attributeName,
                                           java.lang.Class<T> returnClass,
                                           T defaultValue,
                                           boolean required)
                                    throws javax.xml.stream.XMLStreamException

Find a FreeCol AI object from an attribute in a stream.

Type Parameters:

T - The actual return type.

Parameters:

aiMain - The AIMain that contains the object.

attributeName - The attribute name.

returnClass - The AIObject type to expect.

defaultValue - The default value.

required - If true a null result should throw an exception.

Returns:

The AIObject found, or the default value if not.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

makeAIObject

public <T extends AIObject> T makeAIObject(AIMain aiMain,
                                           java.lang.String attributeName,
                                           java.lang.Class<T> returnClass,
                                           T defaultValue,
                                           boolean required)
                                    throws javax.xml.stream.XMLStreamException

Either get an existing AIObject from a stream attribute or create it if it does not exist. Use this routine when the object may not necessarily already be present in the game, but is expected to be defined eventually.

Type Parameters:

T - The actual return type.

Parameters:

aiMain - The AIMain that contains the object.

attributeName - The attribute name.

returnClass - The AIObject type to expect.

defaultValue - The default value.

required - If true, throw exceptions on missing data.

Returns:

The AIObject found, or the default value if not.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

shouldClearContainers

public boolean shouldClearContainers()

Should the game object type being read clear its containers before reading the child elements? Usually true, but not if the type is extending another one.

Returns:

True if the containers should be cleared.

getType

public <T extends FreeColSpecObjectType> T getType(Specification spec,
                                                   java.lang.String attributeName,
                                                   java.lang.Class<T> returnClass,
                                                   T defaultValue)

Get a FreeColSpecObjectType by identifier from a stream from a specification.

Type Parameters:

T - The actual return type.

Parameters:

spec - The Specification to look in.

attributeName - the name of the attribute identifying the FreeColSpecObjectType.

returnClass - The expected class of the return value.

defaultValue - A default value to return if the attributeName attribute is not present.

Returns:

The FreeColSpecObjectType found, or the defaultValue.

copy

public <T extends FreeColObject> T copy(Game game,
                                        java.lang.Class<T> returnClass)
                                 throws javax.xml.stream.XMLStreamException

Copy a FreeColObject by serializing it and reading back the result with a non-interning stream.

Type Parameters:

T - The actual return type.

Parameters:

game - The Game to look in.

returnClass - The class to expect.

Returns:

The copied FreeColObject found, or null there was no ID_ATTRIBUTE_TAG present.

Throws:

javax.xml.stream.XMLStreamException - if there is problem reading the stream.

readAttributeValues

public int readAttributeValues(java.util.Map<java.lang.String,java.lang.String> map,
                               java.lang.String attr)
                        throws javax.xml.stream.XMLStreamException

Fill in the identifier values supplied in a map. Special case for early reads of the client options.

Parameters:

map - A map containing identifiers to find as keys.

attr - The attribute to get for each identifier found.

Returns:

The number of identifiers found or negative on error.

Throws:

javax.xml.stream.XMLStreamException - if a problem was encountered during parsing.