AggregationElement.h

// This file is part of the "NcML Module" project, a BES module designed
// to allow NcML files to be used to be used as a wrapper to add
// AIS to existing datasets of any format.
//
// Copyright (c) 2009 OPeNDAP, Inc.
// Author: Michael Johnson  <m.johnson@opendap.org>
//
// For more information, please also see the main website: http://opendap.org/
//
// 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
//
// Please see the files COPYING and COPYRIGHT for more information on the GLPL.
//
// You can contact OPeNDAP, Inc. at PO Box 112, Saunderstown, RI. 02874-0112.
#ifndef __NCML_MODULE__AGGREGATION_ELEMENT_H__
#define __NCML_MODULE__AGGREGATION_ELEMENT_H__
 
#include <memory>
 
#include "AggMemberDataset.h" // agg_util
#include "AggregationUtil.h" // agg_util
#include "ArrayJoinExistingAggregation.h" // agg_util
 
#include "NCMLElement.h"
#include "NCMLUtil.h"
 
namespace agg_util {
struct Dimension;
}
 
namespace libdap {
class Array;
class BaseType;
class DDS;
class Grid;
}
 
using agg_util::AggMemberDataset;
using libdap::Array;
using libdap::BaseType;
using libdap::DDS;
using libdap::Grid;
 
namespace ncml_module {
class NetcdfElement;
class NCMLParser;
class ScanElement;
 
class AggregationElement: public NCMLElement {
private:
    AggregationElement& operator=(const AggregationElement& rhs); // disallow
 
public:
    // Name of the element
    static const string _sTypeName;
 
    // All possible attributes for this element.
    static const vector<string> _sValidAttrs;
 
    AggregationElement();
    AggregationElement(const AggregationElement& proto);
    virtual ~AggregationElement();
    virtual const string& getTypeName() const;
    virtual AggregationElement* clone() const; // override clone with more specific subclass
    virtual void setAttributes(const XMLAttributeMap& attrs);
    virtual void handleBegin();
    virtual void handleContent(const string& content);
    virtual void handleEnd();
    virtual string toString() const;
 
    const string& type() const
    {
        return _type;
    }
    const string& dimName() const
    {
        return _dimName;
    }
    const string& recheckEvery() const
    {
        return _recheckEvery;
    }
 
    bool isJoinNewAggregation() const;
    bool isUnionAggregation() const;
    bool isJoinExistingAggregation() const;

    NetcdfElement* setParentDataset(NetcdfElement* parent);
    NetcdfElement* getParentDataset() const
    {
        return _parent;
    }

    void addChildDataset(NetcdfElement* pDataset);

    void addAggregationVariable(const string& name);

    bool isAggregationVariable(const string& name) const;
 
    string printAggregationVariables() const;
 
    typedef vector<string>::const_iterator AggVarIter;
    AggVarIter beginAggVarIter() const;
    AggVarIter endAggVarIter() const;

    bool gotVariableAggElement() const;

    void setVariableAggElement();

    void addScanElement(ScanElement* pScanner);

    void processParentDatasetComplete();

    void setAggregationVariableCoordinateAxisType(const std::string& cat);

    const std::string& getAggregationVariableCoordinateAxisType() const;
 
private:
    // methods
 
    void processUnion();
    void processJoinNew();
    void processJoinExisting();

    void unionAddAllRequiredNonAggregatedVariablesFrom(const DDS& templateDDS);

    void fillDimensionCacheForJoinExistingDimension(agg_util::AMDList& granuleList, const std::string& aggDimName);

    bool doesFirstGranuleSpecifyNcoords() const;

    bool doAllGranulesSpecifyNcoords() const;

    void seedDimensionCacheFromUserSpecs(agg_util::AMDList& rGranuleList) const;

    void addNewDimensionForJoinExisting(const agg_util::AMDList& rGranuleList);

    void decideWhichVariablesToJoinExist(const libdap::DDS& templateDDS);

    void findVariablesWithOuterDimensionName(vector<string>& oMatchingVars, const DDS& templateDDS,
        const string& outerDimName) const;

    struct JoinAggParams {
        JoinAggParams() :
            _pAggVarTemplate(0), _pAggDim(0), _memberDatasets()
        {
        }
 
        ~JoinAggParams()
        {
            _pAggVarTemplate = NULL;
            _pAggDim = NULL;
            _memberDatasets.clear();
            _memberDatasets.resize(0);
        }
 
        libdap::BaseType* _pAggVarTemplate; // template for the granule's aggVar
        const agg_util::Dimension* _pAggDim; // the aggregated dimension (with full size)
        agg_util::AMDList _memberDatasets; // the granule datasets to use
    }; // struct JoinAggParams

    void getParamsForJoinAggOnVariable(JoinAggParams* pOutParams, const DDS& aggOutputDDS, const std::string& varName,
        const DDS& templateDDS);

    void processJoinNewOnAggVar(DDS* pAggDDS, const std::string& varName, const DDS& templateDDS);

    void processJoinExistingOnAggVar(DDS* pAggDDS, const std::string& varName, const DDS& templateDDS);

    static void processAggVarJoinNewForArray(DDS& aggDDS, const Array& arrayTemplate, const agg_util::Dimension& dim,
        const agg_util::AMDList& memberDatasets);

    void processAggVarJoinNewForGrid(DDS& aggDDS, const Grid& gridTemplate, const agg_util::Dimension& dim,
        const agg_util::AMDList& memberDatasets);
 
    static void processAggVarJoinExistingForArray(DDS& aggDDS, const libdap::Array& arrayTemplate,
        const agg_util::Dimension& dim, const agg_util::AMDList& memberDatasets);
 
    void processAggVarJoinExistingForGrid(DDS& aggDDS, const Grid& gridTemplate, const agg_util::Dimension& dim,
        const agg_util::AMDList& memberDatasets);

    void collectDatasetsInOrder(vector<const DDS*>& ddsList) const;

    void collectAggMemberDatasets(agg_util::AMDList& rMemberDatasets) const;

    void processAnyScanElements();

    void mergeDimensions(bool checkDimensionMismatch = true, const std::string& dimToSkip = "");

    void processParentDatasetCompleteForJoinNew();

    void processParentDatasetCompleteForJoinExisting();

    void processPlaceholderCoordinateVariableForJoinExisting(const libdap::BaseType& placeholderVar,
        libdap::Array* pNewVar);

    libdap::Array* ensureVariableIsProperNewCoordinateVariable(libdap::BaseType* pBT, const agg_util::Dimension& dim,
        bool throwIfInvalid) const;

    libdap::Array* findMatchingCoordinateVariable(const DDS& dds, const agg_util::Dimension& dim,
        bool throwOnInvalidCV = true) const;

    libdap::Array* processDeferredCoordinateVariable(libdap::BaseType* pBT, const agg_util::Dimension& dim);

    std::unique_ptr<libdap::Array> createCoordinateVariableForNewDimension(const agg_util::Dimension& dim) const;

    libdap::Array* createAndAddCoordinateVariableForNewDimension(libdap::DDS& dds, const agg_util::Dimension& dim);

    std::unique_ptr<libdap::Array> createCoordinateVariableForNewDimensionUsingCoordValue(
        const agg_util::Dimension& dim) const;
    std::unique_ptr<libdap::Array> createCoordinateVariableForNewDimensionUsingCoordValueAsDouble(
        const agg_util::Dimension& dim) const;
    std::unique_ptr<libdap::Array> createCoordinateVariableForNewDimensionUsingCoordValueAsString(
        const agg_util::Dimension& dim) const;

    std::unique_ptr<libdap::Array> createCoordinateVariableForNewDimensionUsingLocation(const agg_util::Dimension& dim) const;

    static void addCoordinateAxisType(libdap::Array& rCV, const std::string& cat);
 
    // Return the list of valid attribute names.
    static vector<string> getValidAttributes();
 
private:
    // Data rep
 
    string _type; // required oneof { union | joinNew | joinExisting | forecastModelRunCollection | forecastModelSingleRunCollection }
    string _dimName;
    string _recheckEvery;
 
    // Our containing NetcdfElement, which must exist.  This needs to be a weak reference to avoid ref loop....
    NetcdfElement* _parent;
 
    // The vector of explicit, ordered NetcdfElement*.  We assume a STRONG reference to these
    // if they are in this container and we must deref() them on dtor.
    vector<NetcdfElement*> _datasets;
 
    // The vector of scan elements
    vector<ScanElement*> _scanners;
 
    // A vector containing the names of the variables to be aggregated in this aggregation.
    // Not used for union.
    vector<string> _aggVars;
 
    // Did a variableAgg element set our _aggVars or not?
    bool _gotVariableAggElement;
 
    // Did we add a join existing aggregated Grid to the output yet?
    // Needed to know if we need to add an aggregated map c.v. to output.
    bool _wasAggregatedMapAddedForJoinExistingGrid;
 
    // If set, we want to create a new attribute _CoordinateAxisType
    // with this value on each aggVar.
    std::string _coordinateAxisType;
 
};
 
}
 
#endif /* __NCML_MODULE__AGGREGATION_ELEMENT_H__ */