echelon/i2p.i2p
1
0
Fork 0
forked from I2P_Developers/i2p.i2p
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

API: Fix some client-side APIs to honor defaults in Properties;

Browse Source 
add javadocs to specify where we do and don't (ticket #1491)
This commit is contained in:
zzz
2015-03-31 13:18:11 +00:00
parent 22c4149358
commit fadc624f7c
14 changed files with 116 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
core/java/src/net/i2p/client/I2PClient.java
View File

@ -72,6 +72,8 @@ public interface I2PClient {
* the router how to handle the new session, and to configure the end to end
* encryption.
*
* As of 0.9.19, defaults in options are honored.
*
* @param destKeyStream location from which to read the Destination, PrivateKey, and SigningPrivateKey from,
* format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile}
* @param options set of options to configure the router with, if null will use System properties

15
core/java/src/net/i2p/client/I2PSessionImpl.java
View File

@ -235,6 +235,8 @@ abstract class I2PSessionImpl implements I2PSession, I2CPMessageReader.I2CPMessa
* Create a new session, reading the Destination, PrivateKey, and SigningPrivateKey
* from the destKeyStream, and using the specified options to connect to the router
*
* As of 0.9.19, defaults in options are honored.
*
* @param destKeyStream stream containing the private key data,
* format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile}
* @param options set of options to configure the router with, if null will use System properties
@ -314,11 +316,14 @@ abstract class I2PSessionImpl implements I2PSession, I2CPMessageReader.I2CPMessa
}
}
/** save some memory, don't pass along the pointless properties */
/**
* Save some memory, don't pass along the pointless properties.
* As of 0.9.19, defaults from options will be promoted to real values in rv.
* @return a new Properties without defaults
*/
private Properties filter(Properties options) {
Properties rv = new Properties();
for (Object oKey : options.keySet()) { // TODO-Java6: s/keySet()/stringPropertyNames()/
String key = (String) oKey;
for (String key : options.stringPropertyNames()) {
if (key.startsWith("java.") ||
key.startsWith("user.") ||
key.startsWith("os.") ||
@ -787,7 +792,9 @@ abstract class I2PSessionImpl implements I2PSession, I2CPMessageReader.I2CPMessa
I2CPMessageProducer getProducer() { return _producer; }
/**
* Retrieve the configuration options
* Retrieve the configuration options, filtered.
* All defaults passed in via constructor have been promoted to the primary map.
*
* @return non-null, if insantiated with null options, this will be the System properties.
*/
Properties getOptions() { return _options; }

18
core/java/src/net/i2p/data/DataHelper.java
View File

@ -172,11 +172,13 @@ public class DataHelper {
* Property keys and values must not contain '=' or ';', this is not checked and they are not escaped
* Keys and values must be 255 bytes or less,
* Formatted length must not exceed 65535 bytes
* @throws DataFormatException if either is too long.
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* @param rawStream stream to write to
* @param props properties to write out
* @throws DataFormatException if there is not enough valid data to write out
* @throws DataFormatException if there is not enough valid data to write out,
* or a length limit is exceeded
* @throws IOException if there is an IO error writing out the data
*/
public static void writeProperties(OutputStream rawStream, Properties props)
@ -190,7 +192,8 @@ public class DataHelper {
* Property keys and values must not contain '=' or ';', this is not checked and they are not escaped
* Keys and values must be 255 bytes or less,
* Formatted length must not exceed 65535 bytes
* @throws DataFormatException if either is too long.
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* jrandom disabled UTF-8 in mid-2004, for performance reasons,
* i.e. slow foo.getBytes("UTF-8")
@ -199,6 +202,7 @@ public class DataHelper {
* Use utf8 = false for RouterAddress (fast, non UTF-8)
* Use utf8 = true for SessionConfig (slow, UTF-8)
* @param props source may be null
* @throws DataFormatException if a length limit is exceeded
*/
public static void writeProperties(OutputStream rawStream, Properties props, boolean utf8)
throws DataFormatException, IOException {
@ -213,6 +217,8 @@ public class DataHelper {
* Keys and values must be 255 bytes or less,
* Formatted length must not exceed 65535 bytes
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* jrandom disabled UTF-8 in mid-2004, for performance reasons,
* i.e. slow foo.getBytes("UTF-8")
* Re-enable it so we can pass UTF-8 tunnel names through the I2CP SessionConfig.
@ -269,6 +275,8 @@ public class DataHelper {
* Strings will be UTF-8 encoded in the byte array.
* Warning - confusing method name, Properties is the source.
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* @deprecated unused
*
* @param target returned array as specified in data structure spec
@ -364,6 +372,8 @@ public class DataHelper {
* Formatted length must not exceed 65535 bytes
* Warning - confusing method name, Properties is the source.
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* @throws DataFormatException if key, value, or total is too long
*/
public static byte[] toProperties(Properties opts) throws DataFormatException {
@ -477,6 +487,8 @@ public class DataHelper {
* Note that this does not escape the \r or \n that are unescaped in loadProps() above.
* As of 0.8.1, file will be mode 600.
*
* Properties from the defaults table of props (if any) are not written out by this method.
*
* Leading or trailing whitespace in values is not checked but
* will be trimmed by loadProps()
*

4
core/java/src/net/i2p/data/i2cp/GetDateMessage.java
View File

@ -45,6 +45,10 @@ public class GetDateMessage extends I2CPMessageImpl {
}
/**
* Defaults in GetDateMessage options are, in general, NOT honored.
* Defaults are not serialized out-of-JVM, and the router does not recognize defaults in-JVM.
* Client side must promote defaults to the primary map.
*
* @param version the client's version String to be sent to the router; may be null;
* must be non-null if options is non-null and non-empty.
* @param options Client options to be sent to the router; primarily for authentication; may be null;

4
core/java/src/net/i2p/data/i2cp/SessionConfig.java
View File

@ -91,6 +91,10 @@ public class SessionConfig extends DataStructureImpl {
* Configure the session with the given options;
* keys and values 255 bytes (not chars) max each
*
* Defaults in SessionConfig options are, in general, NOT honored.
* Defaults are not serialized out-of-JVM, and the router does not recognize defaults in-JVM.
* Client side must promote defaults to the primary map.
*
* @param options Properties for this session
*/
public void setOptions(Properties options) {