AggregationElement.h

Go to the documentation of this file.

// 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 "AggMemberDataset.h" // agg_util
#include "AggregationUtil.h" // agg_util
#include "ArrayJoinExistingAggregation.h" // agg_util
#include <memory>
#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;
using std::auto_ptr;

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 doesDimensionCacheExist() const;

    void loadDimensionCacheFromCacheFile(agg_util::AMDList& rGranuleList);

    bool doesFirstGranuleSpecifyNcoords() const;

    bool doAllGranulesSpecifyNcoords() const;

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

    void seedDimensionCacheByQueryOfDatasets(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);


    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 );

    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);

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

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

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

    auto_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__ */