Manuale di javabase64 1.3

Indice

Requisiti
Installazione
Javadoc
Per cominciare
Encoding con Base64OutputStream
Decoding con Base64InputStream

Requisiti

Per eseguire ed utilizzare la libreria javabase64 serve un Java Runtime Environment J2SE versione 1.2 o successiva.

Installazione

Il file javabase64-1.3.jar deve essere inserito nel CLASSPATH dell'applicazione.

Javadoc

Ecco i javadoc di javabase64.

Per cominciare

La libreria javabase64 comprende due stream ed una classe di utilità

La classe di utilità it.sauronsoftware.base64.Base64, nella maggior parte dei casi, dispone di tutto ciò di cui si ha bisogno per codificare e decodificare dei flussi Base64.

Per prima cosa bisogna distinguere il caso in cui l'informazione da codificare o decodificare è di tipo testuale da quando l'informazione è invece di tipo binario.

Per codificare una stringa, quindi un'informazione testuale, è sufficiente chiamare:

String encoded = Base64.encode("Ciao, mondo!");

Il risultato di questa operazione è una seconda stringa codificata in Base64, che può successivamente essere decodificata chiamando:

String decoded = Base64.decode(encoded);

E' possibile forzare l'uso di uno specifico charset durante le operazioni di codifica e decodifica dei testi:

String encoded = Base64.encode("Ciao, mondo!", "UTF-8");
String decoded = Base64.decode(encoded, "UTF-8");

Quando si lavora con i dati binari (ad esempio con delle immagini) è meglio utilizzare le altre forme dei metodi encode() e decode() messe a disposizione dalla classe.

Se i dati trattati non sono troppi, è possibile gestirli mantenendoli direttamente in memoria mediante un array di byte:

byte[] source = ...; // caricamento dei dati qui
byte[] encoded = Base64.encode(source);
byte[] decoded = Base64.decode(encoded);

I dati di grossa mole, invece di tenerli in memoria, è meglio gestirli con gli stream. Il prossimo esempio codifica i contenuti di un file scrivendoli direttamente all'interno di un secondo file, facendo uso di oggetti di tipo java.io.InputStream e java.io.OutputStream:

InputStream inputStream = new FileInputStream("source.jpg");
OutputStream outputStream = new FileOutputStream("encoded.b64");
Base64.encode(inputStream, outputStream);
outputStream.close();
inputStream.close();

In maniera simile, uno stream può essere decodificato:

InputStream inputStream = new FileInputStream("encoded.b64");
OutputStream outputStream = new FileOutputStream("decoded.jpg");
Base64.decode(inputStream, outputStream);
outputStream.close();
inputStream.close();

Sono disponibili anche delle facilitazioni per chi lavora con gli oggetti java.io.File di Java. Ecco come codificare direttamente da un file ad un altro:

File source = new File("source.jpg");
File encoded = new File("encoded.b64");
Base64.encode(source, encoded);

Ed ecco come compiere l'operazione inversa:

File encoded = new File("encoded.b64");
File decoded = new File("decoded.jpg");
Base64.decode(encoded, decoded);

Encoding con Base64OutputStream

Si può ottenere un controllo più di dettaglio sulle operazioni di codifica utilizzando la classe it.sauronsoftware.base64.Base64OutputStream.

Base64OutputStream estende java.io.OutputStream e si comporta proprio come un comune output stream di Java.

Un Base64OutputStream va creato avvolgendo un altro OutputStream stabilito in precedenza:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream);

Ad esempio si possono mandare i dati codificati direttamente ad un file:

Base64OutputStream encodingStream = new Base64OutputStream(new FileOutputStream("encoded.b64"));

Una volta che lo stream è stato aperto è possibile scrivere dati al suo interno, come si farebbe con qualsiasi altro output stream. L'unica differenza è che Base64OutputStream filtra i dati ricevuti, scrivendoli sullo stream sottostante dopo averli codificati in Base64.

encodingStream.write(bytes);

Non si deve dimenticare di chiudere lo stream, una volta che la scrittura è stata completata. Questa operazione è necessaria per rilasciare le risorse e terminare correttamente la codifica dei dati.

encodingStream.close();

Base64OutputStream, ogni 76 byte scritti sull'ouput sottostante, inserisce una sequenza di ritorno a capo. Si tratta di una prassi comune quando si codificano dati Base64. Tale comportamento, ad ogni modo, può essere variato, fornendo al costruttore di Base64OutputStream una dimensione di riga differente:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream, 48);

Un valore più piccolo di 1 disabilita i ritorni a capo automatici, scrivendo i dati tutti su una unica riga:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream, 0);

Decoding con Base64InputStream

Si può ottenere un controllo più di dettaglio sulle operazioni di decodifica utilizzando la classe it.sauronsoftware.base64.Base64InputStream.

Base64InputStream estende java.io.InputStream e si comporta proprio come un comune input stream di Java.

Un Base64InputStream va creato avvolgendo un altro InputStream stabilito in precedenza:

Base64InputStream decodingStream = new Base64InputStream(myInputStream);

Ad esempio si possono leggere dei dati codificati da un file:

Base64InputStream decodingStream = new Base64InputStream(new FileInputStream("encoded.b64"));

Una volta che lo stream è stato aperto è possibile leggere dati dal suo interno, come si farebbe con qualsiasi altro input stream. L'unica differenza è che Base64InputStream filtra i dati letti, restituendoli dopo averli decodificati.

decodingStream.read(bytes);

Non si deve dimenticare di chiudere lo stream, una volta che la lettura è stata completata.

decodingStream.close();