Aggregator.h

00001 /*
00002  * Aggregator.h
00003  *
00004  * Created on: Nov 1, 2013
00005  * * Authors: Vincent Wochnik <v.wochnik@gmail.com>
00006  *
00007  * Copyright (c) 2013 Cumulocity GmbH
00008  *
00009  * Permission is hereby granted, free of charge, to any person obtaining
00010  * a copy of this software and associated documentation files (the
00011  * "Software"), to deal in the Software without restriction, including
00012  * without limitation the rights to use, copy, modify, merge, publish,
00013  * distribute, sublicense, and/or sell copies of the Software, and to
00014  * permit persons to whom the Software is furnished to do so, subject to
00015  * the following conditions:
00016  *
00017  * The above copyright notice and this permission notice shall be
00018  * included in all copies or substantial portions of the Software.
00019  *
00020  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00021  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00022  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00023  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
00024  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
00025  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00026  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00027  */
00028 
00029 #ifndef AGGREGATOR_H
00030 #define AGGREGATOR_H
00031 
00032 #include "config.h"
00033 #include <stddef.h>
00034 #include "DataGenerator.h"
00035 #include "Record.h"
00036 
00037 #ifndef SMARTREST_AGGREGATOR_INITIAL_CAPACITY
00038 #define SMARTREST_AGGREGATOR_INITIAL_CAPACITY 50
00039 #endif
00040 #ifndef SMARTREST_AGGREGATOR_MEMORY_INCREMENT
00041 #define SMARTREST_AGGREGATOR_MEMORY_INCREMENT 25
00042 #endif
00043 //#define SMARTREST_AGGREGATOR_FIXED_SIZE 100
00044 
00045 /**
00046  * An aggregator of records.
00047  * 
00048  * Example:
00049  * @code
00050  * // Given: A concrete SmartRest implementation.
00051  * SmartRest client;
00052  * 
00053  * // sets up a growing aggregator which copies all added objects
00054  * // to the heap
00055  * Aggregator buffer(25, true, true);
00056  * 
00057  * // random data collection
00058  * for (uint8_t i = 0; i < 32; ++i) {
00059  *     // Note: ComposedRecord is not copying any values into the heap
00060  *     // because the availability of its values in guaranteed during the
00061  *     // instance's lifetime.
00062  *     ComposedRecord record(false);
00063  *     
00064  *     CharValue msgId(100);
00065  *     IntegerValue number(i);
00066  *     record.add(msgId).add(number);
00067  *     
00068  *     // Note: ComposedRecord is now cloned into the heap to extend its
00069  *     // lifetime beyond this code block.
00070  *     buffer.add(record);
00071  * }
00072  * 
00073  * // send the bulk request
00074  * uint8_t ret = client.send(buffer);
00075  * if (ret != SMARTREST_SUCCESS) {
00076  *     // error handling
00077  * }
00078  * @encode
00079  */
00080 class Aggregator : public DataGenerator
00081 {
00082     public:
00083 #ifndef SMARTREST_AGGREGATOR_FIXED_SIZE
00084         /**
00085          * Creates a new Aggregator instance.
00086          * @param capacity the initial capacity of the instance
00087          * @param growing specifies the capability of this instance to grow
00088          * @param managed specifies whether internal memory management shall be
00089          *                used. If true, all added records will be copied to
00090          *                the heap and freed accordingly.
00091          */
00092         Aggregator(size_t = SMARTREST_AGGREGATOR_INITIAL_CAPACITY, bool = true, bool = false);
00093 #else
00094         /**
00095          * Creates a new Aggregator instance.
00096          * @param managed specifies whether internal memory management shall be
00097          *                used. If true, all added records will be copied to
00098          *                the heap and freed accordingly.
00099          */
00100         Aggregator(bool = false);
00101 #endif
00102         virtual ~Aggregator();
00103 
00104         /**
00105          * Adds a record to the aggregator.
00106          * @param record the record to add
00107          * @return true if added, false otherwise.
00108          */
00109         bool add(const Record&);
00110 
00111         /**
00112          * Retrieves the nth record from the aggregator.
00113          * @param index the index of the nth element to retrieve
00114          */
00115         const Record& get(size_t) const;
00116 
00117         /**
00118          * Clears the aggregator. The capacity will shrink to it's initial
00119          * size.
00120          */
00121         void clear();
00122 
00123         /**
00124          * Returns the number of records aggregated by this instance.
00125          * @return the number of records aggregated
00126          */
00127         size_t length() const;
00128 
00129         /**
00130          * Returns whether the aggregator is full. If growing, this will
00131          * always return false.
00132          * @return whether the aggregator is full
00133          */
00134         bool full() const;
00135 
00136         /**
00137          * Returns the capacity of the aggregator. This will always return zero
00138          * if the aggregator is growing.
00139          */
00140         size_t capacity() const;
00141 
00142         /**
00143          * Returns whether this aggregator is using internal memory management.
00144          * @return whether internal memory management is being used
00145          */
00146         bool managed() const;
00147 
00148         virtual size_t writeTo(AbstractDataSink&) const;
00149         virtual size_t writtenLength() const;
00150         virtual Aggregator* copy() const;
00151 
00152     private:
00153 #ifdef SMARTREST_AGGREGATOR_FIXED_SIZE
00154         const Record *_list[SMARTREST_AGGREGATOR_FIXED_SIZE];
00155 #else
00156         const Record **_list;
00157 #endif
00158         size_t _length;
00159 #ifndef SMARTREST_AGGREGATOR_FIXED_SIZE
00160         size_t _capacity, _initial;
00161         bool _growing;
00162 #endif
00163         bool _managed;
00164 };
00165 
00166 #endif