commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tobr...@apache.org
Subject cvs commit: jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/binary Base64.java
Date Mon, 24 Feb 2003 11:53:29 GMT
tobrien     2003/02/24 03:53:29

  Modified:    codec/src/java/org/apache/commons/codec BinaryDecoder.java
                        BinaryEncoder.java Decoder.java
                        DecoderException.java Encoder.java
                        EncoderException.java StringEncoder.java
                        StringEncoderComparator.java
               codec/src/java/org/apache/commons/codec/binary Base64.java
  Log:
  Added javadoc
  
  Revision  Changes    Path
  1.2       +22 -3     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/BinaryDecoder.java
  
  Index: BinaryDecoder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/BinaryDecoder.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- BinaryDecoder.java	16 Feb 2003 19:04:42 -0000	1.1
  +++ BinaryDecoder.java	24 Feb 2003 11:53:28 -0000	1.2
  @@ -53,11 +53,30 @@
    */
   package org.apache.commons.codec;
   
  +
  +
   /**
  - * @author tobrien@transolutions.net
  + * This interface defines common decoding methods for decoders
  + * which decode byte arrays.
  + *
  + * @author <a href="mailto:tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public interface BinaryDecoder extends Decoder {
  -    byte[] decode(byte[] pArray) throws DecoderException;
  +
  +    /**
  +     * Decode a byte array and return the results of the decode
  +     * as a byte array. 
  +     *
  +     * @param pArray A byte array which has been encoded with the
  +     *      appropriate encoder
  +     * 
  +     * @return a byte array that contains decoded content
  +     * 
  +     * @throws DecoderException A decoder exception is thrown
  +     *          if a Decoder encounters a failure condition during
  +     *          the decode process.
  +     */
  +    public byte[] decode(byte[] pArray) throws DecoderException;
   }  
   
  
  
  
  1.2       +18 -2     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/BinaryEncoder.java
  
  Index: BinaryEncoder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/BinaryEncoder.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- BinaryEncoder.java	16 Feb 2003 19:04:03 -0000	1.1
  +++ BinaryEncoder.java	24 Feb 2003 11:53:28 -0000	1.2
  @@ -54,10 +54,26 @@
   package org.apache.commons.codec;
   
   /**
  - * @author tobrien@transolutions.net
  + * A binary encoder contains methods common to all
  + * encoders for binary data. 
  + * 
  + * @author <a href="tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public interface BinaryEncoder extends Encoder {
  +    
  +    /**
  +     * Encode a byte array and return the encoded data
  +     * as a byte array.
  +     * 
  +     * @param pArray Data to be encoded
  +     *
  +     * @return A byte array containing the encoded data
  +     * 
  +     * @throws EncoderException thrown if the Encoder
  +     *      encounters a failure condition during the
  +     *      encoding process.
  +     */
       byte[] encode(byte[] pArray) throws EncoderException;
   }  
   
  
  
  
  1.2       +26 -2     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/Decoder.java
  
  Index: Decoder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/Decoder.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Decoder.java	16 Feb 2003 19:04:03 -0000	1.1
  +++ Decoder.java	24 Feb 2003 11:53:28 -0000	1.2
  @@ -54,10 +54,34 @@
   package org.apache.commons.codec;
   
   /**
  - * @author tobrien@transolutions.net
  + * Forms one of the two interfaces at the center of the
  + * codec package.  All decoders implement this interface
  + * which allows a user to pass a generic Object to any
  + * Decoder implementation in the codec package.
  + * 
  + * @author <a href="tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public interface Decoder {
  +
  +    /**
  +     * Decode an "encoded" Object and return a "decoded"
  +     * Object.  Note that the implementation of this
  +     * interface will try to cast the Object parameter
  +     * to the specific type expected by a particular Decoder
  +     * implementation.  If a ClassCastException occurs
  +     * this decode method will throw a DecoderException.
  +     * 
  +     * @param pObject an object to "decode"
  +     * 
  +     * @return a 'decoded" object
  +     * 
  +     * @throws DecoderException a decoder exception can
  +     * be thrown for any number of reasons.  Some good
  +     * candidates are that the parameter passed to this
  +     * method is null, a param cannot be cast to the
  +     * appropriate type for a specific encoder.
  +     */
       Object decode(Object pObject) throws DecoderException;
   }  
   
  
  
  
  1.2       +11 -3     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/DecoderException.java
  
  Index: DecoderException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/DecoderException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- DecoderException.java	16 Feb 2003 19:04:03 -0000	1.1
  +++ DecoderException.java	24 Feb 2003 11:53:28 -0000	1.2
  @@ -54,13 +54,21 @@
   package org.apache.commons.codec;
   
   /**
  - * @author tobrien@transolutions.net
  + * The DecoderException is thrown when a Decoder has
  + * encounter a failure condition during a decode. 
  + * 
  + * @author <a href="tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public class DecoderException extends Exception {
   
  +    /**
  +     * Create a DecoderException
  +     * 
  +     * @param pMessage A message with meaning to a human
  +     */
       public DecoderException(String pMessage) {
  -	super( pMessage );
  +	       super( pMessage );
       }
   
   }  
  
  
  
  1.6       +21 -4     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/Encoder.java
  
  Index: Encoder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/Encoder.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- Encoder.java	16 Feb 2003 19:04:03 -0000	1.5
  +++ Encoder.java	24 Feb 2003 11:53:28 -0000	1.6
  @@ -54,13 +54,30 @@
   package org.apache.commons.codec;
   
   /**
  - * Encoder is an interface, which is implemented by Soundex,
  - * Metaphone, Soundex2, etc.
  + * Encoder is the sister interface of Decoder, it provides
  + * the highest level of abstraction for Encoders.  All
  + * Encoders implement this common generic interface.
    *
  - * @author tobrien@transolutions.net
  + * @author <a href="tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public interface Encoder {
  +    
  +    /**
  +     * All encoders allow a library-user to pass an 
  +     * Object and get an Object in return.  This function
  +     * encodes an "Object" - returning the encoded content 
  +     * as an Object.  The Objects here may just be byte[]
  +     * or Strings depending on the implementation used.
  +     *   
  +     * @param pObject An object ot encode
  +     * 
  +     * @return An "encoded" Object
  +     * 
  +     * @throws EncoderException an encoder exception is
  +     *  thrown if the encoder experiences a failure
  +     *  condition during the encoding process.
  +     */
       Object encode(Object pObject) throws EncoderException;
   }  
   
  
  
  
  1.2       +12 -4     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/EncoderException.java
  
  Index: EncoderException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/EncoderException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- EncoderException.java	16 Feb 2003 19:04:03 -0000	1.1
  +++ EncoderException.java	24 Feb 2003 11:53:29 -0000	1.2
  @@ -54,14 +54,22 @@
   package org.apache.commons.codec;
   
   /**
  - * @author tobrien@transolutions.net
  + * An EncoderException is thrown when there is a
  + * failure condition during the encoding process.
  + * 
  + * @author <a href="tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public class EncoderException extends Exception {
   
  +    /**
  +     * Create a new instance of this exception with
  +     * an informative message.
  +     * 
  +     * @param pMessage a human intelligible message
  +     */
       public EncoderException(String pMessage) {
  -	super( pMessage );
  +	   super( pMessage );
       }
  -
   }  
   
  
  
  
  1.2       +15 -3     jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/StringEncoder.java
  
  Index: StringEncoder.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/StringEncoder.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- StringEncoder.java	16 Feb 2003 19:04:03 -0000	1.1
  +++ StringEncoder.java	24 Feb 2003 11:53:29 -0000	1.2
  @@ -54,13 +54,25 @@
   package org.apache.commons.codec;
   
   /**
  - * Encoder is an interface, which is implemented by Soundex,
  - * Metaphone, Soundex2, etc.
  + * A StringEncoder is an encoder which expects a String as
  + * a method parameter and one that produces a String as the
  + * output of the Encoding process.
    *
    * @author tobrien@transolutions.net
    * @version $Revision$ $Date$
    */
   public interface StringEncoder extends Encoder {
  +    
  +    /**
  +     * Encode a String and produce a String.
  +     * 
  +     * @param pString a String to encode
  +     * 
  +     * @return the encoded String
  +     * 
  +     * @throws EncoderException thrown if there is
  +     *  an error conidition during the Encoding process.
  +     */
       String encode(String pString) throws EncoderException;
   }  
   
  
  
  
  1.2       +32 -15    jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/StringEncoderComparator.java
  
  Index: StringEncoderComparator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/StringEncoderComparator.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- StringEncoderComparator.java	17 Feb 2003 16:52:31 -0000	1.1
  +++ StringEncoderComparator.java	24 Feb 2003 11:53:29 -0000	1.2
  @@ -56,16 +56,27 @@
   import java.util.Comparator;
   
   /**
  - * Compare using an Encoder.
  + * String are comparable, and this comparator allows 
  + * you to configure it with an instance of a class
  + * which implements the StringEncoder.  This comparator
  + * is used to sort Strings by an encoding shceme such
  + * as Soundex, Metaphone, etc.  This class can come in
  + * handy if one need to sort Strings by an encoded
  + * form of a name such as Soundex.
    *
  - * @author tobrien@transolutions.net
  + * @author <a href="mailto:tobrien@apache.org">Tim O'Brien</a>
    * @version $Revision$ $Date$
    */
   public class StringEncoderComparator implements Comparator {
   
  +    // Private encoder instance
       private StringEncoder stringEncoder;
   
  -    public StringEncoderComparator() {}
  +    /**
  +     * A no-arg, do-nothing constructor
  +     */
  +    public StringEncoderComparator() {
  +    }
   
       /**
        * Use the provided soundex algorithm.
  @@ -74,19 +85,25 @@
           this.stringEncoder = en;
       }
   
  +    /**
  +     * Compare 2 strings based not on the strings 
  +     * themselves, but on an encoding of the two 
  +     * strings using the StringEncoder this Comparator
  +     * was created with.
  +     */
  + 
       public int compare(Object o1, Object o2) {
  -	
  -	int compareCode = 0;
   
  -	try {
  -	    String s1 = stringEncoder.encode(o1.toString());
  -	    String s2 = stringEncoder.encode(o2.toString());
  -	    compareCode = s1.compareTo(s2);
  -	} catch( EncoderException ee ) {
  -	    compareCode = 0;
  -	}
  -        return(compareCode);
  +        int compareCode = 0;
  +
  +        try {
  +            String s1 = stringEncoder.encode(o1.toString());
  +            String s2 = stringEncoder.encode(o2.toString());
  +            compareCode = s1.compareTo(s2);
  +        } catch (EncoderException ee) {
  +            compareCode = 0;
  +        }
  +        return (compareCode);
       }
   
   }
  -
  
  
  
  1.4       +4 -4      jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/binary/Base64.java
  
  Index: Base64.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/codec/src/java/org/apache/commons/codec/binary/Base64.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- Base64.java	16 Feb 2003 19:04:03 -0000	1.3
  +++ Base64.java	24 Feb 2003 11:53:29 -0000	1.4
  @@ -66,7 +66,7 @@
   import java.util.Enumeration;
   import java.util.Vector;
   
  -import org.apache.commons.codec.BinaryDecoder;
  +import org.apache.commons.codec.*;
   import org.apache.commons.codec.BinaryEncoder;
   import org.apache.commons.codec.DecoderException;
   import org.apache.commons.codec.EncoderException;
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message