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.

      On Android the cap is per data type when a query names several. Health Connect pages per record type, so a limit of ten over two types can return twenty. Neither alternative works: dividing the budget cannot find a newest-ten that all lives in one type, and trimming the merged page discards records the per-type continuation tokens have already moved past. Honouring it exactly needs an incremental k-way merge across the types, which is not implemented yet. Query one type at a time where the cap has to be exact -- which is also what iOS does, since HKSampleQuery reads one type per query.

    • 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.

      Only Health Connect and the local stores group measurements into records, so only they have anything to withhold. HealthKit stores each measurement separately and the iOS port returns ordinary QuantitySample objects whichever way this is set -- not one-point series -- so code that turns flattening off and then casts to SeriesSample fails there. Test the type rather than assuming it.

    • isFlattenSeries

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

    • setSleepSessionGap

      public SampleQuery setSleepSessionGap(Duration value)

      The gap that separates two sleep sessions.

      The

      invalid reference 
      Duration
      form of setSleepSessionGapMillis(long), which is the type the rest of

      the framework speaks; the millis form stays for the ports and the wire format.

    • getSleepSessionGap

      public Duration getSleepSessionGap()

      The gap that separates two sleep sessions, as a

      invalid reference 
      Duration
      .

    • setSleepSessionGapMillis

      public SampleQuery setSleepSessionGapMillis(long gapMillis)

    • 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