sensorconfig.h 10.9 KB
Newer Older
1
2
3
4
//================================================================================
// Name        : sensorconfig.h
// Author      : Axel Auweter
// Copyright   : Leibniz Supercomputing Centre
Michael Ott's avatar
Michael Ott committed
5
// Description : C++ API for configuring libdcdb public sensors.
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
//================================================================================

//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2011-2016 Leibniz Supercomputing Centre
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
//================================================================================

Axel Auweter's avatar
Axel Auweter committed
27
28
29
30

/**
 * @file
 * @brief This file contains parts of the public API for the
Michael Ott's avatar
Michael Ott committed
31
 * libdcdb library.
Axel Auweter's avatar
Axel Auweter committed
32
33
34
35
36
37
38
39
 * It contains the class definition of the SensorConfig class,
 * that handles sensor configuration and initialization.
 */

#include <string>
#include <list>

#include "connection.h"
Axel Auweter's avatar
Axel Auweter committed
40
41
42
#include "timestamp.h"
#include "sensorid.h"

Axel Auweter's avatar
Axel Auweter committed
43
44
#include "cassandra.h"

45
46
47
48
#ifndef DCDB_SENSORCONFIG_H
#define DCDB_SENSORCONFIG_H

namespace DCDB {
Axel Auweter's avatar
Axel Auweter committed
49

50
/* Forward-declaration of the implementation-internal classes */
Axel Auweter's avatar
Axel Auweter committed
51
52
class SensorConfigImpl;

53
54
55
/**
 * This class is a container for the information DCDB keeps about public sensors.
 */
56
class PublicSensor
Axel Auweter's avatar
Axel Auweter committed
57
58
{
public:
59
60
61
  std::string name;             /**< The public sensor's (public) name. */
  bool        is_virtual;       /**< Denotes whether the sensor is a virtual sensor. */
  std::string pattern;          /**< For non-virtual sensors, this holds a pattern describing the (internal) sensor IDs to which this public sensor matches. */
Michael Ott's avatar
Michael Ott committed
62
  double      scaling_factor;   /**< Scaling factor for every sensor reading */
63
64
65
66
67
68
  std::string unit;             /**< Describes the unit of the sensor. See unitconv.h for known units. */
  bool        integrable;       /**< Determines this sensor as being integrable. */
  std::string expression;       /**< For virtual sensors, this field holds the expression through which the virtual sensor's value is calculated. */
  std::string v_sensorid;       /**< For virtual sensors, this field holds a SensorID used for storing cached values in the database. (FIXME: Cache to be implemented) */
  uint64_t    t_zero;           /**< For virtual sensors, this field holds the first point in time at which the sensor carries a value. */
  uint64_t    frequency;        /**< For virtual sensors, this field holds the interval at which the sensor evaluates (in nanoseconds). */
69
    
70
71
  PublicSensor();
  PublicSensor(const PublicSensor &copy);
Axel Auweter's avatar
Axel Auweter committed
72
73
};

74
75
76
/**
 * Enum type for representing the outcome of a DCDB SensorConfig API operation.
 */
Axel Auweter's avatar
Axel Auweter committed
77
typedef enum {
78
79
80
81
82
83
84
85
86
87
  SC_OK,                /**< Everything went fine. */
  SC_INVALIDSESSION,    /**< The session / database connection is invalid */
  SC_INVALIDPATTERN,    /**< The supplied SensorID pattern is invalid */
  SC_INVALIDPUBLICNAME, /**< The specified public name is invalid */
  SC_INVALIDEXPRESSION, /**< The specified virtual sensor expression is invalid */
  SC_EXPRESSIONSELFREF, /**< The specified virtual sensor references itself in the expression */
  SC_INVALIDVSENSORID,  /**< The virtual SensorID is invalid */
  SC_WRONGTYPE,         /**< You requested an operation for virtual sensors on a physical sensor or vice versa */
  SC_UNKNOWNSENSOR,     /**< The specified sensor is not known */
  SC_UNKNOWNERROR       /**< An unknown error occurred */
Axel Auweter's avatar
Axel Auweter committed
88
89
} SCError;

90
91
92
/**
 * This class holds all functions to create/delete/modify the configuration of (virtual and non-virtual) public sensors in DCDB.
 */
Axel Auweter's avatar
Axel Auweter committed
93
94
95
96
97
98
class SensorConfig
{
protected:
  SensorConfigImpl* impl;

public:
99
100
101
102
103
104
105
  /**
   * @brief Makes a physical sensor public.
   *
   * @param publicName     Name under which the sensor becomes publicly available
   * @param sensorPattern  Pattern which describes the SensorIDs to which this sensor matches
   * @return               See SCError.
   */
Axel Auweter's avatar
Axel Auweter committed
106
  SCError publishSensor(const char* publicName, const char* sensorPattern);
107
108
109
110
111
112
113
114
115
116
117

  /**
   * @brief Creates a new virtual sensor.
   *
   * @param publicName          Name under which the sensor becomes publicly available
   * @param vSensorExpression   Arithmetic expression describing how to evaluate the virtual sensor.
   * @param vSensorId           SensorID under which previously evaluated values may be cached (FIXME: cache to be implemented).
   * @param tZero               Point in time at which the sensor evaluates for the first time.
   * @param frequency           Interval at which the sensor will evaluate (starting from tZero) in nanoseconds.
   * @return                    See SCError.
   */
118
  SCError publishVirtualSensor(const char* publicName, const char* vSensorExpression, const char * vSensorId, TimeStamp tZero, uint64_t frequency);
119
120
121
122
123
124
125

  /**
   * @brief Removes a (virtual or non-virtual) sensor from the list of public sensors.
   *
   * @param publicName          Name under which the sensor becomes publicly available
   * @return                    See SCError.
   */
126
  SCError unPublishSensor(const char* publicName);
127
128
129
130
131
132
133

  /**
   * @brief Get the entire list of (virtual or non-virtual) public sensors.
   *
   * @param publicSensors       Reference to a list of strings that will be populated with the sensor names.
   * @return                    See SCError.
   */
134
  SCError getPublicSensorNames(std::list<std::string>& publicSensors);
135
136
137
138
139
140
141

  /**
   * @brief Get the entire list of (virtual and non-virtual) public sensors including their definition.
   *
   * @param publicSensors       Reference to a list of PublicSensor that will be populated with the sensors' definition.
   * @return                    See SCError.
   */
142
  SCError getPublicSensorsVerbose(std::list<PublicSensor>& publicSensors);
143

144
145
146
147
148
149
150
  /**
   * @brief Get the definition of a virtual sensor.
   *
   * @param sensor              Reference to a PublicSensor object that will be populated with the sensor's definition.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @return                    See SCError.
   */
151
  SCError getPublicSensorByName(PublicSensor& sensor, const char* publicName);
Axel Auweter's avatar
Axel Auweter committed
152

153
154
155
156
157
158
159
  /**
   * @brief Determine whether a given sensor is a virtual sensor.
   *
   * @param isVirtual           Reference to a bool which holds the result.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @return                    See SCError.
   */
160
161
  SCError isVirtual(bool& isVirtual, std::string publicName);

162
163
164
165
166
167
168
  /**
   * @brief Get the SensorID pattern for a given public sensor.
   *
   * @param pattern             Reference to a string which holds the result.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @return                    See SCError.
   */
Axel Auweter's avatar
Axel Auweter committed
169
  SCError getSensorPattern(std::string& pattern, std::string publicName);
170
171
172
173
174
175
176
177

  /**
   * @brief Get the list of SensorIDs (available in the database) that match a given pattern.
   *
   * @param sensorIDs           Reference to a list of SensorID which holds the result.
   * @param pattern             The SensorID pattern which should be matched by the resulting sensors.
   * @return                    See SCError.
   */
Axel Auweter's avatar
Axel Auweter committed
178
  SCError getSensorListForPattern(std::list<SensorId>& sensorIds, std::string pattern);
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

  /**
   * @brief Get the list of SensorIDs (available in the database) that match a given pattern - optimized version.
   *
   * @param pattern             Reference to a string which holds the result.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @param start               Start of the time window
   * @param end                 End of the time window
   * @return                    See SCError.
   *
   * @details Since seeking the list of SensorIDs that match a given SensorID pattern is often
   *          used before querying the database in a given time window, this optimized version
   *          will be helpful in that it only returns SensorIDs that provide data in the given
   *          time window.
   */
194
  SCError getSensorListForPattern(std::list<SensorId>& sensorIds, std::string pattern, TimeStamp start, TimeStamp end);
Axel Auweter's avatar
Axel Auweter committed
195

196
197
198
199
200
201
202
  /**
   * @brief Set the scaling factor for a public sensor. (FIXME: Scaling factors system is not in use!)
   *
   * @param publicName          Name of the sensor.
   * @param scalingFactor       New scaling factor for the sensor.
   * @return                    See SCError.
   */
203
  SCError setSensorScalingFactor(std::string publicName, double scalingFactor);
204
205
206
207
208
209
210
211

  /**
   * @brief Set the unit for a public sensor.
   *
   * @param publicName          Name of the sensor.
   * @param unit                New unis for the sensor. See unitconv.h for a list of supported units.
   * @return                    See SCError.
   */
212
  SCError setSensorUnit(std::string publicName, std::string unit);
213
214
215
216
217
218
219
220

  /**
   * @brief Set a sensor integrable or not.
   *
   * @param publicName          Name of the sensor.
   * @param integrable          New integrable setting for the sensor.
   * @return                    See SCError.
   */
221
222
  SCError setSensorIntegrable(std::string publicName, bool integrable);

223
224
225
226
227
228
229
  /**
   * @brief Set a new sensor expression for a virtual sensor.
   *
   * @param publicName          Name of the sensor.
   * @param expression          New virtual sensor expression.
   * @return                    See SCError.
   */
230
  SCError setVirtualSensorExpression(std::string publicName, std::string expression);
231
232
233
234
235
236
237
238

  /**
   * @brief Set the t0 for a virtual sensor.
   *
   * @param publicName          Name of the sensor.
   * @param tZero               New tZero for the sensor.
   * @return                    See SCError.
   */
239
  SCError setVirtualSensorTZero(std::string publicName, TimeStamp tZero);
240
241
242
243
244
245
246
247

  /**
   * @brief Set the frequency (evaluation interval) for a virtual sensor.
   *
   * @param publicName          Name of the sensor.
   * @param frequency           New evaluation interval for the sensor in nanoseconds.
   * @return                    See SCError.
   */
248
249
  SCError setVirtualSensorFrequency(std::string publicName, uint64_t frequency);

250
251
252
253
254
  /**
   * @brief Constructor for the SensorConfig class.
   *
   * @param conn                Connection object of the current connection into the DCDB data store.
   */
255
  SensorConfig(Connection* conn);
Axel Auweter's avatar
Axel Auweter committed
256
257
258
  virtual ~SensorConfig();
};

259
} /* End of namespace DCDB */
Axel Auweter's avatar
Axel Auweter committed
260

261
#endif /* DCDB_SENSORCONFIG_H */