+ *
Uses "The Base64 Alphabet" as specified in Table 1 of + * RFC 4648 and RFC 2045 for encoding and decoding operation. + * The encoder does not add any line feed (line separator) + * character. The decoder rejects data that contains characters + * outside the base64 alphabet.
Uses the "URL and Filename safe Base64 Alphabet" as specified + * in Table 2 of RFC 4648 for encoding and decoding. The + * encoder does not add any line feed (line separator) character. + * The decoder rejects data that contains characters outside the + * base64 alphabet.
Uses the "The Base64 Alphabet" as specified in Table 1 of + * RFC 2045 for encoding and decoding operation. The encoded output + * must be represented in lines of no more than 76 characters each + * and uses a carriage return {@code '\r'} followed immediately by + * a linefeed {@code '\n'} as the line separator. All line separators + * or other characters not found in the base64 alphabet table are + * ignored in decoding operation.
Unless otherwise noted, passing a {@code null} argument to a + * method of this class will cause a {@link java.lang.NullPointerException + * NullPointerException} to be thrown. + * + * @author Xueming Shen + * @since 1.8 + */ + +public class Base64 { + + private Base64() {} + + /** + * Returns a {@link Encoder} that encodes using the + * Basic type base64 encoding scheme. + * + * @return A Base64 encoder. + */ + public static Encoder getEncoder() { + return Encoder.RFC4648; + } + + /** + * Returns a {@link Encoder} that encodes using the + * URL and Filename safe type base64 + * encoding scheme. + * + * @return A Base64 encoder. + */ + public static Encoder getUrlEncoder() { + return Encoder.RFC4648_URLSAFE; + } + + /** + * Returns a {@link Encoder} that encodes using the + * MIME type base64 encoding scheme. + * + * @return A Base64 encoder. + */ + public static Encoder getMimeEncoder() { + return Encoder.RFC2045; + } + + /** + * Returns a {@link Encoder} that encodes using the + * MIME type base64 encoding scheme + * with specified line length and line separators. + * + * @param lineLength + * the length of each output line (rounded down to nearest multiple + * of 4). If {@code lineLength <= 0} the output will not be separated + * in lines + * @param lineSeparator + * the line separator for each output line + * + * @return A Base64 encoder. + * + * @throws IllegalArgumentException if {@code lineSeparator} includes any + * character of "The Base64 Alphabet" as specified in Table 1 of + * RFC 2045. + */ + public static Encoder getEncoder(int lineLength, byte[] lineSeparator) { + Objects.requireNonNull(lineSeparator); + int[] base64 = Decoder.fromBase64; + for (byte b : lineSeparator) { + if (base64[b & 0xff] != -1) + throw new IllegalArgumentException( + "Illegal base64 line separator character 0x" + Integer.toString(b, 16)); + } + return new Encoder(false, lineSeparator, lineLength >> 2 << 2); + } + + /** + * Returns a {@link Decoder} that decodes using the + * Basic type base64 encoding scheme. + * + * @return A Base64 decoder. + */ + public static Decoder getDecoder() { + return Decoder.RFC4648; + } + + /** + * Returns a {@link Decoder} that decodes using the + * URL and Filename safe type base64 + * encoding scheme. + * + * @return A Base64 decoder. + */ + public static Decoder getUrlDecoder() { + return Decoder.RFC4648_URLSAFE; + } + + /** + * Returns a {@link Decoder} that decodes using the + * MIME type base64 decoding scheme. + * + * @return A Base64 decoder. + */ + public static Decoder getMimeDecoder() { + return Decoder.RFC2045; + } + + /** + * This class implements an encoder for encoding byte data using + * the Base64 encoding scheme as specified in RFC 4648 and RFC 2045. + * + *
Instances of {@link Encoder} class are safe for use by + * multiple concurrent threads. + * + *
Unless otherwise noted, passing a {@code null} argument to + * a method of this class will cause a + * {@link java.lang.NullPointerException NullPointerException} to + * be thrown. + * + * @see Decoder + * @since 1.8 + */ + public static class Encoder { + + private final byte[] newline; + private final int linemax; + private final boolean isURL; + + private Encoder(boolean isURL, byte[] newline, int linemax) { + this.isURL = isURL; + this.newline = newline; + this.linemax = linemax; + } + + /** + * This array is a lookup table that translates 6-bit positive integer + * index values into their "Base64 Alphabet" equivalents as specified + * in "Table 1: The Base64 Alphabet" of RFC 2045 (and RFC 4648). + */ + private static final char[] toBase64 = { + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', + 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', + 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', + 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', + '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' + }; + + /** + * It's the lookup table for "URL and Filename safe Base64" as specified + * in Table 2 of the RFC 4648, with the '+' and '/' changed to '-' and + * '_'. This table is used when BASE64_URL is specified. + */ + private static final char[] toBase64URL = { + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', + 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', + 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', + 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', + '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '_' + }; + + private static final int MIMELINEMAX = 76; + private static final byte[] CRLF = new byte[] {'\r', '\n'}; + + static final Encoder RFC4648 = new Encoder(false, null, -1); + static final Encoder RFC4648_URLSAFE = new Encoder(true, null, -1); + static final Encoder RFC2045 = new Encoder(false, CRLF, MIMELINEMAX); + + /** + * Encodes all bytes from the specified byte array into a newly-allocated + * byte array using the {@link Base64} encoding scheme. The returned byte + * array is of the length of the resulting bytes. + * + * @param src + * the byte array to encode + * @return A newly-allocated byte array containing the resulting + * encoded bytes. + */ + public byte[] encode(byte[] src) { + int len = 4 * ((src.length + 2) / 3); // dst array size + if (linemax > 0) // line separators + len += (len - 1) / linemax * newline.length; + byte[] dst = new byte[len]; + int ret = encode0(src, 0, src.length, dst); + if (ret != dst.length) + return Arrays.copyOf(dst, ret); + return dst; + } + + /** + * Encodes all bytes from the specified byte array using the + * {@link Base64} encoding scheme, writing the resulting bytes to the + * given output byte array, starting at offset 0. + * + *
It is the responsibility of the invoker of this method to make + * sure the output byte array {@code dst} has enough space for encoding + * all bytes from the input byte array. No bytes will be written to the + * output byte array if the output byte array is not big enough. + * + * @param src + * the byte array to encode + * @param dst + * the output byte array + * @return The number of bytes written to the output byte array + * + * @throws IllegalArgumentException if {@code dst} does not have enough + * space for encoding all input bytes. + */ + public int encode(byte[] src, byte[] dst) { + int len = 4 * ((src.length + 2) / 3); // dst array size + if (linemax > 0) { + len += (len - 1) / linemax * newline.length; + } + if (dst.length < len) + throw new IllegalArgumentException( + "Output byte array is too small for encoding all input bytes"); + return encode0(src, 0, src.length, dst); + } + + /** + * Encodes the specified byte array into a String using the {@link Base64} + * encoding scheme. + * + *
This method first encodes all input bytes into a base64 encoded + * byte array and then constructs a new String by using the encoded byte + * array and the {@link java.nio.charset.StandardCharsets.ISO_8859_1 ISO-8859-1} + * charset. + * + *
In other words, an invocation of this method has exactly the same + * effect as invoking + * {@code new String(encode(src), StandardCharsets.ISO_8859_1)}. + * + * @param src + * the byte array to encode + * @return A String containing the resulting Base64 encoded characters + */ + @SuppressWarnings("deprecation") + public String encodeToString(byte[] src) { + byte[] encoded = encode(src); + return new String(encoded, 0, 0, encoded.length); + } + + /** + * Encodes all remaining bytes from the specified byte buffer into + * a newly-allocated ByteBuffer using the {@link Base64} encoding + * scheme. + * + * Upon return, the source buffer's position will be updated to + * its limit; its limit will not have been changed. The returned + * output buffer's position will be zero and its limit will be the + * number of resulting encoded bytes. + * + * @param buffer + * the source ByteBuffer to encode + * @return A newly-allocated byte buffer containing the encoded bytes. + */ + public ByteBuffer encode(ByteBuffer buffer) { + int len = 4 * ((buffer.remaining() + 2) / 3); + if (linemax > 0) + len += (len - 1) / linemax * newline.length; + byte[] dst = new byte[len]; + int ret = 0; + if (buffer.hasArray()) { + ret = encode0(buffer.array(), + buffer.arrayOffset() + buffer.position(), + buffer.arrayOffset() + buffer.limit(), + dst); + buffer.position(buffer.limit()); + } else { + byte[] src = new byte[buffer.remaining()]; + buffer.get(src); + ret = encode0(src, 0, src.length, dst); + } + if (ret != dst.length) + dst = Arrays.copyOf(dst, ret); + return ByteBuffer.wrap(dst); + } + + /** + * Encodes as many bytes as possible from the input byte buffer + * using the {@link Base64} encoding scheme, writing the resulting + * bytes to the given output byte buffer. + * + *
The buffers are read from, and written to, starting at their + * current positions. Upon return, the input and output buffers' + * positions will be advanced to reflect the bytes read and written, + * but their limits will not be modified. + * + *
The encoding operation will stop and return if either all + * remaining bytes in the input buffer have been encoded and written + * to the output buffer, or the output buffer has insufficient space + * to encode any more input bytes. The encoding operation can be + * continued, if there is more bytes in input buffer to be encoded, + * by invoking this method again with an output buffer that has more + * {@linkplain Buffer#remaining remaining} bytes. This is typically + * done by draining any encoded bytes from the output buffer. The + * value returned from last invocation needs to be passed in as the + * third parameter {@code bytesOut} if it is to continue an unfinished + * encoding, 0 otherwise. + * + *
Recommended Usage Example + *
+ * ByteBuffer src = ...;
+ * ByteBuffer dst = ...;
+ * Base64.Encoder enc = Base64.getMimeDecoder();
+ *
+ * int bytesOut = 0;
+ * while (src.hasRemaining()) {
+ * // clear output buffer for decoding
+ * dst.clear();
+ * bytesOut = enc.encode(src, dst, bytesOut);
+ *
+ * // read encoded bytes out of "dst"
+ * dst.flip();
+ * ...
+ * }
+ *
+ *
+ * @param src
+ * the input byte buffer to encode
+ * @param dst
+ * the output byte buffer
+ * @param bytesOut
+ * the return value of last invocation if this is to continue
+ * an unfinished encoding operation, 0 otherwise
+ * @return The sum total of {@code bytesOut} and the number of bytes
+ * written to the output ByteBuffer during this invocation.
+ */
+ public int encode(ByteBuffer src, ByteBuffer dst, int bytesOut) {
+ if (src.hasArray() && dst.hasArray())
+ return encodeArray(src, dst, bytesOut);
+ return encodeBuffer(src, dst, bytesOut);
+ }
+
+ /**
+ * Wraps an output stream for encoding byte data using the {@link Base64}
+ * encoding scheme.
+ *
+ * It is recommended to promptly close the returned output stream after + * use, during which it will flush all possible leftover bytes to the underlying + * output stream. Closing the returned output stream will close the underlying + * output stream. + * + * @param os + * the output stream. + * @return the output stream for encoding the byte data into the + * specified Base64 encoded format + */ + public OutputStream wrap(OutputStream os) { + return new EncOutputStream(os, isURL ? toBase64URL : toBase64, + newline, linemax); + } + + private int encodeArray(ByteBuffer src, ByteBuffer dst, int bytesOut) { + char[] base64 = isURL? toBase64URL : toBase64; + byte[] sa = src.array(); + int sp = src.arrayOffset() + src.position(); + int sl = src.arrayOffset() + src.limit(); + byte[] da = dst.array(); + int dp = dst.arrayOffset() + dst.position(); + int dl = dst.arrayOffset() + dst.limit(); + int dp00 = dp; + int dpos = 0; // dp of each line + if (linemax > 0 && bytesOut > 0) + dpos = bytesOut % (linemax + newline.length); + try { + if (dpos == linemax && sp < src.limit()) { + if (dp + newline.length > dl) + return dp - dp00 + bytesOut; + for (byte b : newline){ + dst.put(dp++, b); + } + dpos = 0; + } + sl = sp + (sl - sp) / 3 * 3; + while (sp < sl) { + int slen = (linemax > 0) ? (linemax - dpos) / 4 * 3 + : sl - sp; + int sl0 = Math.min(sp + slen, sl); + for (int sp0 = sp, dp0 = dp ; sp0 < sl0; ) { + if (dp0 + 4 > dl) { + sp = sp0; dp = dp0; + return dp0 - dp00 + bytesOut; + } + int bits = (sa[sp0++] & 0xff) << 16 | + (sa[sp0++] & 0xff) << 8 | + (sa[sp0++] & 0xff); + da[dp0++] = (byte)base64[(bits >>> 18) & 0x3f]; + da[dp0++] = (byte)base64[(bits >>> 12) & 0x3f]; + da[dp0++] = (byte)base64[(bits >>> 6) & 0x3f]; + da[dp0++] = (byte)base64[bits & 0x3f]; + } + int n = (sl0 - sp) / 3 * 4; + dpos += n; + dp += n; + sp = sl0; + if (dpos == linemax && sp < src.limit()) { + if (dp + newline.length > dl) + return dp - dp00 + bytesOut; + for (byte b : newline){ + da[dp++] = b; + } + dpos = 0; + } + } + sl = src.arrayOffset() + src.limit(); + if (sp < sl && dl >= dp + 4) { // 1 or 2 leftover bytes + int b0 = sa[sp++] & 0xff; + da[dp++] = (byte)base64[b0 >> 2]; + if (sp == sl) { + da[dp++] = (byte)base64[(b0 << 4) & 0x3f]; + da[dp++] = '='; + da[dp++] = '='; + } else { + int b1 = sa[sp++] & 0xff; + da[dp++] = (byte)base64[(b0 << 4) & 0x3f | (b1 >> 4)]; + da[dp++] = (byte)base64[(b1 << 2) & 0x3f]; + da[dp++] = '='; + } + } + return dp - dp00 + bytesOut; + } finally { + src.position(sp - src.arrayOffset()); + dst.position(dp - dst.arrayOffset()); + } + } + + private int encodeBuffer(ByteBuffer src, ByteBuffer dst, int bytesOut) { + char[] base64 = isURL? toBase64URL : toBase64; + int sp = src.position(); + int sl = src.limit(); + int dp = dst.position(); + int dl = dst.limit(); + int dp00 = dp; + + int dpos = 0; // dp of each line + if (linemax > 0 && bytesOut > 0) + dpos = bytesOut % (linemax + newline.length); + try { + if (dpos == linemax && sp < src.limit()) { + if (dp + newline.length > dl) + return dp - dp00 + bytesOut; + for (byte b : newline){ + dst.put(dp++, b); + } + dpos = 0; + } + sl = sp + (sl - sp) / 3 * 3; + while (sp < sl) { + int slen = (linemax > 0) ? (linemax - dpos) / 4 * 3 + : sl - sp; + int sl0 = Math.min(sp + slen, sl); + for (int sp0 = sp, dp0 = dp ; sp0 < sl0; ) { + if (dp0 + 4 > dl) { + sp = sp0; dp = dp0; + return dp0 - dp00 + bytesOut; + } + int bits = (src.get(sp0++) & 0xff) << 16 | + (src.get(sp0++) & 0xff) << 8 | + (src.get(sp0++) & 0xff); + dst.put(dp0++, (byte)base64[(bits >>> 18) & 0x3f]); + dst.put(dp0++, (byte)base64[(bits >>> 12) & 0x3f]); + dst.put(dp0++, (byte)base64[(bits >>> 6) & 0x3f]); + dst.put(dp0++, (byte)base64[bits & 0x3f]); + } + int n = (sl0 - sp) / 3 * 4; + dpos += n; + dp += n; + sp = sl0; + if (dpos == linemax && sp < src.limit()) { + if (dp + newline.length > dl) + return dp - dp00 + bytesOut; + for (byte b : newline){ + dst.put(dp++, b); + } + dpos = 0; + } + } + if (sp < src.limit() && dl >= dp + 4) { // 1 or 2 leftover bytes + int b0 = src.get(sp++) & 0xff; + dst.put(dp++, (byte)base64[b0 >> 2]); + if (sp == src.limit()) { + dst.put(dp++, (byte)base64[(b0 << 4) & 0x3f]); + dst.put(dp++, (byte)'='); + dst.put(dp++, (byte)'='); + } else { + int b1 = src.get(sp++) & 0xff; + dst.put(dp++, (byte)base64[(b0 << 4) & 0x3f | (b1 >> 4)]); + dst.put(dp++, (byte)base64[(b1 << 2) & 0x3f]); + dst.put(dp++, (byte)'='); + } + } + return dp - dp00 + bytesOut; + } finally { + src.position(sp); + dst.position(dp); + } + } + + private int encode0(byte[] src, int off, int end, byte[] dst) { + char[] base64 = isURL ? toBase64URL : toBase64; + int sp = off; + int slen = (end - off) / 3 * 3; + int sl = off + slen; + if (linemax > 0 && slen > linemax / 4 * 3) + slen = linemax / 4 * 3; + int dp = 0; + while (sp < sl) { + int sl0 = Math.min(sp + slen, sl); + for (int sp0 = sp, dp0 = dp ; sp0 < sl0; ) { + int bits = (src[sp0++] & 0xff) << 16 | + (src[sp0++] & 0xff) << 8 | + (src[sp0++] & 0xff); + dst[dp0++] = (byte)base64[(bits >>> 18) & 0x3f]; + dst[dp0++] = (byte)base64[(bits >>> 12) & 0x3f]; + dst[dp0++] = (byte)base64[(bits >>> 6) & 0x3f]; + dst[dp0++] = (byte)base64[bits & 0x3f]; + } + int dlen = (sl0 - sp) / 3 * 4; + dp += dlen; + sp = sl0; + if (dlen == linemax && sp < end) { + for (byte b : newline){ + dst[dp++] = b; + } + } + } + if (sp < end) { // 1 or 2 leftover bytes + int b0 = src[sp++] & 0xff; + dst[dp++] = (byte)base64[b0 >> 2]; + if (sp == end) { + dst[dp++] = (byte)base64[(b0 << 4) & 0x3f]; + dst[dp++] = '='; + dst[dp++] = '='; + } else { + int b1 = src[sp++] & 0xff; + dst[dp++] = (byte)base64[(b0 << 4) & 0x3f | (b1 >> 4)]; + dst[dp++] = (byte)base64[(b1 << 2) & 0x3f]; + dst[dp++] = '='; + } + } + return dp; + } + } + + /** + * This class implements a decoder for decoding byte data using the + * Base64 encoding scheme as specified in RFC 4648 and RFC 2045. + * + *
Instances of {@link Decoder} class are safe for use by + * multiple concurrent threads. + * + *
Unless otherwise noted, passing a {@code null} argument to + * a method of this class will cause a + * {@link java.lang.NullPointerException NullPointerException} to + * be thrown. + * + * @see Encoder + * @since 1.8 + */ + public static class Decoder { + + private final boolean isURL; + private final boolean isMIME; + + private Decoder(boolean isURL, boolean isMIME) { + this.isURL = isURL; + this.isMIME = isMIME; + } + + /** + * Lookup table for decoding unicode characters drawn from the + * "Base64 Alphabet" (as specified in Table 1 of RFC 2045) into + * their 6-bit positive integer equivalents. Characters that + * are not in the Base64 alphabet but fall within the bounds of + * the array are encoded to -1. + * + */ + private static final int[] fromBase64 = new int[256]; + static { + Arrays.fill(fromBase64, -1); + for (int i = 0; i < Encoder.toBase64.length; i++) + fromBase64[Encoder.toBase64[i]] = i; + fromBase64['='] = -2; + } + + /** + * Lookup table for decoding "URL and Filename safe Base64 Alphabet" + * as specified in Table2 of the RFC 4648. + */ + private static final int[] fromBase64URL = new int[256]; + + static { + Arrays.fill(fromBase64URL, -1); + for (int i = 0; i < Encoder.toBase64URL.length; i++) + fromBase64URL[Encoder.toBase64URL[i]] = i; + fromBase64URL['='] = -2; + } + + static final Decoder RFC4648 = new Decoder(false, false); + static final Decoder RFC4648_URLSAFE = new Decoder(true, false); + static final Decoder RFC2045 = new Decoder(false, true); + + /** + * Decodes all bytes from the input byte array using the {@link Base64} + * encoding scheme, writing the results into a newly-allocated output + * byte array. The returned byte array is of the length of the resulting + * bytes. + * + * @param src + * the byte array to decode + * + * @return A newly-allocated byte array containing the decoded bytes. + * + * @throws IllegalArgumentException + * if {@code src} is not in valid Base64 scheme + */ + public byte[] decode(byte[] src) { + byte[] dst = new byte[outLength(src, 0, src.length)]; + int ret = decode0(src, 0, src.length, dst); + if (ret != dst.length) { + dst = Arrays.copyOf(dst, ret); + } + return dst; + } + + /** + * Decodes a Base64 encoded String into a newly-allocated byte array + * using the {@link Base64} encoding scheme. + * + *
An invocation of this method has exactly the same effect as invoking + * {@code return decode(src.getBytes(StandardCharsets.ISO_8859_1))} + * + * @param src + * the string to decode + * + * @return A newly-allocated byte array containing the decoded bytes. + * + * @throws IllegalArgumentException + * if {@code src} is not in valid Base64 scheme + */ + public byte[] decode(String src) { + return decode(src.getBytes(StandardCharsets.ISO_8859_1)); + } + + /** + * Decodes all bytes from the input byte array using the {@link Base64} + * encoding scheme, writing the results into the given output byte array, + * starting at offset 0. + * + *
It is the responsibility of the invoker of this method to make + * sure the output byte array {@code dst} has enough space for decoding + * all bytes from the input byte array. No bytes will be be written to + * the output byte array if the output byte array is not big enough. + * + *
If the input byte array is not in valid Base64 encoding scheme + * then some bytes may have been written to the output byte array before + * IllegalargumentException is thrown. + * + * @param src + * the byte array to decode + * @param dst + * the output byte array + * + * @return The number of bytes written to the output byte array + * + * @throws IllegalArgumentException + * if {@code src} is not in valid Base64 scheme, or {@code dst} + * does not have enough space for decoding all input bytes. + */ + public int decode(byte[] src, byte[] dst) { + int len = outLength(src, 0, src.length); + if (dst.length < len) + throw new IllegalArgumentException( + "Output byte array is too small for decoding all input bytes"); + return decode0(src, 0, src.length, dst); + } + + /** + * Decodes all bytes from the input byte buffer using the {@link Base64} + * encoding scheme, writing the results into a newly-allocated ByteBuffer. + * + *
Upon return, the source buffer's position will be updated to + * its limit; its limit will not have been changed. The returned + * output buffer's position will be zero and its limit will be the + * number of resulting decoded bytes + * + * @param buffer + * the ByteBuffer to decode + * + * @return A newly-allocated byte buffer containing the decoded bytes + * + * @throws IllegalArgumentException + * if {@code src} is not in valid Base64 scheme. + */ + public ByteBuffer decode(ByteBuffer buffer) { + int pos0 = buffer.position(); + try { + byte[] src; + int sp, sl; + if (buffer.hasArray()) { + src = buffer.array(); + sp = buffer.arrayOffset() + buffer.position(); + sl = buffer.arrayOffset() + buffer.limit(); + buffer.position(buffer.limit()); + } else { + src = new byte[buffer.remaining()]; + buffer.get(src); + sp = 0; + sl = src.length; + } + byte[] dst = new byte[outLength(src, sp, sl)]; + return ByteBuffer.wrap(dst, 0, decode0(src, sp, sl, dst)); + } catch (IllegalArgumentException iae) { + buffer.position(pos0); + throw iae; + } + } + + /** + * Decodes as many bytes as possible from the input byte buffer + * using the {@link Base64} encoding scheme, writing the resulting + * bytes to the given output byte buffer. + * + *
The buffers are read from, and written to, starting at their + * current positions. Upon return, the input and output buffers' + * positions will be advanced to reflect the bytes read and written, + * but their limits will not be modified. + * + *
If the input buffer is not in valid Base64 encoding scheme + * then some bytes may have been written to the output buffer + * before IllegalArgumentException is thrown. The positions of + * both input and output buffer will not be advanced in this case. + * + *
The decoding operation will end and return if all remaining + * bytes in the input buffer have been decoded and written to the + * output buffer. + * + *
The decoding operation will stop and return if the output + * buffer has insufficient space to decode any more input bytes. + * The decoding operation can be continued, if there is more bytes + * in input buffer to be decoded, by invoking this method again with + * an output buffer that has more {@linkplain Buffer#remaining remaining} + * bytes.This is typically done by draining any decoded bytes from the + * output buffer. + * + *
Recommended Usage Example + *
+ * ByteBuffer src = ...;
+ * ByteBuffer dst = ...;
+ * Base64.Decoder dec = Base64.getDecoder();
+ *
+ * while (src.hasRemaining()) {
+ *
+ * // prepare the output byte buffer
+ * dst.clear();
+ * dec.decode(src, dst);
+ *
+ * // read bytes from the output buffer
+ * dst.flip();
+ * ...
+ * }
+ *
+ *
+ * @param src
+ * the input byte buffer to decode
+ * @param dst
+ * the output byte buffer
+ *
+ * @return The number of bytes written to the output byte buffer during
+ * this decoding invocation
+ *
+ * @throws IllegalArgumentException
+ * if {@code src} is not in valid Base64 scheme.
+ */
+ public int decode(ByteBuffer src, ByteBuffer dst) {
+ int sp0 = src.position();
+ int dp0 = dst.position();
+ try {
+ if (src.hasArray() && dst.hasArray())
+ return decodeArray(src, dst);
+ return decodeBuffer(src, dst);
+ } catch (IllegalArgumentException iae) {
+ src.position(sp0);
+ dst.position(dp0);
+ throw iae;
+ }
+ }
+
+ /**
+ * Returns an input stream for decoding {@link Base64} encoded byte stream.
+ *
+ * Closing the returned input stream will close the underlying
+ * input stream.
+ *
+ * @param is
+ * the input stream
+ *
+ * @return the input stream for decoding the specified Base64 encoded
+ * byte stream
+ */
+ public InputStream wrap(InputStream is) {
+ return new DecInputStream(is, isURL ? fromBase64URL : fromBase64, isMIME);
+ }
+
+ private int decodeArray(ByteBuffer src, ByteBuffer dst) {
+ int[] base64 = isURL ? fromBase64URL : fromBase64;
+ int bits = 0;
+ int shiftto = 18; // pos of first byte of 4-byte atom
+ byte[] sa = src.array();
+ int sp = src.arrayOffset() + src.position();
+ int sl = src.arrayOffset() + src.limit();
+ byte[] da = dst.array();
+ int dp = dst.arrayOffset() + dst.position();
+ int dl = dst.arrayOffset() + dst.limit();
+ int dp0 = dp;
+ int mark = sp;
+ boolean padding = false;
+ try {
+ while (sp < sl) {
+ int b = sa[sp++] & 0xff;
+ if ((b = base64[b]) < 0) {
+ if (b == -2) { // padding byte
+ padding = true;
+ break;
+ }
+ if (isMIME) // skip if for rfc2045
+ continue;
+ else
+ throw new IllegalArgumentException(
+ "Illegal base64 character " +
+ Integer.toString(sa[sp - 1], 16));
+ }
+ bits |= (b << shiftto);
+ shiftto -= 6;
+ if (shiftto < 0) {
+ if (dl < dp + 3)
+ return dp;
+ da[dp++] = (byte)(bits >> 16);
+ da[dp++] = (byte)(bits >> 8);
+ da[dp++] = (byte)(bits);
+ shiftto = 18;
+ bits = 0;
+ mark = sp;
+ }
+ }
+ if (shiftto == 6) {
+ if (dl - dp < 1)
+ return dp;
+ if (padding && (sp + 1 != sl || sa[sp++] != '='))
+ throw new IllegalArgumentException(
+ "Input buffer has wrong 4-byte ending unit");
+ da[dp++] = (byte)(bits >> 16);
+ mark = sp;
+ } else if (shiftto == 0) {
+ if (dl - dp < 2)
+ return dp;
+ if (padding && sp != sl)
+ throw new IllegalArgumentException(
+ "Input buffer has wrong 4-byte ending unit");
+ da[dp++] = (byte)(bits >> 16);
+ da[dp++] = (byte)(bits >> 8);
+ mark = sp;
+ } else if (padding || shiftto != 18) {
+ throw new IllegalArgumentException(
+ "Last unit does not have enough valid bits");
+ }
+ return dp - dp0;
+ } finally {
+ src.position(mark);
+ dst.position(dp);
+ }
+ }
+
+ private int decodeBuffer(ByteBuffer src, ByteBuffer dst) {
+ int[] base64 = isURL ? fromBase64URL : fromBase64;
+ int bits = 0;
+ int shiftto = 18; // pos of first byte of 4-byte atom
+ int sp = src.position();
+ int sl = src.limit();
+ int dp = dst.position();
+ int dl = dst.limit();
+ int dp0 = dp;
+ int mark = sp;
+ boolean padding = false;
+
+ try {
+ while (sp < sl) {
+ int b = src.get(sp++) & 0xff;
+ if ((b = base64[b]) < 0) {
+ if (b == -2) { // padding byte
+ padding = true;
+ break;
+ }
+ if (isMIME) // skip if for rfc2045
+ continue;
+ else
+ throw new IllegalArgumentException(
+ "Illegal base64 character " +
+ Integer.toString(src.get(sp - 1), 16));
+ }
+ bits |= (b << shiftto);
+ shiftto -= 6;
+ if (shiftto < 0) {
+ if (dl < dp + 3)
+ return dp;
+ dst.put(dp++, (byte)(bits >> 16));
+ dst.put(dp++, (byte)(bits >> 8));
+ dst.put(dp++, (byte)(bits));
+ shiftto = 18;
+ bits = 0;
+ mark = sp;
+ }
+ }
+ if (shiftto == 6) {
+ if (dl - dp < 1)
+ return dp;
+ if (padding && (sp + 1 != sl || src.get(sp++) != '='))
+ throw new IllegalArgumentException(
+ "Input buffer has wrong 4-byte ending unit");
+ dst.put(dp++, (byte)(bits >> 16));
+ mark = sp;
+ } else if (shiftto == 0) {
+ if (dl - dp < 2)
+ return dp;
+ if (padding && sp != sl)
+ throw new IllegalArgumentException(
+ "Input buffer has wrong 4-byte ending unit");
+ dst.put(dp++, (byte)(bits >> 16));
+ dst.put(dp++, (byte)(bits >> 8));
+ mark = sp;
+ } else if (padding || shiftto != 18) {
+ throw new IllegalArgumentException(
+ "Last unit does not have enough valid bits");
+ }
+ return dp - dp0;
+ } finally {
+ src.position(mark);
+ dst.position(dp);
+ }
+ }
+
+ private int outLength(byte[] src, int sp, int sl) {
+ int[] base64 = isURL ? fromBase64URL : fromBase64;
+ int paddings = 0;
+ int len = sl - sp;
+ if (len == 0)
+ return 0;
+ if (len < 2)
+ throw new IllegalArgumentException(
+ "Input byte[] should at least have 2 bytes for base64 bytes");
+ if (src[sl - 1] == '=') {
+ paddings++;
+ if (src[sl - 2] == '=')
+ paddings++;
+ }
+ if (isMIME) {
+ // scan all bytes to fill out all non-alphabet. a performance
+ // trade-off of pre-scan or Arrays.copyOf
+ int n = 0;
+ while (sp < sl) {
+ int b = src[sp++] & 0xff;
+ if (b == '=')
+ break;
+ if ((b = base64[b]) == -1)
+ n++;
+ }
+ len -= n;
+ }
+ if (paddings == 0 && (len & 0x3) != 0)
+ paddings = 4 - (len & 0x3);
+ return 3 * ((len + 3) / 4) - paddings;
+ }
+
+ private int decode0(byte[] src, int sp, int sl, byte[] dst) {
+ int[] base64 = isURL ? fromBase64URL : fromBase64;
+ int dp = 0;
+ int bits = 0;
+ int shiftto = 18; // pos of first byte of 4-byte atom
+ boolean padding = false;
+ while (sp < sl) {
+ int b = src[sp++] & 0xff;
+ if ((b = base64[b]) < 0) {
+ if (b == -2) { // padding byte
+ padding = true;
+ break;
+ }
+ if (isMIME) // skip if for rfc2045
+ continue;
+ else
+ throw new IllegalArgumentException(
+ "Illegal base64 character " +
+ Integer.toString(src[sp - 1], 16));
+ }
+ bits |= (b << shiftto);
+ shiftto -= 6;
+ if (shiftto < 0) {
+ dst[dp++] = (byte)(bits >> 16);
+ dst[dp++] = (byte)(bits >> 8);
+ dst[dp++] = (byte)(bits);
+ shiftto = 18;
+ bits = 0;
+ }
+ }
+ // reach end of byte arry or hit padding '=' characters.
+ // if '=' presents, they must be the last one or two.
+ if (shiftto == 6) { // xx==
+ if (padding && (sp + 1 != sl || src[sp] != '='))
+ throw new IllegalArgumentException(
+ "Input byte array has wrong 4-byte ending unit");
+ dst[dp++] = (byte)(bits >> 16);
+ } else if (shiftto == 0) { // xxx=
+ if (padding && sp != sl)
+ throw new IllegalArgumentException(
+ "Input byte array has wrong 4-byte ending unit");
+ dst[dp++] = (byte)(bits >> 16);
+ dst[dp++] = (byte)(bits >> 8);
+ } else if (padding || shiftto != 18) {
+ throw new IllegalArgumentException(
+ "last unit does not have enough bytes");
+ }
+ return dp;
+ }
+ }
+
+ /*
+ * An output stream for encoding bytes into the Base64.
+ */
+ private static class EncOutputStream extends FilterOutputStream {
+
+ private int leftover = 0;
+ private int b0, b1, b2;
+ private boolean closed = false;
+
+ private final char[] base64; // byte->base64 mapping
+ private final byte[] newline; // line separator, if needed
+ private final int linemax;
+ private int linepos = 0;
+
+ EncOutputStream(OutputStream os,
+ char[] base64, byte[] newline, int linemax) {
+ super(os);
+ this.base64 = base64;
+ this.newline = newline;
+ this.linemax = linemax;
+ }
+
+ @Override
+ public void write(int b) throws IOException {
+ byte[] buf = new byte[1];
+ buf[0] = (byte)(b & 0xff);
+ write(buf, 0, 1);
+ }
+
+ private void checkNewline() throws IOException {
+ if (linepos == linemax) {
+ out.write(newline);
+ linepos = 0;
+ }
+ }
+
+ @Override
+ public void write(byte[] b, int off, int len) throws IOException {
+ if (closed)
+ throw new IOException("Stream is closed");
+ if (off < 0 || len < 0 || off + len > b.length)
+ throw new ArrayIndexOutOfBoundsException();
+ if (len == 0)
+ return;
+ if (leftover != 0) {
+ if (leftover == 1) {
+ b1 = b[off++] & 0xff;
+ len--;
+ if (len == 0) {
+ leftover++;
+ return;
+ }
+ }
+ b2 = b[off++] & 0xff;
+ len--;
+ checkNewline();
+ out.write(base64[b0 >> 2]);
+ out.write(base64[(b0 << 4) & 0x3f | (b1 >> 4)]);
+ out.write(base64[(b1 << 2) & 0x3f | (b2 >> 6)]);
+ out.write(base64[b2 & 0x3f]);
+ linepos += 4;
+ }
+ int nBits24 = len / 3;
+ leftover = len - (nBits24 * 3);
+ while (nBits24-- > 0) {
+ checkNewline();
+ int bits = (b[off++] & 0xff) << 16 |
+ (b[off++] & 0xff) << 8 |
+ (b[off++] & 0xff);
+ out.write(base64[(bits >>> 18) & 0x3f]);
+ out.write(base64[(bits >>> 12) & 0x3f]);
+ out.write(base64[(bits >>> 6) & 0x3f]);
+ out.write(base64[bits & 0x3f]);
+ linepos += 4;
+ }
+ if (leftover == 1) {
+ b0 = b[off++] & 0xff;
+ } else if (leftover == 2) {
+ b0 = b[off++] & 0xff;
+ b1 = b[off++] & 0xff;
+ }
+ }
+
+ @Override
+ public void close() throws IOException {
+ if (!closed) {
+ closed = true;
+ if (leftover == 1) {
+ checkNewline();
+ out.write(base64[b0 >> 2]);
+ out.write(base64[(b0 << 4) & 0x3f]);
+ out.write('=');
+ out.write('=');
+ } else if (leftover == 2) {
+ checkNewline();
+ out.write(base64[b0 >> 2]);
+ out.write(base64[(b0 << 4) & 0x3f | (b1 >> 4)]);
+ out.write(base64[(b1 << 2) & 0x3f]);
+ out.write('=');
+ }
+ leftover = 0;
+ out.close();
+ }
+ }
+ }
+
+ /*
+ * An input stream for decoding Base64 bytes
+ */
+ private static class DecInputStream extends InputStream {
+
+ private final InputStream is;
+ private final boolean isMIME;
+ private final int[] base64; // base64 -> byte mapping
+ private int bits = 0; // 24-bit buffer for decoding
+ private int nextin = 18; // next available "off" in "bits" for input;
+ // -> 18, 12, 6, 0
+ private int nextout = -8; // next available "off" in "bits" for output;
+ // -> 8, 0, -8 (no byte for output)
+ private boolean eof = false;
+ private boolean closed = false;
+
+ DecInputStream(InputStream is, int[] base64, boolean isMIME) {
+ this.is = is;
+ this.base64 = base64;
+ this.isMIME = isMIME;
+ }
+
+ private byte[] sbBuf = new byte[1];
+
+ @Override
+ public int read() throws IOException {
+ return read(sbBuf, 0, 1) == -1 ? -1 : sbBuf[0] & 0xff;
+ }
+
+ @Override
+ public int read(byte[] b, int off, int len) throws IOException {
+ if (closed)
+ throw new IOException("Stream is closed");
+ if (eof && nextout < 0) // eof and no leftover
+ return -1;
+ if (off < 0 || len < 0 || len > b.length - off)
+ throw new IndexOutOfBoundsException();
+ int oldOff = off;
+ if (nextout >= 0) { // leftover output byte(s) in bits buf
+ do {
+ if (len == 0)
+ return off - oldOff;
+ b[off++] = (byte)(bits >> nextout);
+ len--;
+ nextout -= 8;
+ } while (nextout >= 0);
+ bits = 0;
+ }
+ while (len > 0) {
+ int v = is.read();
+ if (v == -1) {
+ eof = true;
+ if (nextin != 18)
+ throw new IOException("Base64 stream has un-decoded dangling byte(s).");
+ if (off == oldOff)
+ return -1;
+ else
+ return off - oldOff;
+ }
+ if (v == '=') { // padding byte(s)
+ if (nextin != 6 && nextin != 0) {
+ throw new IOException("Illegal base64 ending sequence:" + nextin);
+ }
+ b[off++] = (byte)(bits >> (16));
+ len--;
+ if (nextin == 0) { // only one padding byte
+ if (len == 0) { // no enough output space
+ bits >>= 8; // shift to lowest byte
+ nextout = 0;
+ } else {
+ b[off++] = (byte) (bits >> 8);
+ }
+ }
+ eof = true;
+ break;
+ }
+ if ((v = base64[v]) == -1) {
+ if (isMIME) // skip if for rfc2045
+ continue;
+ else
+ throw new IOException("Illegal base64 character " +
+ Integer.toString(v, 16));
+ }
+ bits |= (v << nextin);
+ if (nextin == 0) {
+ nextin = 18; // clear for next
+ nextout = 16;
+ while (nextout >= 0) {
+ b[off++] = (byte)(bits >> nextout);
+ len--;
+ nextout -= 8;
+ if (len == 0 && nextout >= 0) { // don't clean "bits"
+ return off - oldOff;
+ }
+ }
+ bits = 0;
+ } else {
+ nextin -= 6;
+ }
+ }
+ return off - oldOff;
+ }
+
+ @Override
+ public int available() throws IOException {
+ if (closed)
+ throw new IOException("Stream is closed");
+ return is.available(); // TBD:
+ }
+
+ @Override
+ public void close() throws IOException {
+ if (!closed) {
+ closed = true;
+ is.close();
+ }
+ }
+ }
+}
diff -r 9ed95934188b -r be67058c3dc7 jdk/test/java/util/Base64/TestBase64.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/test/java/util/Base64/TestBase64.java Tue Nov 27 22:07:11 2012 -0800
@@ -0,0 +1,483 @@
+/*
+ * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * @test 4235519
+ * @summary tests java.util.Base64
+ */
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.ByteBuffer;
+import java.util.Arrays;
+import java.util.Base64;
+import java.util.Random;
+
+public class TestBase64 {
+
+ public static void main(String args[]) throws Throwable {
+ int numRuns = 10;
+ int numBytes = 200;
+ if (args.length > 1) {
+ numRuns = Integer.parseInt(args[0]);
+ numBytes = Integer.parseInt(args[1]);
+ }
+
+ test(Base64.getEncoder(), Base64.getDecoder(),
+ numRuns, numBytes);
+ test(Base64.getUrlEncoder(), Base64.getUrlDecoder(),
+ numRuns, numBytes);
+ test(Base64.getMimeEncoder(), Base64.getMimeDecoder(),
+ numRuns, numBytes);
+
+ Random rnd = new java.util.Random();
+ byte[] nl_1 = new byte[] {'\n'};
+ byte[] nl_2 = new byte[] {'\n', '\r'};
+ byte[] nl_3 = new byte[] {'\n', '\r', '\n'};
+ for (int i = 0; i < 10; i++) {
+ int len = rnd.nextInt(200) + 4;
+ test(Base64.getEncoder(len, nl_1),
+ Base64.getMimeDecoder(),
+ numRuns, numBytes);
+ test(Base64.getEncoder(len, nl_2),
+ Base64.getMimeDecoder(),
+ numRuns, numBytes);
+ test(Base64.getEncoder(len, nl_3),
+ Base64.getMimeDecoder(),
+ numRuns, numBytes);
+ }
+
+ testNull(Base64.getEncoder());
+ testNull(Base64.getUrlEncoder());
+ testNull(Base64.getMimeEncoder());
+ testNull(Base64.getEncoder(10, new byte[]{'\n'}));
+ testNull(Base64.getDecoder());
+ testNull(Base64.getUrlDecoder());
+ testNull(Base64.getMimeDecoder());
+ checkNull(new Runnable() { public void run() { Base64.getEncoder(10, null); }});
+
+ testIOE(Base64.getEncoder());
+ testIOE(Base64.getUrlEncoder());
+ testIOE(Base64.getMimeEncoder());
+ testIOE(Base64.getEncoder(10, new byte[]{'\n'}));
+
+ byte[] src = new byte[1024];
+ new Random().nextBytes(src);
+ final byte[] decoded = Base64.getEncoder().encode(src);
+ testIOE(Base64.getDecoder(), decoded);
+ testIOE(Base64.getMimeDecoder(), decoded);
+ testIOE(Base64.getUrlDecoder(), Base64.getUrlEncoder().encode(src));
+
+ // illegal line separator
+ checkIAE(new Runnable() { public void run() { Base64.getEncoder(10, new byte[]{'\r', 'N'}); }});
+
+ // illegal base64 character
+ decoded[2] = (byte)0xe0;
+ checkIAE(new Runnable() {
+ public void run() { Base64.getDecoder().decode(decoded); }});
+ checkIAE(new Runnable() {
+ public void run() { Base64.getDecoder().decode(decoded, new byte[1024]); }});
+ checkIAE(new Runnable() { public void run() {
+ Base64.getDecoder().decode(ByteBuffer.wrap(decoded)); }});
+ checkIAE(new Runnable() { public void run() {
+ Base64.getDecoder().decode(ByteBuffer.wrap(decoded), ByteBuffer.allocate(1024)); }});
+ checkIAE(new Runnable() { public void run() {
+ Base64.getDecoder().decode(ByteBuffer.wrap(decoded), ByteBuffer.allocateDirect(1024)); }});
+ }
+
+ private static sun.misc.BASE64Encoder sunmisc = new sun.misc.BASE64Encoder();
+
+ private static void test(Base64.Encoder enc, Base64.Decoder dec,
+ int numRuns, int numBytes) throws Throwable {
+ Random rnd = new java.util.Random();
+
+ enc.encode(new byte[0]);
+ dec.decode(new byte[0]);
+
+ for (int i=0; i