net.i2p.data

## Interface DataStructure

- All Known Implementing Classes:
    AbuseReason, AbuseSeverity, Certificate, DatabaseEntry, DataStructureImpl, DateAndFlags, DeliveryInstructions, Destination, EncryptedBuildRecord, EncryptedLeaseSet, GarlicClove, Hash, Hash384, Hash512, InfoHash, KeyCertificate, KeysAndCert, Lease, Lease2, LeaseSet, LeaseSet2, LocalHash, MetaLease, MetaLeaseSet, NextSessionKey, NID, NodeInfo, Payload, Peer, PrivateKey, PublicKey, RouterAddress, RouterIdentity, RouterInfo, RSASigningPrivateCrtKey, SendMessageOptions, SessionConfig, SessionKey, SessionKeyAndNonce, SHA1Hash, ShortEncryptedBuildRecord, Signature, SigningPrivateKey, SigningPublicKey, SimpleDataStructure, TokenKey, VerifiedDestination

      public interface DataStructure

  Base interface defining standard binary representation for I2P data structures.

  DataStructure provides the foundation for all I2P protocol data:

  - Binary Protocol: Defines exact bit-level representation
  - Serialization: Standard methods for reading/writing to streams
  - Network Compatibility: Ensures consistent data encoding
  - Validation: Built-in integrity and format checking

  Core Operations:

  - `readBytes(InputStream)` - Deserialize from binary stream
  - `writeBytes(OutputStream)` - Serialize to binary stream
  - Format Compliance: Follows I2P data structure specification
  - Error Handling: Proper exception reporting for invalid data

  Integrity Protection:

  - Immutable After Initialization: Prevents modification after deserialization
  - IllegalStateException: Thrown when modification is attempted
  - NetDb Protection: Safeguards network database from corruption
  - Message Safety: Protects I2NP messages during transmission

  Usage Throughout I2P:

  - I2NP Messages: All protocol messages implement DataStructure
  - NetDb Entries: RouterInfo and LeaseSet storage format
  - I2CP Protocol: Client-router communication data
  - Cryptography: Keys, signatures, and certificates
  - Routing: Tunnel IDs, leases, and routing information

  Implementation Guidelines:

  - Do Not Reuse: Create new instances for each data element
  - Thread Safety: Protection is not guaranteed to be thread-safe
  - Corruption Prevention: Multiple protection layers but not foolproof
  - Direct Modification: Avoid modifying internal byte[] arrays

  Security Considerations:

  - Input Validation: Always validate deserialized data
  - Bounds Checking: Prevent buffer overflows and underflows
  - Exception Handling: Properly handle DataFormatException
  - Memory Safety: Be cautious with direct byte array access

  Performance Aspects:

  - Efficient Serialization: Optimized for network transmission
  - Minimal Overhead: Compact binary representation
  - Fast Validation: Quick integrity and format checking
  - Memory Management: Careful allocation and cleanup

  Common Implementations:

  - `DataStructureImpl` - Base class with common functionality
  - `SimpleDataStructure` - Fixed-size byte array structures
  - `DatabaseEntry` - NetDb-storable objects with signatures
  - All I2P protocol message classes

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Hash` | `calculateHash()` Calculate the SHA256 value of this object (useful for a few scenarios)
    `void` | `fromBase64(String data)` Load the structure from the provided base64 string.
    `void` | `fromByteArray(byte[] data)` Load's structure from the data provided Warning - many classes will throw IllegalStateException if data is already set.
    `void` | `readBytes(InputStream in)` Load up the current object with data from the given stream.
    `String` | `toBase64()` render the structure into modified base 64 notation
    `byte[]` | `toByteArray()` Convert the structure to a byte array.
    `void` | `writeBytes(OutputStream out)` Write out the data structure to the stream, using the format defined in the I2P data structure specification.

- - ### Method Detail

    - #### calculateHash

          Hash calculateHash()

      Calculate the SHA256 value of this object (useful for a few scenarios)
      Returns:
        SHA256 hash, or null if there were problems (data format or io errors)

    - #### fromBase64

          void fromBase64(String data)
                   throws DataFormatException

      Load the structure from the provided base64 string. Warning - many classes will throw IllegalStateException if data is already set. Warning - many classes will throw IllegalArgumentException if data is the wrong size.
      Parameters:
        `data` - base64 encoded string to load from
      Throws:
        `DataFormatException` - if the data format is invalid

    - #### fromByteArray

          void fromByteArray(byte[] data)
                      throws DataFormatException

      Load's structure from the data provided Warning - many classes will throw IllegalStateException if data is already set. Warning - many classes will throw IllegalArgumentException if data is the wrong size.
      Parameters:
        `data` - byte array to load from
      Throws:
        `DataFormatException` - if the data format is invalid

    - #### readBytes

          void readBytes(InputStream in)
                  throws DataFormatException,
                         IOException

      Load up the current object with data from the given stream. Data loaded this way must match the I2P data structure specification. Warning - many classes will throw IllegalStateException if data is already set.
      Parameters:
        `in` - stream to read from
      Throws:
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### toBase64

          String toBase64()

      render the structure into modified base 64 notation
      Returns:
        null on error

    - #### toByteArray

          byte[] toByteArray()

      Convert the structure to a byte array.
      Returns:
        may be null if data is not set

    - #### writeBytes

          void writeBytes(OutputStream out)
                   throws DataFormatException,
                          IOException

      Write out the data structure to the stream, using the format defined in the I2P data structure specification.
      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