Package com.apicatalog.tree.io

Interface TreeAdapter

All Known Implementing Classes:
NativeAdapter
public interface TreeAdapter
Provides a uniform, read-only abstraction for navigating tree-like data structures. This interface acts as a "wrapper" or "view" over an existing, underlying tree model, decoupling processing logic from any specific data format or library.

It is the conceptual counterpart to TreeGenerator. Where NodeGenerator offers a "write-only" API for constructing a tree, NodeAdapter provides a "read-only" API for inspecting one.

Core Use Cases

  1. Standalone Processing: Use an adapter to traverse and extract data from a native tree representation (e.g., an in-memory JSON object model) using a consistent API. This keeps application logic independent of the underlying data-binding library.
  2. Data Transformation: Serve as the input for a TreeTraversal, which walks the tree exposed by this adapter and drives a TreeGenerator. This powerful pattern is the foundation for converting between different data formats (e.g., from a YAML document to a binary CBOR representation).

Implementations are responsible for interpreting the native node objects of a specific format. Methods are expected to throw runtime exceptions such as ClassCastException or UnsupportedOperationException if a node is of an unexpected type or an operation is not supported for a given node.

  • Method Details

    • features

      Features features()

    • isCompatibleWith

      default boolean isCompatibleWith(TreeAdapter adapter)

    • isNode

      boolean isNode(Object node)
      Checks if the given object is a native node that this adapter can process. This method is the primary entry point for determining if the adapter is suitable for a given piece of data.
      Parameters:
      node - the object to check, which may be null.
      Returns:
      true if the adapter can handle the object's type, false otherwise.

    • type

      NodeType type(Object node)
      Determines the NodeType of the given native node.
      Parameters:
      node - the node to inspect, which must be a valid node for this adapter.
      Returns:
      the NodeType corresponding to the node.
      Throws:
      IllegalArgumentException - if the object is not a node this adapter can process.

    • isNull

      default boolean isNull(Object node)
      Checks if the adapted node represents a null value.
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a null value, false otherwise.

    • isBoolean

      boolean isBoolean(Object node)
      Checks if the adapted node represents a boolean value.
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a boolean value, false otherwise.

    • isBinary

      boolean isBinary(Object node)
      Checks if the adapted node contains binary data.
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents binary data, false otherwise.

    • size

      @Deprecated int size(Object node)
      Deprecated.
      Returns the number of entries in a map or elements in a collection. This method is intended for nodes where isMap(Object) or isCollection(Object) returns true.
      Parameters:
      node - the structure node to inspect.
      Returns:
      the number of entries (for a map) or elements (for a collection).
      Throws:
      UnsupportedOperationException - if the node is not a map or collection.

    • isEmpty

      default boolean isEmpty(Object node)
      Checks if a map or collection node is empty.
      Parameters:
      node - the structure node to inspect.
      Returns:
      true if the node contains no entries or elements, false otherwise.
      Throws:
      UnsupportedOperationException - if the node is not a map or collection.

    • isMap

      boolean isMap(Object node)
      Checks if the adapted node represents a map (an object with key-value pairs).
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a map, false otherwise.

    • keys

      Collection<?> keys(Object node)
      Returns a collection of the native key objects from a map node. The types of the keys depend on the underlying format (e.g., Strings for JSON, various scalars for CBOR).
      Parameters:
      node - the map node to inspect.
      Returns:
      a collection containing the map's native key objects.
      Throws:
      UnsupportedOperationException - if the node is not a map.

    • keyStream

      default Stream<?> keyStream(Object node)

    • property

      Object property(Object key, Object node)
      Retrieves the value associated with a given native key object from a map node.
      Parameters:
      key - the native key object used for the lookup.
      node - the map node to query.
      Returns:
      the native value node, or null if the key is not found.
      Throws:
      UnsupportedOperationException - if the node is not a map.

    • property

      Object property(Object key, TreeAdapter keyAdapter, Object node)

    • entries

      Iterable<Map.Entry<?,?>> entries(Object node)
      Returns all key-value pairs of a map node as an Iterable. The entries contain the native key and value objects.
      Parameters:
      node - the map node to inspect.
      Returns:
      an Iterable of its entries.
      Throws:
      UnsupportedOperationException - if the node is not a map.

    • entryStream

      Stream<Map.Entry<?,?>> entryStream(Object node)
      Returns all key-value pairs of a map node as a Stream. This is a convenience method for processing map entries using the Stream API.
      Parameters:
      node - the map node to inspect.
      Returns:
      a Stream of its entries.
      Throws:
      UnsupportedOperationException - if the node is not a map.

    • isSingleEntry

      default boolean isSingleEntry(Object node)

    • singleEntry

      default Map.Entry<?,?> singleEntry(Object node)

    • isCollection

      boolean isCollection(Object node)
      Checks if the adapted node represents a collection of elements (e.g., an array or list).
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a collection, false otherwise.

    • isList

      boolean isList(Object node)
      Checks if the adapted collection node is a list (an ordered collection that allows duplicates).
      Parameters:
      node - the collection node to check.
      Returns:
      true if the node is a list, false otherwise.

    • isSet

      boolean isSet(Object node)
      Checks if the adapted collection node is a set (an unordered collection of unique elements).
      Parameters:
      node - the collection node to check.
      Returns:
      true if the node is a set, false otherwise.

    • elements

      Iterable<?> elements(Object node)
      Returns the elements of a collection node as an Iterable.
      Parameters:
      node - the collection node to inspect.
      Returns:
      an Iterable of its native element objects.
      Throws:
      UnsupportedOperationException - if the node is not a collection.

    • elementStream

      Stream<?> elementStream(Object node)
      Returns the elements of a collection node as a Stream.
      Parameters:
      node - the collection node to inspect.
      Returns:
      a Stream of its native element objects.
      Throws:
      UnsupportedOperationException - if the node is not a collection.

    • isSingleElement

      default boolean isSingleElement(Object node)

    • singleElement

      default Object singleElement(Object node)

    • isString

      boolean isString(Object node)
      Checks if the adapted node represents a string value.
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a string, false otherwise.

    • stringValue

      String stringValue(Object node)
      Extracts the string value from a string node.
      Parameters:
      node - the string node.
      Returns:
      the string value.
      Throws:
      ClassCastException - if the node is not a string.

    • isNumber

      boolean isNumber(Object node)
      Checks if the adapted node represents any numeric value (integral or floating-point).
      Parameters:
      node - the node to check.
      Returns:
      true if the node represents a number, false otherwise.

    • isIntegral

      boolean isIntegral(Object node)
      Checks if a number node represents an integral value (e.g., an integer or long) as opposed to a floating-point value.
      Parameters:
      node - the number node to check.
      Returns:
      true if the node's value is integral, false otherwise.
      Throws:
      ClassCastException - if the node is not a number.

    • intValue

      int intValue(Object node)
      Extracts the int value from a numeric node. This may involve a narrowing primitive conversion.
      Parameters:
      node - the numeric node.
      Returns:
      the value as an int.
      Throws:
      ClassCastException - if the node is not a number.

    • longValue

      long longValue(Object node)
      Extracts the long value from a numeric node. This may involve a narrowing primitive conversion.
      Parameters:
      node - the numeric node.
      Returns:
      the value as a long.
      Throws:
      ClassCastException - if the node is not a number.

    • integerValue

      BigInteger integerValue(Object node)
      Extracts the BigInteger value from a numeric node.
      Parameters:
      node - the numeric node.
      Returns:
      the value as a BigInteger.
      Throws:
      ClassCastException - if the node is not a number.

    • doubleValue

      double doubleValue(Object node)
      Extracts the double value from a numeric node.
      Parameters:
      node - the numeric node.
      Returns:
      the value as a double.
      Throws:
      ClassCastException - if the node is not a number.

    • decimalValue

      BigDecimal decimalValue(Object node)
      Extracts the BigDecimal value from a numeric node.
      Parameters:
      node - the numeric node.
      Returns:
      the value as a BigDecimal.
      Throws:
      ClassCastException - if the node is not a number.

    • binaryValue

      byte[] binaryValue(Object node)
      Extracts the binary data from a binary node.
      Parameters:
      node - the binary node.
      Returns:
      the data as a byte array.
      Throws:
      ClassCastException - if the node is not binary.

    • asIterable

      Iterable<?> asIterable(Object node)
      Returns the node's contents as a universal Iterable. This is a convenience method that enables uniform iteration logic.
      • If the node is a collection, returns its elements.
      • If the node is not a collection, wraps it in a single-element iterable.
      • If the node is null, returns an empty iterable.
      Parameters:
      node - the node to convert.
      Returns:
      a non-null Iterable representing the node's contents.

    • asStream

      Stream<?> asStream(Object node)
      Returns the node's contents as a universal Stream.
      Parameters:
      node - the node to convert.
      Returns:
      a non-null Stream representing the node's contents.

    • asString

      String asString(Object node)
      Returns a string representation of the node, coercing non-string scalar types where applicable.
      Parameters:
      node - the node to convert.
      Returns:
      a string representation of the node's value.

    • asDecimal

      BigDecimal asDecimal(Object node)
      Converts a given node to a BigDecimal, if possible. This method can be used to treat both numeric and string nodes as decimal values.
      Parameters:
      node - the node to convert.
      Returns:
      the BigDecimal representation.
      Throws:
      NumberFormatException - if a string node cannot be parsed into a BigDecimal.
      ClassCastException - if the node is neither a number nor a string.

    • isTrue

      default boolean isTrue(Object node)

    • isFalse

      default boolean isFalse(Object node)

    • numericValue

      default Number numericValue(Object node)

    • isEmptyMap

      default boolean isEmptyMap(Object node)

    • isEmptyCollection

      default boolean isEmptyCollection(Object node)