Class Base64Variant

  • All Implemented Interfaces:
    java.io.Serializable

    public final class Base64Variant
    extends java.lang.Object
    implements java.io.Serializable
    Class used to define specific details of which variant of Base64 encoding/decoding is to be used. Although there is somewhat standard basic version (so-called "MIME Base64"), other variants exists, see Base64 Wikipedia entry for details.
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int[] _asciiToBase64
      Decoding table used for base 64 decoding.
      private byte[] _base64ToAsciiB
      Alternative encoding table used for base 64 decoding when output is done as ascii bytes.
      private char[] _base64ToAsciiC
      Encoding table used for base 64 decoding when output is done as characters.
      private int _maxLineLength
      Maximum number of encoded base64 characters to output during encoding before adding a linefeed, if line length is to be limited (Integer.MAX_VALUE if not limited).
      (package private) java.lang.String _name
      Symbolic name of variant; used for diagnostics/debugging.
      private char _paddingChar
      Character used for padding, if any (PADDING_CHAR_NONE if not).
      private boolean _usesPadding
      Whether this variant uses padding or not.
      static int BASE64_VALUE_INVALID
      Marker used to denote ascii characters that do not correspond to a 6-bit value (in this variant), and is not used as a padding character.
      static int BASE64_VALUE_PADDING
      Marker used to denote ascii character (in decoding table) that is the padding character using this variant (if any).
      private static int INT_SPACE  
      (package private) static char PADDING_CHAR_NONE
      Placeholder used by "no padding" variant, to be used when a character value is needed.
      private static long serialVersionUID  
    • Constructor Summary

      Constructors 
      Constructor Description
      Base64Variant​(Base64Variant base, java.lang.String name, boolean usesPadding, char paddingChar, int maxLineLength)
      "Copy constructor" that can be used when the base alphabet is identical to one used by another variant, but other details (padding, maximum line length) differ
      Base64Variant​(Base64Variant base, java.lang.String name, int maxLineLength)
      "Copy constructor" that can be used when the base alphabet is identical to one used by another variant except for the maximum line length (and obviously, name).
      Base64Variant​(java.lang.String name, java.lang.String base64Alphabet, boolean usesPadding, char paddingChar, int maxLineLength)  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void _reportBase64EOF()  
      protected void _reportInvalidBase64​(char ch, int bindex, java.lang.String msg)  
      byte[] decode​(java.lang.String input)
      Convenience method for decoding contents of a Base64-encoded String, using this variant's settings.
      void decode​(java.lang.String str, ByteArrayBuilder builder)
      Convenience method for decoding contents of a Base64-encoded String, using this variant's settings and appending decoded binary data using provided ByteArrayBuilder.
      int decodeBase64Byte​(byte b)  
      int decodeBase64Char​(char c)  
      int decodeBase64Char​(int ch)  
      java.lang.String encode​(byte[] input)
      Convenience method for converting given byte array as base64 encoded String using this variant's settings.
      java.lang.String encode​(byte[] input, boolean addQuotes)
      Convenience method for converting given byte array as base64 encoded String using this variant's settings, optionally enclosed in double-quotes.
      java.lang.String encode​(byte[] input, boolean addQuotes, java.lang.String linefeed)
      Convenience method for converting given byte array as base64 encoded String using this variant's settings, optionally enclosed in double-quotes.
      byte encodeBase64BitsAsByte​(int value)  
      char encodeBase64BitsAsChar​(int value)  
      int encodeBase64Chunk​(int b24, byte[] buffer, int ptr)
      Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 bytes (ascii), stored in given result buffer.
      int encodeBase64Chunk​(int b24, char[] buffer, int ptr)
      Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 characters, stored in given result buffer.
      void encodeBase64Chunk​(java.lang.StringBuilder sb, int b24)  
      int encodeBase64Partial​(int bits, int outputBytes, byte[] buffer, int outPtr)
      Method that outputs partial chunk (which only encodes one or two bytes of data).
      int encodeBase64Partial​(int bits, int outputBytes, char[] buffer, int outPtr)
      Method that outputs partial chunk (which only encodes one or two bytes of data).
      void encodeBase64Partial​(java.lang.StringBuilder sb, int bits, int outputBytes)  
      boolean equals​(java.lang.Object o)  
      int getMaxLineLength()  
      java.lang.String getName()  
      byte getPaddingByte()  
      char getPaddingChar()  
      int hashCode()  
      java.lang.String missingPaddingMessage()
      Helper method that will construct a message to use in exceptions for cases where input ends prematurely in place where padding would be expected.
      protected java.lang.Object readResolve()
      Method used to "demote" deserialized instances back to canonical ones
      java.lang.String toString()  
      boolean usesPadding()  
      boolean usesPaddingChar​(char c)  
      boolean usesPaddingChar​(int ch)  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • PADDING_CHAR_NONE

        static final char PADDING_CHAR_NONE
        Placeholder used by "no padding" variant, to be used when a character value is needed.
        See Also:
        Constant Field Values
      • BASE64_VALUE_INVALID

        public static final int BASE64_VALUE_INVALID
        Marker used to denote ascii characters that do not correspond to a 6-bit value (in this variant), and is not used as a padding character.
        See Also:
        Constant Field Values
      • BASE64_VALUE_PADDING

        public static final int BASE64_VALUE_PADDING
        Marker used to denote ascii character (in decoding table) that is the padding character using this variant (if any).
        See Also:
        Constant Field Values
      • _asciiToBase64

        private final transient int[] _asciiToBase64
        Decoding table used for base 64 decoding.
      • _base64ToAsciiC

        private final transient char[] _base64ToAsciiC
        Encoding table used for base 64 decoding when output is done as characters.
      • _base64ToAsciiB

        private final transient byte[] _base64ToAsciiB
        Alternative encoding table used for base 64 decoding when output is done as ascii bytes.
      • _name

        final java.lang.String _name
        Symbolic name of variant; used for diagnostics/debugging.

        Note that this is the only non-transient field; used when reading back from serialized state.

        Also: must not be private, accessed from `BaseVariants`

      • _usesPadding

        private final transient boolean _usesPadding
        Whether this variant uses padding or not.
      • _paddingChar

        private final transient char _paddingChar
        Character used for padding, if any (PADDING_CHAR_NONE if not).
      • _maxLineLength

        private final transient int _maxLineLength
        Maximum number of encoded base64 characters to output during encoding before adding a linefeed, if line length is to be limited (Integer.MAX_VALUE if not limited).

        Note: for some output modes (when writing attributes) linefeeds may need to be avoided, and this value ignored.

    • Constructor Detail

      • Base64Variant

        public Base64Variant​(java.lang.String name,
                             java.lang.String base64Alphabet,
                             boolean usesPadding,
                             char paddingChar,
                             int maxLineLength)
      • Base64Variant

        public Base64Variant​(Base64Variant base,
                             java.lang.String name,
                             int maxLineLength)
        "Copy constructor" that can be used when the base alphabet is identical to one used by another variant except for the maximum line length (and obviously, name).
      • Base64Variant

        public Base64Variant​(Base64Variant base,
                             java.lang.String name,
                             boolean usesPadding,
                             char paddingChar,
                             int maxLineLength)
        "Copy constructor" that can be used when the base alphabet is identical to one used by another variant, but other details (padding, maximum line length) differ
    • Method Detail

      • readResolve

        protected java.lang.Object readResolve()
        Method used to "demote" deserialized instances back to canonical ones
      • getName

        public java.lang.String getName()
      • usesPadding

        public boolean usesPadding()
      • usesPaddingChar

        public boolean usesPaddingChar​(char c)
      • usesPaddingChar

        public boolean usesPaddingChar​(int ch)
      • getPaddingChar

        public char getPaddingChar()
      • getPaddingByte

        public byte getPaddingByte()
      • getMaxLineLength

        public int getMaxLineLength()
      • decodeBase64Char

        public int decodeBase64Char​(char c)
        Returns:
        6-bit decoded value, if valid character;
      • decodeBase64Char

        public int decodeBase64Char​(int ch)
      • decodeBase64Byte

        public int decodeBase64Byte​(byte b)
      • encodeBase64BitsAsChar

        public char encodeBase64BitsAsChar​(int value)
      • encodeBase64Chunk

        public int encodeBase64Chunk​(int b24,
                                     char[] buffer,
                                     int ptr)
        Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 characters, stored in given result buffer.
      • encodeBase64Chunk

        public void encodeBase64Chunk​(java.lang.StringBuilder sb,
                                      int b24)
      • encodeBase64Partial

        public int encodeBase64Partial​(int bits,
                                       int outputBytes,
                                       char[] buffer,
                                       int outPtr)
        Method that outputs partial chunk (which only encodes one or two bytes of data). Data given is still aligned same as if it as full data; that is, missing data is at the "right end" (LSB) of int.
        Parameters:
        outputBytes - Number of encoded bytes included (either 1 or 2)
      • encodeBase64Partial

        public void encodeBase64Partial​(java.lang.StringBuilder sb,
                                        int bits,
                                        int outputBytes)
      • encodeBase64BitsAsByte

        public byte encodeBase64BitsAsByte​(int value)
      • encodeBase64Chunk

        public int encodeBase64Chunk​(int b24,
                                     byte[] buffer,
                                     int ptr)
        Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 bytes (ascii), stored in given result buffer.
      • encodeBase64Partial

        public int encodeBase64Partial​(int bits,
                                       int outputBytes,
                                       byte[] buffer,
                                       int outPtr)
        Method that outputs partial chunk (which only encodes one or two bytes of data). Data given is still aligned same as if it as full data; that is, missing data is at the "right end" (LSB) of int.
        Parameters:
        outputBytes - Number of encoded bytes included (either 1 or 2)
      • encode

        public java.lang.String encode​(byte[] input)
        Convenience method for converting given byte array as base64 encoded String using this variant's settings. Resulting value is "raw", that is, not enclosed in double-quotes.
        Parameters:
        input - Byte array to encode
      • encode

        public java.lang.String encode​(byte[] input,
                                       boolean addQuotes)
        Convenience method for converting given byte array as base64 encoded String using this variant's settings, optionally enclosed in double-quotes. Linefeeds added, if needed, are expressed as 2-character JSON (and Java source) escape sequence of backslash + `n`.
        Parameters:
        input - Byte array to encode
        addQuotes - Whether to surround resulting value in double quotes or not
      • encode

        public java.lang.String encode​(byte[] input,
                                       boolean addQuotes,
                                       java.lang.String linefeed)
        Convenience method for converting given byte array as base64 encoded String using this variant's settings, optionally enclosed in double-quotes. Linefeed character to use is passed explicitly.
        Parameters:
        input - Byte array to encode
        addQuotes - Whether to surround resulting value in double quotes or not
        Since:
        2.10
      • decode

        public byte[] decode​(java.lang.String input)
                      throws java.lang.IllegalArgumentException
        Convenience method for decoding contents of a Base64-encoded String, using this variant's settings.
        Parameters:
        input -
        Throws:
        java.lang.IllegalArgumentException - if input is not valid base64 encoded data
        Since:
        2.3
      • decode

        public void decode​(java.lang.String str,
                           ByteArrayBuilder builder)
                    throws java.lang.IllegalArgumentException
        Convenience method for decoding contents of a Base64-encoded String, using this variant's settings and appending decoded binary data using provided ByteArrayBuilder.

        NOTE: builder will NOT be reset before decoding (nor cleared afterwards); assumption is that caller will ensure it is given in proper state, and used as appropriate afterwards.

        Throws:
        java.lang.IllegalArgumentException - if input is not valid base64 encoded data
        Since:
        2.3
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • _reportInvalidBase64

        protected void _reportInvalidBase64​(char ch,
                                            int bindex,
                                            java.lang.String msg)
                                     throws java.lang.IllegalArgumentException
        Parameters:
        bindex - Relative index within base64 character unit; between 0 and 3 (as unit has exactly 4 characters)
        Throws:
        java.lang.IllegalArgumentException
      • _reportBase64EOF

        protected void _reportBase64EOF()
                                 throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException
      • missingPaddingMessage

        public java.lang.String missingPaddingMessage()
        Helper method that will construct a message to use in exceptions for cases where input ends prematurely in place where padding would be expected.
        Since:
        2.10