directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dran...@apache.org
Subject directory-kerberos git commit: Added some javadoc in kerby-asn1 module
Date Sun, 01 Feb 2015 01:26:30 GMT
Repository: directory-kerberos
Updated Branches:
  refs/heads/master 66a3df64e -> 0228e16db


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/master
Commit: 0228e16db4c3e102f530d0375b945f99c1a0a6a6
Parents: 66a3df6
Author: Drankye <drankye@gmail.com>
Authored: Sun Feb 1 09:26:00 2015 +0800
Committer: Drankye <drankye@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;
 }


Mime
View raw message