Initial commit of persistence extensions (#1872)

* Initial commit of persistence extensions Signed-off-by: Chris Jackson <[email protected]>
eclipse-archived · Aug 2, 2016 · f7ec19f · f7ec19f
1 parent 057849a
commit f7ec19f
Show file tree

Hide file tree

Showing 17 changed files with 515 additions and 94 deletions.
diff --git a/bundles/core/org.eclipse.smarthome.core.persistence/META-INF/MANIFEST.MF b/bundles/core/org.eclipse.smarthome.core.persistence/META-INF/MANIFEST.MF
@@ -11,5 +11,6 @@ Import-Package: org.eclipse.smarthome.core.items,
  org.eclipse.smarthome.core.persistence,
  org.eclipse.smarthome.core.types,
  org.slf4j
-Export-Package: org.eclipse.smarthome.core.persistence
+Export-Package: org.eclipse.smarthome.core.persistence,
+ org.eclipse.smarthome.core.persistence.dto
 Bundle-ClassPath: .
diff --git a/...e.core.persistence/src/main/java/org/eclipse/smarthome/core/persistence/HistoricItem.java b/...e.core.persistence/src/main/java/org/eclipse/smarthome/core/persistence/HistoricItem.java
@@ -27,23 +27,23 @@ public interface HistoricItem {
 
     /**
      * returns the timestamp of the persisted item
-     * 
+     *
      * @return the timestamp of the item
      */
     Date getTimestamp();
 
     /**
      * returns the current state of the item
-     * 
+     *
      * @return the current state
      */
-    public State getState();
+    State getState();
 
     /**
      * returns the name of the item
-     * 
+     *
      * @return the name of the item
      */
-    public String getName();
+    String getName();
 
 }
diff --git a/...ce/src/main/java/org/eclipse/smarthome/core/persistence/ModifiablePersistenceService.java b/...ce/src/main/java/org/eclipse/smarthome/core/persistence/ModifiablePersistenceService.java
@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2014-2016 by the respective copyright holders.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.core.persistence;
+
+import java.util.Date;
+
+import org.eclipse.smarthome.core.items.Item;
+import org.eclipse.smarthome.core.types.State;
+
+/**
+ * This class provides an interface to the a {@link PersistenceService} to allow data to be stored
+ * at a specific time. This allows bindings that interface to devices that store data internally,
+ * and then periodically provide it to the server to be accommodated.
+ *
+ * @author Chris Jackson - Initial implementation and API
+ *
+ */
+public interface ModifiablePersistenceService extends QueryablePersistenceService {
+    /**
+     * <p>
+     * Stores the historic item value. This allows the item, time and value to be specified.
+     * </p>
+     * <p>
+     * Adding data with the same time as an existing record should update the current record value rather than adding a
+     * new record.
+     * </p>
+     * <p>
+     * Implementors should keep in mind that all registered {@link PersistenceService}s are called synchronously. Hence
+     * long running operations should be processed asynchronously. E.g. <code>store</code> adds things to a queue which
+     * is processed by some asynchronous workers (Quartz Job, Thread, etc.).
+     * </p>
+     *
+     * @param item the data to be stored
+     * @param date the date of the record
+     * @param state the state to be recorded
+     */
+    void store(Item item, Date date, State state);
+
+    /**
+     * Removes data associated with an item from a persistence service.
+     * If all data is removed for the specified item, the persistence service should free any resources associated with
+     * the item (eg. remove any tables or delete files from the storage).
+     *
+     * @param filter the filter to apply to the data removal. ItemName can not be null.
+     * @return true if the query executed successfully
+     * @throws {@link IllegalArgumentException} if item name is null.
+     */
+    boolean remove(FilterCriteria filter) throws IllegalArgumentException;
+}
diff --git a/...persistence/src/main/java/org/eclipse/smarthome/core/persistence/PersistenceItemInfo.java b/...persistence/src/main/java/org/eclipse/smarthome/core/persistence/PersistenceItemInfo.java
@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2014-2016 by the respective copyright holders.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.core.persistence;
+
+import java.util.Date;
+
+/**
+ * This class provides information about an item that is stored in a persistence service.
+ * It is used to return information about the item to the system
+ *
+ * @author Chris Jackson - Initial contribution
+ *
+ */
+public interface PersistenceItemInfo {
+    /**
+     * Returns the item name.
+     * It should be noted that the item name is as stored in the persistence service and as such may not be linked to an
+     * item. This may be the case if the item was removed from the system, but data still exists in the persistence
+     * service.
+     *
+     * @return Item name
+     */
+    String getName();
+
+    /**
+     * Returns a counter with the number of rows of data associated with the item
+     * Note that this should be used as a guide to the amount of data and may note be 100% accurate. If accurate
+     * information is required, the {@link QueryablePersistenceService#query} method should be used.
+     *
+     * @return count of the number of rows of data. May return null if the persistence service doesn't support this.
+     */
+    Integer getCount();
+
+    /**
+     * Returns the earliest timestamp from data in the persistence database
+     *
+     * @return the earliest {@link Date} stored in the database. May return null if the persistence service doesn't
+     *         support this.
+     */
+    Date getEarliest();
+
+    /**
+     * Returns the latest timestamp from data in the persistence database
+     *
+     * @return the latest {@link Date} stored in the database. May return null if the persistence service doesn't
+     *         support this.
+     */
+    Date getLatest();
+}
diff --git a/....persistence/src/main/java/org/eclipse/smarthome/core/persistence/PersistenceService.java b/....persistence/src/main/java/org/eclipse/smarthome/core/persistence/PersistenceService.java
@@ -7,6 +7,8 @@
  */
 package org.eclipse.smarthome.core.persistence;
 
+import java.util.Locale;
+
 import org.eclipse.smarthome.core.items.Item;
 
 /**
@@ -20,12 +22,22 @@
 public interface PersistenceService {
 
     /**
-     * Returns the name of this {@link PersistenceService}.
-     * This name is used to uniquely identify the {@link PersistenceService}.
-     * 
-     * @return the name to uniquely identify the {@link PersistenceService}.
+     * Returns the id of this {@link PersistenceService}.
+     * This id is used to uniquely identify the {@link PersistenceService}.
+     *
+     * @return the id to uniquely identify the {@link PersistenceService}.
+     */
+    String getId();
+
+    /**
+     * Returns the label of this {@link PersistenceService}.
+     * This label provides a user friendly name for the {@link PersistenceService}.
+     *
+     * @param locale the language to return the label in, or null for the default language
+     *
+     * @return the label of the {@link PersistenceService}.
      */
-    String getName();
+    String getLabel(Locale locale);
 
     /**
      * Stores the current value of the given item.
@@ -34,7 +46,7 @@ public interface PersistenceService {
      * long running operations should be processed asynchronously. E.g. <code>store</code> adds things to a queue which
      * is processed by some asynchronous workers (Quartz Job, Thread, etc.).
      * </p>
-     * 
+     *
      * @param item the item which state should be persisted.
      */
     void store(Item item);
@@ -48,7 +60,7 @@ public interface PersistenceService {
      * long running operations should be processed asynchronously. E.g. <code>store</code> adds things to a queue which
      * is processed by some asynchronous workers (Quartz Job, Thread, etc.).
      * </p>
-     * 
+     *
      * @param item the item which state should be persisted.
      * @param alias the alias under which the item should be persisted.
      */

diff --git a/...nce/src/main/java/org/eclipse/smarthome/core/persistence/QueryablePersistenceService.java b/...nce/src/main/java/org/eclipse/smarthome/core/persistence/QueryablePersistenceService.java
@@ -7,20 +7,34 @@
  */
 package org.eclipse.smarthome.core.persistence;
 
+import java.util.Set;
+
+import org.eclipse.smarthome.core.items.Item;
+
 /**
  * A queryable persistence service which can be used to store and retrieve
  * data from openHAB. This is most likely some kind of database system.
  *
  * @author Kai Kreuzer - Initial contribution and API
+ * @author Chris Jackson - Added getItems method
  */
 public interface QueryablePersistenceService extends PersistenceService {
 
     /**
      * Queries the {@link PersistenceService} for data with a given filter criteria
-     * 
+     *
      * @param filter the filter to apply to the query
      * @return a time series of items
      */
     Iterable<HistoricItem> query(FilterCriteria filter);
 
+    /**
+     * Returns a list of items that are stored in the persistence service
+     *
+     * This is returned as a string to allow the persistence service to return items that are no long available as an
+     * ESH {@link Item}.
+     *
+     * @return list of strings of item names contained in the store. Not null.
+     */
+    Set<PersistenceItemInfo> getItemInfo();
 }
diff --git a/...est/core/persistence/ItemHistoryBean.java → .../core/persistence/dto/ItemHistoryDTO.java b/...est/core/persistence/ItemHistoryBean.java → .../core/persistence/dto/ItemHistoryDTO.java
@@ -5,7 +5,7 @@
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  */
-package org.eclipse.smarthome.io.rest.core.persistence;
+package org.eclipse.smarthome.core.persistence.dto;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -18,15 +18,15 @@
  * @author Chris Jackson - Initial Contribution
  *
  */
-public class ItemHistoryBean {
+public class ItemHistoryDTO {
 
     public String name;
     public String totalrecords;
     public String datapoints;
 
     public List<HistoryDataBean> data = new ArrayList<HistoryDataBean>();
 
-    public ItemHistoryBean() {
+    public ItemHistoryDTO() {
     };
 
     /**

diff --git a/...io/rest/core/persistence/ServiceBean.java → ...ersistence/dto/PersistenceServiceDTO.java b/...io/rest/core/persistence/ServiceBean.java → ...ersistence/dto/PersistenceServiceDTO.java
@@ -5,17 +5,30 @@
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  */
-package org.eclipse.smarthome.io.rest.core.persistence;
+package org.eclipse.smarthome.core.persistence.dto;
 
 /**
- * This is a java bean that is used to serialize items to JSON.
+ * This is a java bean that is used to serialize services to JSON.
  *
  * @author Chris Jackson - Initial Contribution
  *
  */
-public class ServiceBean {
-    ServiceBean() {
+public class PersistenceServiceDTO {
+    public PersistenceServiceDTO() {
     }
 
-    public String name;
+    /**
+     * Service Id
+     */
+    public String id;
+
+    /**
+     * Service label
+     */
+    public String label;
+
+    /**
+     * Persistence service class
+     */
+    public String type;
 }
diff --git a/bundles/io/org.eclipse.smarthome.io.rest.core/META-INF/MANIFEST.MF b/bundles/io/org.eclipse.smarthome.io.rest.core/META-INF/MANIFEST.MF
@@ -29,6 +29,7 @@ Import-Package: com.google.common.base,
  org.eclipse.smarthome.core.library.items,
  org.eclipse.smarthome.core.library.types,
  org.eclipse.smarthome.core.persistence,
+ org.eclipse.smarthome.core.persistence.dto,
  org.eclipse.smarthome.core.thing,
  org.eclipse.smarthome.core.thing.dto,
  org.eclipse.smarthome.core.thing.link,
@@ -40,6 +41,7 @@ Import-Package: com.google.common.base,
  org.eclipse.smarthome.io.rest,
  org.eclipse.smarthome.io.rest.core.item,
  org.eclipse.smarthome.io.rest.core.thing,
+ org.eclipse.smarthome.model.persistence.extensions,
  org.osgi.framework,
  org.osgi.service.cm,
  org.osgi.service.component,

diff --git a/bundles/io/org.eclipse.smarthome.io.rest.core/OSGI-INF/persistenceresource.xml b/bundles/io/org.eclipse.smarthome.io.rest.core/OSGI-INF/persistenceresource.xml
@@ -11,6 +11,7 @@
 <scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="org.eclipse.smarthome.core.persistence.internal.rest">
    <implementation class="org.eclipse.smarthome.io.rest.core.persistence.PersistenceResource"/>
    <reference bind="addPersistenceService" cardinality="0..n" interface="org.eclipse.smarthome.core.persistence.PersistenceService" name="PersistenceService" policy="dynamic" unbind="removePersistenceService"/>
+   <reference bind="setItemRegistry" cardinality="1..1" interface="org.eclipse.smarthome.core.items.ItemRegistry" name="ItemRegistry" policy="dynamic" unbind="unsetItemRegistry"/>
    <service>
       <provide interface="org.eclipse.smarthome.io.rest.RESTResource"/>
    </service>

diff --git a/...core/persistence/ItemHistoryListBean.java → .../core/persistence/ItemHistoryListDTO.java b/...core/persistence/ItemHistoryListBean.java → .../core/persistence/ItemHistoryListDTO.java
@@ -11,19 +11,21 @@
 import java.util.Collection;
 import java.util.List;
 
+import org.eclipse.smarthome.core.persistence.dto.ItemHistoryDTO;
+
 /**
  * This is a java bean that is used to serialize item lists.
  *
  * @author Chris Jackson - Initial Contribution
  *
  */
-public class ItemHistoryListBean {
-    public final List<ItemHistoryBean> item = new ArrayList<ItemHistoryBean>();
+public class ItemHistoryListDTO {
+    public final List<ItemHistoryDTO> item = new ArrayList<ItemHistoryDTO>();
 
-    public ItemHistoryListBean() {
+    public ItemHistoryListDTO() {
     }
 
-    public ItemHistoryListBean(Collection<ItemHistoryBean> list) {
+    public ItemHistoryListDTO(Collection<ItemHistoryDTO> list) {
         item.addAll(list);
     }
 }