# Class SleepSample

java.lang.Object
com.codename1.health.HealthSample
com.codename1.health.SessionSample
com.codename1.health.SleepSample

public final class SleepSample extends SessionSample

A sleep session, optionally broken into `SleepStageInterval` spans.

##### Stage detail is not guaranteed

A session recorded by a watch usually carries stages; one inferred by a phone usually does not, and neither did iOS before version 16. Check `hasStageDetail()` and fall back to showing the total duration -- drawing a hypnogram from a single "asleep" span produces an empty chart that looks like a bug.

    if (night.hasStageDetail()) {
        for (SleepStageInterval iv : night.getStages()) {
            drawBand(iv.getStage(), iv.getStartMillis(), iv.getEndMillis());
        }
    } else {
        showTotal(night.getDurationMillis());
    }

##### Neither phone reads sleep in this release

Sleep is available on the simulator, the desktop and the JavaScript port, and on none of the mobile ones: a sleep query is refused on iOS and Android alike, so no session of this shape ever comes back from a device. Build against it by all means -- but do not build a mobile screen around it yet.

The reason it is unfinished on iOS is worth knowing, because it shapes what finishing it will look like. HealthKit has no sleep-session object at all, only a run of overlapping category samples, so the port has to group them into sessions itself -- Apple's own convention is to split on a gap, which is what `SampleQuery.setSleepSessionGapMillis(long)` is there to tune. That grouping is a heuristic, which is why it belongs in the port rather than baked into the shared code.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addStage(SleepStageInterval interval)`
  Appends a stage span.
  `static SleepSample`
  `create(long startMillis, long endMillis)`
  A session with no stage breakdown.
  `static SleepSample`
  `create(long startMillis, long endMillis, List<SleepStageInterval> stages)`
  A session with stage detail.
  `Duration`
  `getAsleepDuration()`
  Time asleep in this session, as a `Duration`.
  `long`
  `getAsleepDurationMillis()`
  The total time spent asleep -- every span except `SleepStage.AWAKE`, `SleepStage.AWAKE_IN_BED` and `SleepStage.OUT_OF_BED`.
  `long`
  `getDurationMillis(SleepStage stage)`
  The total time in `stage` -- the time actually covered by its spans, so two overlapping spans of the same stage count the overlap once.
  `List<SleepStageInterval>`
  `getStages()`
  The stage breakdown, in the order the platform reported it.
  `SleepStageSupport`
  `getStageSupport()`
  `true` when this session carries a real stage breakdown -- that is, at least one span classified as something more specific than "asleep", "in bed" or "unknown".
  `boolean`
  `hasStageDetail()`
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class SessionSample

  `getNotes, getTitle, setNotes, setTitle`

  ### Methods inherited from class HealthSample

  `equals, getDuration, getDurationMillis, getEnd, getEndMillis, getId, getMetadata, getRecordingMethod, getSource, getStart, getStartMillis, getType, hashCode, isInstantaneous, putMetadata, setId, setRecordingMethod, setSource`

  ### Methods inherited from class Object

  `clone, getClass, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### create

    public static SleepSample create(long startMillis, long endMillis)
    A session with no stage breakdown.

  - ### create

    public static SleepSample create(long startMillis, long endMillis, List<SleepStageInterval> stages)
    A session with stage detail. The list is copied defensively.

  - ### getStages

    public List<SleepStageInterval> getStages()
    The stage breakdown, in the order the platform reported it. Empty when no breakdown is available.

  - ### addStage

    public void addStage(SleepStageInterval interval)
    Appends a stage span. Used when building a session to write.

  - ### getStageSupport

    public SleepStageSupport getStageSupport()

    `true` when this session carries a real stage breakdown -- that is, at least one span classified as something more specific than "asleep", "in bed" or "unknown".

    Returns `false` for an empty stage list and for a list containing only `SleepStage.ASLEEP_UNSPECIFIED`, `SleepStage.AWAKE_IN_BED` and `SleepStage.UNKNOWN`, because none of those tell you anything a hypnogram could show. How much stage detail this session carries.

    Three answers rather than the boolean `hasStageDetail()`, because "has stages" collapses two cases an app has to draw differently: a session that knows only asleep-versus-awake, and one carrying a real hypnogram. Branch on this before building the UI rather than discovering it from an empty chart.

    `hasStageDetail()` is kept and is exactly `getStageSupport() == SleepStageSupport.STAGED`.

  - ### hasStageDetail

    public boolean hasStageDetail()

  - ### getDurationMillis

    public long getDurationMillis(SleepStage stage)
    The total time in `stage` -- the time actually covered by its spans, so two overlapping spans of the same stage count the overlap once.

  - ### getAsleepDurationMillis

    public long getAsleepDurationMillis()

    The total time spent asleep -- every span except `SleepStage.AWAKE`, `SleepStage.AWAKE_IN_BED` and `SleepStage.OUT_OF_BED`.

    Falls back to the whole session duration when no stages are present, which is the best available answer for a source that only reported "asleep from X to Y".

  - ### getAsleepDuration

    public Duration getAsleepDuration()

    Time asleep in this session, as a `Duration`.

    The millis form stays for the ports and the wire format; this is the type the rest of the framework speaks.

  - ### toString

    public String toString()
    Description copied from class: `Object`
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
      `toString` in class `HealthSample`