java.lang.Object
net.i2p.data.SimpleDataStructure
All Implemented Interfaces:
DataStructure
Direct Known Subclasses:
EncryptedBuildRecord, Hash, Hash384, Hash512, NodeInfo, PrivateKey, PublicKey, SessionKey, SHA1Hash, Signature, SigningPrivateKey, SigningPublicKey
public abstract class SimpleDataStructureextends Object implements DataStructure
Base class for I2P data structures holding a single byte array in a protected _data field.

What the base class actually provides:

Not provided here:

  • No cache: there is no LRU or any other cache in this class. Subclasses that want one supply their own static SDSCache and expose create() factory methods that go through it - see Hash.
  • Not thread-safe: nothing here is synchronized and _data is not volatile, so an instance must be published safely (final field, or a happens-before edge) before other threads read it. Safe sharing applies only to a fully populated instance that nobody mutates - and callers that mutate the array returned by getData() break that.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected byte[]
    _data
    The byte array data for this structure.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SimpleDataStructure()
    A new instance with the data set to null.
    SimpleDataStructure(byte[] data)
    Creates a SimpleDataStructure with the given data.

  • Method Summary

    Modifier and Type
    Method
    Description
    Hash
    calculateHash()
    SHA256 hash of the byte array, or null if data is null.
    boolean
    equals(Object obj)
    Compares the raw data only: two different SimpleDataStructure subclasses of the same length holding the same bytes are equal, e.g.
    void
    fromBase64(String data)
    Data from the base64 string.
    void
    fromByteArray(byte[] data)
    Does the same thing as setData(byte[]) but null not allowed.
    byte[]
    getData()
    Data reference (not a copy).
    int
    hashCode()
    We assume the data has enough randomness in it, so use the first 4 bytes for speed.
    abstract int
    length()
    The legal length of the byte array in this data structure.
    protected int
    read(InputStream in, byte[] target)
    Repeated reads until the buffer is full or IOException is thrown.
    void
    readBytes(InputStream in)
    Data read from the stream.
    void
    setData(byte[] data)
    The byte array data, or null.
    String
    toBase64()
    Renders the structure into modified base 64 notation.
    byte[]
    toByteArray()
    Same thing as getData().
    String
    toString()
    Returns a string representation of this data structure.
    void
    writeBytes(OutputStream out)
    Writes the data to the output stream.

    Methods inherited from class Object

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

  • Field Details

    • _data

      protected byte[] _data
      The byte array data for this structure.

  • Constructor Details

    • SimpleDataStructure

      public SimpleDataStructure()
      A new instance with the data set to null. Call readBytes(InputStream), setData(), or fromByteArray() after this to set the data.

    • SimpleDataStructure

      public SimpleDataStructure(byte[] data)
      Creates a SimpleDataStructure with the given data.
      Parameters:
      data - the byte array, or null
      Throws:
      IllegalArgumentException - if data is not the legal number of bytes (but null is ok)

  • Method Details

    • length

      public abstract int length()
      The legal length of the byte array in this data structure.
      Returns:
      the legal length of the byte array

    • getData

      public byte[] getData()
      Data reference (not a copy). Mutating the returned array mutates this structure, and breaks the hashCode contract of any subclass that caches a hash of the data.
      Returns:
      the backing array, always exactly length() long or null before the data has been set

    • setData

      public void setData(byte[] data)
      The byte array data, or null. Not a copy - see the class documentation.
      Parameters:
      data - of correct length, or null
      Throws:
      IllegalArgumentException - if data is not the legal number of bytes (but null is ok)
      RuntimeException - if data already set.

    • readBytes

      public void readBytes(InputStream in) throws DataFormatException, IOException
      Data read from the stream.
      Specified by:
      readBytes in interface DataStructure
      Parameters:
      in - the stream to read
      Throws:
      RuntimeException - if data already set.
      DataFormatException - if the data is improperly formatted
      IOException - if there was a problem reading the stream

    • read

      protected int read(InputStream in, byte[] target) throws IOException
      Repeated reads until the buffer is full or IOException is thrown.
      Parameters:
      in - the stream to read from
      target - the buffer to fill
      Returns:
      number of bytes read (should always equal target.length)
      Throws:
      IOException - on IO error

    • writeBytes

      public void writeBytes(OutputStream out) throws DataFormatException, IOException
      Writes the data to the output stream.
      Specified by:
      writeBytes in interface DataStructure
      Parameters:
      out - stream to write to
      Throws:
      DataFormatException - if the data was incomplete or not yet ready to be written
      IOException - if there was a problem writing to the stream

    • toBase64

      public String toBase64()
      Renders the structure into modified base 64 notation.
      Specified by:
      toBase64 in interface DataStructure
      Returns:
      null on error

    • fromBase64

      public void fromBase64(String data) throws DataFormatException
      Data from the base64 string.
      Specified by:
      fromBase64 in interface DataStructure
      Parameters:
      data - base64 encoded string to load from
      Throws:
      DataFormatException - if decoded data is not the legal number of bytes or on decoding error
      RuntimeException - if data already set.

    • calculateHash

      public Hash calculateHash()
      SHA256 hash of the byte array, or null if data is null.
      Specified by:
      calculateHash in interface DataStructure
      Returns:
      SHA256 hash, or null if there were problems (data format or io errors)

    • toByteArray

      public byte[] toByteArray()
      Same thing as getData().
      Specified by:
      toByteArray in interface DataStructure
      Returns:
      same thing as getData()

    • fromByteArray

      public void fromByteArray(byte[] data) throws DataFormatException
      Does the same thing as setData(byte[]) but null not allowed.
      Specified by:
      fromByteArray in interface DataStructure
      Parameters:
      data - non-null byte array
      Throws:
      DataFormatException - if null or wrong length
      RuntimeException - if data already set

    • toString

      public String toString()
      Returns a string representation of this data structure.
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      We assume the data has enough randomness in it, so use the first 4 bytes for speed. If this is not the case, override in the extending class.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code

    • equals

      public boolean equals(Object obj)
      Compares the raw data only: two different SimpleDataStructure subclasses of the same length holding the same bytes are equal, e.g. a 32-byte SessionKey and a 32-byte Hash. Only compare instances of the same class, and only use them as map keys or set members when that cannot happen.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare
      Returns:
      true if the data arrays are equal