bundles/org.simantics.history/src/org/simantics/history/util/subscription/SubscriptionItem.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2011 Association for Decentralized Information Management in\r
   3  * Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.history.util.subscription;\r
  13 \r
  14 import java.util.Collection;\r
  15 import java.util.Iterator;\r
  16 \r
  17 import org.simantics.databoard.annotations.Identifier;\r
  18 import org.simantics.databoard.type.Datatype;\r
  19 import org.simantics.databoard.util.Bean;\r
  20 \r
  21 /**\r
  22  * (Utility Class) Item format for HistoryManager, Collector, and meta-data for Simantics subscription configurations.\r
  23  * \r
  24  * The items objects the HistoryManager and Collector uses are complete meta-data\r
  25  * descriptions. Different formats are supported and the content is written to disc\r
  26  * completely as is. \r
  27  * \r
  28  * The "id" is composed with the following aggregation: [subscriptionId] [variableId] [formatId].\r
  29  * \r
  30  * @author toni.kalajainen\r
  31  */\r
  32 public class SubscriptionItem extends Bean {\r
  33 \r
  34         /**\r
  35          * Create HistoryItem descriptions for collecting one variable with multiple\r
  36          * sampling formats.\r
  37          * \r
  38          * @param item\r
  39          *            the item to use as a template for the created sampled items\r
  40          * @param groupItemId\r
  41          *            the group item id to use with\r
  42          *            {@link #composeItemName(String, String, String)}\r
  43          * @param groupId\r
  44          *            the group id to use with\r
  45          *            {@link #composeItemName(String, String, String)}\r
  46          * @param formats\r
  47          *            the sampling formats to create\r
  48          * @return an array of history items\r
  49          */\r
  50         public static SubscriptionItem[] createItems(\r
  51                         SubscriptionItem item,\r
  52                         String groupItemId,\r
  53                         String groupId,\r
  54                         Collection<SamplingFormat> formats) {\r
  55                 Iterator<SamplingFormat> itr = formats.iterator();\r
  56                 SubscriptionItem[] items = new SubscriptionItem[ formats.size() ];\r
  57                 for (int i=0; i<formats.size(); i++) {\r
  58                         items[i] = createItem( item, groupItemId, groupId, itr.next() );\r
  59                 }\r
  60                 return items;\r
  61         }\r
  62 \r
  63         /**\r
  64          * Create HistoryItem descriptions for collecting one variable with multiple\r
  65          * sampling formats.\r
  66          * \r
  67          * @param variableId\r
  68          * @param subscriptionId\r
  69          * @param formats\r
  70          * @return an array of history items\r
  71          */\r
  72         public static SubscriptionItem[] createItems(\r
  73                         String variableId,\r
  74                         String subscriptionId,\r
  75                         SamplingFormat...formats\r
  76                                 ) {\r
  77                         SubscriptionItem[] items = new SubscriptionItem[ formats.length ];\r
  78                         for (int i=0; i<formats.length; i++) {\r
  79                                 items[i] = createItem( variableId, subscriptionId, formats[i] );\r
  80                         }\r
  81                         return items;\r
  82                 }\r
  83                 \r
  84         /**\r
  85          * Create HistoryItem descriptions for collecting one variable with multiple\r
  86          * sampling formats.\r
  87          * \r
  88          * @param groupItemId\r
  89          * @param groupId\r
  90          * @param formats\r
  91          * @return an array of history items\r
  92          */\r
  93         public static SubscriptionItem[] createItems(\r
  94                         String groupItemId,\r
  95                         String groupId,\r
  96                         Collection<SamplingFormat> formats) {\r
  97                         Iterator<SamplingFormat> itr = formats.iterator();\r
  98                         SubscriptionItem[] items = new SubscriptionItem[ formats.size() ];\r
  99                         for (int i=0; i<formats.size(); i++) {\r
 100                                 items[i] = createItem( groupItemId, groupId, itr.next() );\r
 101                         }\r
 102                         return items;\r
 103                 }\r
 104 \r
 105         /**\r
 106          * Create HistoryItem description for collecting one variable with one\r
 107          * sampling format.\r
 108          * \r
 109          * @param item\r
 110          *            the subscription item to clone values from\r
 111          * @param groupItemId\r
 112          *            the group item id to use with\r
 113          *            {@link #composeItemName(String, String, String)}\r
 114          * @param groupId\r
 115          *            the group id to use with\r
 116          *            {@link #composeItemName(String, String, String)}\r
 117          * @param format\r
 118          * @return HistoryItem description.\r
 119          */\r
 120         public static SubscriptionItem createItem(\r
 121                         SubscriptionItem item,\r
 122                         String groupItemId,\r
 123                         String groupId,\r
 124                         SamplingFormat format\r
 125                         ) {\r
 126                 SubscriptionItem hi = new SubscriptionItem();\r
 127                 hi.variableId = item.variableId;\r
 128                 hi.groupItemId = item.groupItemId;\r
 129                 hi.id = composeItemName(groupId, groupItemId, format.formatId);\r
 130                 hi.deadband = format.deadband;\r
 131                 hi.interval = format.interval;\r
 132                 hi.gain = item.gain;\r
 133                 hi.bias = item.bias;\r
 134                 hi.formatId = format.formatId;\r
 135                 hi.format = format.format;\r
 136                 hi.groupId = item.groupId;\r
 137                 hi.enabled = item.enabled;\r
 138                 return hi;\r
 139         }\r
 140 \r
 141         /**\r
 142          * Create HistoryItem description for collecting one variable with one\r
 143          * sampling format. \r
 144          * \r
 145          * @param groupItemId\r
 146          *            the group item id to use with\r
 147          *            {@link #composeItemName(String, String, String)}\r
 148          * @param groupId\r
 149          *            the group id to use with\r
 150          *            {@link #composeItemName(String, String, String)}\r
 151          * @param format\r
 152          * @return HistoryItem description.\r
 153          */\r
 154         public static SubscriptionItem createItem(\r
 155                         String groupItemId,\r
 156                         String groupId,\r
 157                         SamplingFormat format\r
 158                         ) {\r
 159                 SubscriptionItem hi = new SubscriptionItem();\r
 160                 hi.variableId = groupItemId;\r
 161                 hi.groupItemId = groupItemId;\r
 162                 hi.id = composeItemName(groupId, groupItemId, format.formatId);\r
 163                 hi.deadband = format.deadband;\r
 164                 hi.interval = format.interval;\r
 165                 hi.formatId = format.formatId;\r
 166                 hi.format = format.format;\r
 167                 hi.groupId = groupId;\r
 168                 hi.enabled = true;\r
 169                 return hi;\r
 170         }\r
 171 \r
 172         public static String composeItemName(String groupId, String groupItemId, String formatId)\r
 173         {\r
 174                 return groupId+" "+groupItemId+" "+formatId;\r
 175         }\r
 176 \r
 177         /** Item identifier in the HistoryManager */\r
 178         public @Identifier String id;\r
 179                 \r
 180         /** Variable Id, Reference of variable in Datasource. This field is used by Collector */\r
 181         public String variableId;\r
 182         \r
 183         /** \r
 184          * Describes the format of the packed sample. The sample must be a record.\r
 185          * The record must have any combination of the following named fields.\r
 186          * The field types must one of: byte, integer, long, float, double.\r
 187          * \r
 188          * time, endTime, value - are mandatory fields.\r
 189          * \r
 190          *  time      -  Region start time, the time of the 1st sample included into the band\r
 191          *  endTime   -  Region end time, the time of the last sample included into the band\r
 192          *  \r
 193          *  value     -  First value in the band\r
 194          *  lastValue -  Last value in the band\r
 195          *  avg       -  Average value of all included samples\r
 196          *  median    -  Median value of all samples in the band\r
 197          *  min       -  Lowest value in the band\r
 198          *  max       -  Highest value in the band\r
 199          *  \r
 200          *  quality   -  0 = Good, -1 = No value\r
 201          *  count     -  The number of included samples in the band\r
 202          */\r
 203         public Datatype format;\r
 204                         \r
 205         // Subscription parameters\r
 206         public double deadband = Double.NaN;\r
 207         public double interval = Double.NaN;\r
 208         public double gain = 1.0;\r
 209         public double bias = 0.0;\r
 210         public boolean enabled = true;\r
 211 \r
 212         /** Identifier of group or subscription, used by Simantics */\r
 213         public String groupId = "";\r
 214         \r
 215         /** Identifier of the item in the group, used by Simantics */\r
 216         public String groupItemId = "";\r
 217         \r
 218         /** Identifier of the sample format description, used by Simantics */\r
 219         public String formatId = "";\r
 220 \r
 221 }\r