You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by dr...@apache.org on 2015/02/09 07:27:45 UTC
[04/30] directory-kerberos git commit: Added some javadoc in
kerby-asn1 module
Added some javadoc in kerby-asn1 module
Project: http://git-wip-us.apache.org/repos/asf/directory-kerberos/repo
Commit: http://git-wip-us.apache.org/repos/asf/directory-kerberos/commit/0228e16d
Tree: http://git-wip-us.apache.org/repos/asf/directory-kerberos/tree/0228e16d
Diff: http://git-wip-us.apache.org/repos/asf/directory-kerberos/diff/0228e16d
Branch: refs/heads/installation
Commit: 0228e16db4c3e102f530d0375b945f99c1a0a6a6
Parents: 66a3df6
Author: Drankye <dr...@gmail.com>
Authored: Sun Feb 1 09:26:00 2015 +0800
Committer: Drankye <dr...@gmail.com>
Committed: Sun Feb 1 09:26:00 2015 +0800
----------------------------------------------------------------------
.../java/org/apache/kerby/asn1/Asn1Factory.java | 13 ++++
.../org/apache/kerby/asn1/Asn1InputBuffer.java | 27 ++++++-
.../java/org/apache/kerby/asn1/TagClass.java | 25 ++++++
.../org/apache/kerby/asn1/TaggingOption.java | 50 +++++++++++-
.../kerby/asn1/type/AbstractAsn1Type.java | 12 +++
.../org/apache/kerby/asn1/type/Asn1Type.java | 80 ++++++++++++++++++++
6 files changed, 204 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1Factory.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1Factory.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1Factory.java
index 2762476..ea4eca8 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1Factory.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1Factory.java
@@ -23,8 +23,16 @@ import org.apache.kerby.asn1.type.Asn1Collection;
import org.apache.kerby.asn1.type.Asn1Simple;
import org.apache.kerby.asn1.type.Asn1Type;
+/**
+ * ASN1 type factory
+ */
public class Asn1Factory {
+ /**
+ * Create an ASN1 type with specified tag number
+ * @param tagNo
+ * @return ASN1 type
+ */
public static Asn1Type create(int tagNo) {
UniversalTag tagNoEnum = UniversalTag.fromValue(tagNo);
if (tagNoEnum != UniversalTag.UNKNOWN) {
@@ -33,6 +41,11 @@ public class Asn1Factory {
throw new IllegalArgumentException("Unexpected tag " + tagNo);
}
+ /**
+ * Create an ASN1 type with specified tag
+ * @param tagNo
+ * @return ASN1 type
+ */
public static Asn1Type create(UniversalTag tagNo) {
if (Asn1Simple.isSimple(tagNo)) {
return Asn1Simple.createSimple(tagNo);
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1InputBuffer.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1InputBuffer.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1InputBuffer.java
index 934b0c1..985bd7e 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1InputBuffer.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/Asn1InputBuffer.java
@@ -27,23 +27,43 @@ import java.io.IOException;
import java.nio.ByteBuffer;
/**
- * Asn1 decoder
+ * Asn1 decoder. Given an input stream, it validates and parses
+ * according to ASN1 spec, and the resultant object can be read
+ * and read until exhausted.
*/
public class Asn1InputBuffer {
private final LimitedByteBuffer limitedBuffer;
+ /**
+ * Constructor with bytes.
+ * @param bytes
+ */
public Asn1InputBuffer(byte[] bytes) {
this(new LimitedByteBuffer(bytes));
}
+ /**
+ * Constructor with a ByteBuffer.
+ * @param byteBuffer
+ */
public Asn1InputBuffer(ByteBuffer byteBuffer) {
this(new LimitedByteBuffer(byteBuffer));
}
+ /**
+ * Constructor with LimitedByteBuffer.
+ * @param limitedByteBuffer
+ */
public Asn1InputBuffer(LimitedByteBuffer limitedByteBuffer) {
this.limitedBuffer = limitedByteBuffer;
}
+ /**
+ * Parse and read ASN1 object from the stream. If it's already
+ * exhausted then null will be returned to indicate the end.
+ * @return an ASN1 object if available otherwise null
+ * @throws IOException
+ */
public Asn1Type read() throws IOException {
if (! limitedBuffer.available()) {
return null;
@@ -60,6 +80,11 @@ public class Asn1InputBuffer {
return one;
}
+ /**
+ *
+ * @param bytes
+ * @throws IOException
+ */
public void readBytes(byte[] bytes) throws IOException {
limitedBuffer.readBytes(bytes);
}
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/TagClass.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/TagClass.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/TagClass.java
index 430630f..bac9db8 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/TagClass.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/TagClass.java
@@ -19,6 +19,9 @@
*/
package org.apache.kerby.asn1;
+/**
+ * Tag class defined by the spec.
+ */
public enum TagClass {
UNKNOWN(-1),
UNIVERSAL(0x00),
@@ -28,14 +31,26 @@ public enum TagClass {
private int value;
+ /**
+ * The constructor given the value.
+ * @param value
+ */
private TagClass(int value) {
this.value = value;
}
+ /**
+ * Get the tag class value.
+ * @return value
+ */
public int getValue() {
return value;
}
+ /**
+ * Tell it's universal or not.
+ * @return true if it's universal otherwise false
+ */
public boolean isUniversal() {
return this == UNIVERSAL;
}
@@ -52,6 +67,11 @@ public enum TagClass {
return this == APPLICATION || this == CONTEXT_SPECIFIC;
}
+ /**
+ * Converted from an integer
+ * @param value
+ * @return tag class
+ */
public static TagClass fromValue(int value) {
// Optimized by Emmanuel
switch (value) {
@@ -68,6 +88,11 @@ public enum TagClass {
}
}
+ /**
+ * Converted from a tag value, which contains tag class info.
+ * @param tag
+ * @return tag class
+ */
public static TagClass fromTagFlags(int tag) {
return fromValue(tag & 0xC0);
}
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/TaggingOption.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/TaggingOption.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/TaggingOption.java
index 534977b..0911a1c 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/TaggingOption.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/TaggingOption.java
@@ -19,49 +19,95 @@
*/
package org.apache.kerby.asn1;
-public class TaggingOption
-{
+/**
+ * Tagging option for tagging an ASN1 type.
+ */
+public class TaggingOption {
private int tagNo;
private boolean isImplicit;
private boolean isAppSpecific;
+ /**
+ * Create an implicit application specific tagging option with tagNo.
+ * @param tagNo
+ * @return tagging option
+ */
public static TaggingOption newImplicitAppSpecific(int tagNo) {
return new TaggingOption(tagNo, true, true);
}
+ /**
+ * Create an explicit application specific tagging option with tagNo.
+ * @param tagNo
+ * @return tagging option
+ */
public static TaggingOption newExplicitAppSpecific(int tagNo) {
return new TaggingOption(tagNo, false, true);
}
+ /**
+ * Create an implicit context specific tagging option with tagNo.
+ * @param tagNo
+ * @return tagging option
+ */
public static TaggingOption newImplicitContextSpecific(int tagNo) {
return new TaggingOption(tagNo, true, false);
}
+ /**
+ * Create an explicit context specific tagging option with tagNo.
+ * @param tagNo
+ * @return tagging option
+ */
public static TaggingOption newExplicitContextSpecific(int tagNo) {
return new TaggingOption(tagNo, false, false);
}
+ /**
+ * The private constructor.
+ * @param tagNo
+ * @param isImplicit
+ * @param isAppSpecific
+ */
private TaggingOption(int tagNo, boolean isImplicit, boolean isAppSpecific) {
this.tagNo = tagNo;
this.isImplicit = isImplicit;
this.isAppSpecific = isAppSpecific;
}
+ /**
+ * Make tag flags giving it's tagged constructed.
+ * @param isTaggedConstructed
+ * @return tag flag
+ */
public int tagFlags(boolean isTaggedConstructed) {
boolean isConstructed = isImplicit ? isTaggedConstructed : true;
TagClass tagClass = isAppSpecific ? TagClass.APPLICATION : TagClass.CONTEXT_SPECIFIC;
int flags = tagClass.getValue() | (isConstructed ? EncodingOption.CONSTRUCTED_FLAG : 0x00);
+
return flags;
}
+ /**
+ * Get the tag number.
+ * @return tag number
+ */
public int getTagNo() {
return tagNo;
}
+ /**
+ * Tell it's application specific or not.
+ * @return true if it's application specific otherwise false
+ */
public boolean isAppSpecific() {
return isAppSpecific;
}
+ /**
+ * Tell it's implicit or not.
+ * @return true if it's implicit otherwise false
+ */
public boolean isImplicit() {
return isImplicit;
}
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/AbstractAsn1Type.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/AbstractAsn1Type.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/AbstractAsn1Type.java
index 3aefed7..99b54fb 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/AbstractAsn1Type.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/AbstractAsn1Type.java
@@ -28,14 +28,26 @@ import java.io.EOFException;
import java.io.IOException;
import java.nio.ByteBuffer;
+/**
+ * The abstract ASN1 type for all the ASN1 types. It provides basic
+ * encoding and decoding utilities.
+ *
+ * @param <T> the type of the value encoded/decoded or wrapped by this
+ */
public abstract class AbstractAsn1Type<T> implements Asn1Type {
private TagClass tagClass = TagClass.UNKNOWN;
private int tagNo = -1;
private int tagFlags = -1;
protected EncodingOption encodingOption = EncodingOption.UNKNOWN;
private int encodingLen = -1;
+ // The wrapped real value.
private T value;
+ /**
+ *
+ * @param tagClass
+ * @param tagNo
+ */
public AbstractAsn1Type(TagClass tagClass, int tagNo) {
this(tagClass, tagNo, null);
}
http://git-wip-us.apache.org/repos/asf/directory-kerberos/blob/0228e16d/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/Asn1Type.java
----------------------------------------------------------------------
diff --git a/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/Asn1Type.java b/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/Asn1Type.java
index 48f0d26..95f8855 100644
--- a/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/Asn1Type.java
+++ b/kerby-asn1/src/main/java/org/apache/kerby/asn1/type/Asn1Type.java
@@ -25,17 +25,97 @@ import org.apache.kerby.asn1.TaggingOption;
import java.io.IOException;
import java.nio.ByteBuffer;
+/**
+ * The ASN1 type interface for all ASN1 types.
+ */
public interface Asn1Type {
+ /**
+ *
+ * @return
+ */
public int tagFlags();
+
+ /**
+ * Get tag number for the type
+ * @return tag number
+ */
public int tagNo();
+
+ /**
+ * Set encoding option.
+ * See {@link org.apache.kerby.asn1.EncodingOption}.
+ * @param encodingOption
+ */
public void setEncodingOption(EncodingOption encodingOption);
+
+ /**
+ * Get length of encoding bytes by just calculating without real encoding.
+ * Generally it's called to prepare for the encoding buffer.
+ * @return length of encoding bytes
+ */
public int encodingLength();
+
+ /**
+ * Encode the type, by recursively.
+ * @return encoded bytes
+ */
public byte[] encode();
+
+ /**
+ * Encode the type, by recursively, using the provided buffer.
+ * @param buffer
+ */
public void encode(ByteBuffer buffer);
+
+ /**
+ * Decode the content bytes into this type.
+ * @param content
+ * @throws IOException
+ */
public void decode(byte[] content) throws IOException;
+
+ /**
+ * Decode the content bytes into this type.
+ * @param content
+ * @throws IOException
+ */
public void decode(ByteBuffer content) throws IOException;
+
+ /**
+ * Tag and encode this type using the provided tagging option.
+ * @param taggingOption
+ * @return encoded bytes
+ */
public byte[] taggedEncode(TaggingOption taggingOption);
+
+ /**
+ * Tag and encode this type using the provided tagging option.
+ * @param taggingOption
+ * @return encoded bytes
+ */
public void taggedEncode(ByteBuffer buffer, TaggingOption taggingOption);
+
+ /**
+ * Decode the content bytes into this type as it's tagged with the provided
+ * tagging option.
+ *
+ * See {@link org.apache.kerby.asn1.TaggingOption}
+ *
+ * @param content
+ * @param taggingOption
+ * @throws IOException
+ */
public void taggedDecode(ByteBuffer content, TaggingOption taggingOption) throws IOException;
+
+ /**
+ * Decode the content bytes into this type as it's tagged with the provided
+ * tagging option.
+ *
+ * See {@link org.apache.kerby.asn1.TaggingOption}
+ *
+ * @param content
+ * @param taggingOption
+ * @throws IOException
+ */
public void taggedDecode(byte[] content, TaggingOption taggingOption) throws IOException;
}