Package com.fasterxml.jackson.core

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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Base64Variant.PaddingReadBehaviour
      Defines how the Base64Variant deals with Padding while reading

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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).

    • Constructor Summary

      Constructors 
      Constructor Description
      Base64Variant​(Base64Variant base, java.lang.String name, boolean writePadding, 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 writePadding, char paddingChar, int maxLineLength)  

    • Field Detail

      • 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

    • Constructor Detail

      • Base64Variant

        public Base64Variant​(java.lang.String name,
                     java.lang.String base64Alphabet,
                     boolean writePadding,
                     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).
        Parameters:
        base - Variant to use for settings not specific by other parameters
        name - Name of this variant
        maxLineLength - Maximum length (in characters) of lines to output before using linefeed

      • Base64Variant

        public Base64Variant​(Base64Variant base,
                     java.lang.String name,
                     boolean writePadding,
                     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
        Parameters:
        base - Variant to use for settings not specific by other parameters
        name - Name of this variant
        writePadding - Whether variant will use padding when encoding
        paddingChar - Padding character used for encoding, excepted on reading, if any
        maxLineLength - Maximum length (in characters) of lines to output before using linefeed

    • Method Detail

      • withPaddingAllowed

        public Base64Variant withPaddingAllowed()
        Returns:
        Base64Variant which does not require padding on read
        Since:
        2.12

      • withPaddingRequired

        public Base64Variant withPaddingRequired()
        Returns:
        Base64Variant which requires padding on read
        Since:
        2.12

      • withPaddingForbidden

        public Base64Variant withPaddingForbidden()
        Returns:
        Base64Variant which does not accept padding on read
        Since:
        2.12

      • withReadPadding

        public Base64Variant withReadPadding​(Base64Variant.PaddingReadBehaviour readPadding)
        Parameters:
        readPadding - Padding read behavior desired
        Returns:
        Instance with desired padding read behavior setting (this if already has setting; new instance otherwise)
        Since:
        2.12

      • withWritePadding

        public Base64Variant withWritePadding​(boolean writePadding)
        Parameters:
        writePadding - Determines if padding is output on write or not
        Returns:
        Base64Variant which writes padding or not depending on writePadding
        Since:
        2.12

      • getName

        public java.lang.String getName()

      • usesPadding

        public boolean usesPadding()
        Returns:
        True if this Base64 encoding will write padding on output (note: before Jackson 2.12 also dictated whether padding was accepted on read)

      • requiresPaddingOnRead

        public boolean requiresPaddingOnRead()
        Returns:
        True if this variant requires padding on content decoded; false if not.
        Since:
        2.12

      • acceptsPaddingOnRead

        public boolean acceptsPaddingOnRead()
        Returns:
        True if this variant accepts padding on content decoded; false if not.
        Since:
        2.12

      • usesPaddingChar

        public boolean usesPaddingChar​(char c)

      • usesPaddingChar

        public boolean usesPaddingChar​(int ch)

      • paddingReadBehaviour

        public Base64Variant.PaddingReadBehaviour paddingReadBehaviour()
        Returns:
        Indicator on how this Base64 encoding will handle possible padding in content when reading.
        Since:
        2.12

      • getPaddingChar

        public char getPaddingChar()

      • getPaddingByte

        public byte getPaddingByte()

      • getMaxLineLength

        public int getMaxLineLength()

      • decodeBase64Char

        public int decodeBase64Char​(char c)
        Parameters:
        c - Character to decode
        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 outPtr)
        Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 characters, stored in given result buffer. Caller must ensure there is sufficient space for 4 encoded characters at specified position.
        Parameters:
        b24 - 3-byte value to encode
        buffer - Output buffer to append characters to
        outPtr - Starting position within buffer to append encoded characters
        Returns:
        Pointer in output buffer after appending 4 encoded characters

      • 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:
        bits - 24-bit chunk containing 1 or 2 bytes to encode
        outputBytes - Number of input bytes to encode (either 1 or 2)
        buffer - Output buffer to append characters to
        outPtr - Starting position within buffer to append encoded characters
        Returns:
        Pointer in output buffer after appending encoded characters (2, 3 or 4)

      • 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 outPtr)
        Method that encodes given right-aligned (LSB) 24-bit value into 4 base64 bytes (ascii), stored in given result buffer.
        Parameters:
        b24 - 3-byte value to encode
        buffer - Output buffer to append characters (as bytes) to
        outPtr - Starting position within buffer to append encoded characters
        Returns:
        Pointer in output buffer after appending 4 encoded characters

      • 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:
        bits - 24-bit chunk containing 1 or 2 bytes to encode
        outputBytes - Number of input bytes to encode (either 1 or 2)
        buffer - Output buffer to append characters to
        outPtr - Starting position within buffer to append encoded characters
        Returns:
        Pointer in output buffer after appending encoded characters (2, 3 or 4)

      • 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
        Returns:
        Base64 encoded String of encoded input bytes, not surrounded by quotes

      • 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
        Returns:
        Base64 encoded String of encoded input bytes, possibly surrounded by quotes (if addQuotes enabled)

      • 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
        linefeed - Linefeed to use for encoded content
        Returns:
        Base64 encoded String of encoded input bytes
        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 - Base64-encoded input String to decode
        Returns:
        Byte array of decoded contents
        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.

        Parameters:
        str - Input to decode
        builder - Builder used for assembling decoded content
        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

      • 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.
        Returns:
        Exception message for indicating "missing padding" case
        Since:
        2.10