/*
* Copyright 2021 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.appsearch.builtintypes;
import androidx.annotation.IntDef;
import androidx.annotation.NonNull;
import androidx.annotation.RestrictTo;
import androidx.appsearch.annotation.Document;
import androidx.appsearch.utils.DateTimeFormatValidator;
import androidx.core.util.Preconditions;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* AppSearch document representing an {@link AlarmInstance} entity.
*
* <p>An {@link AlarmInstance} must be associated with an {@link Alarm}. It represents a
* particular point in time for that Alarm. For example, if an Alarm is set to
* repeat every Monday, then each {@link AlarmInstance} for it will be the exact Mondays that the
* Alarm did trigger.
*
* <p>The scheduled time should be timezone independent so that it remains unchanged across
* timezones. E.g.: An {@link AlarmInstance} set to fire at 7am GMT should also fire at 7am when
* the timezone is changed to PST.
*/
@Document(name = "builtin:AlarmInstance")
public final class AlarmInstance {
/** @hide */
@RestrictTo(RestrictTo.Scope.LIBRARY)
@IntDef({STATUS_UNKNOWN, STATUS_SCHEDULED, STATUS_FIRING, STATUS_DISMISSED, STATUS_SNOOZED,
STATUS_MISSED})
@Retention(RetentionPolicy.SOURCE)
public @interface Status {}
/** The {@link AlarmInstance} is in an unknown error state. */
public static final int STATUS_UNKNOWN = 0;
/** The {@link AlarmInstance} is scheduled to fire at some point in the future. */
public static final int STATUS_SCHEDULED = 1;
/** The {@link AlarmInstance} is firing. */
public static final int STATUS_FIRING = 2;
/** The {@link AlarmInstance} has been dismissed. */
public static final int STATUS_DISMISSED = 3;
/** The {@link AlarmInstance} has been snoozed. */
public static final int STATUS_SNOOZED = 4;
/** The {@link AlarmInstance} has been missed. */
public static final int STATUS_MISSED = 5;
@Document.Namespace
private final String mNamespace;
@Document.Id
private final String mId;
@Document.Score
private final int mDocumentScore;
@Document.CreationTimestampMillis
private final long mCreationTimestampMillis;
@Document.TtlMillis
private final long mDocumentTtlMillis;
@Document.StringProperty
private final String mScheduledTime;
@Document.LongProperty
private final int mStatus;
@Document.LongProperty
private final long mSnoozeDurationMillis;
AlarmInstance(@NonNull String namespace, @NonNull String id, int documentScore,
long creationTimestampMillis, long documentTtlMillis, @NonNull String scheduledTime,
int status, long snoozeDurationMillis) {
mNamespace = Preconditions.checkNotNull(namespace);
mId = Preconditions.checkNotNull(id);
mDocumentScore = documentScore;
mCreationTimestampMillis = creationTimestampMillis;
mDocumentTtlMillis = documentTtlMillis;
mScheduledTime = Preconditions.checkNotNull(scheduledTime);
mStatus = status;
mSnoozeDurationMillis = snoozeDurationMillis;
}
/** Returns the namespace. */
@NonNull
public String getNamespace() {
return mNamespace;
}
/** Returns the unique identifier. */
@NonNull
public String getId() {
return mId;
}
/**
* Returns the user-provided opaque document score of the current AppSearch document, which can
* be used for ranking using
* {@link androidx.appsearch.app.SearchSpec.RankingStrategy#RANKING_STRATEGY_DOCUMENT_SCORE}.
*
* <p>See {@link Document.Score} for more information on score.
*/
public int getDocumentScore() {
return mDocumentScore;
}
/**
* Returns the creation timestamp for the current AppSearch entity, in milliseconds using the
* {@link System#currentTimeMillis()} time base.
*
* <p>This timestamp refers to the creation time of the AppSearch entity, not when the
* document is written into AppSearch.
*
* <p>If not set, then the current timestamp will be used.
*
* <p>See {@link androidx.appsearch.annotation.Document.CreationTimestampMillis} for more
* information on creation timestamp.
*/
public long getCreationTimestampMillis() {
return mCreationTimestampMillis;
}
/**
* Returns the time-to-live (TTL) for the current AppSearch document as a duration in
* milliseconds.
*
* <p>The document will be automatically deleted when the TTL expires.
*
* <p>See {@link Document.TtlMillis} for more information on TTL.
*/
public long getDocumentTtlMillis() {
return mDocumentTtlMillis;
}
/**
* Returns the time that this is expected to fire in ISO 8601 format.
* E.g.: 2022-01-14T00:00:00
*
* <p>The scheduledTime is a timezone independent date time. When used, it should be
* converted into a date time in the local timezone.
*/
@NonNull
public String getScheduledTime() {
return mScheduledTime;
}
/**
* Returns the current status.
*
* <p>Status can be either {@link #STATUS_UNKNOWN}, {@link #STATUS_SCHEDULED},
* {@link #STATUS_FIRING}, {@link #STATUS_DISMISSED}, {@link #STATUS_SNOOZED}, or
* {@link #STATUS_MISSED}.
*/
@Status
public int getStatus() {
return mStatus;
}
/**
* Returns the length of time in milliseconds the {@link AlarmInstance} will remain snoozed
* before it fires again, or -1 if it does not support snoozing.
*/
public long getSnoozeDurationMillis() {
return mSnoozeDurationMillis;
}
/** Builder for {@link AlarmInstance}. */
public static final class Builder extends BaseBuiltinTypeBuilder<Builder> {
private final String mScheduledTime;
private int mStatus;
private long mSnoozeDurationMillis;
/**
* Constructor for {@link AlarmInstance.Builder}.
*
* @param namespace Namespace for the Document. See {@link Document.Namespace}.
* @param id Unique identifier for the Document. See {@link Document.Id}.
* @param scheduledTime The time that this is expected to fire in
* ISO 8601 format. E.g.: 2022-01-14T00:00:00. Scheduled time should
* be timezone independent.
*/
public Builder(@NonNull String namespace, @NonNull String id,
@NonNull String scheduledTime) {
super(namespace, id);
Preconditions.checkNotNull(scheduledTime);
Preconditions.checkArgument(
DateTimeFormatValidator.validateISO8601DateTime(scheduledTime),
"scheduledTime must be in the format: yyyy-MM-ddTHH:mm:ss");
mScheduledTime = scheduledTime;
// default for snooze length. Indicates no snoozing.
mSnoozeDurationMillis = -1;
}
/**
* Constructor for {@link AlarmInstance.Builder} with all the existing values.
*/
public Builder(@NonNull AlarmInstance alarmInstance) {
this(alarmInstance.getNamespace(), alarmInstance.getId(),
alarmInstance.getScheduledTime());
mDocumentScore = alarmInstance.getDocumentScore();
mCreationTimestampMillis = alarmInstance.getCreationTimestampMillis();
mDocumentTtlMillis = alarmInstance.getDocumentTtlMillis();
mStatus = alarmInstance.getStatus();
mSnoozeDurationMillis = alarmInstance.getSnoozeDurationMillis();
}
/**
* Sets the current status.
*
* <p>Status can be either {@link #STATUS_UNKNOWN}, {@link #STATUS_SCHEDULED},
* {@link #STATUS_FIRING}, {@link #STATUS_DISMISSED}, {@link #STATUS_SNOOZED}, or
* {@link #STATUS_MISSED}.
*/
@NonNull
public Builder setStatus(@Status int status) {
mStatus = status;
return this;
}
/**
* Sets the length of time in milliseconds the {@link AlarmInstance} will remain snoozed
* before it fires again.
*
* <p>If not set, or set to -1, then it does not support snoozing.
*/
@NonNull
public Builder setSnoozeDurationMillis(long snoozeDurationMillis) {
mSnoozeDurationMillis = snoozeDurationMillis;
return this;
}
/** Builds the {@link AlarmInstance}. */
@NonNull
public AlarmInstance build() {
return new AlarmInstance(mNamespace, mId, mDocumentScore,
mCreationTimestampMillis, mDocumentTtlMillis, mScheduledTime, mStatus,
mSnoozeDurationMillis);
}
}
}