Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.fourthline.cling.controlpoint
Class SubscriptionCallback

    java.lang.Object
      org.fourthline.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()`
`protected void` | `invalidMessage(RemoteGENASubscription remoteGENASubscription, UnsupportedDataException ex)` Called when a received event message could not be parsed successfully.
`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 and failed creation of a remote subscription protocol (before sending the subscribe request), any exception that caused the failure, otherwise `null`.
    `defaultMsg` - A user-friendly error message.
  See Also:
    `createDefaultFailureMessage(org.fourthline.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.

### invalidMessage

    protected void invalidMessage(RemoteGENASubscription remoteGENASubscription,
                                  UnsupportedDataException ex)

  Called when a received event message could not be parsed successfully.

  This typically indicates a broken device which is not UPnP compliant. You can react to this failure in any way you like, for example, you could terminate the subscription or simply create an error report/log.

  The default implementation will log the exception at `INFO` level, and the invalid XML at `FINE` level.

  Parameters:
    `remoteGENASubscription` - The established subscription.
    `ex` - Call `UnsupportedDataException.getData()` to access the invalid XML.

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2013 4th Line GmbH, Switzerland. All Rights Reserved.