home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1995 November / PCWK1195.iso / inne / win95 / sieciowe / hotja32.lzh / hotjava / classsrc / java / util / characterencoder.java < prev    next >
Text File  |  1995-08-11  |  5KB  |  165 lines
  1. /*
  2.  * @(#)CharacterEncoder.java    1.6 95/04/02 Chuck McManis
  3.  *
  4.  * Copyright (c) 1994 Sun Microsystems, Inc. All Rights Reserved.
  5.  *
  6.  * Permission to use, copy, modify, and distribute this software
  7.  * and its documentation for NON-COMMERCIAL purposes and without
  8.  * fee is hereby granted provided that this copyright notice
  9.  * appears in all copies. Please refer to the file "copyright.html"
  10.  * for further important copyright and licensing information.
  11.  *
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  13.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  14.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  15.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  16.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  17.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  18.  */
  19.  
  20. package java.util;
  21.  
  22. import java.io.InputStream;
  23. import java.io.InputStreamBuffer;
  24. import java.io.OutputStream;
  25. import java.io.OutputStreamBuffer;
  26. import java.io.PrintStream;
  27.  
  28.  
  29. /**
  30.  * This class defines the encoding half of character encoders.
  31.  * A character encoder is an algorithim for transforming 8 bit binary
  32.  * data into text (generally 7 bit ASCII or 8 bit ISO-Latin-1 text)
  33.  * for transmition over text channels such as e-mail and network news.
  34.  * 
  35.  * The character encoders have been structured around a central theme
  36.  * that, in general, the encoded text has the form:
  37.  *
  38.  * <pre>
  39.  *    [Buffer Prefix]
  40.  *    [Line Prefix][encoded data atoms][Line Suffix]
  41.  *    [Buffer Suffix]
  42.  * </pre>
  43.  *
  44.  * In the CharacterEncoder and CharacterDecoder classes, one complete
  45.  * chunk of data is referred to as a <i>buffer</i>. Encoded buffers 
  46.  * are all text, and decoded buffers (sometimes just referred to as 
  47.  * buffers) are binary octets.
  48.  *
  49.  * To create a custom encoder, you must, at a minimum,  overide three
  50.  * abstract methods in this class.
  51.  * <DL>
  52.  * <DD>bytesPerAtom which tells the encoder how many bytes to 
  53.  * send to encodeAtom
  54.  * <DD>encodeAtom which encodes the bytes sent to it as text.
  55.  * <DD>bytesPerLine which tells the encoder the maximum number of
  56.  * bytes per line.
  57.  * </DL>
  58.  *
  59.  * Several useful encoders have already been written and are 
  60.  * referenced in the See Also list below.
  61.  *
  62.  * @version    02 Apr 1995, 1.6
  63.  * @author    Chuck McManis
  64.  * @see        CharacterDecoder;
  65.  * @see        UCEncoder
  66.  * @see        UUEncoder
  67.  * @see        BASE64Encoder
  68.  */
  69.  
  70. public class CharacterEncoder {
  71.  
  72.     /** Stream that understands "printing" */
  73.     protected PrintStream pStream;
  74.  
  75.     /** Return the number of bytes per atom of encoding */
  76.     abstract int bytesPerAtom();
  77.  
  78.     /** Return the number of bytes that can be encoded per line */
  79.     abstract int bytesPerLine();
  80.  
  81.     /**
  82.      * Encode the prefix for the entire buffer. By default is simply
  83.      * opens the PrintStream for use by the other functions.
  84.      */
  85.     void encodeBufferPrefix(OutputStream aStream) {
  86.     pStream = new PrintStream(aStream);
  87.     }
  88.  
  89.     /**
  90.      * Encode the suffix for the entire buffer.
  91.      */
  92.     void encodeBufferSuffix(OutputStream aStream) { }
  93.  
  94.     /**
  95.      * Encode the prefix that starts every output line.
  96.      */
  97.     void encodeLinePrefix(OutputStream aStream, int aLength) { }
  98.  
  99.     /**
  100.      * Encode the suffix that ends every output line. By default
  101.      * this method just prints a <newline> into the output stream.
  102.      */
  103.     void encodeLineSuffix(OutputStream aStream) {
  104.     pStream.println();
  105.     }
  106.  
  107.     /** Encode one "atom" of information into characters. */
  108.     abstract void encodeAtom(OutputStream aStream, byte someBytes[],
  109.         int anOffset, int aLength);
  110.  
  111.     /**
  112.      * Encode bytes from the input stream, and write them as text characters
  113.      * to the output stream. This method will run until it exhausts the
  114.      * input stream.
  115.      */
  116.     public void encodeBuffer(InputStream inStream, OutputStream outStream) {
  117.     int    j;
  118.     int    numBytes;
  119.     byte    tmpbuffer[] = new byte[bytesPerLine()];
  120.  
  121.     encodeBufferPrefix(outStream);
  122.     
  123.     while (true) {
  124.         numBytes = inStream.read(tmpbuffer);
  125.         if (numBytes == -1) {
  126.         break;
  127.         }
  128.         encodeLinePrefix(outStream, numBytes);
  129.         for (j = 0; j < numBytes; j += bytesPerAtom()) {
  130.         if ((j + bytesPerAtom()) <= numBytes) {
  131.             encodeAtom(outStream, tmpbuffer, j, bytesPerAtom());
  132.         } else {
  133.             encodeAtom(outStream, tmpbuffer, j, tmpbuffer.length - j);
  134.         }
  135.         }
  136.         encodeLineSuffix(outStream);
  137.         if (numBytes < bytesPerLine()) {
  138.         break;    
  139.         }
  140.     }
  141.     encodeBufferSuffix(outStream);
  142.     }
  143.  
  144.     /**
  145.      * Encode the buffer in <i>aBuffer</i> and write the encoded
  146.      * result to the OutputStream <i>aStream</i>.
  147.      */
  148.     public void encodeBuffer(byte aBuffer[], OutputStream aStream) {
  149.     InputStreamBuffer inStream = new InputStreamBuffer(aBuffer);
  150.     encodeBuffer(inStream, aStream);
  151.     }
  152.  
  153.     /**
  154.      * A 'streamless' version of encode that simply takes a buffer of
  155.      * bytes and returns a string containing the encoded buffer.
  156.      */
  157.     public String encodeBuffer(byte aBuffer[]) {
  158.     OutputStreamBuffer    outStream = new OutputStreamBuffer();
  159.     InputStreamBuffer    inStream = new InputStreamBuffer(aBuffer);
  160.     encodeBuffer(inStream, outStream);
  161.     return (outStream.toString());
  162.     }
  163.  
  164. }
  165.