org.jmythapi.protocol.utils
Class CommandUtils

java.lang.Object
  org.jmythapi.protocol.utils.CommandUtils

public class CommandUtils
extends Object

This class provides protocol command related utility functions.

This class can be used to:

• Determine the protocol-version range of a command (link)
• Check if a given command is supported by any known protocol version (link)
• Print out all supported commands for a specific protocol version (link)
• Read a command from a string (link)
• Write a command to an output stream (link)

See Also:

IMythCommand, MythProtoVersionAnnotation

Field Summary

static LinkedHashMap<String,Object[]>	COMMANDS A list of known MythTV-protocol commands.
static String	DELIM

Constructor Summary

CommandUtils()

Method Summary

static MythProtocolCmd	getCommandDeclaration(String commandName, String subCommandName)
static ProtocolVersionRange	getCommandVersionRange(String commandName) Returns the version-range the given command is supported in.
static boolean	isKnownCommand(IMythCommand command) Checks if the command is known to be supported by any supported MythTV version.
static boolean	isKnownCommand(IMythRequest request) Checks if the command of a request is known to be supported by any supported MythTV version.
static boolean	isKnownCommand(String commandName) Checks if a command is known to be supported by any supported MythTV version.
static void	printCommands(ProtocolVersion protoVersion) Prints all MythTV-protocol-commands that are supported by the given protocol-version to stdout.
static IMythCommand	readFrom(ProtocolVersion protoVersion, String commandString) Reads a MythTV protocol command from a string.
static void	writeTo(IMythCommand command, OutputStream output) Writes the given command object to an output stream.

Methods inherited from class java.lang.Object

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

Field Detail

DELIM

public static final String DELIM

See Also:

Constant Field Values

COMMANDS

public static final LinkedHashMap<String,Object[]> COMMANDS

A list of known MythTV-protocol commands.

The key of this map is the command-name, the value is an array containing two elements. The first element is the Field defined in IMythCommand, the second is a LinkedHashMap containing all sub-commands that belong to the command.

Constructor Detail

CommandUtils

public CommandUtils()

Method Detail

printCommands

public static void printCommands(ProtocolVersion protoVersion)

Prints all MythTV-protocol-commands that are supported by the given protocol-version to stdout.

Parameters:

protoVersion - the version for which a commandlist should be printed. Use ProtocolVersion.PROTO_VERSION_LATEST for the current trunk version or null to print all known commands independently of the protocol version.

isKnownCommand

public static boolean isKnownCommand(IMythRequest request)

Checks if the command of a request is known to be supported by any supported MythTV version.

Parameters:

request - the request whose command should be checked

Returns:

true if the given command is supported or false otherwise.

isKnownCommand

public static boolean isKnownCommand(IMythCommand command)

Checks if the command is known to be supported by any supported MythTV version.

Parameters:

command - the command to check

Returns:

true if the given command is supported or false otherwise.

isKnownCommand

public static boolean isKnownCommand(String commandName)

Checks if a command is known to be supported by any supported MythTV version.

Parameters:

commandName - the name of the command, e.g. QUERY_RECORDER

Returns:

true if the given command is supported or false otherwise.

getCommandVersionRange

public static ProtocolVersionRange getCommandVersionRange(String commandName)
                                                   throws UnknownCommandException

Returns the version-range the given command is supported in.

A command can only be used in the version range returned by this method. Otherwise an UnsupportedCommandException will be thrown by the backend-connection.

Usage example:

    // the following will return the version range [9,-1)
    ProtocolVersionRange versionRange = CommandUtils.getCommandVersionRange(IMythCommand.GET_FREE_RECORDER_COUNT);
    System.out.println(versionRange);
 

In the above example the command GET_FREE_RECORDER_COUNT was introduced in protocol version 09 and is supported up to the current protocol version.

Parameters:

commandName - the command name

Returns:

the protocol version range of the command

Throws:

UnknownCommandException - if the command is not supported by any known protocol-version.

getCommandDeclaration

public static MythProtocolCmd getCommandDeclaration(String commandName,
                                                    String subCommandName)
                                             throws UnknownCommandException

Throws:

UnknownCommandException

readFrom

public static final IMythCommand readFrom(ProtocolVersion protoVersion,
                                          String commandString)
                                   throws IllegalArgumentException

Reads a MythTV protocol command from a string.

The given command string is splitted into parts (using the separator DELIM) and thereafter a IMythCommand object is created with the extracted command-name and -arguments.

Usage example:

  String commandString = "ANN Monitor MythClient 0";
  IMythCommand command = CommandUtils.readFrom(PROTO_VERSION_56, commandString);
 

Parameters:

protoVersion - the protocol version of the command

commandString - the command string, e.g. ANN Monitor MythClient 0

Returns:

a command object

Throws:

IllegalArgumentException - if the given command string is invalid

writeTo

public static final void writeTo(IMythCommand command,
                                 OutputStream output)
                          throws UnsupportedEncodingException,
                                 IOException

Writes the given command object to an output stream.

Parameters:

command - the command to write out

output - the output stream.

Throws:

UnsupportedEncodingException - on encoding errors

IOException - on communication errors