NCMLParser.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_NCML_PARSER_H__
#define __NCML_MODULE_NCML_PARSER_H__
 
#include "config.h"
 
#include <memory>
#include <stack>
#include <string>
#include <vector>
 
#include <libdap/AttrTable.h> // needed due to parameter with AttrTable::Attr_iter
 
#include "DDSLoader.h"
#include "NCMLElement.h" // NCMLElement::Factory
#include "SaxParser.h" // interface superclass
#include "ScopeStack.h"
#include "XMLHelpers.h"
 
//FDecls
 
namespace agg_util {
class DDSLoader;
}
 
namespace libdap {
class BaseType;
class DAS;
class DDS;
}
 
class BESDapResponse;
class BESDataDDSResponse;
class BESDDSResponse;
 
namespace ncml_module {
class AggregationElement;
class DimensionElement;
class NCMLElement;
class NetcdfElement;
class OtherXMLParser;
}
 
using namespace libdap;

namespace ncml_module {
 
// FDecls
class NCMLParser;
 
// Helper class to lazy load the AttrTable for a DDS so we don't load for aggregations
// that do not actually use it.
class AttrTableLazyPtr {
private:
    // disallow these.
    AttrTableLazyPtr(const AttrTableLazyPtr&);
    AttrTableLazyPtr& operator=(const AttrTableLazyPtr&);
public:
    AttrTableLazyPtr(const NCMLParser& parser, AttrTable* pAT = 0);
    ~AttrTableLazyPtr();

    AttrTable* get() const;

    void set(AttrTable* pAT);

    void invalidate();
 
private:
 
    void loadAndSetAttrTable();
 
    const NCMLParser& _parser;
    mutable AttrTable* _pAttrTable;
    mutable bool _loaded;
};
 
class NCMLParser: public SaxParser {
public:
    // Friends
    // We allow the various NCMLElement concrete classes to be friends so we can separate out the functionality
    // into several files, one for each NcML element type.
    friend class AggregationElement;
    friend class AttrTableLazyPtr;
    friend class AttributeElement;
    friend class DimensionElement;
    friend class ExplicitElement;
    friend class NetcdfElement;
    friend class ReadMetadataElement;
    friend class RemoveElement;
    friend class ScanElement;
    friend class ValuesElement;
    friend class VariableAggElement;
    friend class VariableElement;
 
public:
    NCMLParser(agg_util::DDSLoader& loader);
 
    virtual ~NCMLParser();
 
private:
    NCMLParser(const NCMLParser& from);

    NCMLParser& operator=(const NCMLParser& from);
 
public:

    std::unique_ptr<BESDapResponse> parse(const std::string& ncmlFilename, agg_util::DDSLoader::ResponseType type);

    void parseInto(const string& ncmlFilename, agg_util::DDSLoader::ResponseType responseType,
        BESDapResponse* response);

    bool parsing() const;

    int getParseLineNumber() const;

    const XMLNamespaceStack& getXMLNamespaceStack() const;

    // Interface SaxParser:  Wrapped calls from the libxml C SAX parser
 
    virtual void onStartDocument();
    virtual void onEndDocument();
    virtual void onStartElement(const std::string& name, const XMLAttributeMap& attrs);
    virtual void onEndElement(const std::string& name);
 
    virtual void onStartElementWithNamespace(const std::string& localname, const std::string& prefix,
        const std::string& uri, const XMLAttributeMap& attributes, const XMLNamespaceMap& namespaces);
 
    virtual void onEndElementWithNamespace(const std::string& localname, const std::string& prefix,
        const std::string& uri);
 
    virtual void onCharacters(const std::string& content);
    virtual void onParseWarning(std::string msg);
    virtual void onParseError(std::string msg);
    virtual void setParseLineNumber(int line);

 
private:
    //methods

    bool isScopeAtomicAttribute() const;

    bool isScopeAttributeContainer() const;

    bool isScopeSimpleVariable() const;

    bool isScopeCompositeVariable() const;

    bool isScopeVariable() const;

    bool isScopeGlobal() const;

    bool isScopeNetcdf() const;

    bool isScopeAggregation() const;

    bool withinNetcdf() const;

    bool withinVariable() const;
 
    agg_util::DDSLoader& getDDSLoader() const;

    NetcdfElement* getCurrentDataset() const;

    void setCurrentDataset(NetcdfElement* dataset);

    NetcdfElement* getRootDataset() const;

    DDS* getDDSForCurrentDataset() const;

    void pushCurrentDataset(NetcdfElement* dataset);

    void addChildDatasetToCurrentDataset(NetcdfElement* dataset);

    void popCurrentDataset(NetcdfElement* dataset);

    bool parsingDataRequest() const;

    void resetParseState();

    void loadLocation(const std::string& location, agg_util::DDSLoader::ResponseType responseType,
        BESDapResponse* response);

    bool isNameAlreadyUsedAtCurrentScope(const std::string& name);

    BaseType* getVariableInCurrentVariableContainer(const string& name);

    BaseType* getVariableInContainer(const string& varName, BaseType* pContainer);

    BaseType* getVariableInDDS(const string& varName);

    void addCopyOfVariableAtCurrentScope(BaseType& varTemplate);

    void deleteVariableAtCurrentScope(const string& name);

    BaseType* getCurrentVariable() const;

    void setCurrentVariable(BaseType* pVar);

    static bool typeCheckDAPVariable(const BaseType& var, const string& expectedType);

    AttrTable* getCurrentAttrTable() const;

    void setCurrentAttrTable(AttrTable* pAT);

    AttrTable* getGlobalAttrTable() const;

    bool attributeExistsAtCurrentScope(const string& name) const;

    bool findAttribute(const string& name, AttrTable::Attr_iter& attr) const;

    void clearAllAttrTables(DDS* dds);

    void clearVariableMetadataRecursively(BaseType* var);

    int tokenizeAttrValues(vector<string>& tokens, const string& values, const string& dapAttrTypeName,
        const string& separator);

    int tokenizeValuesForDAPType(vector<string>& tokens, const string& values, AttrType dapType,
        const string& separator);

    void enterScope(const string& name, ScopeStack::ScopeType type);

    void exitScope();

    void printScope() const;

    string getScopeString() const;

    string getTypedScopeString() const;

    int getScopeDepth() const;

    void pushElement(NCMLElement* elt);

    void popElement();

    NCMLElement* getCurrentElement() const;

    typedef std::vector<NCMLElement*>::const_reverse_iterator ElementStackConstIterator;
    ElementStackConstIterator getElementStackBegin() const
    {
        return _elementStack.rbegin();
    }
    ElementStackConstIterator getElementStackEnd() const
    {
        return _elementStack.rend();
    }

    void clearElementStack();

    void processStartNCMLElement(const std::string& name, const XMLAttributeMap& attrs);

    void processEndNCMLElement(const std::string& name);

    const DimensionElement* getDimensionAtLexicalScope(const string& dimName) const;

    string printAllDimensionsAtLexicalScope() const;

    void enterOtherXMLParsingState(OtherXMLParser* pOtherXMLParser);
    bool isParsingOtherXML() const;

    void cleanup();
 
public:
    // Class Helpers

    static const string STRUCTURE_TYPE;

    static string convertNcmlTypeToCanonicalType(const string& ncmlType);

    void checkDataIsValidForCanonicalTypeOrThrow(const string& type, const vector<string>& tokens) const;

private:
    // data rep
 
    // If true, we will consider unknown ncml elements as parse errors and raise exception.
    // If false, we just BESDEBUG the warning and ignore them entirely.
    static bool sThrowExceptionOnUnknownElements;
 
    // name of the ncml file we are parsing
    string _filename;
 
    // Handed in at creation, this is a helper to load a given DDS.  It is assumed valid for the life of this.
    agg_util::DDSLoader& _loader;
 
    // The type of response in _response
    agg_util::DDSLoader::ResponseType _responseType;
 
    // The response object containing the DDS (or DataDDS) for the root dataset we are processing, or null if not processing.
    // Type is based on _responseType.   We do not own this memory!  It is a temp while we parse and is handed in.
    // NOTE: The root dataset will use this for its response object!
    BESDapResponse* _response;
 
    // The element factory to use to create our NCMLElement's.
    // All objects created by this factory will be deleted in the dtor
    // regardless of their ref counts!
    NCMLElement::Factory _elementFactory;
 
    // The root dataset, as a NetcdfElement*.
    NetcdfElement* _rootDataset;
 
    // The currently being parsed dataset, as a NetcdfElement
    NetcdfElement* _currentDataset;
 
    // pointer to currently processed variable, or NULL if none (ie we're at global level).
    BaseType* _pVar;
 
    // Only grabs the actual ptr (by loading the DDS from the current dataset)
    // when getCurrentAttrTable() is called so we don't explicitly load every
    // DDS, only those which we want to modify.
    AttrTableLazyPtr _pCurrentTable;
 
    // A stack of NcML elements we push as we begin and pop as we end.
    // The memory is owned by this, so we must clear this in dtor and
    // on pop.
    std::vector<NCMLElement*> _elementStack;
 
    // As we parse, we'll use this as a stack for keeping track of the current
    // scope we're in.  In other words, this stack will refer to the container where _pCurrTable is in the DDS.
    // if empty() then we're in global dataset scope (or no scope if not parsing location yet).
    ScopeStack _scope;
 
    // Keeps track of the XMLNamespace's that come in with each new
    // onStartElementWithNamespace and gets popped on
    // onEndElementWithNamespace.
    XMLNamespaceStack _namespaceStack;
 
    // If not null, we've temporarily stopped the normal NCML parse and are passing
    // all calls to this proxy until the element on the stack when it was added is
    // closed (and the parser depth is zero!).
    OtherXMLParser* _pOtherXMLParser;
 
    // Where we are in the parse to help debugging, set from the SaxParser interface.
    int _currentParseLine;
 
};
// class NCMLParser
 
}//namespace ncml_module
 
#endif /* __NCML_MODULE_NCML_PARSER_H__ */