# Class SubscriptionRequest

java.lang.Object
com.codename1.health.SubscriptionRequest

public final class SubscriptionRequest extends Object

Describes a standing subscription to changes in the health store.

##### The id must never change

The identifier keys the persisted cursor that says how far the app has already read. Reuse it across launches and app updates and you resume exactly where you left off; change it -- even to fix a typo -- and the framework treats it as a brand-new subscription and resynchronizes from scratch. Hard-code it as a constant, and version it deliberately (`"steps-v1"`) if you ever need a clean start.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_MAX_SAMPLES_PER_BATCH`
  The default cap on how many samples one change batch carries.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SubscriptionRequest(String id)`
  Creates a request under a stable identifier.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SubscriptionRequest`
  `addType(HealthDataType type)`
  Adds a type to watch.
  `String`
  `getId()`
  The stable identifier for this subscription.
  `int`
  `getMaxSamplesPerBatch()`
  The per-batch sample cap.
  `List<HealthDataType>`
  `getTypes()`
  The types being watched.
  `boolean`
  `isDeliverSamples()`
  `true` when batches carry samples.
  `boolean`
  `isIncludeDeletions()`
  `true` when deletions are reported.
  `SubscriptionRequest`
  `setDeliverSamples(boolean deliverSamples)`
  Whether batches carry the changed samples themselves.
  `SubscriptionRequest`
  `setIncludeDeletions(boolean includeDeletions)`
  Whether deletions are reported alongside additions.
  `SubscriptionRequest`
  `setMaxSamplesPerBatch(int maxSamplesPerBatch)`
  Caps how many samples one batch carries.
  `void`
  `validate()`
  Validates the request.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_MAX_SAMPLES_PER_BATCH

    public static final int DEFAULT_MAX_SAMPLES_PER_BATCH
    The default cap on how many samples one change batch carries.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### SubscriptionRequest

    public SubscriptionRequest(String id)

    Creates a request under a stable identifier.

    ###### Throws

    - `IllegalArgumentException`: if `id` is null, blank, or contains a control character.

- ## Method Details

  - ### getId

    public String getId()
    The stable identifier for this subscription.

  - ### addType

    public SubscriptionRequest addType(HealthDataType type)
    Adds a type to watch. At least one is required.

  - ### getTypes

    public List<HealthDataType> getTypes()
    The types being watched.

  - ### setIncludeDeletions

    public SubscriptionRequest setIncludeDeletions(boolean includeDeletions)
    Whether deletions are reported alongside additions. Defaults to `true`; turn it off only if your app genuinely never needs to un-count something a user removed.

  - ### isIncludeDeletions

    public boolean isIncludeDeletions()
    `true` when deletions are reported.

  - ### setDeliverSamples

    public SubscriptionRequest setDeliverSamples(boolean deliverSamples)
    Whether batches carry the changed samples themselves. Defaults to `true`. Set `false` for a notify-only subscription -- cheaper when all you want is a signal to refresh a screen.

  - ### isDeliverSamples

    public boolean isDeliverSamples()
    `true` when batches carry samples.

  - ### setMaxSamplesPerBatch

    public SubscriptionRequest setMaxSamplesPerBatch(int maxSamplesPerBatch)

    Caps how many samples one batch carries. Batches beyond the cap are reported through `HealthChangeBatch.hasMore()`.

    The default exists because a background delivery has only a few seconds of wall clock before the OS suspends the process; handing the listener fifty thousand samples guarantees it does not finish.

  - ### getMaxSamplesPerBatch

    public int getMaxSamplesPerBatch()
    The per-batch sample cap.

  - ### validate

    public void validate() throws HealthException

    Validates the request.

    ###### Throws

    - `HealthException`: `HealthError.INVALID_ARGUMENT` when no type is named or the batch cap is not positive.
    Throws:
      `HealthException`