/*
 * @(#)Codec.java    1.0  7 February 2001
 *
 * Copyright 2004
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.codec;

import java.text.ParseException;

/**
 * <P>Interface describing the required functionality of a
 * class of objects whose instances can be used 
 * to encode and decode data <CODE>{@link String String}</CODE>s
 * using a recursively-enabled data language.</P>
 *
 * <P>In short, an class implementing this interface 
 * must be able to encode an array of data <CODE>String</CODE>s 
 * into a single, compound data <CODE>String</CODE> 
 * that can later be decoded back to the original array 
 * of data <CODE>String</CODE>s.
 *
 * Implementation details such as the encoding scheme, 
 * compression ratio, or information loss, are specific 
 * to a class that implements this interface.</P>
 *
 * <P>A CODEC class may only be used 
 * after an instance of the class has been installed 
 * using the <CODE>{@link CodecUtilities#installCodec(Codec) 
 * CodecUtilities.installCodec(Codec)}</CODE> method.
 *
 * The standard CODECs provided by the JPT,
 * whose CODEC identifiers are "CPC" and "ESC",
 * and are defined in classes
 * <CODE>{@link CountPrefixCodec CountPrefixCodec}</CODE> and
 * <CODE>{@link EscapedCodec EscapedCodec}</CODE> respectively,
 * are installed by default by the JPT,
 * and may be used at any time.</P>
 * 
 * @author  Jeff Raab
 * @version 2.2
 * @since   1.0
 * @see CodecUtilities
 */
public interface Codec {
    
    /**
     * Encodes the given array of data <CODE>String</CODE>s
     * into a single compound data <CODE>String</CODE> 
     * using the encoding scheme for this class.
     *
     * @param data an array of data <CODE>String</CODE>s
     * @return the resulting encoded <CODE>String</CODE>
     * @see #decode(String)
     * @see CodecUtilities#encode(String[])
     * @see CodecUtilities#encode(Stringable[])
     */
    public String encode(String[] data);
    
    /**
     * Decodes the given compound data <CODE>String</CODE> 
     * into an array of data <CODE>String</CODE>s 
     * using the encoding scheme for this class.
     *
     * @param data an encoded data <CODE>String</CODE>
     * @return the resulting array of data <CODE>String</CODE>s
     * @throws ParseException if the data was not encoded 
     *		using this scheme
     * @see #encode(String[])
     * @see CodecUtilities#decode(String)
     */
    public String[] decode(String data) throws ParseException;
    
    /**
     * Returns the unique three character prefix 
     * used to identify the encoding scheme for this class
     */
    public String getPrefix();
}