NCMLParser.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_NCML_PARSER_H__
#define __NCML_MODULE_NCML_PARSER_H__

#include "config.h"

#include <memory>
#include <stack>
#include <string>
#include <vector>

#include <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;
using namespace std;


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:

  auto_ptr<BESDapResponse> parse(const 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__ */