Package net.shibboleth.sp.ddf

Class DDF

java.lang.Object
net.shibboleth.sp.ddf.DDF
All Implemented Interfaces:
Iterable<DDF>
@NotThreadSafe public class DDF extends Object implements Iterable<DDF>
The core object in the DDF mode, this is a node in a tree of objects that make up the entire data structure.

Each node contains references to its parant and children, if any, as well as data type and possibly a value if a leaf node.

Most of the types are self-explanatory, but strings may be "safe" or "unsafe". Safe strings are understood to be Unicode that can be safely converted between UTF-8 and UTF-16. Unsafe strings are represented as Java String objects but have an unknown character encoding so the individual code points above 127 are essentially undefined and cannot be assumed to represent the "correct" value. They may only be compared with other values that are understood to represent the same range of values.

The method names do not align to normal Java conventions for compatibility with the other version(s) of the same API.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    DDF.DDFType
    Type enum.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private String
    name
    Name of node.
    private DDF
    parent
    Parent node.
    private DDF.DDFType
    type
    Node type.
    private Object
    value
    Reference to the value, which depends on the type.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DDF()
    Constructor.
    DDF(String n)
    Constructor.
    DDF(String n, byte[] val)
    Constructor.
    DDF(String n, double val)
    Constructor.
    DDF(String n, int val)
    Constructor.
    DDF(String n, long val)
    Constructor.
    DDF(String n, String val)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    DDF
    add(DDF child)
    Adds a node to the end of a struct or list and returns it.
    DDF
    addafter(DDF child, DDF after)
    Adds a node to a list after a specified node.
    DDF
    addbefore(DDF child, DDF before)
    Adds a node to a list prior to a specified node.
    DDF
    addmember(String path)
    Adds a new empty node to a structure, possibly creating nested structures based on dotted path notation (existing nodes matching the path segments are not altered other than to convert them to structures).
    List<DDF>
    asList()
    Expose an immutable list representing a structure or list node.
    Map<String,DDF>
    asMap()
    Expose an immutable map representing a structure node.
    (package private) DDF
    copy()
    Performs a deep copy of the node and all children, if any.
    static DDF
    deserialize(InputStream is)
    Parses a seralized DDF from an input stream.
    DDF
    destroy()
    Destroys a node's content, resets it to a null object and clears its name.
    private StringBuilder
    dump(StringBuilder builder, long indent)
    Helper method to dump to a string for debugging.
    DDF
    empty()
    Converts this node to an empty type/value.
    (package private) static void
    encode(OutputStream os, byte[] bytes)
    A simple encoder for non-ASCII characters.
    boolean
    equals(Object obj)
    Double
    floating()
    Get the floating point value of this node.
    DDF
    floating(double val)
    Converts this node to an floating point type/value.
    DDF
    floating(String val)
    Converts this node to a floating point type/value based on the converted form of the input.
    DDF
    getmember(String path)
    Access a (possibly nested) structure member via dotted path notation, also allowing access to list elements via "[n]" array notation.
    int
    hashCode()
    private static int
    hexchar(int b)
    Converts a byte into a hex character.
    Integer
    integer()
    Get the integer value of this node.
    DDF
    integer(int val)
    Converts this node to an integer type/value.
    DDF
    integer(String val)
    Converts this node to an integer type/value based on the converted form of the input.
    boolean
    isempty()
    Returns true iff the node is empty.
    boolean
    isfloat()
    Returns true iff the node is a floating point.
    boolean
    isint()
    Returns true iff the node is an integer.
    boolean
    islist()
    Returns true iff the node is a list/array.
    boolean
    islong()
    Returns true iff the node is a long integer.
    boolean
    isnull()
    Returns true iff the node is null.
    boolean
    isstring()
    Returns true iff the node is a string.
    boolean
    isstruct()
    Returns true iff the node is a structure.
    boolean
    isunsafestring()
    Returns true iff the node is an unsafe string.
    Iterator<DDF>
    iterator()
    DDF
    list()
    Converts this node to a list/array.
    Long
    longinteger()
    Get the long integer value of this node.
    DDF
    longinteger(long val)
    Converts this node to a long integer type/value.
    DDF
    longinteger(String val)
    Converts this node to a long integer type/value based on the converted form of the input.
    String
    name()
    Get the node name.
    DDF
    name(String n)
    Set the node name.
    DDF
    parent()
    Get the parent node.
    DDF
    remove()
    Isolate this object from its surrounding nodes and return it.
    OutputStream
    serialize(OutputStream os)
    Serialize this object to a provided stream.
    String
    string()
    Get the string value of this node.
    DDF
    string(double val)
    Converts this node to a string type/value based on the converted form of the input.
    DDF
    string(int val)
    Converts this node to a string type/value based on the converted form of the input.
    DDF
    string(long val)
    Converts this node to a string type/value based on the converted form of the input.
    DDF
    string(String val)
    Converts this node to a string type/value.
    DDF
    structure()
    Converts this node to a structure.
    String
    toString()
    byte[]
    unsafe_string()
    Get the byte array value of this node if an unsafe string.
    DDF
    unsafe_string(byte[] val)
    Converts this node to an unsafe string type/value.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Field Details

    • name

      @Nullable private String name
      Name of node.

    • parent

      @Nullable private DDF parent
      Parent node.

    • type

      @Nonnull private DDF.DDFType type
      Node type.

    • value

      @Nullable private Object value
      Reference to the value, which depends on the type.

  • Constructor Details

    • DDF

      public DDF()
      Constructor.

    • DDF

      public DDF(@Nullable @NotEmpty String n)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name

    • DDF

      public DDF(@Nullable @NotEmpty String n, @Nullable String val)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name
      val - string value, assumed to be "safe" Unicode

    • DDF

      public DDF(@Nullable @NotEmpty String n, @Nullable byte[] val)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name
      val - byte array value, handled without knowledge of the encoding

    • DDF

      public DDF(@Nullable @NotEmpty String n, int val)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name
      val - integer value

    • DDF

      public DDF(@Nullable @NotEmpty String n, long val)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name
      val - long integer value

    • DDF

      public DDF(@Nullable @NotEmpty String n, double val)
      Constructor.

      For compatibility, the name is constrained to no more than 255 characters.

      Parameters:
      n - node name
      val - floating value

  • Method Details

    • destroy

      @Nonnull public DDF destroy()
      Destroys a node's content, resets it to a null object and clears its name.

      This is primarily for tree maintenance, given the lack of need for explicit memory management.

      Returns:
      this object

    • copy

      @Nonnull DDF copy()
      Performs a deep copy of the node and all children, if any.
      Returns:
      the copy

    • name

      @Nullable public String name()
      Get the node name.
      Returns:
      the name

    • name

      @Nonnull public DDF name(@Nullable @NotEmpty String n)
      Set the node name.

      For compatibility, the name is constrained to no more than 255 characters.

      The name will not be set if the node is already a child of a structure.

      Parameters:
      n - the new name
      Returns:
      this object

    • isnull

      public boolean isnull()
      Returns true iff the node is null.
      Returns:
      true iff the node is null

    • isempty

      public boolean isempty()
      Returns true iff the node is empty.
      Returns:
      true iff the node is empty

    • isstring

      public boolean isstring()
      Returns true iff the node is a string.
      Returns:
      true iff the node is a string

    • isunsafestring

      public boolean isunsafestring()
      Returns true iff the node is an unsafe string.
      Returns:
      true iff the node is an unsafe string

    • isint

      public boolean isint()
      Returns true iff the node is an integer.
      Returns:
      true iff the node is an integer

    • islong

      public boolean islong()
      Returns true iff the node is a long integer.
      Returns:
      true iff the node is a long integer

    • isfloat

      public boolean isfloat()
      Returns true iff the node is a floating point.
      Returns:
      true iff the node is a floating point

    • isstruct

      public boolean isstruct()
      Returns true iff the node is a structure.
      Returns:
      true iff the node is a structure

    • islist

      public boolean islist()
      Returns true iff the node is a list/array.
      Returns:
      true iff the node is a list/array.

    • string

      @Nullable public String string()
      Get the string value of this node.

      The string value of a non-string value is null.

      Returns:
      the string value or null

    • unsafe_string

      @Nullable public byte[] unsafe_string()
      Get the byte array value of this node if an unsafe string.
      Returns:
      the byte array value or null

    • integer

      @Nullable public Integer integer()
      Get the integer value of this node.

      Integers are coerced from other types based on numeric conversions or the count of a structure or list.

      Returns:
      the integer value or null

    • longinteger

      @Nullable public Long longinteger()
      Get the long integer value of this node.

      Longs are coerced from other types based on numeric conversions or the count of a structure or list.

      Returns:
      the long integer value or null

    • floating

      @Nullable public Double floating()
      Get the floating point value of this node.

      Doubles are coerced from other types based on numeric conversions or the count of a structure or list.

      Returns:
      the floating point value or null

    • empty

      @Nonnull public DDF empty()
      Converts this node to an empty type/value.

      All children should be considered disposed of, though in Java this is circumventable by means of maintaining references to them.

      Returns:
      this object

    • string

      @Nonnull public DDF string(@Nullable String val)
      Converts this node to a string type/value.
      Parameters:
      val - the value to inject
      Returns:
      this object

    • unsafe_string

      @Nonnull public DDF unsafe_string(@Nullable byte[] val)
      Converts this node to an unsafe string type/value.
      Parameters:
      val - the value to inject
      Returns:
      this object

    • string

      @Nonnull public DDF string(int val)
      Converts this node to a string type/value based on the converted form of the input.
      Parameters:
      val - input value
      Returns:
      this object

    • string

      @Nonnull public DDF string(long val)
      Converts this node to a string type/value based on the converted form of the input.
      Parameters:
      val - input value
      Returns:
      this object

    • string

      @Nonnull public DDF string(double val)
      Converts this node to a string type/value based on the converted form of the input.
      Parameters:
      val - input value
      Returns:
      this object

    • integer

      @Nonnull public DDF integer(int val)
      Converts this node to an integer type/value.
      Parameters:
      val - value to inject
      Returns:
      this object

    • integer

      @Nonnull public DDF integer(@Nonnull @NotEmpty String val)
      Converts this node to an integer type/value based on the converted form of the input.

      A conversion error will assign zero as the value.

      Parameters:
      val - value to inject
      Returns:
      this object

    • longinteger

      @Nonnull public DDF longinteger(long val)
      Converts this node to a long integer type/value.
      Parameters:
      val - value to inject
      Returns:
      this object

    • longinteger

      @Nonnull public DDF longinteger(@Nonnull @NotEmpty String val)
      Converts this node to a long integer type/value based on the converted form of the input.

      A conversion error will assign zero as the value.

      Parameters:
      val - value to inject
      Returns:
      this object

    • floating

      @Nonnull public DDF floating(double val)
      Converts this node to an floating point type/value.
      Parameters:
      val - value to inject
      Returns:
      this object

    • floating

      @Nonnull public DDF floating(@Nonnull @NotEmpty String val)
      Converts this node to a floating point type/value based on the converted form of the input.

      A conversion error will assign zero as the value.

      Parameters:
      val - value to inject
      Returns:
      this object

    • structure

      @Nonnull public DDF structure()
      Converts this node to a structure.
      Returns:
      this object

    • list

      @Nonnull public DDF list()
      Converts this node to a list/array.
      Returns:
      this object

    • add

      @Nonnull public DDF add(@Nonnull DDF child)
      Adds a node to the end of a struct or list and returns it.

      If this node is not a struct or list or the child is a null node, then it is returned with no further action.

      If this node is a struct with an existing member by the same name, the input replaces that member.

      Parameters:
      child - the child to add
      Returns:
      the child

    • addbefore

      @Nonnull public DDF addbefore(@Nonnull DDF child, @Nonnull DDF before)
      Adds a node to a list prior to a specified node.

      If this node is not a list, does not contain the second parameter, or either parameter is a null node, then the first parameter is returned with no further action.

      Parameters:
      child - the child to add
      before - the node to insert the child before
      Returns:
      the child

    • addafter

      @Nonnull public DDF addafter(@Nonnull DDF child, @Nonnull DDF after)
      Adds a node to a list after a specified node.

      If this node is not a list, does not contain the second parameter, or either parameter is a null node, then the first parameter is returned with no further action.

      Parameters:
      child - the child to add
      after - the node to insert the child after
      Returns:
      the child

    • remove

      @Nonnull public DDF remove()
      Isolate this object from its surrounding nodes and return it.
      Returns:
      this object

    • parent

      @Nullable public DDF parent()
      Get the parent node.
      Returns:
      parent node

    • asMap

      @Nonnull @NonnullElements @Unmodifiable @NotLive public Map<String,DDF> asMap()
      Expose an immutable map representing a structure node.
      Returns:
      immutable map, or null if the node is not a structure

    • asList

      @Nonnull @NonnullElements @Unmodifiable @NotLive public List<DDF> asList()
      Expose an immutable list representing a structure or list node.
      Returns:
      immutable list, or null if the node is not a structure or list

    • addmember

      @Nonnull public DDF addmember(@Nonnull @NotEmpty String path)
      Adds a new empty node to a structure, possibly creating nested structures based on dotted path notation (existing nodes matching the path segments are not altered other than to convert them to structures).

      The input path MUST contain at least one non-empty path segment.

      This node will be converted to a structure if not already one unless it starts out as null.

      Parameters:
      path - dotted path to use
      Returns:
      the last node added to the nested tree, or a null node if unable to do so

    • getmember

      @Nonnull public DDF getmember(@Nonnull @NotEmpty String path)
      Access a (possibly nested) structure member via dotted path notation, also allowing access to list elements via "[n]" array notation.

      Failure to navigate the tree at any point will cause a null node to be returned.

      Parameters:
      path - dotted path to use
      Returns:
      the matching node, or a null node

    • iterator

      @Nonnull public Iterator<DDF> iterator()
      Specified by:
      iterator in interface Iterable<DDF>

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      @Nonnull public String toString()

      The string output is for debugging purposes and should not be used when serializing.

      Overrides:
      toString in class Object

    • dump

      @Nonnull private StringBuilder dump(@Nonnull StringBuilder builder, long indent)
      Helper method to dump to a string for debugging.
      Parameters:
      builder - string builder to use
      indent - size of indent
      Returns:
      the first parameter

    • serialize

      @Nonnull public OutputStream serialize(@Nonnull OutputStream os) throws IOException
      Serialize this object to a provided stream.
      Parameters:
      os - output stream
      Returns:
      the output stream
      Throws:
      IOException - if an error occurs

    • deserialize

      @Nonnull public static DDF deserialize(@Nonnull InputStream is) throws IOException
      Parses a seralized DDF from an input stream.
      Parameters:
      is - input stream
      Returns:
      the parsed object
      Throws:
      IOException - if an error occurs

    • encode

      static void encode(@Nonnull OutputStream os, @Nonnull byte[] bytes) throws IOException
      A simple encoder for non-ASCII characters.

      Made this package-accessible for unit testing.

      Parameters:
      os - output stream
      bytes - bytes to encode
      Throws:
      IOException - if an error occurs

    • hexchar

      private static int hexchar(int b)
      Converts a byte into a hex character.
      Parameters:
      b - input byte
      Returns:
      the hex character equivalent (capitalized)