git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.persistence.dynamodb.internal;
  14
  15 import java.time.ZonedDateTime;
  16
  17 import javax.measure.Unit;
  18
  19 import org.eclipse.jdt.annotation.NonNullByDefault;
  20 import org.eclipse.jdt.annotation.Nullable;
  21 import org.openhab.core.items.Item;
  22 import org.openhab.core.persistence.HistoricItem;
  23
  24 /**
  25  * Represents openHAB Item serialized in a suitable format for the database
  26  *
  27  * @param <T> Type of the state as accepted by the AWS SDK.
  28  *
  29  * @author Sami Salonen - Initial contribution
  30  */
  31 @NonNullByDefault
  32 public interface DynamoDBItem<T> {
  33
  34     static final String DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'";
  35
  36     static final String ATTRIBUTE_NAME_TIMEUTC_LEGACY = "timeutc";
  37     static final String ATTRIBUTE_NAME_ITEMNAME_LEGACY = "itemname";
  38     static final String ATTRIBUTE_NAME_ITEMSTATE_LEGACY = "itemstate";
  39     static final String ATTRIBUTE_NAME_TIMEUTC = "t";
  40     static final String ATTRIBUTE_NAME_ITEMNAME = "i";
  41     static final String ATTRIBUTE_NAME_ITEMSTATE_STRING = "s";
  42     static final String ATTRIBUTE_NAME_ITEMSTATE_NUMBER = "n";
  43     static final String ATTRIBUTE_NAME_EXPIRY = "exp";
  44
  45     /**
  46      * Convert this AbstractDynamoItem as HistoricItem, i.e. converting serialized state back to openHAB state.
  47      *
  48      * Returns null when this instance has null state.
  49      *
  50      * If item is NumberItem and has an unit, the data is converted to QuantityType with item.getUnit().
  51      *
  52      * @param item Item representing this item. Used to determine item type.
  53      * @return HistoricItem representing this DynamoDBItem.
  54      */
  55     @Nullable
  56     HistoricItem asHistoricItem(Item item);
  57
  58     /**
  59      * Convert this AbstractDynamoItem as HistoricItem.
  60      *
  61      * Returns null when this instance has null state.
  62      * The implementation can deal with legacy schema as well.
  63      *
  64      * Use this method when repeated calls are expected for same item (avoids the expensive call to item.getUnit())
  65      *
  66      * @param item Item representing this item. Used to determine item type.
  67      * @param targetUnit unit to convert the data if item is with Dimension. Has only effect with NumberItems and with
  68      *            numeric DynamoDBItems.
  69      * @return HistoricItem representing this DynamoDBItem.
  70      */
  71     @Nullable
  72     HistoricItem asHistoricItem(Item item, @Nullable Unit<?> targetUnit);
  73
  74     /**
  75      * Get item name
  76      *
  77      * @return item name
  78      */
  79     String getName();
  80
  81     /**
  82      * Get item state, in the serialized format
  83      *
  84      * @return item state as serialized format
  85      */
  86     @Nullable
  87     T getState();
  88
  89     /**
  90      * Get timestamp of this value
  91      *
  92      * @return timestamp
  93      */
  94     ZonedDateTime getTime();
  95
  96     /**
  97      * Get expire time for the DynamoDB item in days.
  98      *
  99      * Does not have any effect with legacy schema.
 100      *
 101      * Also known as time-to-live or TTL.
 102      * Null means that expire is disabled
 103      *
 104      * @return expire time in days
 105      */
 106     @Nullable
 107     Integer getExpireDays();
 108
 109     /**
 110      * Get expiry date for the DynamoDB item in epoch seconds
 111      *
 112      * This is used with DynamoDB Time to Live TTL feature.
 113      *
 114      * @return expiry date of the data. Equivalent to getTime() + getExpireDays() or null when expireDays is null.
 115      */
 116     @Nullable
 117     Long getExpiryDate();
 118
 119     /**
 120      * Setter for item name
 121      *
 122      * @param name item name
 123      */
 124     void setName(String name);
 125
 126     /**
 127      * Setter for serialized state
 128      *
 129      * @param state serialized state
 130      */
 131     void setState(@Nullable T state);
 132
 133     /**
 134      * Set timestamp of the data
 135      *
 136      * @param time timestamp
 137      */
 138     void setTime(ZonedDateTime time);
 139
 140     /**
 141      * Set expire time for the DynamoDB item in days.
 142      *
 143      * Does not have any effect with legacy schema.
 144      *
 145      * Also known as time-to-live or TTL.
 146      * Use null to disable expiration
 147      *
 148      * @param expireDays expire time in days. Should be positive or null.
 149      *
 150      */
 151     void setExpireDays(@Nullable Integer expireDays);
 152
 153     <R> R accept(DynamoDBItemVisitor<R> visitor);
 154 }