diff --git a/core/java/src/net/i2p/data/DataStructure.java b/core/java/src/net/i2p/data/DataStructure.java index d331eb82a..0b9e65ba2 100644 --- a/core/java/src/net/i2p/data/DataStructure.java +++ b/core/java/src/net/i2p/data/DataStructure.java @@ -16,6 +16,18 @@ import java.io.OutputStream; /** * Defines the class as a standard object with particular bit representation, * exposing methods to read and write that representation. + *

+ * Do not reuse objects. + * Many of modifying methods contain checks to prevent + * altering a DataStructure after it is initialized. This protects the netdb, + * messages that contain DataStructures, + * caches, and the object itself from simple causes of corruption, by + * throwing IllegalStateExceptions. + * These checks are not necessarily thread-safe, and are not guaranteed + * to catch all possible means of corruption. + * Beware of other avenues of corruption, such as directly modifying data + * stored in byte[] objects. + *

* * @author jrandom */ @@ -62,4 +74,4 @@ public interface DataStructure /* extends Serializable */ { * @return SHA256 hash, or null if there were problems (data format or io errors) */ public Hash calculateHash(); -} \ No newline at end of file +} diff --git a/core/java/src/net/i2p/data/DatabaseEntry.java b/core/java/src/net/i2p/data/DatabaseEntry.java index 943fdbd73..92e9d9706 100644 --- a/core/java/src/net/i2p/data/DatabaseEntry.java +++ b/core/java/src/net/i2p/data/DatabaseEntry.java @@ -12,15 +12,28 @@ package net.i2p.data; import net.i2p.crypto.DSAEngine; /** + *

* Base implementation of common methods for the two data structures * that are stored in the netDb, i.e. LeaseSet and RouterInfo. * Implemented in 0.8.2 and retrofitted over LeaseSet and RouterInfo. * * This consolidates some common code and makes it easier to * implement the NetDB and I2NP without doing instanceof all over the place. - * + *

* DatabaseEntries have a SHA256 hash, a routing key, a timestamp, and * signatures. + *

+ * Do not reuse objects. + * Many of the setters and other methods contain checks to prevent + * altering a DatabaseEntry after it is signed. This protects the netdb, + * messages that contain DatabaseEntries, + * and the object itself from simple causes of corruption, by + * throwing IllegalStateExceptions. + * These checks are not necessarily thread-safe, and are not guaranteed + * to catch all possible means of corruption. + * Beware of other avenues of corruption, such as directly modifying data + * stored in byte[] objects. + *

* * @author zzz * @since 0.8.2 diff --git a/core/java/src/net/i2p/package.html b/core/java/src/net/i2p/package.html index acc673d1c..c62843c10 100644 --- a/core/java/src/net/i2p/package.html +++ b/core/java/src/net/i2p/package.html @@ -3,5 +3,10 @@

Core I2P package, contains information about the I2P version and an entry point to access important elements.

+

+With a few exceptions, +this package and all others in i2p.jar are maintained as a stable API for use +by apps, clients, and plugins. +

diff --git a/core/java/src/net/metanotion/package.html b/core/java/src/net/metanotion/package.html index 9ca87ac2c..68fe923e5 100644 --- a/core/java/src/net/metanotion/package.html +++ b/core/java/src/net/metanotion/package.html @@ -9,6 +9,16 @@ BlockFile +

+I2P Notes: +This is the database used by the BlockfileNamingService class. +It is heavily modified from the original 0.1.1 version. +Not for direct use by apps, clients, or plugins. +This package is not currently intended for general use, as +the API may be subject to change. +Contact I2P developers if you are considering use in another application. +Following is the original documentation copied from metanotion website. +

Metanotion BlockFile Database

A 100% Java 1.3, BSD Licensed, embeddable single file database engine in 32KB. This database was designed for PDA based and J2ME applications.

diff --git a/router/java/src/net/i2p/data/i2np/package.html b/router/java/src/net/i2p/data/i2np/package.html index 02de465c4..ecca73625 100644 --- a/router/java/src/net/i2p/data/i2np/package.html +++ b/router/java/src/net/i2p/data/i2np/package.html @@ -1,5 +1,12 @@

+This package defines the low-level messages sent between routers, +called the Invisible Internet Network Protocol (I2NP). +

+

+Not for use by apps, clients or plugins. +

+

The Invisible Internet Network Protocol (I2NP) is only a part of how an application can send messages over the network. The Invisible Internet Client Protocol (I2CP) defines how client applications written in any language can diff --git a/router/java/src/net/i2p/router/package.html b/router/java/src/net/i2p/router/package.html index 02e1bb656..e18dbdf96 100644 --- a/router/java/src/net/i2p/router/package.html +++ b/router/java/src/net/i2p/router/package.html @@ -6,5 +6,10 @@

It encompasses sending and receiving messages, building up tunnels, encrypting and decrypting (on multiple levels) where applicable, and so on.

+

+Classes in this package, sub-packages, and others in router.jar are +not for use by apps, clients or plugins (except for routerconsole). +Subject to change. Not necessarily maintained as a stable API. +

diff --git a/router/java/src/net/i2p/router/util/package.html b/router/java/src/net/i2p/router/util/package.html index bf81eb3fa..184777086 100644 --- a/router/java/src/net/i2p/router/util/package.html +++ b/router/java/src/net/i2p/router/util/package.html @@ -3,4 +3,8 @@ These classes define the several useful utilities used throughout the router.

+

+Not for use by apps, clients or plugins. +Subject to change. Not necessarily maintained as a stable API. +