org.lyra.Host
Class Terminus

java.lang.Object
  org.lyra.Host.Terminus

All Implemented Interfaces:

LossListener

public class Terminus
extends java.lang.Object
implements LossListener

The Terminus Class deals with establishing the Multimedia Player Daemon connection. Effectively creating a terminus at our end enabling us to extract status information and control the player.

Version:

1.0.5, %Revision, 174%, %LastChangedDate, 27/10/12 3:33PM%

Author:

Martin Foster

Field Summary

private int	Attempts
private static int	ATTEMPTS
static java.lang.String	AUDIT_ADDED Descriptor used for the auditing of entries added to the current playlist.
static java.lang.String	AUDIT_REMOVED Descriptor used for the auditing of entries removed to the current playlist.
private static java.lang.String	CLASS
private java.lang.String	dHost
static java.lang.String	DIRECTORY Part of the protocol which is normally ignored by this application.
private java.lang.String	dPass
private java.lang.Integer	dPort
private java.net.Socket	dSocket
private static java.lang.String	ENCODING
private static java.util.List<Terminus>	Instances
private Ledger	Logger
static int	MAX_COL In multiple reply key/pair elements, this defines how many splits can be accomplished.
private LossListener	mySource
static java.lang.String	PLAYLIST Part of the stored playlist listing which defines a new playlist.
static java.util.Map<java.lang.String,java.lang.String>	PROTOCOL The protocol is well defined, however in order to reduce changes to the code if there are changes in the future they have been embedded into a HashMap.
static java.util.TreeSet<java.lang.String>	ROW_ALLOW Certain elements of song information may fall outside what the database allows.
static java.util.TreeSet<java.lang.String>	ROW_REQUIRED Certain elements are required by the database.
static java.lang.String	SECTION Part of the protocol which defines a new song entry.
static java.lang.String	SEPARATOR Separator for key/pair elements.
private java.io.BufferedReader	sIn
private java.io.PrintWriter	sOut
static java.lang.String	STATE_PAUSE Descriptor which applies to the daemon state when playback is paused.
static java.lang.String	STATE_PLAY Descriptor which applies to the daemon state when playback is started.
static java.lang.String	STATE_STOP Descriptor which applies to the daemon state when playback has stopped.
static java.lang.String	UNIQUE Rarely used but at times its useful to know what makes a song set unique which is the existence of the File identifier.
static java.util.Map<java.lang.String,java.lang.String>	UPDATES Holds the update elements and uses terminology that is hopefully less confusing and consistent with the application.
static java.lang.String	UPDATING Element that should never be found when doing a host database synch with our own store.

Constructor Summary

Terminus(Ledger logger, java.lang.String host, java.lang.String port, java.lang.String pass)
Constructor for the class, requires the provision of information related to the host and an optional password.

Terminus(Ledger logger, java.lang.String host, java.lang.String port, java.lang.String pass, LossListener source)
Constructor for the class, requires the provision of information related to the host and an optional password.

Method Summary

boolean	Connect() As the name implies, deals with the connection to the host establishing a socket and permitting command/status information to be passed from connection onward.
void	Disconnect() Prior to exiting we close the connection properly and clean up all memory handles.
void	hostLost(LossEvent e) Notifies a client that the connection to the Music Player Daemon (MPD) has been interrupted.
private java.lang.String	readChannel() It was discovered that channels would return a NullPointerException when the channel is not properly closed such as when the computer is suspended.
java.lang.String	readLine() Basic reading method used to extract a single row of information.
java.util.List<java.lang.String>	readList() Basic reading method used to extract all information.
java.util.List<java.lang.String>	readList(int col) The main readList() method does not parse the line as it is extracted from the socket.
java.util.Map<java.lang.String,java.lang.String>	readMap() Reads and parses the returned input treating it as a Key/Pair structure which is returned by elements like STATS and STATUS of the MPD protocol.
boolean	readResult() This method is used primarily in circumstances where bulk entries are dropped into place.
private boolean	readResult(java.lang.String reply) General method to cover the basics about reading from the protocol in order to avoid repeating the same lines everywhere.
boolean	Recover(java.lang.Exception e) The recover function is used to recover from IOExceptions or NullPointerException that have been triggered.
static boolean	testConnect(java.lang.String host, java.lang.Integer port) Provides a quick and painless way of checking the connection without much overhead.
static boolean	testConnect(java.lang.String host, java.lang.String port) Provides a quick and painless way of checking the connection without much overhead.
void	writeArgument(java.lang.String command, java.lang.String... args) For more complex commands which have a requirement to pass on arguments useful when dealing with the play lists.
void	writeBatch(java.lang.String... command) Method which will write a specific series of commands to the socket for processing by the host.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dHost

private java.lang.String dHost

dPort

private java.lang.Integer dPort

dPass

private java.lang.String dPass

dSocket

private java.net.Socket dSocket

sOut

private java.io.PrintWriter sOut

sIn

private java.io.BufferedReader sIn

mySource

private LossListener mySource

Logger

private Ledger Logger

Attempts

private int Attempts

Instances

private static java.util.List<Terminus> Instances

CLASS

private static final java.lang.String CLASS

See Also:

Constant Field Values

ATTEMPTS

private static final int ATTEMPTS

See Also:

Constant Field Values

ENCODING

private static final java.lang.String ENCODING

See Also:

Constant Field Values

DIRECTORY

public static final java.lang.String DIRECTORY

Part of the protocol which is normally ignored by this application.

See Also:

Constant Field Values

SECTION

public static final java.lang.String SECTION

Part of the protocol which defines a new song entry.

See Also:

Constant Field Values

SEPARATOR

public static final java.lang.String SEPARATOR

Separator for key/pair elements. Used primarily to separate the two elements into a Map.

See Also:

Constant Field Values

PLAYLIST

public static final java.lang.String PLAYLIST

Part of the stored playlist listing which defines a new playlist.

See Also:

Constant Field Values

MAX_COL

public static final int MAX_COL

In multiple reply key/pair elements, this defines how many splits can be accomplished.

See Also:

Constant Field Values

UNIQUE

public static final java.lang.String UNIQUE

Rarely used but at times its useful to know what makes a song set unique which is the existence of the File identifier.

See Also:

Constant Field Values

UPDATING

public static final java.lang.String UPDATING

Element that should never be found when doing a host database synch with our own store. So we check for it to make sure.

See Also:

Constant Field Values

ROW_ALLOW

public static final java.util.TreeSet<java.lang.String> ROW_ALLOW

Certain elements of song information may fall outside what the database allows. Note that this would only happen if new elements were added to the protocol after this version was released.

ROW_REQUIRED

public static final java.util.TreeSet<java.lang.String> ROW_REQUIRED

Certain elements are required by the database. This keeps track of the elements.

PROTOCOL

public static final java.util.Map<java.lang.String,java.lang.String> PROTOCOL

The protocol is well defined, however in order to reduce changes to the code if there are changes in the future they have been embedded into a HashMap.

UPDATES

public static final java.util.Map<java.lang.String,java.lang.String> UPDATES

Holds the update elements and uses terminology that is hopefully less confusing and consistent with the application.

STATE_PLAY

public static final java.lang.String STATE_PLAY

Descriptor which applies to the daemon state when playback is started.

See Also:

Constant Field Values

STATE_PAUSE

public static final java.lang.String STATE_PAUSE

Descriptor which applies to the daemon state when playback is paused.

See Also:

Constant Field Values

STATE_STOP

public static final java.lang.String STATE_STOP

Descriptor which applies to the daemon state when playback has stopped.

See Also:

Constant Field Values

AUDIT_ADDED

public static final java.lang.String AUDIT_ADDED

Descriptor used for the auditing of entries added to the current playlist.

See Also:

Constant Field Values

AUDIT_REMOVED

public static final java.lang.String AUDIT_REMOVED

Descriptor used for the auditing of entries removed to the current playlist.

See Also:

Constant Field Values

Constructor Detail

Terminus

public Terminus(Ledger logger,
                java.lang.String host,
                java.lang.String port,
                java.lang.String pass)

Constructor for the class, requires the provision of information related to the host and an optional password. A null password will result in the class ignoring authentication.

Parameters:

logger - Ledger instance for logging of faults.

host - String containing host name or IP address.

port - String containing the port number.

pass - String containing the optional password.

Terminus

public Terminus(Ledger logger,
                java.lang.String host,
                java.lang.String port,
                java.lang.String pass,
                LossListener source)

Constructor for the class, requires the provision of information related to the host and an optional password. A null password will result in the class ignoring authentication.

Parameters:

logger - Ledger instance for logging of faults.

host - String containing host name or IP address.

port - String containing the port number.

pass - String containing the optional password.

source - LossListener instance to inform up the chain.

Method Detail

Connect

public boolean Connect()

As the name implies, deals with the connection to the host establishing a socket and permitting command/status information to be passed from connection onward.

Returns:

A boolean indicating the success of the operation.

Disconnect

public void Disconnect()

Prior to exiting we close the connection properly and clean up all memory handles.

Recover

public boolean Recover(java.lang.Exception e)

The recover function is used to recover from IOExceptions or NullPointerException that have been triggered. Since that typically means a loss of connection it will attempt to cleanly disconnect and connect once again.

Parameters:

e - Exception received and handled.

Returns:

Has the attempt passed or failed.

readResult

private boolean readResult(java.lang.String reply)
                    throws java.io.IOException

General method to cover the basics about reading from the protocol in order to avoid repeating the same lines everywhere.

Parameters:

reply - Reply received from the host.

Returns:

Boolean indicating continuation.

Throws:

java.io.IOException

readChannel

private java.lang.String readChannel()
                              throws java.io.IOException

It was discovered that channels would return a NullPointerException when the channel is not properly closed such as when the computer is suspended. So we learn to treat them as such.

Returns:

String containing results.

Throws:

java.io.IOException

testConnect

public static boolean testConnect(java.lang.String host,
                                  java.lang.Integer port)

Provides a quick and painless way of checking the connection without much overhead.

Parameters:

host - String containing host element.

port - Integer containing host element.

Returns:

Boolean indicating success.

testConnect

public static boolean testConnect(java.lang.String host,
                                  java.lang.String port)

Provides a quick and painless way of checking the connection without much overhead.

Parameters:

host - String containing host element.

port - String containing host element.

Returns:

Boolean indicating success.

readLine

public java.lang.String readLine()
                          throws java.io.IOException

Basic reading method used to extract a single row of information. Will return the values until the EOL and then return null.

Returns:

String containing result line.

Throws:

java.io.IOException

readList

public java.util.List<java.lang.String> readList()
                                          throws java.io.IOException

Basic reading method used to extract all information. This one will do nothing more then ensure that the correct termination was sent.

Returns:

LinkedList containing results line.

Throws:

java.io.IOException

readList

public java.util.List<java.lang.String> readList(int col)
                                          throws java.io.IOException

The main readList() method does not parse the line as it is extracted from the socket. This one however will parse and bring forth a singular column.

Parameters:

col - Returns elements at specified integer.

Returns:

List of Strings containing split results.

Throws:

java.io.IOException

readMap

public java.util.Map<java.lang.String,java.lang.String> readMap()
                                                         throws java.io.IOException

Reads and parses the returned input treating it as a Key/Pair structure which is returned by elements like STATS and STATUS of the MPD protocol.

Returns:

Map containing the results set.

Throws:

java.io.IOException

readResult

public boolean readResult()
                   throws java.io.IOException,
                          java.lang.NullPointerException

This method is used primarily in circumstances where bulk entries are dropped into place. Since these commands may not necessarily return a specific output, this method will just confirm that everything is good. It also clears that line from input that can cause problems with other commands.

Returns:

boolean indicating result of process.

Throws:

java.io.IOException

java.lang.NullPointerException

writeArgument

public void writeArgument(java.lang.String command,
                          java.lang.String... args)

For more complex commands which have a requirement to pass on arguments useful when dealing with the play lists.

Parameters:

command - String containing completed command.

args - String array containing arguments to pass.

writeBatch

public void writeBatch(java.lang.String... command)

Method which will write a specific series of commands to the socket for processing by the host. Mostly used for status information updates as they will not require the use of arguments.

Parameters:

command - String array of commands which will be sent.

hostLost

public void hostLost(LossEvent e)

Description copied from interface: LossListener

Notifies a client that the connection to the Music Player Daemon (MPD) has been interrupted.

Specified by:

hostLost in interface LossListener

Parameters:

e - Update notification method.

See Also:

UpdateEvent