Module javafx.base
Package javafx.util

# Interface Subscription

Functional Interface:
  This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface Subscription
Represents a cancel or cleanup operation for an action that can be cancelled or that allocated resources. Subscriptions can be obtained, for example, as a result of registering a callback, starting a timer, or allocating resources. They provide a convenient way for subscribers to cancel these actions at a later time, without requiring additional information or even access to the source from where they were originally obtained.

     class Publisher {
       public Subscription subscribe(Consumer<NewsLetter> subscriber) {
         register(subscriber);

         // return a Subscription which unregisters the original subscriber
         return () -> unregister(subscriber);
       }
     }

Subscriptions can also be combined using `combine(javafx.util.Subscription...)` and `and(javafx.util.Subscription)`, which allows for multiple subscriptions to be unsubscribed together. This is useful when they share the same lifecycle, for example, when performing cleanup for the same object.

Since:
  21

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Subscription`
  `EMPTY`
  An empty subscription.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default Subscription`
  `and(Subscription other)`
  Combines this `Subscription` with the given `Subscription` and returns a new `Subscription` which will cancel both when cancelled.
  `static Subscription`
  `combine(Subscription... subscriptions)`
  Returns a `Subscription` which combines all of the given subscriptions.
  `void`
  `unsubscribe()`
  Cancels this subscription, or does nothing if already cancelled.

- ## Field Details

  - ### EMPTY

    static final Subscription EMPTY
    An empty subscription. Does nothing when cancelled.

- ## Method Details

  - ### combine

    static Subscription combine(Subscription... subscriptions)
    Returns a `Subscription` which combines all of the given subscriptions.
    Parameters:
      `subscriptions` - an array of subscriptions to combine, cannot be `null` or contain `null`
    Returns:
      a `Subscription`, never `null`
    Throws:
      `NullPointerException` - when `subscriptions` is `null` or contains `null`

  - ### unsubscribe

    void unsubscribe()
    Cancels this subscription, or does nothing if already cancelled.

    Implementation Requirements:
      Implementors must ensure the implementation is idempotent (a no-op if called more than once).

  - ### and

    default Subscription and(Subscription other)
    Combines this `Subscription` with the given `Subscription` and returns a new `Subscription` which will cancel both when cancelled.

    This is equivalent to `Subscription.combine(this, other)`.

    Parameters:
      `other` - another `Subscription`, cannot be `null`
    Returns:
      a combined `Subscription` which will cancel both when cancelled, never `null`
    Throws:
      `NullPointerException` - when `other` is `null`