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

    All Methods Instance Methods Concrete Methods
    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