Maven module :un.api : api-encoding :
Class : un.impl.io.base64.Base64
Extends/Implements : -
Subclasses : -

Encodes and decodes to and from Base64 notation.


Homepage: http://iharder.net/base64.



Example:



String encoded = Base64.encode( myByteArray );


byte[] myByteArray = Base64.decode( encoded );

The options parameter, which appears in a few places, is used to pass
several pieces of information to the encoder. In the "higher level" methods such as
encodeBytes( bytes, options ) the options parameter can be used to indicate such
things as first gzipping the bytes before encoding them, not inserting linefeeds,
and encoding using the URL-safe and Ordered dialects.



Note, according to RFC3548,
Section 2.1, implementations should not add line feeds unless explicitly told
to do so. I've got Base64 set to this behavior now, although earlier versions
broke lines by default.



The constants defined in Base64 can be OR-ed together to combine options, so you
might make a call like this:



String encoded = Base64.encodeBytes( mybytes, Base64.GZIP | Base64.DO_BREAK_LINES );

to compress the data before encoding it and then making the output have newline characters.


Also...


String encoded = Base64.encodeBytes( crazyString.getBytes() );


I am placing this code in the Public Domain. Do with it as you will.
This software comes with no guarantees or warranties but with
plenty of well-wishing instead!
Please visit http://iharder.net/base64
periodically to check for updates or to contribute improvements.



@author Robert Harder
@author rob@iharder.net
@version 2.3.7

Variables : NO_OPTIONS, ENCODE, DECODE, GZIP, DONT_GUNZIP, DO_BREAK_LINES, URL_SAFE, ORDERED
Functions : encode, encode, encodeBytes, encodeBytes, encodeBytes, encodeBytes, encodeBytesToBytes, encodeBytesToBytes, decode, decode, decode, decode


No options specified. Value is zero. */
public int NO_OPTIONS


Specify encoding in first bit. Value is one. */
public int ENCODE


Specify decoding in first bit. Value is zero. */
public int DECODE


Specify that data should be gzip-compressed in second bit. Value is two. */
public int GZIP


Specify that gzipped data should not be automatically gunzipped. */
public int DONT_GUNZIP


Do break lines when encoding. Value is 8. */
public int DO_BREAK_LINES


Encode using Base64-like encoding that is URL- and Filename-safe as described
in Section 4 of RFC3548:
http://www.faqs.org/rfcs/rfc3548.html.
It is important to note that data encoded this way is not officially valid Base64,
or at the very least should not be called Base64 without also specifying that is
was encoded using the URL- and Filename-safe dialect.
public int URL_SAFE


Encode using the special "ordered" dialect of Base64 described here:
http://www.faqs.org/qa/rfcc-1940.html.
public int ORDERED


Performs Base64 encoding on the raw ByteBuffer,
writing it to the encoded ByteBuffer.
This is an experimental feature. Currently it does not
pass along any options (such as {@link #DO_BREAK_LINES}
or {@link #GZIP}.
param  raw input buffer
param  encoded output buffer
since  2.3
public void encode (java.nio.ByteBuffer raw, java.nio.ByteBuffer encoded)


Performs Base64 encoding on the raw ByteBuffer,
writing it to the encoded CharBuffer.
This is an experimental feature. Currently it does not
pass along any options (such as {@link #DO_BREAK_LINES}
or {@link #GZIP}.
param  raw input buffer
param  encoded output buffer
since  2.3
public void encode (java.nio.ByteBuffer raw, java.nio.CharBuffer encoded)


Encodes a byte array into Base64 notation.
Does not GZip-compress data.
param  source The data to convert
return  The data in Base64-encoded form
throws  NullPointerException if source array is null
since  1.4
public String encodeBytes (byte[] source)


Encodes a byte array into Base64 notation.


Example options:


GZIP: gzip-compresses object before encoding it.

DO_BREAK_LINES: break lines at 76 characters

Note: Technically, this makes your encoding non-compliant.


Example: encodeBytes( myData, Base64.GZIP ) or


Example: encodeBytes( myData, Base64.GZIP | Base64.DO_BREAK_LINES )


As of v 2.3, if there is an error with the GZIP stream,
the method will throw an IOException. This is new to v2.3!
In earlier versions, it just returned a null value, but
in retrospect that's a pretty poor way to handle it.




@param source The data to convert
@param options Specified options
@return The Base64-encoded data as a String
@see Base64#GZIP
@see Base64#DO_BREAK_LINES
@throws IOException if there is an error
@throws NullPointerException if source array is null
@since 2.0
public String encodeBytes (byte[] source, int options)


Encodes a byte array into Base64 notation.
Does not GZip-compress data.

As of v 2.3, if there is an error,
the method will throw an IOException. This is new to v2.3!
In earlier versions, it just returned a null value, but
in retrospect that's a pretty poor way to handle it.




@param source The data to convert
@param off Offset in array where conversion should begin
@param len Length of data to convert
@return The Base64-encoded data as a String
@throws NullPointerException if source array is null
@throws IllegalArgumentException if source array, offset, or length are invalid
@since 1.4
public String encodeBytes (byte[] source, int off, int len)


Encodes a byte array into Base64 notation.


Example options:


GZIP: gzip-compresses object before encoding it.

DO_BREAK_LINES: break lines at 76 characters

Note: Technically, this makes your encoding non-compliant.


Example: encodeBytes( myData, Base64.GZIP ) or


Example: encodeBytes( myData, Base64.GZIP | Base64.DO_BREAK_LINES )


As of v 2.3, if there is an error with the GZIP stream,
the method will throw an IOException. This is new to v2.3!
In earlier versions, it just returned a null value, but
in retrospect that's a pretty poor way to handle it.




@param source The data to convert
@param off Offset in array where conversion should begin
@param len Length of data to convert
@param options Specified options
@return The Base64-encoded data as a String
@see Base64#GZIP
@see Base64#DO_BREAK_LINES
@throws IOException if there is an error
@throws NullPointerException if source array is null
@throws IllegalArgumentException if source array, offset, or length are invalid
@since 2.0
public String encodeBytes (byte[] source, int off, int len, int options)


Similar to {@link #encodeBytes(byte[])} but returns
a byte array instead of instantiating a String. This is more efficient
if you're working with I/O streams and have large data sets to encode.
param  source The data to convert
return  The Base64-encoded data as a byte[] (of ASCII characters)
throws  NullPointerException if source array is null
since  2.3.1
public byte[] encodeBytesToBytes (byte[] source)


Similar to {@link #encodeBytes(byte[], int, int, int)} but returns
a byte array instead of instantiating a String. This is more efficient
if you're working with I/O streams and have large data sets to encode.
param  source The data to convert
param  off Offset in array where conversion should begin
param  len Length of data to convert
param  options Specified options
return  The Base64-encoded data as a String
see  Base64#GZIP
see  Base64#DO_BREAK_LINES
throws  IOException if there is an error
throws  NullPointerException if source array is null
throws  IllegalArgumentException if source array, offset, or length are invalid
since  2.3.1
public byte[] encodeBytesToBytes (byte[] source, int off, int len, int options)


Low-level access to decoding ASCII characters in
the form of a byte array. Ignores GUNZIP option, if
it's set. This is not generally a recommended method,
although it is used internally as part of the decoding process.
Special case: if len = 0, an empty array is returned. Still,
if you need more speed and reduced memory footprint (and aren't
gzipping), consider this method.

@param source The Base64 encoded data
@return decoded data
@since 2.3.1
public byte[] decode (byte[] source)


Low-level access to decoding ASCII characters in
the form of a byte array. Ignores GUNZIP option, if
it's set. This is not generally a recommended method,
although it is used internally as part of the decoding process.
Special case: if len = 0, an empty array is returned. Still,
if you need more speed and reduced memory footprint (and aren't
gzipping), consider this method.

@param source The Base64 encoded data
@param off The offset of where to begin decoding
@param len The length of characters to decode
@param options Can specify options such as alphabet type to use
@return decoded data
@throws IOException If bogus characters exist in source data
@since 1.3
public byte[] decode (byte[] source, int off, int len, int options)


Decodes data from Base64 notation, automatically
detecting gzip-compressed data and decompressing it.
param  s the string to decode
return  the decoded data
throws  IOException If there is a problem
since  1.4
public byte[] decode (String s)


Decodes data from Base64 notation, automatically
detecting gzip-compressed data and decompressing it.
param  s the string to decode
param  options encode options such as URL_SAFE
return  the decoded data
throws  IOException if there is an error
throws  NullPointerException if s is null
since  1.4
public byte[] decode (String s, int options)