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.


Copyright © 2008-2013. All Rights Reserved.