Channel.java

package paulscode.sound;

import java.util.LinkedList;
import javax.sound.sampled.AudioFormat;

/**
 * The Channel class is the base class which can be extended for 
 * library-specific channels.  It is also used in the "no-sound" library.  
 * A channel is a reserved sound-card voice through which sources are played 
 * back.  Channels can be either streaming channels or normal (non-streaming) 
 * ones.  For consistant naming conventions, each sub-class should have the 
 * name prefix "Channel".
 *<br><br>
 *<b><i>    SoundSystem License:</b></i><br><b><br>
 *    You are free to use this library for any purpose, commercial or otherwise.
 *    You may modify this library or source code, and distribute it any way you
 *    like, provided the following conditions are met:
 *<br>
 *    1) You may not falsely claim to be the author of this library or any
 *    unmodified portion of it.
 *<br>
 *    2) You may not copyright this library or a modified version of it and then
 *    sue me for copyright infringement.
 *<br>
 *    3) If you modify the source code, you must clearly document the changes
 *    made before redistributing the modified source code, so other users know
 *    it is not the original code.
 *<br>
 *    4) You are not required to give me credit for this library in any derived
 *    work, but if you do, you must also mention my website:
 *    http://www.paulscode.com
 *<br>
 *    5) I the author will not be responsible for any damages (physical,
 *    financial, or otherwise) caused by the use if this library or any part
 *    of it.
 *<br>
 *    6) I the author do not guarantee, warrant, or make any representations,
 *    either expressed or implied, regarding the use of this library or any
 *    part of it.
 * <br><br>
 *    Author: Paul Lamb
 * <br>
 *    http://www.paulscode.com
 * </b>
 */
public class Channel
{
/**
 * The library class associated with this type of channel.
 */
    protected Class libraryType = Library.class;
    
/**
 * Global identifier for the type of channel (normal or streaming).  Possible 
 * values for this varriable can be found in the 
 * {@link paulscode.sound.SoundSystemConfig SoundSystemConfig} class.
 */
    public int channelType;

/**
 * Processes status messages, warnings, and error messages.
 */
    private SoundSystemLogger logger;

/**
 * Whatever source is attached to this channel.
 */
    public Source attachedSource = null;

/**
 * Cumulative counter of the buffers played then unqued.
 */
    public int buffersUnqueued = 0;
    
/**
 * Constructor:  Takes channelType identifier as a paramater.  Possible values 
 * for channel type can be found in the 
 * {@link paulscode.sound.SoundSystemConfig SoundSystemConfig} class.
 * @param type Type of channel (normal or streaming).
 */
    public Channel( int type )
    {
        // grab a handle to the message logger:
        logger = SoundSystemConfig.getLogger();
        
        channelType = type;
    }
    
/**
 * Shuts the channel down and removes references to all instantiated objects.
 */
    public void cleanup()
    {
        logger = null;
    }
    
/**
 * Queues up the initial byte[] buffers of data to be streamed.
 * @param bufferList List of the first buffers to be played for a streaming source.
 * @return False if an error occurred or if end of stream was reached.
 */
    public boolean preLoadBuffers( LinkedList<byte[]> bufferList )
    {
        return true;
    }
    
/**
 * Queues up a byte[] buffer of data to be streamed.
 * @param buffer The next buffer to be played for a streaming source.
 * @return False if an error occurred or if the channel is shutting down.
 */
    public boolean queueBuffer( byte[] buffer )
    {
        return false;
    }

/**
 * Feeds raw data to the stream.
 * @param buffer Buffer containing raw audio data to stream.
 * @return Number of prior buffers that have been processed.
 */
    public int feedRawAudioData( byte[] buffer )
    {
        return 1;
    }
    
/**
 * Returns the number of queued byte[] buffers that have finished playing.
 * @return Number of buffers processed.
 */
    public int buffersProcessed()
    {
        return 0;
    }
    
/**
 * Calculates the number of milliseconds since the channel began playing.
 * @return Milliseconds, or -1 if unable to calculate.
 */
    public float millisecondsPlayed()
    {
        return -1;
    }
/**
 * Plays the next queued byte[] buffer.  This method is run from the seperate 
 * {@link paulscode.sound.StreamThread StreamThread}.
 * @return False when no more buffers are left to process.
 */
    public boolean processBuffer()
    {
        return false;
    }

/**
 * Sets the channel up to receive the specified audio format.
 */
    public void setAudioFormat( AudioFormat audioFormat )
    {}
    
/**
 * Dequeues all previously queued data.
 */
    public void flush()
    {}
    
/**
 * Stops the channel, dequeues any queued data, and closes the channel.
 */
    public void close()
    {}
    
/**
 * Plays the currently attached normal source, opens this channel up for 
 * streaming, or resumes playback if this channel was paused.
 */
    public void play()
    {}
    
/**
 * Temporarily stops playback for this channel.
 */
    public void pause()
    {}
    
/**
 * Stops playback for this channel and rewinds the attached source to the 
 * beginning.
 */
    public void stop()
    {}
    
/**
 * Rewinds the attached source to the beginning.  Stops the source if it was 
 * paused.
 */
    public void rewind()
    {}
    
/**
 * Used to determine if a channel is actively playing a source.  This method 
 * will return false if the channel is paused or stopped and when no data is 
 * queued to be streamed.
 * @return True if this channel is playing a source.
 */
    public boolean playing()
    {
        return false;
    }
    
/**
 * Returns the name of the class.
 * @return "Channel" + library title.
 */
    public String getClassName()
    {
        String libTitle = SoundSystemConfig.getLibraryTitle( libraryType );

        if( libTitle.equals( "No Sound" ) )
            return "Channel";
        else
            return "Channel" + libTitle;
    }
    
/**
 * Prints a message.
 * @param message Message to print.
 */
    protected void message( String message )
    {
        logger.message( message, 0 );
    }
    
/**
 * Prints an important message.
 * @param message Message to print.
 */
    protected void importantMessage( String message )
    {
        logger.importantMessage( message, 0 );
    }
    
/**
 * Prints the specified message if error is true.
 * @param error True or False.
 * @param message Message to print if error is true.
 * @return True if error is true.
 */
    protected boolean errorCheck( boolean error, String message )
    {
        return logger.errorCheck( error, getClassName(), message, 0 );
    }
    
/**
 * Prints an error message.
 * @param message Message to print.
 */
    protected void errorMessage( String message )
    {
        logger.errorMessage( getClassName(), message, 0 );
    }
    
/**
 * Prints an exception's error message followed by the stack trace.
 * @param e Exception containing the information to print.
 */
    protected void printStackTrace( Exception e )
    {
        logger.printStackTrace( e, 1 );
    }
}