Class SampleQuery

java.lang.Object
com.codename1.health.SampleQuery
public final class SampleQuery extends Object

Describes a read against HealthStore. Fluent setters return this.

SampleQuery q = new SampleQuery()
        .addType(HealthDataType.HEART_RATE)
        .setTimeRange(HealthTimeRange.lastHours(24))
        .setSortDescending(true)
        .setLimit(500);
Always set a limit for high-frequency types

A year of continuous heart rate is on the order of half a million samples. The default limit of 10,000 exists so that a naive query cannot exhaust the heap on a phone; raise it deliberately, and prefer paging through HealthStore.readSamplePage(SampleQuery) over asking for everything at once.

  • Field Details

    • DEFAULT_LIMIT

      public static final int DEFAULT_LIMIT
      The limit applied when none is set.
      See Also:

  • Constructor Details

    • SampleQuery

      public SampleQuery()

  • Method Details

    • addType

      public SampleQuery addType(HealthDataType type)
      Adds a type to read. At least one is required.

    • getTypes

      public List<HealthDataType> getTypes()
      The types this query reads.

    • addSource

      public SampleQuery addSource(String bundleId)

      Restricts the query to samples written by one app, identified by its bundle id or package name -- see HealthSource.getBundleId(). Call more than once to allow several.

      Worth doing when a phone and a watch both record the same activity: see the double-counting warning on AggregateQuery.

    • getSources

      public List<String> getSources()
      The source filter, empty when unrestricted.

    • setTimeRange

      public SampleQuery setTimeRange(HealthTimeRange timeRange)
      The span to read. Required.

    • getTimeRange

      public HealthTimeRange getTimeRange()
      The span this query reads, or null when unset.

    • setLimit

      public SampleQuery setLimit(int limit)
      Caps how many samples come back. Must be positive.

    • getLimit

      public int getLimit()
      The sample cap.

    • setSortDescending

      public SampleQuery setSortDescending(boolean sortDescending)
      Returns the newest samples first. Default is oldest first.

    • isSortDescending

      public boolean isSortDescending()
      true when results come back newest first.

    • setUnit

      public SampleQuery setUnit(HealthUnit unit)

      Returns values in unit instead of the type's canonical unit.

      Throws

      The unit is validated when the query runs, not here: a unit that measures the wrong dimension fails with HealthError.UNIT_MISMATCH before the platform is touched.

    • getUnit

      public HealthUnit getUnit()
      The requested unit, or null for each type's canonical unit.

    • setFlattenSeries

      public SampleQuery setFlattenSeries(boolean flattenSeries)

      Whether to expand SeriesSample records into individual QuantitySample objects. Defaults to true.

      Leave it on and both platforms return the same thing, so your code is identical across them. Turn it off when you need a series' record identity -- to delete it, for instance -- and accept that iOS, which has no such grouping, returns series of size 1.

    • isFlattenSeries

      public boolean isFlattenSeries()
      true when series are expanded into individual samples.

    • setSleepSessionGapMillis

      public SampleQuery setSleepSessionGapMillis(long gapMillis)

      The gap that separates two sleep sessions, for the iOS port's session reassembly. Defaults to 15 minutes.

      HealthKit stores sleep as a run of category samples with no session object, so the port groups samples separated by less than this gap into one SleepSample. Raise it if your users nap; lower it if you would rather see brief wakings split the night. Ignored on Android, where sessions are stored natively.

    • getSleepSessionGapMillis

      public long getSleepSessionGapMillis()
      The sleep-session grouping gap in milliseconds.

    • setPageToken

      public SampleQuery setPageToken(String pageToken)
      Continues a previous read from SamplePage.getNextPageToken().

    • getPageToken

      public String getPageToken()
      The continuation token, or null to start from the beginning.

    • validate

      public void validate() throws HealthException

      Validates the query and throws if it cannot be run.

      Called by HealthStore before the platform is touched, so a malformed query fails immediately and locally rather than as an opaque platform error later.

      Throws
      Throws:
      HealthException