From a97b5aa9d1024e3966eef3cf4596038fe3b229db Mon Sep 17 00:00:00 2001 From: youwenbusi <1245549353@qq.com> Date: Mon, 26 Sep 2022 14:25:16 +0800 Subject: [PATCH] fix javadoc --- VERSION | 2 +- .../protocol/base/AuthenticationProperty.java | 1 - .../java/com/webank/weid/rpc/WeIdService.java | 3 +- .../weid/service/impl/WeIdServiceImpl.java | 1 - .../impl/engine/WeIdServiceEngine.java | 2 +- .../AmbiguousCodecEncodingException.java | 26 ------- .../util/Multicodec/MulticodecEncoder.java | 47 +++++-------- .../webank/weid/util/Multicodec/VarInt.java | 67 ++++--------------- 8 files changed, 34 insertions(+), 115 deletions(-) delete mode 100644 src/main/java/com/webank/weid/util/Multicodec/AmbiguousCodecEncodingException.java diff --git a/VERSION b/VERSION index 2655edda3..411a3f46c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.8.5-rc.9-SNAPSHOT \ No newline at end of file +1.8.6-rc.1-SNAPSHOT \ No newline at end of file diff --git a/src/main/java/com/webank/weid/protocol/base/AuthenticationProperty.java b/src/main/java/com/webank/weid/protocol/base/AuthenticationProperty.java index 9bb5140bb..8fccb80c0 100644 --- a/src/main/java/com/webank/weid/protocol/base/AuthenticationProperty.java +++ b/src/main/java/com/webank/weid/protocol/base/AuthenticationProperty.java @@ -4,7 +4,6 @@ import com.webank.weid.util.DataToolUtils; import com.webank.weid.util.Multibase.Multibase; -import com.webank.weid.util.Multicodec.AmbiguousCodecEncodingException; import com.webank.weid.util.Multicodec.DecodedData; import com.webank.weid.util.Multicodec.MulticodecEncoder; import lombok.Data; diff --git a/src/main/java/com/webank/weid/rpc/WeIdService.java b/src/main/java/com/webank/weid/rpc/WeIdService.java index a398510e2..8ffe40e06 100644 --- a/src/main/java/com/webank/weid/rpc/WeIdService.java +++ b/src/main/java/com/webank/weid/rpc/WeIdService.java @@ -7,12 +7,11 @@ import com.webank.weid.protocol.base.*; import com.webank.weid.protocol.request.AuthenticationArgs; import com.webank.weid.protocol.request.CreateWeIdArgs; -import com.webank.weid.protocol.request.PublicKeyArgs; import com.webank.weid.protocol.request.ServiceArgs; import com.webank.weid.protocol.response.CreateWeIdDataResult; import com.webank.weid.protocol.response.ResponseData; import com.webank.weid.protocol.response.WeIdListResult; -import com.webank.weid.util.Multicodec.AmbiguousCodecEncodingException; + /** diff --git a/src/main/java/com/webank/weid/service/impl/WeIdServiceImpl.java b/src/main/java/com/webank/weid/service/impl/WeIdServiceImpl.java index 7faf942c9..39e9e96be 100644 --- a/src/main/java/com/webank/weid/service/impl/WeIdServiceImpl.java +++ b/src/main/java/com/webank/weid/service/impl/WeIdServiceImpl.java @@ -12,7 +12,6 @@ import com.webank.weid.protocol.base.*; import com.webank.weid.util.Multibase.Multibase; -import com.webank.weid.util.Multicodec.AmbiguousCodecEncodingException; import com.webank.weid.util.Multicodec.Multicodec; import com.webank.weid.util.Multicodec.MulticodecEncoder; import org.apache.commons.lang3.StringUtils; diff --git a/src/main/java/com/webank/weid/service/impl/engine/WeIdServiceEngine.java b/src/main/java/com/webank/weid/service/impl/engine/WeIdServiceEngine.java index 6ab90103e..4c5962421 100644 --- a/src/main/java/com/webank/weid/service/impl/engine/WeIdServiceEngine.java +++ b/src/main/java/com/webank/weid/service/impl/engine/WeIdServiceEngine.java @@ -30,7 +30,7 @@ ResponseData createWeId( String weAddress, String publicKey, String privateKey - ) throws NoSuchAlgorithmException; + ); /** * call weid contract to deactivate a weid. diff --git a/src/main/java/com/webank/weid/util/Multicodec/AmbiguousCodecEncodingException.java b/src/main/java/com/webank/weid/util/Multicodec/AmbiguousCodecEncodingException.java deleted file mode 100644 index 3a59f6497..000000000 --- a/src/main/java/com/webank/weid/util/Multicodec/AmbiguousCodecEncodingException.java +++ /dev/null @@ -1,26 +0,0 @@ -package com.webank.weid.util.Multicodec; - -/** - * Some codec codes are multibyte values and these cannot be distinguished from single byte codec codes when the data follows. - *
- * Consider this encoding of sample data 'A1E9D3D8EC'
- * 
- *  1. cidv1 encoding starts with 0x10.
- *     - therefore sample encoding hex data is: 01A1E9D3D8EC
- *  2. udp encoding starts with 0x0111
- *     - therefore sample encoding hex data is: 0111A1E9D3D8EC
- *
- * Looking 2 it is impossible to determine if its cidv1 encoding with data '11A1E9D3D8EC' or if it is udp encoding with data 'A1E9D3D8EC'.
- *
- *

- * This reveals an issue in the multi codec specification for codec prefixes greater than 1 byte, as they cannot - * be 1:1 unambiguously mapped between each other. - *

- * - */ -public class AmbiguousCodecEncodingException extends Exception { - - AmbiguousCodecEncodingException(String message) { - super(message); - } -} diff --git a/src/main/java/com/webank/weid/util/Multicodec/MulticodecEncoder.java b/src/main/java/com/webank/weid/util/Multicodec/MulticodecEncoder.java index 116dfdbac..983cdf063 100644 --- a/src/main/java/com/webank/weid/util/Multicodec/MulticodecEncoder.java +++ b/src/main/java/com/webank/weid/util/Multicodec/MulticodecEncoder.java @@ -6,20 +6,19 @@ import java.io.IOException; /** - *

Multicodec is part of the Multiformats collection of protocols.

- *
- *

Multiformats is a collection of protocols which aim to future-proof systems, today. They do this mainly by allowing - * data to be self-describable.

- *

See: https://github.com/multiformats/multiformats

- *

The Multicodec is an agreed way for encoding bytes with a prefix that specifies the type of encoding. + * Multicodec is part of the Multiformats collection of protocols. + * + * Multiformats is a collection of protocols which aim to future-proof systems, today. They do this mainly by allowing + * data to be self-describable. + * See: https://github.com/multiformats/multiformats + * The Multicodec is an agreed way for encoding bytes with a prefix that specifies the type of encoding. * The format is therefore a portable and self describing way of expressing an encoding of bytes that does not assume - * a specific context.

- *

See: https://github.com/multiformats/multicodec

- *

For example, the multicodec specification is used in the specifications for Decentralised Identifiers (DIDs) in + * a specific context. + * See: https://github.com/multiformats/multicodec + * For example, the multicodec specification is used in the specifications for Decentralised Identifiers (DIDs) in * regard to the DID Method 'key' specification. - * Therefore, any work on `did:key` implementations needs to also solve for the use of multicodecs.

- *

See: https://w3c-ccg.github.io/did-method-key

- *
+ * Therefore, any work on `did:key` implementations needs to also solve for the use of multicodecs. + * See: https://w3c-ccg.github.io/did-method-key * */ public class MulticodecEncoder { @@ -57,31 +56,21 @@ public static byte[] encode(Multicodec multicodec, byte[] data) { } /** - * Decodes a multicodec encoded byte array.
- *
- * Assumption: The decoding only supports single byte codec codes.
- * Some codec codes are multibyte values and these cannot be distinguished from single byte codec codes
+ * Decodes a multicodec encoded byte array. + * Assumption: The decoding only supports single byte codec codes. + * Some codec codes are multibyte values and these cannot be distinguished from single byte codec codes * when the data follows. - *
- *
- * Consider this encoding of sample data 'A1E9D3D8EC'
- *
+     * Consider this encoding of sample data 'A1E9D3D8EC'
      * 1. cidv1 encoding starts with 0x10.
      *    - therefore sample encoding hex data is: 01A1E9D3D8EC
      * 2. udp encoding starts with 0x0111
      *    - therefore sample encoding hex data is: 0111A1E9D3D8EC
-     *
- * - * Looking 2 it is impossible to determine if its
- *
    - *
  1. cidv1 encoding with data '11A1E9D3D8EC', or
    2. - *
  2. or if it is udp encoding with data 'A1E9D3D8EC'.
    3. - *
* - *

+ * Looking 2 it is impossible to determine if its + * cidv1 encoding with data '11A1E9D3D8EC', + * or if it is udp encoding with data 'A1E9D3D8EC'. * This suggests an issue in the multi codec specification for codec prefixes greater than 1 byte. * They cannot be 1:1 unambiguously mapped between each other. - *
* @param multicodecEncodedData The multicodec encoded data * @return The DecodedData object */ diff --git a/src/main/java/com/webank/weid/util/Multicodec/VarInt.java b/src/main/java/com/webank/weid/util/Multicodec/VarInt.java index 40a862692..68ac2de7f 100644 --- a/src/main/java/com/webank/weid/util/Multicodec/VarInt.java +++ b/src/main/java/com/webank/weid/util/Multicodec/VarInt.java @@ -20,14 +20,13 @@ * limitations under the License. * -------------------------------------------------------------------------------- * - *

Encodes signed and unsigned values using a common variable-length + * Encodes signed and unsigned values using a common variable-length * scheme, found for example in - * - * Google's Protocol Buffers. It uses fewer bytes to encode smaller values, - * but will use slightly more bytes to encode large values.

- *

- *

Signed values are further encoded using so-called zig-zag encoding - * in order to make them "compatible" with variable-length encoding.

+ * http://code.google.com/apis/protocolbuffers/docs/encoding.html + * Google's Protocol Buffers. It uses fewer bytes to encode smaller values, + * but will use slightly more bytes to encode large values. + * Signed values are further encoded using so-called zig-zag encoding + * in order to make them "compatible" with variable-length encoding. */ @SuppressWarnings("GrazieInspection") @@ -37,10 +36,10 @@ private VarInt() {} /** * Encodes a value using the variable-length encoding from - * - * Google Protocol Buffers. It uses zig-zag encoding to efficiently + * http://code.google.com/apis/protocolbuffers/docs/encoding.html + * Google Protocol Buffers. It uses zig-zag encoding to efficiently * encode signed values. If values are known to be non negative, - * {@link #writeUnsignedVarLong(long, DataOutput)} should be used. + * writeUnsignedVarLong should be used. * * @param value value to encode * @param out to write bytes to @@ -53,13 +52,13 @@ public static void writeSignedVarLong(long value, DataOutput out) throws IOExcep /** * Encodes a value using the variable-length encoding from - * - * Google Protocol Buffers. Zig-zag is not used, so input must not be negative. - * If values can be negative, use {@link #writeSignedVarLong(long, DataOutput)} + * http://code.google.com/apis/protocolbuffers/docs/encoding.html + * Google Protocol Buffers. Zig-zag is not used, so input must not be negative. + * If values can be negative, use writeSignedVarLong * instead. This method treats negative input as like a large unsigned value. * * @param value value to encode - * @param out to write bytes to + * @param out to write bytes to * @throws IOException if {@link DataOutput} throws {@link IOException} */ public static void writeUnsignedVarLong(long value, DataOutput out) throws IOException { @@ -70,17 +69,11 @@ public static void writeUnsignedVarLong(long value, DataOutput out) throws IOExc out.writeByte((int) value & 0x7F); } - /** - * @see #writeSignedVarLong(long, DataOutput) - */ public static void writeSignedVarInt(int value, DataOutput out) throws IOException { // Great trick from http://code.google.com/apis/protocolbuffers/docs/encoding.html#types writeUnsignedVarInt((value << 1) ^ (value >> 31), out); } - /** - * @see #writeUnsignedVarLong(long, DataOutput) - */ public static void writeUnsignedVarInt(int value, DataOutput out) throws IOException { while ((value & 0xFFFFFF80) != 0L) { out.writeByte((value & 0x7F) | 0x80); @@ -94,12 +87,6 @@ public static byte[] writeSignedVarInt(int value) { return writeUnsignedVarInt((value << 1) ^ (value >> 31)); } - /** - * @see #writeUnsignedVarLong(long, DataOutput) - *

- * This one does not use streams and is much faster. - * Makes a single object each time, and that object is a primitive array. - */ public static byte[] writeUnsignedVarInt(int value) { byte[] byteArrayList = new byte[10]; int i = 0; @@ -115,14 +102,6 @@ public static byte[] writeUnsignedVarInt(int value) { return out; } - /** - * @param in to read bytes from - * @return decode value - * @throws IOException if {@link DataInput} throws {@link IOException} - * @throws IllegalArgumentException if variable-length value does not terminate - * after 9 bytes have been read - * @see #writeSignedVarLong(long, DataOutput) - */ public static long readSignedVarLong(DataInput in) throws IOException { long raw = readUnsignedVarLong(in); // This undoes the trick in writeSignedVarLong() @@ -133,14 +112,6 @@ public static long readSignedVarLong(DataInput in) throws IOException { return temp ^ (raw & (1L << 63)); } - /** - * @param in to read bytes from - * @return decode value - * @throws IOException if {@link DataInput} throws {@link IOException} - * @throws IllegalArgumentException if variable-length value does not terminate - * after 9 bytes have been read - * @see #writeUnsignedVarLong(long, DataOutput) - */ public static long readUnsignedVarLong(DataInput in) throws IOException { long value = 0L; int i = 0; @@ -155,12 +126,6 @@ public static long readUnsignedVarLong(DataInput in) throws IOException { return value | (b << i); } - /** - * @throws IllegalArgumentException if variable-length value does not terminate - * after 5 bytes have been read - * @throws IOException if {@link DataInput} throws {@link IOException} - * @see #readSignedVarLong(DataInput) - */ public static int readSignedVarInt(DataInput in) throws IOException { int raw = readUnsignedVarInt(in); // This undoes the trick in writeSignedVarInt() @@ -171,12 +136,6 @@ public static int readSignedVarInt(DataInput in) throws IOException { return temp ^ (raw & (1 << 31)); } - /** - * @throws IllegalArgumentException if variable-length value does not terminate - * after 5 bytes have been read - * @throws IOException if {@link DataInput} throws {@link IOException} - * @see #readUnsignedVarLong(DataInput) - */ public static int readUnsignedVarInt(DataInput in) throws IOException { int value = 0; int i = 0;