View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.util;
21  
22  import java.io.BufferedInputStream;
23  import java.io.BufferedOutputStream;
24  import java.io.ByteArrayInputStream;
25  import java.io.ByteArrayOutputStream;
26  import java.io.File;
27  import java.io.FileInputStream;
28  import java.io.FileOutputStream;
29  import java.io.FilterInputStream;
30  import java.io.FilterOutputStream;
31  import java.io.IOException;
32  import java.io.InputStream;
33  import java.io.ObjectInputStream;
34  import java.io.ObjectOutputStream;
35  import java.io.OutputStream;
36  import java.io.Serializable;
37  import java.io.UnsupportedEncodingException;
38  import java.util.zip.GZIPInputStream;
39  import java.util.zip.GZIPOutputStream;
40  
41  import org.apache.commons.logging.Log;
42  import org.apache.commons.logging.LogFactory;
43  import org.apache.hadoop.hbase.classification.InterfaceAudience;
44  import org.apache.hadoop.hbase.classification.InterfaceStability;
45  
46  /**
47   * Encodes and decodes to and from Base64 notation.
48   *
49   * <p>
50   * Homepage: <a href="http://iharder.net/base64">http://iharder.net/base64</a>.
51   * </p>
52   *
53   * <p>
54   * Change Log:
55   * </p>
56   * <ul>
57   *   <li>v2.2.1 - Fixed bug using URL_SAFE and ORDERED encodings. Fixed bug
58   *     when using very small files (~&lt; 40 bytes).</li>
59   *   <li>v2.2 - Added some helper methods for encoding/decoding directly from
60   *     one file to the next. Also added a main() method to support command
61   *     line encoding/decoding from one file to the next. Also added these
62   *     Base64 dialects:
63   *     <ol>
64   *       <li>The default is RFC3548 format.</li>
65   *       <li>Using Base64.URLSAFE generates URL and file name friendly format as
66   *         described in Section 4 of RFC3548.
67   *         http://www.faqs.org/rfcs/rfc3548.html</li>
68   *       <li>Using Base64.ORDERED generates URL and file name friendly format
69   *         that preserves lexical ordering as described in
70   *         http://www.faqs.org/qa/rfcc-1940.html</li>
71   *     </ol>
72   *     <p>
73   *     Special thanks to Jim Kellerman at <a href="http://www.powerset.com/">
74   *     http://www.powerset.com/</a> for contributing the new Base64 dialects.
75   *   </li>
76   *
77   *   <li>v2.1 - Cleaned up javadoc comments and unused variables and methods.
78   *     Added some convenience methods for reading and writing to and from files.
79   *   </li>
80   *   <li>v2.0.2 - Now specifies UTF-8 encoding in places where the code fails on
81   *     systems with other encodings (like EBCDIC).</li>
82   *   <li>v2.0.1 - Fixed an error when decoding a single byte, that is, when the
83   *     encoded data was a single byte.</li>
84   *   <li>v2.0 - I got rid of methods that used booleans to set options. Now
85   *     everything is more consolidated and cleaner. The code now detects when
86   *     data that's being decoded is gzip-compressed and will decompress it
87   *     automatically. Generally things are cleaner. You'll probably have to
88   *     change some method calls that you were making to support the new options
89   *     format (<tt>int</tt>s that you "OR" together).</li>
90   *   <li>v1.5.1 - Fixed bug when decompressing and decoding to a byte[] using
91   *     <tt>decode( String s, boolean gzipCompressed )</tt>. Added the ability to
92   *     "suspend" encoding in the Output Stream so you can turn on and off the
93   *     encoding if you need to embed base64 data in an otherwise "normal" stream
94   *     (like an XML file).</li>
95   *   <li>v1.5 - Output stream pases on flush() command but doesn't do anything
96   *     itself. This helps when using GZIP streams. Added the ability to
97   *     GZip-compress objects before encoding them.</li>
98   *   <li>v1.4 - Added helper methods to read/write files.</li>
99   *   <li>v1.3.6 - Fixed OutputStream.flush() so that 'position' is reset.</li>
100  *   <li>v1.3.5 - Added flag to turn on and off line breaks. Fixed bug in input
101  *     stream where last buffer being read, if not completely full, was not
102  *     returned.</li>
103  *   <li>v1.3.4 - Fixed when "improperly padded stream" error was thrown at the
104  *     wrong time.</li>
105  *   <li>v1.3.3 - Fixed I/O streams which were totally messed up.</li>
106  * </ul>
107  *
108  * <p>
109  * I am placing this code in the Public Domain. Do with it as you will. This
110  * software comes with no guarantees or warranties but with plenty of
111  * well-wishing instead!
112  * <p>
113  * Please visit <a href="http://iharder.net/base64">http://iharder.net/base64</a>
114  * periodically to check for updates or to contribute improvements.
115  * <p>
116  * author: Robert Harder, rob@iharder.net
117  * <br>
118  * version: 2.2.1
119  */
120 @InterfaceAudience.Public
121 @InterfaceStability.Stable
122 public class Base64 {
123 
124   /* ******** P U B L I C   F I E L D S ******** */
125 
126   /** No options specified. Value is zero. */
127   public final static int NO_OPTIONS = 0;
128 
129   /** Specify encoding. */
130   public final static int ENCODE = 1;
131 
132   /** Specify decoding. */
133   public final static int DECODE = 0;
134 
135   /** Specify that data should be gzip-compressed. */
136   public final static int GZIP = 2;
137 
138   /** Don't break lines when encoding (violates strict Base64 specification) */
139   public final static int DONT_BREAK_LINES = 8;
140 
141   /**
142    * Encode using Base64-like encoding that is URL and Filename safe as
143    * described in Section 4 of RFC3548:
144    * <a href="http://www.faqs.org/rfcs/rfc3548.html">
145    * http://www.faqs.org/rfcs/rfc3548.html</a>.
146    * It is important to note that data encoded this way is <em>not</em>
147    * officially valid Base64, or at the very least should not be called Base64
148    * without also specifying that is was encoded using the URL and
149    * Filename safe dialect.
150    */
151   public final static int URL_SAFE = 16;
152 
153   /**
154    * Encode using the special "ordered" dialect of Base64 described here:
155    * <a href="http://www.faqs.org/qa/rfcc-1940.html">
156    * http://www.faqs.org/qa/rfcc-1940.html</a>.
157    */
158   public final static int ORDERED = 32;
159 
160   /* ******** P R I V A T E   F I E L D S ******** */
161 
162   private static final Log LOG = LogFactory.getLog(Base64.class);
163 
164   /** Maximum line length (76) of Base64 output. */
165   private final static int MAX_LINE_LENGTH = 76;
166 
167   /** The equals sign (=) as a byte. */
168   private final static byte EQUALS_SIGN = (byte) '=';
169 
170   /** The new line character (\n) as a byte. */
171   private final static byte NEW_LINE = (byte) '\n';
172 
173   /** Preferred encoding. */
174   private final static String PREFERRED_ENCODING = "UTF-8";
175 
176   private final static byte WHITE_SPACE_ENC = -5; // Indicates white space
177   private final static byte EQUALS_SIGN_ENC = -1; // Indicates equals sign
178 
179   /* ******** S T A N D A R D   B A S E 6 4   A L P H A B E T ******** */
180 
181   /** The 64 valid Base64 values. */
182 
183   /*
184    * Host platform may be something funny like EBCDIC, so we hardcode these
185    * values.
186    */
187   private final static byte[] _STANDARD_ALPHABET = { (byte) 'A', (byte) 'B',
188     (byte) 'C', (byte) 'D', (byte) 'E', (byte) 'F', (byte) 'G', (byte) 'H',
189     (byte) 'I', (byte) 'J', (byte) 'K', (byte) 'L', (byte) 'M', (byte) 'N',
190     (byte) 'O', (byte) 'P', (byte) 'Q', (byte) 'R', (byte) 'S', (byte) 'T',
191     (byte) 'U', (byte) 'V', (byte) 'W', (byte) 'X', (byte) 'Y', (byte) 'Z',
192     (byte) 'a', (byte) 'b', (byte) 'c', (byte) 'd', (byte) 'e', (byte) 'f',
193     (byte) 'g', (byte) 'h', (byte) 'i', (byte) 'j', (byte) 'k', (byte) 'l',
194     (byte) 'm', (byte) 'n', (byte) 'o', (byte) 'p', (byte) 'q', (byte) 'r',
195     (byte) 's', (byte) 't', (byte) 'u', (byte) 'v', (byte) 'w', (byte) 'x',
196     (byte) 'y', (byte) 'z', (byte) '0', (byte) '1', (byte) '2', (byte) '3',
197     (byte) '4', (byte) '5', (byte) '6', (byte) '7', (byte) '8', (byte) '9',
198     (byte) '+', (byte) '/'
199   };
200 
201   /**
202    * Translates a Base64 value to either its 6-bit reconstruction value or a
203    * negative number indicating some other meaning.
204    */
205   private final static byte[] _STANDARD_DECODABET = {
206     -9, -9, -9, -9, -9, -9, -9, -9, -9,             // Decimal 0 - 8
207     -5, -5,                                         // Whitespace: Tab, Newline
208     -9, -9,                                         // Decimal 11 - 12
209     -5,                                             // Whitespace: Return
210     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, // Decimal 14 - 26
211     -9, -9, -9, -9, -9,                             // Decimal 27 - 31
212     -5,                                             // Whitespace: Space
213     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9,         // Decimal 33 - 42
214     62,                                             // Plus sign at decimal 43
215     -9, -9, -9,                                     // Decimal 44 - 46
216     63,                                             // Slash at decimal 47
217     52, 53, 54, 55, 56, 57, 58, 59, 60, 61,         // Numbers zero - nine
218     -9, -9, -9,                                     // Decimal 58 - 60
219     -1,                                             // Equals sign at decimal 61
220     -9, -9, -9,                                     // Decimal 62 - 64
221     0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,   // Letters 'A' - 'N'
222     14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, // Letters 'O' - 'Z'
223     -9, -9, -9, -9, -9, -9,                         // Decimal 91 - 96
224     26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, // Letters 'a' - 'm'
225     39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, // Letters 'n' -'z'
226     -9, -9, -9, -9                                  // Decimal 123 - 126
227   };
228 
229   /* ******** U R L   S A F E   B A S E 6 4   A L P H A B E T ******** */
230 
231   /**
232    * Used in the URL and Filename safe dialect described in Section 4 of RFC3548
233    * <a href="http://www.faqs.org/rfcs/rfc3548.html">
234    * http://www.faqs.org/rfcs/rfc3548.html</a>.
235    * Notice that the last two bytes become "hyphen" and "underscore" instead of
236    * "plus" and "slash."
237    */
238   private final static byte[] _URL_SAFE_ALPHABET = { (byte) 'A', (byte) 'B',
239     (byte) 'C', (byte) 'D', (byte) 'E', (byte) 'F', (byte) 'G', (byte) 'H',
240     (byte) 'I', (byte) 'J', (byte) 'K', (byte) 'L', (byte) 'M', (byte) 'N',
241     (byte) 'O', (byte) 'P', (byte) 'Q', (byte) 'R', (byte) 'S', (byte) 'T',
242     (byte) 'U', (byte) 'V', (byte) 'W', (byte) 'X', (byte) 'Y', (byte) 'Z',
243     (byte) 'a', (byte) 'b', (byte) 'c', (byte) 'd', (byte) 'e', (byte) 'f',
244     (byte) 'g', (byte) 'h', (byte) 'i', (byte) 'j', (byte) 'k', (byte) 'l',
245     (byte) 'm', (byte) 'n', (byte) 'o', (byte) 'p', (byte) 'q', (byte) 'r',
246     (byte) 's', (byte) 't', (byte) 'u', (byte) 'v', (byte) 'w', (byte) 'x',
247     (byte) 'y', (byte) 'z', (byte) '0', (byte) '1', (byte) '2', (byte) '3',
248     (byte) '4', (byte) '5', (byte) '6', (byte) '7', (byte) '8', (byte) '9',
249     (byte) '-', (byte) '_'
250   };
251 
252   /**
253    * Used in decoding URL and Filename safe dialects of Base64.
254    */
255   private final static byte[] _URL_SAFE_DECODABET = {
256     -9, -9, -9, -9, -9, -9, -9, -9, -9,                 // Decimal 0 - 8
257     -5, -5,                                             // Whitespace: Tab, Newline
258     -9, -9,                                             // Decimal 11 - 12
259     -5,                                                 // Whitespace: Return
260     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, // Decimal 14 - 26
261     -9, -9, -9, -9, -9,                                 // Decimal 27 - 31
262     -5,                                                 // Whitespace: Space
263     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9,             // Decimal 33 - 42
264     -9,                                                 // Plus sign at 43
265     -9,                                                 // Decimal 44
266     62,                                                 // Minus sign at 45
267     -9,                                                 // Decimal 46
268     -9,                                                 // Slash at 47
269     52, 53, 54, 55, 56, 57, 58, 59, 60, 61,             // Numbers 0 - 9
270     -9, -9, -9,                                         // Decimal 58 - 60
271     -1,                                                 // Equals sign at 61
272     -9, -9, -9,                                         // Decimal 62 - 64
273     0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,       // Letters 'A' - 'N'
274     14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,     // Letters 'O' - 'Z'
275     -9, -9, -9, -9,                                     // Decimal 91 - 94
276     63,                                                 // Underscore at 95
277     -9,                                                 // Decimal 96
278     26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, // Letters 'a' - 'm'
279     39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, // Letters 'n' - 'z'
280     -9, -9, -9, -9                                      // Decimal 123 - 126
281   };
282 
283   /* ******** O R D E R E D   B A S E 6 4   A L P H A B E T ******** */
284 
285   /**
286    * In addition to being URL and file name friendly, this encoding preserves
287    * the sort order of encoded values. Whatever is input, be it string or
288    * just an array of bytes, when you use this encoding, the encoded value sorts
289    * exactly the same as the input value. It is described in the RFC change
290    * request: <a href="http://www.faqs.org/qa/rfcc-1940.html">
291    * http://www.faqs.org/qa/rfcc-1940.html</a>.
292    *
293    * It replaces "plus" and "slash" with "hyphen" and "underscore" and
294    * rearranges the alphabet so that the characters are in their natural sort
295    * order.
296    */
297   private final static byte[] _ORDERED_ALPHABET = { (byte) '-', (byte) '0',
298     (byte) '1', (byte) '2', (byte) '3', (byte) '4', (byte) '5', (byte) '6',
299     (byte) '7', (byte) '8', (byte) '9', (byte) 'A', (byte) 'B', (byte) 'C',
300     (byte) 'D', (byte) 'E', (byte) 'F', (byte) 'G', (byte) 'H', (byte) 'I',
301     (byte) 'J', (byte) 'K', (byte) 'L', (byte) 'M', (byte) 'N', (byte) 'O',
302     (byte) 'P', (byte) 'Q', (byte) 'R', (byte) 'S', (byte) 'T', (byte) 'U',
303     (byte) 'V', (byte) 'W', (byte) 'X', (byte) 'Y', (byte) 'Z', (byte) '_',
304     (byte) 'a', (byte) 'b', (byte) 'c', (byte) 'd', (byte) 'e', (byte) 'f',
305     (byte) 'g', (byte) 'h', (byte) 'i', (byte) 'j', (byte) 'k', (byte) 'l',
306     (byte) 'm', (byte) 'n', (byte) 'o', (byte) 'p', (byte) 'q', (byte) 'r',
307     (byte) 's', (byte) 't', (byte) 'u', (byte) 'v', (byte) 'w', (byte) 'x',
308     (byte) 'y', (byte) 'z'
309   };
310 
311   /**
312    * Used in decoding the "ordered" dialect of Base64.
313    */
314   private final static byte[] _ORDERED_DECODABET = {
315     -9, -9, -9, -9, -9, -9, -9, -9, -9,                 // Decimal 0 - 8
316     -5, -5,                                             // Whitespace: Tab, Newline
317     -9, -9,                                             // Decimal 11 - 12
318     -5,                                                 // Whitespace: Return
319     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, -9, // Decimal 14 - 26
320     -9, -9, -9, -9, -9,                                 // Decimal 27 - 31
321     -5,                                                 // Whitespace: Space
322     -9, -9, -9, -9, -9, -9, -9, -9, -9, -9,             // Decimal 33 - 42
323     -9,                                                 // Plus sign at 43
324     -9,                                                 // Decimal 44
325     0,                                                  // Minus sign at 45
326     -9,                                                 // Decimal 46
327     -9,                                                 // Slash at decimal 47
328     1, 2, 3, 4, 5, 6, 7, 8, 9, 10,                      // Numbers 0 - 9
329     -9, -9, -9,                                         // Decimal 58 - 60
330     -1,                                                 // Equals sign at 61
331     -9, -9, -9,                                         // Decimal 62 - 64
332     11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, // Letters 'A' - 'M'
333     24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, // Letters 'N' - 'Z'
334     -9, -9, -9, -9,                                     // Decimal 91 - 94
335     37,                                                 // Underscore at 95
336     -9,                                                 // Decimal 96
337     38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, // Letters 'a' - 'm'
338     51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, // Letters 'n' - 'z'
339     -9, -9, -9, -9                                      // Decimal 123 - 126
340   };
341 
342   /* ******** D E T E R M I N E   W H I C H   A L H A B E T ******** */
343 
344   /**
345    * Returns one of the _SOMETHING_ALPHABET byte arrays depending on the options
346    * specified. It's possible, though silly, to specify ORDERED and URLSAFE in
347    * which case one of them will be picked, though there is no guarantee as to
348    * which one will be picked.
349    *
350    * @param options URL_SAFE or ORDERED
351    * @return alphabet array to use
352    */
353   protected static byte[] getAlphabet(int options) {
354     if ((options & URL_SAFE) == URL_SAFE) {
355       return _URL_SAFE_ALPHABET;
356 
357     } else if ((options & ORDERED) == ORDERED) {
358       return _ORDERED_ALPHABET;
359 
360     } else {
361       return _STANDARD_ALPHABET;
362     }
363   } // end getAlphabet
364 
365   /**
366    * Returns one of the _SOMETHING_DECODABET byte arrays depending on the
367    * options specified. It's possible, though silly, to specify ORDERED and
368    * URL_SAFE in which case one of them will be picked, though there is no
369    * guarantee as to which one will be picked.
370    * @param options URL_SAFE or ORDERED
371    * @return alphabet array to use
372    */
373   protected static byte[] getDecodabet(int options) {
374     if ((options & URL_SAFE) == URL_SAFE) {
375       return _URL_SAFE_DECODABET;
376 
377     } else if ((options & ORDERED) == ORDERED) {
378       return _ORDERED_DECODABET;
379 
380     } else {
381       return _STANDARD_DECODABET;
382     }
383   } // end getDecodabet
384 
385   /** Defeats instantiation. */
386   private Base64() {}
387 
388   /**
389    * Main program. Used for testing.
390    *
391    * Encodes or decodes two files from the command line
392    *
393    * @param args command arguments
394    */
395   public static void main(String[] args) {
396     if (args.length < 3) {
397       usage("Not enough arguments.");
398 
399     } else {
400       String flag = args[0];
401       String infile = args[1];
402       String outfile = args[2];
403       if (flag.equals("-e")) {                          // encode
404         encodeFileToFile(infile, outfile);
405 
406       } else if (flag.equals("-d")) {                   // decode
407         decodeFileToFile(infile, outfile);
408 
409       } else {
410         usage("Unknown flag: " + flag);
411       }
412     }
413   } // end main
414 
415   /**
416    * Prints command line usage.
417    *
418    * @param msg A message to include with usage info.
419    */
420   private static void usage(String msg) {
421     System.err.println(msg);
422     System.err.println("Usage: java Base64 -e|-d inputfile outputfile");
423   } // end usage
424 
425   /* ******** E N C O D I N G   M E T H O D S ******** */
426 
427   /**
428    * Encodes up to the first three bytes of array <var>threeBytes</var> and
429    * returns a four-byte array in Base64 notation. The actual number of
430    * significant bytes in your array is given by <var>numSigBytes</var>. The
431    * array <var>threeBytes</var> needs only be as big as <var>numSigBytes</var>.
432    * Code can reuse a byte array by passing a four-byte array as <var>b4</var>.
433    *
434    * @param b4 A reusable byte array to reduce array instantiation
435    * @param threeBytes the array to convert
436    * @param numSigBytes the number of significant bytes in your array
437    * @param options options for get alphabet
438    * @return four byte array in Base64 notation.
439    * @since 1.5.1
440    */
441   protected static byte[] encode3to4(byte[] b4, byte[] threeBytes,
442       int numSigBytes, int options) {
443     encode3to4(threeBytes, 0, numSigBytes, b4, 0, options);
444     return b4;
445   } // end encode3to4
446 
447   /**
448    * Encodes up to three bytes of the array <var>source</var> and writes the
449    * resulting four Base64 bytes to <var>destination</var>. The source and
450    * destination arrays can be manipulated anywhere along their length by
451    * specifying <var>srcOffset</var> and <var>destOffset</var>. This method
452    * does not check to make sure your arrays are large enough to accomodate
453    * <var>srcOffset</var> + 3 for the <var>source</var> array or
454    * <var>destOffset</var> + 4 for the <var>destination</var> array. The
455    * actual number of significant bytes in your array is given by
456    * <var>numSigBytes</var>.
457    * <p>
458    * This is the lowest level of the encoding methods with all possible
459    * parameters.
460    *
461    * @param source the array to convert
462    * @param srcOffset the index where conversion begins
463    * @param numSigBytes the number of significant bytes in your array
464    * @param destination the array to hold the conversion
465    * @param destOffset the index where output will be put
466    * @param options options for get alphabet
467    * @return the <var>destination</var> array
468    * @since 1.3
469    */
470   protected static byte[] encode3to4(byte[] source, int srcOffset,
471       int numSigBytes, byte[] destination, int destOffset, int options) {
472     byte[] ALPHABET = getAlphabet(options);
473 
474     //           1         2         3
475     // 01234567890123456789012345678901 Bit position
476     // --------000000001111111122222222 Array position from threeBytes
477     // --------|    ||    ||    ||    | Six bit groups to index ALPHABET
478     //          >>18  >>12  >> 6  >> 0  Right shift necessary
479     //                0x3f  0x3f  0x3f  Additional AND
480 
481     // Create buffer with zero-padding if there are only one or two
482     // significant bytes passed in the array.
483     // We have to shift left 24 in order to flush out the 1's that appear
484     // when Java treats a value as negative that is cast from a byte to an int.
485     int inBuff =
486         (numSigBytes > 0 ? ((source[srcOffset] << 24) >>> 8) : 0)
487             | (numSigBytes > 1 ? ((source[srcOffset + 1] << 24) >>> 16) : 0)
488             | (numSigBytes > 2 ? ((source[srcOffset + 2] << 24) >>> 24) : 0);
489 
490     switch (numSigBytes) {
491     case 3:
492       destination[destOffset] = ALPHABET[(inBuff >>> 18)];
493       destination[destOffset + 1] = ALPHABET[(inBuff >>> 12) & 0x3f];
494       destination[destOffset + 2] = ALPHABET[(inBuff >>> 6) & 0x3f];
495       destination[destOffset + 3] = ALPHABET[(inBuff) & 0x3f];
496       return destination;
497 
498     case 2:
499       destination[destOffset] = ALPHABET[(inBuff >>> 18)];
500       destination[destOffset + 1] = ALPHABET[(inBuff >>> 12) & 0x3f];
501       destination[destOffset + 2] = ALPHABET[(inBuff >>> 6) & 0x3f];
502       destination[destOffset + 3] = EQUALS_SIGN;
503       return destination;
504 
505     case 1:
506       destination[destOffset] = ALPHABET[(inBuff >>> 18)];
507       destination[destOffset + 1] = ALPHABET[(inBuff >>> 12) & 0x3f];
508       destination[destOffset + 2] = EQUALS_SIGN;
509       destination[destOffset + 3] = EQUALS_SIGN;
510       return destination;
511 
512     default:
513       return destination;
514     } // end switch
515   } // end encode3to4
516 
517   /**
518    * Serializes an object and returns the Base64-encoded version of that
519    * serialized object. If the object cannot be serialized or there is another
520    * error, the method will return <tt>null</tt>. The object is not
521    * GZip-compressed before being encoded.
522    *
523    * @param serializableObject The object to encode
524    * @return The Base64-encoded object
525    * @since 1.4
526    */
527   public static String encodeObject(Serializable serializableObject) {
528     return encodeObject(serializableObject, NO_OPTIONS);
529   } // end encodeObject
530 
531   /**
532    * Serializes an object and returns the Base64-encoded version of that
533    * serialized object. If the object cannot be serialized or there is another
534    * error, the method will return <tt>null</tt>.
535    * <p>
536    * Valid options:
537    * <ul>
538    *   <li>GZIP: gzip-compresses object before encoding it.</li>
539    *   <li>DONT_BREAK_LINES: don't break lines at 76 characters. <i>Note:
540    *     Technically, this makes your encoding non-compliant.</i></li>
541    * </ul>
542    * <p>
543    * Example: <code>encodeObject( myObj, Base64.GZIP )</code> or
544    * <p>
545    * Example:
546    * <code>encodeObject( myObj, Base64.GZIP | Base64.DONT_BREAK_LINES )</code>
547    *
548    * @param serializableObject The object to encode
549    * @param options Specified options
550    * @see Base64#GZIP
551    * @see Base64#DONT_BREAK_LINES
552    * @return The Base64-encoded object
553    * @since 2.0
554    */
555   @SuppressWarnings({"ConstantConditions"})
556   public static String encodeObject(Serializable serializableObject,
557       int options) {
558 
559     ByteArrayOutputStream baos = new ByteArrayOutputStream();
560     OutputStream b64os = null;
561     ObjectOutputStream oos = null;
562     try {
563       // ObjectOutputStream -> (GZIP) -> Base64 -> ByteArrayOutputStream
564       b64os = new Base64OutputStream(baos, ENCODE | options);
565 
566       oos = ((options & GZIP) == GZIP) ?
567           new ObjectOutputStream(new GZIPOutputStream(b64os)) :
568             new ObjectOutputStream(b64os);
569 
570       oos.writeObject(serializableObject);
571       return new String(baos.toByteArray(), PREFERRED_ENCODING);
572 
573     } catch (UnsupportedEncodingException uue) {
574       return new String(baos.toByteArray());
575 
576     } catch (IOException e) {
577       LOG.error("error encoding object", e);
578       return null;
579 
580     } finally {
581       if (oos != null) {
582         try {
583           oos.close();
584         } catch (Exception e) {
585           LOG.error("error closing ObjectOutputStream", e);
586         }
587       }
588       if (b64os != null) {
589         try {
590           b64os.close();
591         } catch (Exception e) {
592           LOG.error("error closing Base64OutputStream", e);
593         }
594       }
595       try {
596         baos.close();
597       } catch (Exception e) {
598         LOG.error("error closing ByteArrayOutputStream", e);
599       }
600     } // end finally
601   } // end encode
602 
603   /**
604    * Encodes a byte array into Base64 notation. Does not GZip-compress data.
605    *
606    * @param source The data to convert
607    * @return encoded byte array
608    * @since 1.4
609    */
610   public static String encodeBytes(byte[] source) {
611     return encodeBytes(source, 0, source.length, NO_OPTIONS);
612   } // end encodeBytes
613 
614   /**
615    * Encodes a byte array into Base64 notation.
616    * <p>
617    * Valid options:
618    * <ul>
619    *   <li>GZIP: gzip-compresses object before encoding it.</li>
620    *   <li>DONT_BREAK_LINES: don't break lines at 76 characters. <i>Note:
621    *     Technically, this makes your encoding non-compliant.</i></li>
622    * </ul>
623    *
624    * <p>
625    * Example: <code>encodeBytes( myData, Base64.GZIP )</code> or
626    * <p>
627    * Example:
628    * <code>encodeBytes( myData, Base64.GZIP | Base64.DONT_BREAK_LINES )</code>
629    *
630    * @param source The data to convert
631    * @param options Specified options
632    * @see Base64#GZIP
633    * @see Base64#DONT_BREAK_LINES
634    * @see Base64#URL_SAFE
635    * @see Base64#ORDERED
636    * @return encoded byte array
637    * @since 2.0
638    */
639   public static String encodeBytes(byte[] source, int options) {
640     return encodeBytes(source, 0, source.length, options);
641   } // end encodeBytes
642 
643   /**
644    * Encodes a byte array into Base64 notation. Does not GZip-compress data.
645    *
646    * @param source The data to convert
647    * @param off Offset in array where conversion should begin
648    * @param len Length of data to convert
649    * @return encoded byte array
650    * @since 1.4
651    */
652   public static String encodeBytes(byte[] source, int off, int len) {
653     return encodeBytes(source, off, len, NO_OPTIONS);
654   } // end encodeBytes
655 
656   /**
657    * Encodes a byte array into Base64 notation.
658    * <p>
659    * Valid options:
660    * <ul>
661    *   <li>GZIP: gzip-compresses object before encoding it.</li>
662    *   <li>DONT_BREAK_LINES: don't break lines at 76 characters. <i>Note:
663    *     Technically, this makes your encoding non-compliant.</i></li>
664    * </ul>
665    *
666    * <p>
667    * Example: <code>encodeBytes( myData, Base64.GZIP )</code> or
668    * <p>
669    * Example:
670    * <code>encodeBytes( myData, Base64.GZIP | Base64.DONT_BREAK_LINES )</code>
671    *
672    * @param source The data to convert
673    * @param off Offset in array where conversion should begin
674    * @param len Length of data to convert
675    * @param options Specified options
676    * @see Base64#GZIP
677    * @see Base64#DONT_BREAK_LINES
678    * @see Base64#URL_SAFE
679    * @see Base64#ORDERED
680    * @return encoded byte array
681    * @since 2.0
682    */
683   public static String encodeBytes(byte[] source, int off, int len, int options) {
684     if ((options & GZIP) == GZIP) {                             // Compress?
685       // GZip -> Base64 -> ByteArray
686       ByteArrayOutputStream baos = new ByteArrayOutputStream();
687       GZIPOutputStream gzos = null;
688 
689       try {
690         gzos =
691           new GZIPOutputStream(new Base64OutputStream(baos, ENCODE | options));
692 
693         gzos.write(source, off, len);
694         gzos.close();
695         gzos = null;
696         return new String(baos.toByteArray(), PREFERRED_ENCODING);
697 
698       } catch (UnsupportedEncodingException uue) {
699         return new String(baos.toByteArray());
700 
701       } catch (IOException e) {
702         LOG.error("error encoding byte array", e);
703         return null;
704 
705       } finally {
706         if (gzos != null) {
707           try {
708             gzos.close();
709           } catch (Exception e) {
710             LOG.error("error closing GZIPOutputStream", e);
711           }
712         }
713         try {
714           baos.close();
715         } catch (Exception e) {
716           LOG.error("error closing ByteArrayOutputStream", e);
717         }
718       } // end finally
719 
720     } // end Compress
721 
722     // Don't compress. Better not to use streams at all then.
723 
724     boolean breakLines = ((options & DONT_BREAK_LINES) == 0);
725 
726     int len43 = len * 4 / 3;
727     byte[] outBuff =
728       new byte[(len43)                                          // Main 4:3
729                + ((len % 3) > 0 ? 4 : 0)                        // padding
730                + (breakLines ? (len43 / MAX_LINE_LENGTH) : 0)]; // New lines
731     int d = 0;
732     int e = 0;
733     int len2 = len - 2;
734     int lineLength = 0;
735     for (; d < len2; d += 3, e += 4) {
736       encode3to4(source, d + off, 3, outBuff, e, options);
737 
738       lineLength += 4;
739       if (breakLines && lineLength == MAX_LINE_LENGTH) {
740         outBuff[e + 4] = NEW_LINE;
741         e++;
742         lineLength = 0;
743       } // end if: end of line
744     } // end for: each piece of array
745 
746     if (d < len) {
747       encode3to4(source, d + off, len - d, outBuff, e, options);
748       e += 4;
749     } // end if: some padding needed
750 
751     // Return value according to relevant encoding.
752     try {
753       return new String(outBuff, 0, e, PREFERRED_ENCODING);
754 
755     } catch (UnsupportedEncodingException uue) {
756       return new String(outBuff, 0, e);
757     }
758   } // end encodeBytes
759 
760   /* ******** D E C O D I N G   M E T H O D S ******** */
761 
762   /**
763    * Decodes four bytes from array <var>source</var> and writes the resulting
764    * bytes (up to three of them) to <var>destination</var>. The source and
765    * destination arrays can be manipulated anywhere along their length by
766    * specifying <var>srcOffset</var> and <var>destOffset</var>. This method
767    * does not check to make sure your arrays are large enough to accomodate
768    * <var>srcOffset</var> + 4 for the <var>source</var> array or
769    * <var>destOffset</var> + 3 for the <var>destination</var> array. This
770    * method returns the actual number of bytes that were converted from the
771    * Base64 encoding.
772    * <p>
773    * This is the lowest level of the decoding methods with all possible
774    * parameters.
775    * </p>
776    *
777    * @param source the array to convert
778    * @param srcOffset the index where conversion begins
779    * @param destination the array to hold the conversion
780    * @param destOffset the index where output will be put
781    * @param options options for getDecoabet
782    * @see Base64#URL_SAFE
783    * @see Base64#ORDERED
784    * @return the number of decoded bytes converted
785    * @since 1.3
786    */
787   @SuppressWarnings({"ConstantConditions"})
788   protected static int decode4to3(byte[] source, int srcOffset,
789       byte[] destination, int destOffset, int options) {
790     byte[] DECODABET = getDecodabet(options);
791 
792     if (source[srcOffset + 2] == EQUALS_SIGN) {                 // Example: Dk==
793       // Two ways to do the same thing. Don't know which way I like best.
794       // int outBuff = ( ( DECODABET[ source[ srcOffset ] ] << 24 ) >>> 6 )
795       // | ( ( DECODABET[ source[ srcOffset + 1] ] << 24 ) >>> 12 );
796       int outBuff =
797           ((DECODABET[source[srcOffset]] & 0xFF) << 18)
798               | ((DECODABET[source[srcOffset + 1]] & 0xFF) << 12);
799 
800       destination[destOffset] = (byte) (outBuff >>> 16);
801       return 1;
802 
803     } else if (source[srcOffset + 3] == EQUALS_SIGN) {          // Example: DkL=
804       // Two ways to do the same thing. Don't know which way I like best.
805       // int outBuff = ( ( DECODABET[ source[ srcOffset ] ] << 24 ) >>> 6 )
806       // | ( ( DECODABET[ source[ srcOffset + 1 ] ] << 24 ) >>> 12 )
807       // | ( ( DECODABET[ source[ srcOffset + 2 ] ] << 24 ) >>> 18 );
808       int outBuff =
809           ((DECODABET[source[srcOffset]] & 0xFF) << 18)
810               | ((DECODABET[source[srcOffset + 1]] & 0xFF) << 12)
811               | ((DECODABET[source[srcOffset + 2]] & 0xFF) << 6);
812 
813       destination[destOffset] = (byte) (outBuff >>> 16);
814       destination[destOffset + 1] = (byte) (outBuff >>> 8);
815       return 2;
816 
817     } else {                                                    // Example: DkLE
818       try {
819         // Two ways to do the same thing. Don't know which way I like best.
820         // int outBuff = ( ( DECODABET[ source[ srcOffset ] ] << 24 ) >>> 6 )
821         // | ( ( DECODABET[ source[ srcOffset + 1 ] ] << 24 ) >>> 12 )
822         // | ( ( DECODABET[ source[ srcOffset + 2 ] ] << 24 ) >>> 18 )
823         // | ( ( DECODABET[ source[ srcOffset + 3 ] ] << 24 ) >>> 24 );
824         int outBuff =
825             ((DECODABET[source[srcOffset]] & 0xFF) << 18)
826                 | ((DECODABET[source[srcOffset + 1]] & 0xFF) << 12)
827                 | ((DECODABET[source[srcOffset + 2]] & 0xFF) << 6)
828                 | ((DECODABET[source[srcOffset + 3]] & 0xFF));
829 
830         destination[destOffset] = (byte) (outBuff >> 16);
831         destination[destOffset + 1] = (byte) (outBuff >> 8);
832         destination[destOffset + 2] = (byte) (outBuff);
833 
834         return 3;
835 
836       } catch (Exception e) {
837         LOG.error("error decoding bytes at " + source[srcOffset] + ": " +
838             (DECODABET[source[srcOffset]]) + ", " + source[srcOffset + 1] +
839             ": " + (DECODABET[source[srcOffset + 1]]) + ", " +
840             source[srcOffset + 2] + ": " + (DECODABET[source[srcOffset + 2]]) +
841             ", " + source[srcOffset + 3] + ": " +
842             (DECODABET[source[srcOffset + 3]]), e);
843         return -1;
844       } // end catch
845     }
846   } // end decodeToBytes
847 
848   /**
849    * Very low-level access to decoding ASCII characters in the form of a byte
850    * array. Does not support automatically gunzipping or any other "fancy"
851    * features.
852    *
853    * @param source The Base64 encoded data
854    * @param off The offset of where to begin decoding
855    * @param len The length of characters to decode
856    * @param options options for getDecodabet
857    * @see Base64#URL_SAFE
858    * @see Base64#ORDERED
859    * @return decoded data
860    * @since 1.3
861    */
862   public static byte[] decode(byte[] source, int off, int len, int options) {
863     byte[] DECODABET = getDecodabet(options);
864 
865     int len34 = len * 3 / 4;
866     byte[] outBuff = new byte[len34];           // Upper limit on size of output
867     int outBuffPosn = 0;
868 
869     byte[] b4 = new byte[4];
870     int b4Posn = 0;
871     int i;
872     byte sbiCrop;
873     byte sbiDecode;
874     for (i = off; i < off + len; i++) {
875       sbiCrop = (byte) (source[i] & 0x7f);      // Only the low seven bits
876       sbiDecode = DECODABET[sbiCrop];
877 
878       if (sbiDecode >= WHITE_SPACE_ENC) {       // Whitespace, Equals or better
879         if (sbiDecode >= EQUALS_SIGN_ENC) {     // Equals or better
880           b4[b4Posn++] = sbiCrop;
881           if (b4Posn > 3) {
882             outBuffPosn += decode4to3(b4, 0, outBuff, outBuffPosn, options);
883             b4Posn = 0;
884 
885             // If that was the equals sign, break out of 'for' loop
886             if (sbiCrop == EQUALS_SIGN)
887               break;
888           } // end if: quartet built
889         } // end if: equals sign or better
890       } else {
891         LOG.error("Bad Base64 input character at " + i + ": " + source[i] +
892             "(decimal)");
893         return null;
894       } // end else:
895     } // each input character
896 
897     byte[] out = new byte[outBuffPosn];
898     System.arraycopy(outBuff, 0, out, 0, outBuffPosn);
899     return out;
900   } // end decode
901 
902   /**
903    * Decodes data from Base64 notation, automatically detecting gzip-compressed
904    * data and decompressing it.
905    *
906    * @param s the string to decode
907    * @return the decoded data
908    * @since 1.4
909    */
910   public static byte[] decode(String s) {
911     return decode(s, NO_OPTIONS);
912   }
913 
914   /**
915    * Decodes data from Base64 notation, automatically detecting gzip-compressed
916    * data and decompressing it.
917    *
918    * @param s the string to decode
919    * @param options options for decode
920    * @see Base64#URL_SAFE
921    * @see Base64#ORDERED
922    * @return the decoded data
923    * @since 1.4
924    */
925   public static byte[] decode(String s, int options) {
926     byte[] bytes;
927     try {
928       bytes = s.getBytes(PREFERRED_ENCODING);
929 
930     } catch (UnsupportedEncodingException uee) {
931       bytes = s.getBytes();
932     } // end catch
933 
934     // Decode
935 
936     bytes = decode(bytes, 0, bytes.length, options);
937 
938     // Check to see if it's gzip-compressed
939     // GZIP Magic Two-Byte Number: 0x8b1f (35615)
940 
941     if (bytes != null && bytes.length >= 4) {
942       int head = (bytes[0] & 0xff) | ((bytes[1] << 8) & 0xff00);
943       if (GZIPInputStream.GZIP_MAGIC == head) {
944         GZIPInputStream gzis = null;
945         ByteArrayOutputStream baos = new ByteArrayOutputStream();
946         try {
947           gzis = new GZIPInputStream(new ByteArrayInputStream(bytes));
948 
949           byte[] buffer = new byte[2048];
950           for (int length; (length = gzis.read(buffer)) >= 0; ) {
951             baos.write(buffer, 0, length);
952           } // end while: reading input
953 
954           // No error? Get new bytes.
955           bytes = baos.toByteArray();
956 
957         } catch (IOException e) {
958           // Just return originally-decoded bytes
959 
960         } finally {
961           try {
962             baos.close();
963           } catch (Exception e) {
964             LOG.error("error closing ByteArrayOutputStream", e);
965           }
966           if (gzis != null) {
967             try {
968               gzis.close();
969             } catch (Exception e) {
970               LOG.error("error closing GZIPInputStream", e);
971             }
972           }
973         } // end finally
974       } // end if: gzipped
975     } // end if: bytes.length >= 2
976 
977     return bytes;
978   } // end decode
979 
980   /**
981    * Attempts to decode Base64 data and deserialize a Java Object within.
982    * Returns <tt>null</tt> if there was an error.
983    *
984    * @param encodedObject The Base64 data to decode
985    * @return The decoded and deserialized object
986    * @since 1.5
987    */
988   public static Object decodeToObject(String encodedObject) {
989     // Decode and gunzip if necessary
990     byte[] objBytes = decode(encodedObject);
991 
992     Object obj = null;
993     ObjectInputStream ois = null;
994     try {
995       ois = new ObjectInputStream(new ByteArrayInputStream(objBytes));
996       obj = ois.readObject();
997 
998     } catch (IOException e) {
999       LOG.error("error decoding object", e);
1000 
1001     } catch (ClassNotFoundException e) {
1002       LOG.error("error decoding object", e);
1003 
1004     } finally {
1005       if (ois != null) {
1006         try {
1007           ois.close();
1008         } catch (Exception e) {
1009           LOG.error("error closing ObjectInputStream", e);
1010         }
1011       }
1012     } // end finally
1013 
1014     return obj;
1015   } // end decodeObject
1016 
1017   /**
1018    * Convenience method for encoding data to a file.
1019    *
1020    * @param dataToEncode byte array of data to encode in base64 form
1021    * @param filename Filename for saving encoded data
1022    * @return <tt>true</tt> if successful, <tt>false</tt> otherwise
1023    *
1024    * @since 2.1
1025    */
1026   public static boolean encodeToFile(byte[] dataToEncode, String filename) {
1027     boolean success = false;
1028     Base64OutputStream bos = null;
1029     try {
1030       bos = new Base64OutputStream(new FileOutputStream(filename), ENCODE);
1031       bos.write(dataToEncode);
1032       success = true;
1033 
1034     } catch (IOException e) {
1035       LOG.error("error encoding file: " + filename, e);
1036       success = false;
1037 
1038     } finally {
1039       if (bos != null) {
1040         try {
1041           bos.close();
1042         } catch (Exception e) {
1043           LOG.error("error closing Base64OutputStream", e);
1044         }
1045       }
1046     } // end finally
1047 
1048     return success;
1049   } // end encodeToFile
1050 
1051   /**
1052    * Convenience method for decoding data to a file.
1053    *
1054    * @param dataToDecode Base64-encoded data as a string
1055    * @param filename Filename for saving decoded data
1056    * @return <tt>true</tt> if successful, <tt>false</tt> otherwise
1057    *
1058    * @since 2.1
1059    */
1060   public static boolean decodeToFile(String dataToDecode, String filename) {
1061     boolean success = false;
1062     Base64OutputStream bos = null;
1063     try {
1064       bos = new Base64OutputStream(new FileOutputStream(filename), DECODE);
1065       bos.write(dataToDecode.getBytes(PREFERRED_ENCODING));
1066       success = true;
1067 
1068     } catch (IOException e) {
1069       LOG.error("error decoding to file: " + filename, e);
1070       success = false;
1071 
1072     } finally {
1073       if (bos != null) {
1074         try {
1075           bos.close();
1076         } catch (Exception e) {
1077           LOG.error("error closing Base64OutputStream", e);
1078         }
1079       }
1080     } // end finally
1081 
1082     return success;
1083   } // end decodeToFile
1084 
1085   /**
1086    * Convenience method for reading a base64-encoded file and decoding it.
1087    *
1088    * @param filename Filename for reading encoded data
1089    * @return decoded byte array or null if unsuccessful
1090    *
1091    * @since 2.1
1092    */
1093   public static byte[] decodeFromFile(String filename) {
1094     byte[] decodedData = null;
1095     BufferedInputStream bufferedInputStream = null;
1096     FileInputStream fileInputStream = null;
1097     Base64InputStream base64InputStream = null;
1098     try {
1099       File file = new File(filename);
1100       byte[] buffer;
1101 
1102       // Check the size of file
1103       if (file.length() > Integer.MAX_VALUE) {
1104         LOG.fatal("File is too big for this convenience method (" +
1105             file.length() + " bytes).");
1106         return null;
1107       } // end if: file too big for int index
1108 
1109       buffer = new byte[(int) file.length()];
1110 
1111       // Open a stream
1112       fileInputStream = new FileInputStream(file);
1113       bufferedInputStream = new BufferedInputStream(fileInputStream);
1114       base64InputStream = new Base64InputStream(bufferedInputStream, DECODE);
1115 
1116       // Read until done
1117 
1118       int length = 0;
1119       for (int numBytes; (numBytes = base64InputStream.read(buffer, length, 4096)) >= 0; ) {
1120         length += numBytes;
1121       }
1122 
1123       // Save in a variable to return
1124 
1125       decodedData = new byte[length];
1126       System.arraycopy(buffer, 0, decodedData, 0, length);
1127 
1128     } catch (IOException e) {
1129       LOG.error("Error decoding from file " + filename, e);
1130 
1131     } finally {
1132       if (fileInputStream != null) {
1133         try {
1134           fileInputStream.close();
1135         } catch (Exception e) {
1136           LOG.error("error closing FileInputStream", e);
1137         }
1138       }
1139       if (bufferedInputStream != null) {
1140         try {
1141           bufferedInputStream.close();
1142         } catch (Exception e) {
1143           LOG.error("error closing BufferedInputStream", e);
1144         }
1145       }
1146       if (base64InputStream != null) {
1147         try {
1148           base64InputStream.close();
1149         } catch (Exception e) {
1150           LOG.error("error closing Base64InputStream", e);
1151         }
1152       }
1153     } // end finally
1154 
1155     return decodedData;
1156   } // end decodeFromFile
1157 
1158   /**
1159    * Convenience method for reading a binary file and base64-encoding it.
1160    *
1161    * @param filename Filename for reading binary data
1162    * @return base64-encoded string or null if unsuccessful
1163    *
1164    * @since 2.1
1165    */
1166   public static String encodeFromFile(String filename) {
1167     String encodedData = null;
1168     FileInputStream fileInputStream = null;
1169     BufferedInputStream bufferedInputStream = null;
1170     Base64InputStream base64InputStream = null;
1171 
1172     try {
1173       File file = new File(filename);
1174 
1175       // Need max() for math on small files (v2.2.1)
1176 
1177       byte[] buffer = new byte[Math.max((int) (file.length() * 1.4), 40)];
1178 
1179       // Open a stream
1180 
1181       fileInputStream = new FileInputStream(file);
1182       bufferedInputStream = new BufferedInputStream(fileInputStream);
1183       base64InputStream = new Base64InputStream(bufferedInputStream, ENCODE);
1184 
1185       // Read until done
1186       int length = 0;
1187       for (int numBytes; (numBytes = base64InputStream.read(buffer, length, 4096)) >= 0; ) {
1188         length += numBytes;
1189       }
1190 
1191       // Save in a variable to return
1192 
1193       encodedData = new String(buffer, 0, length, PREFERRED_ENCODING);
1194 
1195     } catch (IOException e) {
1196       LOG.error("Error encoding from file " + filename, e);
1197 
1198     } finally {
1199       // Can't leak exceptions but still need to clean things up.
1200       if (fileInputStream != null) {
1201         try {
1202           fileInputStream.close();
1203         } catch (Exception e) {
1204           LOG.error("error closing FileInputStream", e);
1205         }
1206       }
1207       if (bufferedInputStream != null) {
1208         try {
1209           bufferedInputStream.close();
1210         } catch (Exception e) {
1211           LOG.error("error closing BufferedInputStream", e);
1212         }
1213       }
1214       if (base64InputStream != null) {
1215         try {
1216           base64InputStream.close();
1217         } catch (Exception e) {
1218           LOG.error("error closing Base64InputStream", e);
1219         }
1220       }
1221     } // end finally
1222 
1223     return encodedData;
1224   } // end encodeFromFile
1225 
1226   /**
1227    * Reads <tt>infile</tt> and encodes it to <tt>outfile</tt>.
1228    *
1229    * @param infile Input file
1230    * @param outfile Output file
1231    * @since 2.2
1232    */
1233   public static void encodeFileToFile(String infile, String outfile) {
1234     String encoded = encodeFromFile(infile);
1235     OutputStream out = null;
1236     try {
1237       out = new BufferedOutputStream(new FileOutputStream(outfile));
1238       out.write(encoded.getBytes("US-ASCII")); // Strict, 7-bit output.
1239 
1240     } catch (IOException e) {
1241       LOG.error("error encoding from file " + infile + " to " + outfile, e);
1242 
1243     } finally {
1244       if (out != null) {
1245         try {
1246           out.close();
1247         } catch (Exception e) {
1248           LOG.error("error closing " + outfile, e);
1249         }
1250       }
1251     } // end finally
1252   } // end encodeFileToFile
1253 
1254   /**
1255    * Reads <tt>infile</tt> and decodes it to <tt>outfile</tt>.
1256    *
1257    * @param infile Input file
1258    * @param outfile Output file
1259    * @since 2.2
1260    */
1261   public static void decodeFileToFile(String infile, String outfile) {
1262     byte[] decoded = decodeFromFile(infile);
1263     OutputStream out = null;
1264     try {
1265       out = new BufferedOutputStream(new FileOutputStream(outfile));
1266       out.write(decoded);
1267 
1268     } catch (IOException e) {
1269       LOG.error("error decoding from file " + infile + " to " + outfile, e);
1270 
1271     } finally {
1272       if (out != null) {
1273         try {
1274           out.close();
1275         } catch (Exception e) {
1276           LOG.error("error closing " + outfile, e);
1277         }
1278       }
1279     } // end finally
1280   } // end decodeFileToFile
1281 
1282   /* ******** I N N E R   C L A S S   I N P U T S T R E A M ******** */
1283 
1284   /**
1285    * A {@link Base64.Base64InputStream} will read data from another
1286    * <tt>InputStream</tt>, given in the constructor, and
1287    * encode/decode to/from Base64 notation on the fly.
1288    *
1289    * @see Base64
1290    * @since 1.3
1291    */
1292   @InterfaceAudience.Public
1293   @InterfaceStability.Stable
1294   public static class Base64InputStream extends FilterInputStream {
1295     private boolean encode;                     // Encoding or decoding
1296     private int position;                       // Current position in the buffer
1297     private byte[] buffer;                      // Buffer holding converted data
1298     private int bufferLength;                   // Length of buffer (3 or 4)
1299     private int numSigBytes;                    // Meaningful bytes in the buffer
1300     private int lineLength;
1301     private boolean breakLines;                 // Break lines at < 80 characters
1302     private int options;                        // Record options
1303     private byte[] decodabet;                   // Local copy avoids method calls
1304 
1305     /**
1306      * Constructs a {@link Base64InputStream} in DECODE mode.
1307      *
1308      * @param in the <tt>InputStream</tt> from which to read data.
1309      * @since 1.3
1310      */
1311     public Base64InputStream(InputStream in) {
1312       this(in, DECODE);
1313     } // end constructor
1314 
1315     /**
1316      * Constructs a {@link Base64.Base64InputStream} in either ENCODE or DECODE mode.
1317      * <p>
1318      * Valid options:
1319      *
1320      * <pre>
1321      *   ENCODE or DECODE: Encode or Decode as data is read.
1322      *   DONT_BREAK_LINES: don't break lines at 76 characters
1323      *     (only meaningful when encoding)
1324      *     &lt;i&gt;Note: Technically, this makes your encoding non-compliant.&lt;/i&gt;
1325      * </pre>
1326      *
1327      * <p>
1328      * Example: <code>new Base64.Base64InputStream( in, Base64.DECODE )</code>
1329      *
1330      *
1331      * @param in the <tt>InputStream</tt> from which to read data.
1332      * @param options Specified options
1333      * @see Base64#ENCODE
1334      * @see Base64#DECODE
1335      * @see Base64#DONT_BREAK_LINES
1336      * @since 2.0
1337      */
1338     public Base64InputStream(InputStream in, int options) {
1339       super(in);
1340       this.breakLines = (options & DONT_BREAK_LINES) != DONT_BREAK_LINES;
1341       this.encode = (options & ENCODE) == ENCODE;
1342       this.bufferLength = encode ? 4 : 3;
1343       this.buffer = new byte[bufferLength];
1344       this.position = -1;
1345       this.lineLength = 0;
1346       this.options = options; // Record for later, mostly to determine which
1347                               // alphabet to use
1348       this.decodabet = getDecodabet(options);
1349     } // end constructor
1350 
1351     /**
1352      * Reads enough of the input stream to convert to/from Base64 and returns
1353      * the next byte.
1354      *
1355      * @return next byte
1356      * @since 1.3
1357      */
1358     @Override
1359     public int read() throws IOException {
1360       // Do we need to get data?
1361       if (position < 0) {
1362         if (encode) {
1363           byte[] b3 = new byte[3];
1364           int numBinaryBytes = 0;
1365           for (int i = 0; i < 3; i++) {
1366             try {
1367               int b = in.read();
1368 
1369               // If end of stream, b is -1.
1370               if (b >= 0) {
1371                 b3[i] = (byte) b;
1372                 numBinaryBytes++;
1373               } // end if: not end of stream
1374 
1375             } catch (IOException e) {
1376               // Only a problem if we got no data at all.
1377               if (i == 0)
1378                 throw e;
1379 
1380             } // end catch
1381           } // end for: each needed input byte
1382 
1383           if (numBinaryBytes > 0) {
1384             encode3to4(b3, 0, numBinaryBytes, buffer, 0, options);
1385             position = 0;
1386             numSigBytes = 4;
1387 
1388           } else {
1389             return -1;
1390           } // end else
1391 
1392         } else {
1393           byte[] b4 = new byte[4];
1394           int i;
1395           for (i = 0; i < 4; i++) {
1396             // Read four "meaningful" bytes:
1397             int b;
1398             do {
1399               b = in.read();
1400             } while (b >= 0 && decodabet[b & 0x7f] <= WHITE_SPACE_ENC);
1401 
1402             if (b < 0) {
1403               break; // Reads a -1 if end of stream
1404             }
1405 
1406             b4[i] = (byte) b;
1407           } // end for: each needed input byte
1408 
1409           if (i == 4) {
1410             numSigBytes = decode4to3(b4, 0, buffer, 0, options);
1411             position = 0;
1412 
1413           } else if (i == 0) {
1414             return -1;
1415 
1416           } else {
1417             // Must have broken out from above.
1418             throw new IOException("Improperly padded Base64 input.");
1419           } // end
1420         } // end else: decode
1421       } // end else: get data
1422 
1423       // Got data?
1424       if (position >= 0) {
1425         // End of relevant data?
1426         if ( /* !encode && */position >= numSigBytes) {
1427           return -1;
1428         }
1429 
1430         if (encode && breakLines && lineLength >= MAX_LINE_LENGTH) {
1431           lineLength = 0;
1432           return '\n';
1433 
1434         }
1435         lineLength++;                   // This isn't important when decoding
1436                                         // but throwing an extra "if" seems
1437                                         // just as wasteful.
1438 
1439         int b = buffer[position++];
1440 
1441         if (position >= bufferLength)
1442           position = -1;
1443 
1444         return b & 0xFF;                // This is how you "cast" a byte that's
1445                                         // intended to be unsigned.
1446 
1447       }
1448 
1449       // When JDK1.4 is more accepted, use an assertion here.
1450       throw new IOException("Error in Base64 code reading stream.");
1451 
1452     } // end read
1453 
1454     /**
1455      * Calls {@link #read()} repeatedly until the end of stream is reached or
1456      * <var>len</var> bytes are read. Returns number of bytes read into array
1457      * or -1 if end of stream is encountered.
1458      *
1459      * @param dest array to hold values
1460      * @param off offset for array
1461      * @param len max number of bytes to read into array
1462      * @return bytes read into array or -1 if end of stream is encountered.
1463      * @since 1.3
1464      */
1465     @Override
1466     public int read(byte[] dest, int off, int len) throws IOException {
1467       int i;
1468       int b;
1469       for (i = 0; i < len; i++) {
1470         b = read();
1471         if (b >= 0) {
1472           dest[off + i] = (byte) b;
1473         } else if (i == 0) {
1474           return -1;
1475         } else {
1476           break; // Out of 'for' loop
1477         }
1478       } // end for: each byte read
1479       return i;
1480     } // end read
1481 
1482   } // end inner class InputStream
1483 
1484   /* ******** I N N E R   C L A S S   O U T P U T S T R E A M ******** */
1485 
1486   /**
1487    * A {@link Base64.Base64OutputStream} will write data to another
1488    * <tt>OutputStream</tt>, given in the constructor, and
1489    * encode/decode to/from Base64 notation on the fly.
1490    *
1491    * @see Base64
1492    * @since 1.3
1493    */
1494   @InterfaceAudience.Public
1495   @InterfaceStability.Stable
1496   public static class Base64OutputStream extends FilterOutputStream {
1497     private boolean encode;
1498     private int position;
1499     private byte[] buffer;
1500     private int bufferLength;
1501     private int lineLength;
1502     private boolean breakLines;
1503     private byte[] b4;                          // Scratch used in a few places
1504     private boolean suspendEncoding;
1505     private int options;                        // Record for later
1506     private byte[] decodabet;                   // Local copy avoids method calls
1507 
1508     /**
1509      * Constructs a {@link Base64OutputStream} in ENCODE mode.
1510      *
1511      * @param out the <tt>OutputStream</tt> to which data will be written.
1512      * @since 1.3
1513      */
1514     public Base64OutputStream(OutputStream out) {
1515       this(out, ENCODE);
1516     } // end constructor
1517 
1518     /**
1519      * Constructs a {@link Base64OutputStream} in either ENCODE or DECODE mode.
1520      * <p>
1521      * Valid options:
1522      *
1523      * <ul>
1524      *   <li>ENCODE or DECODE: Encode or Decode as data is read.</li>
1525      *   <li>DONT_BREAK_LINES: don't break lines at 76 characters (only
1526      *     meaningful when encoding) <i>Note: Technically, this makes your
1527      *     encoding non-compliant.</i></li>
1528      * </ul>
1529      *
1530      * <p>
1531      * Example: <code>new Base64.Base64OutputStream( out, Base64.ENCODE )</code>
1532      *
1533      * @param out the <tt>OutputStream</tt> to which data will be written.
1534      * @param options Specified options.
1535      * @see Base64#ENCODE
1536      * @see Base64#DECODE
1537      * @see Base64#DONT_BREAK_LINES
1538      * @since 1.3
1539      */
1540     @InterfaceAudience.Public
1541     @InterfaceStability.Stable
1542     public Base64OutputStream(OutputStream out, int options) {
1543       super(out);
1544       this.breakLines = (options & DONT_BREAK_LINES) != DONT_BREAK_LINES;
1545       this.encode = (options & ENCODE) == ENCODE;
1546       this.bufferLength = encode ? 3 : 4;
1547       this.buffer = new byte[bufferLength];
1548       this.position = 0;
1549       this.lineLength = 0;
1550       this.suspendEncoding = false;
1551       this.b4 = new byte[4];
1552       this.options = options;
1553       this.decodabet = getDecodabet(options);
1554     } // end constructor
1555 
1556     /**
1557      * Writes the byte to the output stream after converting to/from Base64
1558      * notation. When encoding, bytes are buffered three at a time before the
1559      * output stream actually gets a write() call. When decoding, bytes are
1560      * buffered four at a time.
1561      *
1562      * @param theByte the byte to write
1563      * @since 1.3
1564      */
1565     @Override
1566     public void write(int theByte) throws IOException {
1567       // Encoding suspended?
1568       if (suspendEncoding) {
1569         super.out.write(theByte);
1570         return;
1571       } // end if: supsended
1572 
1573       // Encode?
1574       if (encode) {
1575         buffer[position++] = (byte) theByte;
1576         if (position >= bufferLength) {                 // Enough to encode.
1577           out.write(encode3to4(b4, buffer, bufferLength, options));
1578           lineLength += 4;
1579           if (breakLines && lineLength >= MAX_LINE_LENGTH) {
1580             out.write(NEW_LINE);
1581             lineLength = 0;
1582           } // end if: end of line
1583 
1584           position = 0;
1585         } // end if: enough to output
1586 
1587       } else {
1588         // Meaningful Base64 character?
1589         if (decodabet[theByte & 0x7f] > WHITE_SPACE_ENC) {
1590           buffer[position++] = (byte) theByte;
1591           if (position >= bufferLength) {               // Enough to output.
1592             int len = decode4to3(buffer, 0, b4, 0, options);
1593             out.write(b4, 0, len);
1594             position = 0;
1595           } // end if: enough to output
1596 
1597         } else if (decodabet[theByte & 0x7f] != WHITE_SPACE_ENC) {
1598           throw new IOException("Invalid character in Base64 data.");
1599         } // end else: not white space either
1600       } // end else: decoding
1601     } // end write
1602 
1603     /**
1604      * Calls {@link #write(int)} repeatedly until <var>len</var> bytes are
1605      * written.
1606      *
1607      * @param theBytes array from which to read bytes
1608      * @param off offset for array
1609      * @param len max number of bytes to read into array
1610      * @since 1.3
1611      */
1612     @Override
1613     public void write(byte[] theBytes, int off, int len) throws IOException {
1614       // Encoding suspended?
1615       if (suspendEncoding) {
1616         super.out.write(theBytes, off, len);
1617         return;
1618       } // end if: supsended
1619 
1620       for (int i = 0; i < len; i++) {
1621         write(theBytes[off + i]);
1622       } // end for: each byte written
1623 
1624     } // end write
1625 
1626     /**
1627      * Method added by PHIL. [Thanks, PHIL. -Rob] This pads the buffer without
1628      * closing the stream.
1629      *
1630      * @throws IOException e
1631      */
1632     public void flushBase64() throws IOException {
1633       if (position > 0) {
1634         if (encode) {
1635           out.write(encode3to4(b4, buffer, position, options));
1636           position = 0;
1637 
1638         } else {
1639           throw new IOException("Base64 input not properly padded.");
1640         } // end else: decoding
1641       } // end if: buffer partially full
1642 
1643     } // end flush
1644 
1645     /**
1646      * Flushes and closes (I think, in the superclass) the stream.
1647      *
1648      * @since 1.3
1649      */
1650     @Override
1651     public void close() throws IOException {
1652       // 1. Ensure that pending characters are written
1653       flushBase64();
1654 
1655       // 2. Actually close the stream
1656       // Base class both flushes and closes.
1657       super.close();
1658 
1659       buffer = null;
1660       out = null;
1661     } // end close
1662 
1663     /**
1664      * Suspends encoding of the stream. May be helpful if you need to embed a
1665      * piece of base640-encoded data in a stream.
1666      *
1667      * @throws IOException e
1668      * @since 1.5.1
1669      */
1670     public void suspendEncoding() throws IOException {
1671       flushBase64();
1672       this.suspendEncoding = true;
1673     } // end suspendEncoding
1674 
1675     /**
1676      * Resumes encoding of the stream. May be helpful if you need to embed a
1677      * piece of base640-encoded data in a stream.
1678      *
1679      * @since 1.5.1
1680      */
1681     public void resumeEncoding() {
1682       this.suspendEncoding = false;
1683     } // end resumeEncoding
1684 
1685   } // end inner class OutputStream
1686 
1687 } // end class Base64