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