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

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