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

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