Add HDFDescriptor class that will describe HDF files.

The checks for the headers at the start of HDF4 & HDF5 files have been
put in a static isHDF member to encapsulate the details about
checking for a HDF file and make it reusable.
It will not retain an open file handle to the file so does not
inherit from the standard FileDescriptor.
Refs #7263

Code/Mantid/Framework/Kernel/CMakeLists.txt

@@ -27,6 +27,7 @@ set ( SRC_FILES
 	src/FloatingPointComparison.cpp
 	src/FreeBlock.cpp
 	src/Glob.cpp
+	src/HDFDescriptor.cpp
 	src/IPropertyManager.cpp
 	src/ISaveable.cpp
 	src/InstrumentInfo.cpp
@@ -144,6 +145,7 @@ set ( INC_FILES
 	inc/MantidKernel/FreeBlock.h
 	inc/MantidKernel/FunctionTask.h
 	inc/MantidKernel/Glob.h
+	inc/MantidKernel/HDFDescriptor.h
 	inc/MantidKernel/IPropertyManager.h
 	inc/MantidKernel/IPropertySettings.h
 	inc/MantidKernel/ISaveable.h
@@ -262,6 +264,7 @@ set ( TEST_FILES
 	FunctionTaskTest.h
 	GlobTest.h
 	HermitePolynomialsTest.h
+	HDFDescriptorTest.h
 	IPropertySettingsTest.h
 	ISaveableTest.h
 	IValidatorTest.h

Code/Mantid/Framework/Kernel/inc/MantidKernel/HDFDescriptor.h

+#ifndef MANTID_KERNEL_HIERARCHICALFILEDESCRIPTOR_H_
+#define MANTID_KERNEL_HIERARCHICALFILEDESCRIPTOR_H_
+
+#include "MantidKernel/ClassMacros.h"
+#include "MantidKernel/DllConfig.h"
+
+#include <string>
+
+namespace Mantid
+{
+  namespace Kernel
+  {
+
+    /** 
+        Defines a wrapper around a file whose internal structure is stored in a hierarchy, e.g NeXus.
+
+        On construction the simple details about the layout of the file are cached for faster querying later.
+
+        Copyright &copy; 2013 ISIS Rutherford Appleton Laboratory & NScD Oak Ridge National Laboratory
+
+        This file is part of Mantid.
+
+        Mantid is free software; you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation; either version 3 of the License, or
+        (at your option) any later version.
+
+        Mantid 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 General Public License for more details.
+
+        You should have received a copy of the GNU General Public License
+        along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+        File change history is stored at: <https://github.com/mantidproject/mantid>
+        Code Documentation is available at: <http://doxygen.mantidproject.org>
+     */
+    class MANTID_KERNEL_DLL HDFDescriptor
+    {
+    public:
+      /// Enumerate HDF possible versions
+      enum Version { Version4, Version5, AnyVersion };
+
+      static const size_t HDFMagicSize;
+      /// HDF cookie that is stored in the first 4 bytes of the file.
+      static const unsigned char HDFMagic[4];
+      /// Size of HDF5 signature
+      static size_t HDF5SignatureSize;
+      /// signature identifying a HDF5 file.
+      static const unsigned char HDF5Signature[8];
+
+      /// Returns true if the file is considered to store data in a hierarchy
+      static bool isHDF(const std::string & filename, const Version version = AnyVersion);
+
+    public:
+      /// Constructor accepting a filename
+      HDFDescriptor(const std::string & filename);
+      /**
+       * Access the filename
+       * @returns A reference to a const string containing the filename
+       */
+      inline const std::string & filename() const { return m_filename; }
+      /**
+       * Access the file extension. Defined as the string after and including the last period character
+       * @returns A reference to a const string containing the file extension
+       */
+      inline const std::string & extension() const { return m_extension; }
+
+      /// Query if a path exists
+      bool pathExists(const std::string&) const;
+
+    private:
+      DISABLE_DEFAULT_CONSTRUCT(HDFDescriptor);
+      DISABLE_COPY_AND_ASSIGN(HDFDescriptor);
+
+      /// Initialize object with filename
+      void initialize(const std::string& filename);
+
+
+      /// Full filename
+      std::string m_filename;
+      /// Extension
+      std::string m_extension;
+    };
+
+
+  } // namespace Kernel
+} // namespace Mantid
+
+#endif  /* MANTID_KERNEL_HIERARCHICALFILEDESCRIPTOR_H_ */

Code/Mantid/Framework/Kernel/src/HDFDescriptor.cpp

+#include "MantidKernel/HDFDescriptor.h"
+#include "MantidKernel/Exception.h"
+
+#include <nexus/NeXusFile.hpp>
+#include <nexus/NeXusException.hpp>
+
+#include <Poco/File.h>
+#include <Poco/Path.h>
+
+#include <cstring>
+
+namespace Mantid
+{
+  namespace Kernel
+  {
+    //---------------------------------------------------------------------------------------------------------------------------
+    // static HDFDescriptor constants
+    //---------------------------------------------------------------------------------------------------------------------------
+    /// Size of HDF magic number
+    const size_t HDFDescriptor::HDFMagicSize = 4;
+    /// HDF cookie that is stored in the first 4 bytes of the file.
+    const unsigned char HDFDescriptor::HDFMagic[4] = {'\016','\003','\023','\001'}; // From HDF4::hfile.h
+
+    /// Size of HDF5 signature
+    size_t HDFDescriptor::HDF5SignatureSize = 8;
+    /// signature identifying a HDF5 file.
+    const unsigned char HDFDescriptor::HDF5Signature[8] = { 137, 'H', 'D', 'F', '\r', '\n', '\032', '\n' };
+
+    namespace
+    {
+      //---------------------------------------------------------------------------------------------------------------------------
+      // Anonymous helper methods to use isHDF methods to use an open file handle
+      //---------------------------------------------------------------------------------------------------------------------------
+
+      /**
+       * Currently simply checks for the HDF signatures and returns true if one of them is found
+       * @param fileHandle A file handled opened and pointing at the start of the file. On return the
+       * fileHandle is left at the start of the file
+       * @param version One of the HDFDescriptor::Version enumerations specifying the required version
+       * @return True if the file is considered hierarchical, false otherwise
+       */
+      bool isHDFHandle(FILE *fileHandle, HDFDescriptor::Version version)
+      {
+        if(!fileHandle) throw std::invalid_argument("HierarchicalFileDescriptor::isHierarchical - Invalid file handle");
+
+        bool result(false);
+
+        // HDF4 check requires 4 bytes,  HDF5 check requires 8 bytes
+        // Use same buffer and waste a few bytes if only checking HDF4
+        unsigned char buffer[8] = {'0','0','0','0','0','0','0','0'};
+        std::fread(static_cast<void*>(&buffer), sizeof(unsigned char), HDFDescriptor::HDF5SignatureSize, fileHandle);
+        // Number of bytes read doesn't matter as if it is not enough then the memory simply won't match
+        // as the buffer has been "zeroed"
+        if(version == HDFDescriptor::Version5 || version == HDFDescriptor::AnyVersion )
+        {
+          result = (std::memcmp(&buffer, &HDFDescriptor::HDF5Signature, HDFDescriptor::HDF5SignatureSize) == 0);
+        }
+        if(!result && (version == HDFDescriptor::Version4 || version == HDFDescriptor::AnyVersion) )
+        {
+          result = (std::memcmp(&buffer, &HDFDescriptor::HDFMagic, HDFDescriptor::HDFMagicSize) == 0);
+        }
+
+        // Return file stream to start of file
+        std::rewind(fileHandle);
+        return result;
+      }
+    }
+
+    //---------------------------------------------------------------------------------------------------------------------------
+    // static HDFDescriptor methods
+    //---------------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Checks for the HDF signatures and returns true if one of them is found
+     * @param filename A string filename to check
+     * @param version One of the HDFDescriptor::Version enumerations specifying the required version
+     * @return True if the file is considered hierarchical, false otherwise
+     */
+    bool HDFDescriptor::isHDF(const std::string & filename, const Version version)
+    {
+      FILE *fd = fopen(filename.c_str(), "rb");
+      if(!fd)
+      {
+        throw std::invalid_argument("HierarchicalFileDescriptor::isHierarchical - Unable to open file '" + filename + "'");
+      }
+      const bool result = isHDFHandle(fd, version); // use anonymous helper
+      fclose(fd);
+      return result;
+    }
+
+    //---------------------------------------------------------------------------------------------------------------------------
+    // HDFDescriptor public methods
+    //---------------------------------------------------------------------------------------------------------------------------
+    /**
+     * Constructs the wrapper
+     * @param filename A string pointing to an existing file
+     * @throws std::invalid_argument if the file is not identified to be hierarchical. This currently
+     * involves simply checking for the signature if a HDF file at the start of the file
+     */
+    HDFDescriptor::HDFDescriptor(const std::string & filename)
+      : m_filename(), m_extension()
+    {
+      if(filename.empty())
+      {
+        throw std::invalid_argument("HDFDescriptor() - Empty filename '" + filename + "'");
+      }
+      if(!Poco::File(filename).exists())
+      {
+        throw std::invalid_argument("HDFDescriptor() - File '" + filename + "' does not exist");
+      }
+      initialize(filename);
+    }
+
+    /**
+     * @param path A string giving a path using UNIX-style path separators (/), e.g. /raw_data_1, /entry/bank1
+     * @return True if the path exists in the file, false otherwise
+     */
+    bool HDFDescriptor::pathExists(const std::string& path) const
+    {
+      return true;
+    }
+
+    //---------------------------------------------------------------------------------------------------------------------------
+    // HDFDescriptor private methods
+    //---------------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Creates the internal cached structure of the file as a tree of nodes
+     */
+    void HDFDescriptor::initialize(const std::string& filename)
+    {
+      m_filename = filename;
+      m_extension = "." + Poco::Path(filename).getExtension();
+
+      try
+      {
+        ::NeXus::File file(this->filename());
+      }
+      catch(::NeXus::Exception &)
+      {
+        throw std::invalid_argument("HDFDescriptor::initialize - File '" + filename + "' does not look like a HDF file.");
+      }
+//      // Root node has no type and is named "/"
+//      m_root->name = "/";
+//
+//      addChildren(file, "/", m_root);
+//
+
+//      auto rootEntries = file.getEntries();
+//      for(auto it = rootEntries.begin(); rootEntries.end(); ++it)
+//      {
+//        auto node = boost::make_shared<Node>();
+//        node->name = it->first;
+//        node->type = it->second;
+//        m_roots.insert(std::make_pair(it->first, node));
+//      }
+    }
+
+
+  } // namespace Kernel
+} // namespace Mantid

Code/Mantid/Framework/Kernel/test/HDFDescriptorTest.h

+#ifndef MANTID_KERNEL_HDFDESCRIPTORTEST_H_
+#define MANTID_KERNEL_HDFDESCRIPTORTEST_H_
+
+#include <cxxtest/TestSuite.h>
+#include "MantidKernel/ConfigService.h"
+#include "MantidKernel/HDFDescriptor.h"
+
+#include <Poco/Path.h>
+#include <Poco/File.h>
+
+#include <cstdio>
+
+using Mantid::Kernel::HDFDescriptor;
+
+class HDFDescriptorTest : public CxxTest::TestSuite
+{
+public:
+  // This pair of boilerplate methods prevent the suite being created statically
+  // This means the constructor isn't called when running other tests
+  static HDFDescriptorTest *createSuite() { return new HDFDescriptorTest(); }
+  static void destroySuite( HDFDescriptorTest *suite ) { delete suite; }
+
+
+  HDFDescriptorTest()
+  {
+    using Mantid::Kernel::ConfigService;
+    auto dataPaths = ConfigService::Instance().getDataSearchDirs();
+    for(auto it = dataPaths.begin(); it != dataPaths.end(); ++it)
+    {
+      Poco::Path hdf5Path(*it, "CNCS_7860_event.nxs");
+      if(Poco::File(hdf5Path).exists()) m_testHDF5Path = hdf5Path.toString();
+
+      Poco::Path hdf4Path(*it, "argus0026287.nxs");
+      if(Poco::File(hdf4Path).exists()) m_testHDF4Path = hdf4Path.toString();
+
+      Poco::Path nonhdf5Path(*it, "CSP79590.raw");
+      if(Poco::File(nonhdf5Path).exists()) m_testNonHDFPath = nonhdf5Path.toString();
+
+      if(!m_testHDF5Path.empty() && !m_testHDF4Path.empty() && !m_testNonHDFPath.empty()) break;
+    }
+    if(m_testHDF5Path.empty() || m_testHDF4Path.empty() || m_testNonHDFPath.empty())
+    {
+      throw std::runtime_error("Unable to find test files for FileDescriptorTest. "
+          "The AutoTestData directory needs to be in the search path");
+    }
+  }
+
+  //=================================== Static isHDF methods ======================================
+  void test_isHDF_Returns_False_For_Non_HDF_Filename()
+  {
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testNonHDFPath));
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testNonHDFPath, HDFDescriptor::AnyVersion));
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testNonHDFPath, HDFDescriptor::Version4));
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testNonHDFPath, HDFDescriptor::Version5));
+  }
+
+  void test_isHDF_Defaults_To_All_Versions()
+  {
+    TS_ASSERT(HDFDescriptor::isHDF(m_testHDF4Path));
+    TS_ASSERT(HDFDescriptor::isHDF(m_testHDF5Path));
+  }
+
+  void test_isHDF_With_Version4_Returns_True_Only_For_HDF4()
+  {
+    TS_ASSERT(HDFDescriptor::isHDF(m_testHDF4Path, HDFDescriptor::Version4));
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testHDF5Path, HDFDescriptor::Version4));
+  }
+
+  void test_isHDF_With_Version5_Returns_True_Only_For_HDF4()
+  {
+    TS_ASSERT(HDFDescriptor::isHDF(m_testHDF5Path, HDFDescriptor::Version5));
+    TS_ASSERT(!HDFDescriptor::isHDF(m_testHDF4Path, HDFDescriptor::Version5));
+  }
+
+  void test_isHDF_Throws_With_Invalid_Filename()
+  {
+    TS_ASSERT_THROWS(HDFDescriptor::isHDF(""), std::invalid_argument);
+  }
+
+  //=================================== HDFDescriptor methods ==================================
+
+  void test_Constructor_Initializes_Object_Correctly_Given_HDF_File()
+  {
+    HDFDescriptor descr(m_testHDF5Path);
+
+    TS_ASSERT_EQUALS(m_testHDF5Path, descr.filename());
+    TS_ASSERT_EQUALS(".nxs", descr.extension());
+  }
+
+  void test_Constructor_Throws_With_Empty_filename()
+  {
+    TS_ASSERT_THROWS(HDFDescriptor(""), std::invalid_argument);
+  }
+
+  void test_Constructor_Throws_With_NonExistant_filename()
+  {
+    TS_ASSERT_THROWS(HDFDescriptor("__ThisShouldBeANonExistantFile.txt"), std::invalid_argument);
+  }
+
+  void test_Constructor_Throws_When_Given_File_Not_Identified_As_HDF()
+  {
+    TS_ASSERT_THROWS(HDFDescriptor fd(m_testNonHDFPath), std::invalid_argument);
+  }
+
+  void test_PathExists_Returns_False_For_Path_Not_In_File()
+  {
+    HDFDescriptor fd(m_testHDF5Path);
+
+    TS_ASSERT(!fd.pathExists("/raw_data_1/bank1"));
+  }
+
+  void test_PathExists_Returns_False_For_Invalid_Path_Specification()
+  {
+    HDFDescriptor fd(m_testHDF5Path);
+
+    TS_ASSERT(!fd.pathExists("raw_data_1\\bank1"));
+  }
+
+
+  void test_PathExists_Returns_True_For_Valid_Path_In_File()
+  {
+    HDFDescriptor fd(m_testHDF5Path);
+
+    TS_ASSERT(fd.pathExists("/entry/bank1"));
+
+  }
+
+private:
+
+  std::string m_testHDF5Path;
+  std::string m_testHDF4Path;
+  std::string m_testNonHDFPath;
+};
+
+
+#endif /* MANTID_KERNEL_HDFDESCRIPTORTEST_H_ */