net.sf.saxon.value

## Class ObjectValue

- java.lang.Object
- - net.sf.saxon.om.AbstractItem
  - - net.sf.saxon.value.ObjectValue

- All Implemented Interfaces:
    PullEvent, GroundedValue, Item, Sequence
  Direct Known Subclasses:
    Tuple

      public class ObjectValue
      extends AbstractItem

  An XPath value that encapsulates a Java object. Such a value can only be constructed from Java code either in a Java extension function, or in the calling application.

  Until Saxon 9.4, ObjectValue was a subclass of AtomicValue, and external Java objects were considered to be atomic. From 9.5, this has been changed so that an ObjectValue is another kind of Item: a fourth kind, at the same level as nodes, atomic values, and function items.

  In the same way as ObjectValue is a wrapper around a Java instance object, the type of the value is a wrapper around the corresponding Java class. These types have subtype-supertype relationships that correspond to the Java class hierarchy. The top type in this branch of the class hierarchy, which wraps the Java class "Object", has item() as its superclass. These types can be referred to in the SequenceType syntax using QNames of the form jt:full.package.name.ClassName, where the convetional prefix jt maps to the namespace URI http://saxon.sf.net/java-type.

  An ObjectValue is no longer permitted to wrap a Java null. An empty sequence should be used in this situation.

  The effective boolean value of a wrapped Java object, like that of a node, is always true.

  Atomizing a wrapped Java object is not allowed (fails with a dynamic error). The string() function calls the wrapped object's toString() method, unless the wrapped object is null, in which case it returns the zero-length string.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ObjectValue(Object object)` Constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `displayTypeName()` Display the type name for use in error messages
    `boolean` | `effectiveBooleanValue()` Get the effective boolean value of the value
    `boolean` | `equals(Object other)` Determine if two ObjectValues are equal
    `ItemType` | `getItemType(TypeHierarchy th)` Determine the data type of the items in the expression, if possible
    `Object` | `getObject()` Get the encapsulated object
    `String` | `getStringValue()` Get the value of the item as a string.
    `CharSequence` | `getStringValueCS()` Get the string value of the item as a CharSequence.
    `int` | `hashCode()`

    - ### Methods inherited from class net.sf.saxon.om.AbstractItem

      `getLength, head, itemAt, iterate, reduce, subsequence`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ObjectValue

          public ObjectValue(Object object)

      Constructor
      Parameters:
        `object` - the object to be encapsulated

  - ### Method Detail

    - #### getStringValue

          public String getStringValue()

      Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.

      If the calling code can handle any CharSequence, the method `getStringValueCS()` should be used. If the caller requires a string, this method is preferred.
      Returns:
        the string value of the item
      Throws:
        `UnsupportedOperationException` - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)
      Since:
        8.4
      See Also:
        `getStringValueCS()`

    - #### getStringValueCS

          public CharSequence getStringValueCS()

      Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that `X.getStringValueCS().toString()` returns a string that is equal to `X.getStringValue()`.

      Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

      If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the `getStringValue()` method is preferred.
      Returns:
        the string value of the item
      Throws:
        `UnsupportedOperationException` - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)
      Since:
        8.4
      See Also:
        `getStringValue()`

    - #### getItemType

          public ItemType getItemType(TypeHierarchy th)

      Determine the data type of the items in the expression, if possible
      Parameters:
        `th` - The TypeHierarchy.
      Returns:
        for the default implementation: AnyItemType (not known)

    - #### displayTypeName

          public String displayTypeName()

      Display the type name for use in error messages
      Returns:
        the type name. This will be in the form "java-type:" followed by the full class name of the wrapped Java object.

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue()

      Get the effective boolean value of the value
      Returns:
        true (always)

    - #### getObject

          public Object getObject()

      Get the encapsulated object
      Returns:
        the Java object that this external object wraps

    - #### equals

          public boolean equals(Object other)

      Determine if two ObjectValues are equal
      Overrides:
        `equals` in class `Object`
      Returns:
        true if the other object is also a wrapped Java object and if the two wrapped objects compare equal using the Java equals() method.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.