info.bioinfweb.jphyloio.events.meta

Class LiteralMetadataContentEvent

java.lang.Object

info.bioinfweb.jphyloio.events.ConcreteJPhyloIOEvent

info.bioinfweb.jphyloio.events.ContinuedEvent

info.bioinfweb.jphyloio.events.meta.LiteralMetadataContentEvent

All Implemented Interfaces:

JPhyloIOEvent

public class LiteralMetadataContentEvent
extends ContinuedEvent

This event represents a value of a literal metadata and is therefore always nested inside start and end events of the type EventContentType.LITERAL_META.

Values can be represented in the following ways:

• An instance can represent a single object value directly.
• A sequence of events can represent a longer string that is distributed among several events.
• A sequence of events can represent a more complex XML representation of the literal value. In such cases one event instance will represent each XMLEvent created from the encountered XML.

When readers create instances of this event, they try to create object values from their string representations using a translator returned by ObjectTranslatorFactory. If no according translator is available, the object value will be null.

If the declared data type is mapped to an instance of String (e.g. xsd:string or xsd:token) the object value and its string representation are the same String instance. Large strings may be separated among several events for performance reasons, while ContinuedEvent.isContinuedInNextEvent() will be true in all but the last event of such a sequence. If a string is separated among multiple events, the object value in all of these events will be null and the single parts can be obtained using getStringValue(). (That is because only the whole string is considered as the object and not its parts.)

JPhyloIO event objects are generally immutable. Anyway complex object values may have editable properties themselves. In application code, it should be absolutely avoided to edit such properties while the according event object is still in use, especially if the event contains a string representation of that object (which cannot be edited accordingly).

Since:

0.0.0

Author:

Ben Stöver

See Also:

LiteralMetadataEvent, Metadata demo application

Constructor Summary

Constructors

Constructor and Description
LiteralMetadataContentEvent(java.lang.Object objectValue, java.lang.String stringValue) Creates a new instance of this class.
LiteralMetadataContentEvent(java.lang.String stringValue, boolean continuedInNextEvent) Creates a new instance of this class.
LiteralMetadataContentEvent(javax.xml.stream.events.XMLEvent xmlEvent, boolean continuedInNextEvent) Creates a new instance of this class wrapping an XMLEvent.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	getObjectValue() Returns the Java object representing the metadata element modeled by this event.
java.lang.String	getStringValue() Returns the string value of the meta information.
javax.xml.stream.events.XMLEvent	getXMLEvent() Returns the XMLEvent modeled by this instance.
boolean	hasObjectValue() Determines whether this instance carries a Java object of the metadata element it models.
boolean	hasStringValue() Determines whether this instance carries a string representation of the metadata element it models.
boolean	hasXMLEventValue() Determines whether this instance carries an XMLEvent as its object value.
java.lang.String	toString() Returns the stored string representation of the modeled metadata element if available.

Methods inherited from class info.bioinfweb.jphyloio.events.ContinuedEvent

isContinuedInNextEvent

Methods inherited from class info.bioinfweb.jphyloio.events.ConcreteJPhyloIOEvent

asCharacterDefinitionEvent, asCharacterSetIntervalEvent, asCommentEvent, asEdgeEvent, asLabeledIDEvent, asLinkedLabeledIDEvent, asLiteralMetadataContentEvent, asLiteralMetadataEvent, asNodeEvent, asPartEndEvent, asResourceMetadataEvent, asSequenceTokensEvent, asSetElementEvent, asSingleSequenceTokenEvent, asSingleTokenDefinitionEvent, asTokenSetDefinitionEvent, asUnknownCommandEvent, createEndEvent, getType

Methods inherited from class java.lang.Object

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

Constructor Detail

LiteralMetadataContentEvent

public LiteralMetadataContentEvent(java.lang.String stringValue,
                                   boolean continuedInNextEvent)

Creates a new instance of this class.

Parameters:

stringValue - the string value of the meta information.

continuedInNextEvent - Specify true here if this event does not contain the final part of its value and more events are ahead or false otherwise.

LiteralMetadataContentEvent

public LiteralMetadataContentEvent(java.lang.Object objectValue,
                                   java.lang.String stringValue)

Creates a new instance of this class.

Parameters:

objectValue - the object value of the meta information.

stringValue - the string value of the meta information.

LiteralMetadataContentEvent

public LiteralMetadataContentEvent(javax.xml.stream.events.XMLEvent xmlEvent,
                                   boolean continuedInNextEvent)

Creates a new instance of this class wrapping an XMLEvent.

Parameters:

xmlEvent - the XML event object to be wrapped

continuedInNextEvent - Specify true here if this event does not contain the final part of its value and more events are ahead or false otherwise. (Note that true this is only allowed for character XML events which contain only a part of the represented string.)

Throws:

java.lang.IllegalArgumentException - if continuedInNextEvent in set to true, but the specified XML event was not a characters event

Method Detail

getStringValue

public java.lang.String getStringValue()

Returns the string value of the meta information.

If larger strings are separated among multiple content events, this property returns the part of the string modeled by this event.

It may return null if no string representation was provided in the constructor. Note that no instance of this class will return null for both the object value and the string representation.

If this instance represents carries an XMLEvent as its object value, this method will return the characters for XML event instances implementing Characters and null for other implementations.

Returns:

the string representation of the meta information or null if this metadata event carries no string value

See Also:

getObjectValue()

getObjectValue

public java.lang.Object getObjectValue()

Returns the Java object representing the metadata element modeled by this event. An alternative string representation of this object may be provided that can be obtained using getStringValue().

This method can return null if this content event represents are larger string that is separated among multiple events. In such cases getStringValue() returns the part of the string that is modeled by this event. This method may also return null if null was specified as the object value in the constructor.

Returns:

the metadata object modeled by this event or null

hasStringValue

public boolean hasStringValue()

Determines whether this instance carries a string representation of the metadata element it models.

Returns:

true of a string representation is available or false if getStringValue() will return null

hasObjectValue

public boolean hasObjectValue()

Determines whether this instance carries a Java object of the metadata element it models.

Returns:

true of an object is available or false if getObjectValue() will return null

hasXMLEventValue

public boolean hasXMLEventValue()

Determines whether this instance carries an XMLEvent as its object value. This happens if this instance is used to represent a part the content of an XML representation of a literal metadata element.

Returns:

true if an XML stream event can be returned by getXMLEvent() or false otherwise

getXMLEvent

public javax.xml.stream.events.XMLEvent getXMLEvent()
                                             throws java.lang.ClassCastException

Returns the XMLEvent modeled by this instance. This is only possible if this instance is used to represent a part the content of an XML representation of a literal metadata element.

This convenience method calls getObjectValue() internally and tries to cast it to XMLEvent.

Returns:

the XMLEvent or null if this instance carries no object value

Throws:

java.lang.ClassCastException - if the object value of this instance does not implement XMLEvent

See Also:

hasXMLEventValue(), getObjectValue()

toString

public java.lang.String toString()

Returns the stored string representation of the modeled metadata element if available. If not, the Object.toString() method of the object value is returned.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of the metadata element modeled by this event