org.jmythapi.protocol
Interface IBackendConnection

All Superinterfaces:

IVersionable

All Known Implementing Classes:

BackendConnection

public interface IBackendConnection
extends IVersionable

This interface represents a connection to a MythTV-backend, -recorder or -encoder.

It is used by the IBackend, IRecorder or IRemoteEncoder interfaces to send commands to a backend and to receive the response messages. But it is also possible to create the protocol packets directly and to send them over a backend connection to the MythTV backend.
See IMythPacket for a detailed description how the content of a packet needs to be structured.

Using Request/Response Messages or Packets

When using a backend connection, you can work with packets or messages.

A request message provide a more structured to set request arguments. A response message has additional advantages. All response messages are property-aware. This means that each type of response message has an enumeration property class, describing at which position in the response-arguments list, the value for a specific property can be found. Additionally for each property a version-range is specified, describing in which protocol version a specific property is part of a response.

Read IMythRequest and IMythResponse for detailed informations about request- and response-messages, and MythProtoVersionAnnotation for more infos about protocol versions.

See here for an example how to read request- and response-packets.
See here for an example how to read request- and response-messages.

Usage Examples:

Writing request- and read response-packets:

The following example shows how packets can be written to and read from a backend connection.

   // establish a connection 
   IBackendConnection connection = new BackendConnection("mythbox",6543);
   connection.open();
   
   // annotate the client as monitoring client
   connection.writePacket(new MythPacket(connection.getVersionNr(),"ANN Monitor MythClient 0"));
   
   // check the response
   IMythPacket annResponse = connection.readPacket();
   if(!annResponse.getPacketArg(0).equals("OK")) {
      System.err.println("ANN command failed");
   } else {
      // get the next free recorder
      connection.writePacket(new MythPacket(connection.getVersionNr(),new String[]{
         // the command (incl. space separated command arguments, if required)
         "GET_NEXT_FREE_RECORDER",
         // additional request arguments
         "-1"
      }));
      IMythPacket recorder = connection.readPacket();
      if(recorder.getPacketArg(1).equals("nohost")) {
      	System.out.println("No free recoder available");
      } else {
          // do something with the recorder ....
          System.out.println("Next free recorder is: " + recorder.getPacketArg(0));
      }
   }
   
   // closing the connection
   connection.close();	
 

In the above example the following packets will be send and received.

Establish a connection
21	MYTH_PROTO_VERSION 65
13	ACCEPT[]:[]65
Annotate the client as monitoring client
24	ANN Monitor MythClient 0
2	OK
Get the next free recorder
29	GET_NEXT_FREE_RECORDER[]:[]-1
26	1[]:[]192.168.0.2[]:[]6543
Close the connection
4	DONE

Write request- and read response messages:

To make reading and writing of request and response packets more easy, it is also possible to send request messages to the backend and to convert response packets into more easily to read response messages.

     // get the next free recorder
    connection.writeMessage(new AMythRequest(
       // the command (and additional command arguments, if any)
       new AMythCommand(
          connection.getVersionNr(),
          "GET_NEXT_FREE_RECORDER"
       ),
       // additional request arguments
       "-1"
    ));
 
    // read the response packet
    IMythPacket resp = connection.readPacket();
    
    // convert it into a proper response object
    RecorderInfo recorder = ResponseUtils.readFrom(RecorderInfo.class, resp);
    if(recorder == null) {
       System.out.println("No free recoder available");
    } else {
       // do something with the recorder ....
       System.out.println("Next free recorder is: " + recorder.getRecorderID());
    }
 

See Also:

IMythPacket

Field Summary

static int

DEFAULT_COMMAND_PORT The default MythTV-backend port.

Method Summary

void	addEventListener(IMythEventPacketListener listener) Registers a new event listener.
boolean	canReadData() Checks if data is available to read without blocking.
boolean	canReadPacket() Checks if at least PacketUtils.SIZE_STRING_LENGTH bytes can be read from the underlying input stream without blocking.
void	close() Closes the connection to the MythTV-backend.
void	enableEventListening() Enables event listening.
int	getConnectTimeout()
String	getHostname() Gets the host name of the backend.
int	getPort() Gets the port of the backend.
int	getReadTimeout()
boolean	isClosed() Gets the curernt connection state.
void	open() Opens the connection.
void	open(int streamBufferSize, boolean tcpNoDelay) Opens the connection.
int	readData(byte[] b, int offset, int len) Reads bytes from the socket.
IMythPacket	readPacket() Receives the next packet from the backend.
void	removeEventListener(IMythEventPacketListener listener) Unregisters an event listener.
void	setConnectTimeout(int connectTimeout)
void	setInitialVersionNr(ProtocolVersion initialProtoVersion) Sets the initla protocol-version to use.
void	setMsgDebugOut(PrintStream out) Sets a print stream used to log packets.
void	setReadTimeout(int readTimeout)
void	writeMessage(IMythRequest msg) Sends a request-message to the backend.
void	writePacket(IMythPacket packet) Sends a packet to the backend.

Methods inherited from interface org.jmythapi.IVersionable

getVersionNr

Field Detail

DEFAULT_COMMAND_PORT

static final int DEFAULT_COMMAND_PORT

The default MythTV-backend port.

See Also:

Constant Field Values

Method Detail

getConnectTimeout

int getConnectTimeout()

setConnectTimeout

void setConnectTimeout(int connectTimeout)

getReadTimeout

int getReadTimeout()

setReadTimeout

void setReadTimeout(int readTimeout)

setMsgDebugOut

void setMsgDebugOut(PrintStream out)

Sets a print stream used to log packets.

This method sets a print-stream that is used to log incoming and outgoing packets.
This is mainly used for debugging.

Usage example

Printing the packets to std-out.

    backendConnection.setMsgDebugOut(System.out);
  

Due to the above statement the following will be printed to std-out, e.g.

Parameters:

out - a print-stream to log messages.

setInitialVersionNr

void setInitialVersionNr(ProtocolVersion initialProtoVersion)
                         throws IllegalStateException

Sets the initla protocol-version to use.

This function sets the initial protocol-version that will be used by the connection during version negotiation in the course of open().

This is mainly usefull to speedup connection establishing.

Parameters:

initialProtoVersion - the initial protocol version.

Throws:

IllegalStateException - if the connection is already opened.

getHostname

String getHostname()

Gets the host name of the backend.

Returns:

the host name of the backend.

getPort

int getPort()

Gets the port of the backend.

Returns:

the port of the backend.

open

void open()
          throws IOException

Opens the connection.

This function opens the connection to the MythTV-backend and negotiates the protocol version to use.

Throws:

IOException - on communication errors.

open

void open(int streamBufferSize,
          boolean tcpNoDelay)
          throws IOException

Opens the connection.

This function opens the connection to the MythTV-backend and negotiates the protocol version to use.

Parameters:

streamBufferSize - the stream buffer size to use

tcpNoDelay -

Throws:

IOException - on communication errors

close

void close()

Closes the connection to the MythTV-backend.

isClosed

boolean isClosed()

Gets the curernt connection state.

Returns:

true if the connection was not established so far or is already closed.

readPacket

IMythPacket readPacket()
                       throws IOException

Receives the next packet from the backend.

Returns:

the next read packet.

Throws:

IOException - on communication errors.

canReadPacket

boolean canReadPacket()
                      throws IOException

Checks if at least PacketUtils.SIZE_STRING_LENGTH bytes can be read from the underlying input stream without blocking.

This function can be used to check if we should start reading the next packet.

Returns:

true if the next packet can be read

Throws:

IOException - on communication errors

writePacket

void writePacket(IMythPacket packet)
                 throws IOException

Sends a packet to the backend.

Parameters:

packet - to packet to transfer

Throws:

IOException - on communication errors.

writeMessage

void writeMessage(IMythRequest msg)
                  throws IOException

Sends a request-message to the backend.

Parameters:

msg - the request message to be send

Throws:

IOException - on communication errors

UnknownCommandException - if the given command is unknown

UnsupportedCommandException - if the given command is not supported by the given protocol version

readData

int readData(byte[] b,
             int offset,
             int len)
             throws IOException

Reads bytes from the socket.

Parameters:

b - the byte array to fill with data

offset - to offset used to start writing into the array

len - the amount of bytes to read

Returns:

the amount of read bytes.

Throws:

IOException - on communication errors

canReadData

boolean canReadData()
                    throws IOException

Checks if data is available to read without blocking.

Returns:

true if at least one byte is available to read without blocking.

Throws:

IOException - on communication errors

enableEventListening

void enableEventListening()

Enables event listening.

This function starts a new thread, which reads incoming IMythPacket and passes them to event listeners, if the received packets are event packets.

addEventListener

void addEventListener(IMythEventPacketListener listener)

Registers a new event listener.

Parameters:

listener - the listener to register

removeEventListener

void removeEventListener(IMythEventPacketListener listener)

Unregisters an event listener.

Parameters:

listener - the listener to unregister.