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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static Logger` | `log`
    `protected Integer` | `requestedDurationSeconds`
    `protected Service` | `service`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SubscriptionCallback(Service service)`
    `protected` | `SubscriptionCallback(Service service, int requestedDurationSeconds)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`

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