org.teleal.cling.controlpoint
Class SubscriptionCallback

java.lang.Object
  extended by org.teleal.cling.controlpoint.SubscriptionCallback
All Implemented Interfaces:
Runnable

public abstract class SubscriptionCallback
extends Object
implements Runnable

Subscribe and receive events from a service through GENA.

Usage example, establishing a subscription with a Service:

 SubscriptionCallback callback = new SubscriptionCallback(service, 600) { // Timeout in seconds

      public void established(GENASubscription sub) {
          System.out.println("Established: " + sub.getSubscriptionId());
      }

      public void failed(GENASubscription sub, UpnpResponse response, Exception ex) {
          System.err.println(
              createDefaultFailureMessage(response, ex)
          );
      }

      public void ended(GENASubscription sub, CancelReason reason, UpnpResponse response) {
          // Reason should be null, or it didn't end regularly
      }

      public void eventReceived(GENASubscription sub) {
          System.out.println("Event: " + sub.getCurrentSequence().getValue());
          Map<String, StateVariableValue> values = sub.getCurrentValues();
          StateVariableValue status = values.get("Status");
          System.out.println("Status is: " + status.toString());
      }

      public void eventsMissed(GENASubscription sub, int numberOfMissedEvents) {
          System.out.println("Missed events: " + numberOfMissedEvents);
      }
 };

 upnpService.getControlPoint().execute(callback);
 

Author:
Christian Bauer

Field Summary
protected static Logger log
           
protected  Integer requestedDurationSeconds
           
protected  Service service
           
 
Constructor Summary
protected SubscriptionCallback(Service service)
           
protected SubscriptionCallback(Service service, int requestedDurationSeconds)
           
 
Method Summary
static String createDefaultFailureMessage(UpnpResponse responseStatus, Exception exception)
           
 void end()
           
protected abstract  void ended(GENASubscription subscription, CancelReason reason, UpnpResponse responseStatus)
          Called when a local or remote subscription ended, either on user request or because of a failure.
protected abstract  void established(GENASubscription subscription)
          Called when a local or remote subscription was successfully established.
protected abstract  void eventReceived(GENASubscription subscription)
          Called when an event for an established subscription has been received.
protected abstract  void eventsMissed(GENASubscription subscription, int numberOfMissedEvents)
          Called when a received event was out of sequence, indicating that events have been missed.
protected  void failed(GENASubscription subscription, UpnpResponse responseStatus, Exception exception)
           
protected abstract  void failed(GENASubscription subscription, UpnpResponse responseStatus, Exception exception, String defaultMsg)
          Called when establishing a local or remote subscription failed.
 ControlPoint getControlPoint()
           
 Service getService()
           
 GENASubscription getSubscription()
           
 void run()
           
 void setControlPoint(ControlPoint controlPoint)
           
 void setSubscription(GENASubscription subscription)
           
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

log

protected static Logger log

service

protected final Service service

requestedDurationSeconds

protected final Integer requestedDurationSeconds
Constructor Detail

SubscriptionCallback

protected SubscriptionCallback(Service service)

SubscriptionCallback

protected SubscriptionCallback(Service service,
                               int requestedDurationSeconds)
Method Detail

getService

public Service getService()

getControlPoint

public ControlPoint getControlPoint()

setControlPoint

public void setControlPoint(ControlPoint controlPoint)

getSubscription

public GENASubscription getSubscription()

setSubscription

public void setSubscription(GENASubscription subscription)

run

public void run()
Specified by:
run in interface Runnable

end

public void end()

failed

protected void failed(GENASubscription subscription,
                      UpnpResponse responseStatus,
                      Exception exception)

failed

protected abstract void failed(GENASubscription subscription,
                               UpnpResponse responseStatus,
                               Exception exception,
                               String defaultMsg)
Called when establishing a local or remote subscription failed. To get a nice error message that transparently detects local or remote errors use createDefaultFailureMessage().

Parameters:
subscription - The failed subscription object, not very useful at this point.
responseStatus - For a remote subscription, if a response was received at all, this is it, otherwise null.
exception - For a local subscription, any exception that caused the failure, otherwise null.
defaultMsg - A user-friendly error message.
See Also:
createDefaultFailureMessage(org.teleal.cling.model.message.UpnpResponse, java.lang.Exception)

established

protected abstract void established(GENASubscription subscription)
Called when a local or remote subscription was successfully established.

Parameters:
subscription - The successful subscription.

ended

protected abstract void ended(GENASubscription subscription,
                              CancelReason reason,
                              UpnpResponse responseStatus)
Called when a local or remote subscription ended, either on user request or because of a failure.

Parameters:
subscription - The ended subscription instance.
reason - If the subscription ended regularly (through end()), this is null.
responseStatus - For a remote subscription, if the cause implies a remopte response and it was received, this is it (e.g. renewal failure response).

eventReceived

protected abstract void eventReceived(GENASubscription subscription)
Called when an event for an established subscription has been received.

Use the GENASubscription.getCurrentValues() method to obtain the evented state variable values.

Parameters:
subscription - The established subscription with fresh state variable values.

eventsMissed

protected abstract void eventsMissed(GENASubscription subscription,
                                     int numberOfMissedEvents)
Called when a received event was out of sequence, indicating that events have been missed.

It's up to you if you want to react to missed events or if you (can) silently ignore them.

Parameters:
subscription - The established subscription.
numberOfMissedEvents - The number of missed events.

createDefaultFailureMessage

public static String createDefaultFailureMessage(UpnpResponse responseStatus,
                                                 Exception exception)
Parameters:
responseStatus - The (HTTP) response or null if there was no response.
exception - The exception or null if there was no exception.
Returns:
A human-friendly error message.

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2011 Teleal GmbH, Switzerland. All Rights Reserved.