/* * Copyright 2007 - 2018 ETH Zuerich, CISD and SIS. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package ch.systemsx.cisd.hdf5; import hdf.hdf5lib.exceptions.HDF5JavaException; /** * An interface that provides methods for reading time duration values from HDF5 files. *

* Obtain an object implementing this interface by calling {@link IHDF5Reader#duration()}. * * @author Bernd Rinn */ public interface IHDF5TimeDurationReader { // ///////////////////// // Attributes // ///////////////////// /** * Returns true, if the attribute attributeName of data set * objectPath is a time duration and false otherwise. */ public boolean isTimeDuration(String objectPath, String attributeName) throws HDF5JavaException; /** * Returns the time unit, if the attribute given by attributeName of object * objectPath is a time duration and null otherwise. */ public HDF5TimeUnit tryGetTimeUnit(String objectPath, String attributeName) throws HDF5JavaException; /** * Reads a time duration attribute named attributeName from the data set * objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @param attributeName The name of the attribute to read. * @return The time duration. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDuration getAttr(String objectPath, String attributeName); /** * Reads a time duration array attribute named attributeName from the data set * objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @param attributeName The name of the attribute to read. * @return The time duration. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationArray getArrayAttr(String objectPath, String attributeName); /** * Reads a multi-dimension time duration array attribute named attributeName from the * data set objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @param attributeName The name of the attribute to read. * @return The time duration. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationMDArray getMDArrayAttr(String objectPath, String attributeName); // ///////////////////// // Data Sets // ///////////////////// /** * Returns true, if the data set given by objectPath is a time duration * and false otherwise. */ public boolean isTimeDuration(String objectPath) throws HDF5JavaException; /** * Returns the time unit, if the data set given by objectPath is a time duration and * null otherwise. */ public HDF5TimeUnit tryGetTimeUnit(String objectPath) throws HDF5JavaException; /** * Reads a time duration value and its unit from the data set objectPath. It needs to * be tagged as one of the type variants that indicate a time duration, for example * {@link HDF5DataTypeVariant#TIME_DURATION_SECONDS}. *

* This tagging is done by the writer when using * {@link IHDF5Writer#writeTimeDuration(String, HDF5TimeDuration)} or can be done by calling * {@link IHDF5ObjectReadWriteInfoProviderHandler#setTypeVariant(String, HDF5DataTypeVariant)}. * * @param objectPath The name (including path information) of the data set object in the file. * @return The time duration and its unit. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDuration read(String objectPath) throws HDF5JavaException; /** * Reads a time duration array from the data set objectPath. It needs to be tagged as * one of the type variants that indicate a time duration, for example * {@link HDF5DataTypeVariant#TIME_DURATION_SECONDS}. *

* This tagging is done by the writer when using * {@link IHDF5Writer#writeTimeDuration(String, HDF5TimeDuration)} or can be done by calling * {@link IHDF5ObjectReadWriteInfoProviderHandler#setTypeVariant(String, HDF5DataTypeVariant)}, * most conveniantly by code like * * 

     * writer.addTypeVariant("/dataSetPath", HDF5TimeUnit.SECONDS.getTypeVariant());
     *
* * @param objectPath The name (including path information) of the data set object in the file. * @return The time duration in seconds. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationArray readArray(String objectPath) throws HDF5JavaException; /** * Reads a block of a time duration array (of rank 1) from the data set objectPath. * It needs to be tagged as one of the type variants that indicate a time duration, for example * {@link HDF5DataTypeVariant#TIME_DURATION_SECONDS}. *

* This tagging is done by the writer when using * {@link IHDF5Writer#writeTimeDuration(String, HDF5TimeDuration)} or can be done by calling * {@link IHDF5ObjectReadWriteInfoProviderHandler#setTypeVariant(String, HDF5DataTypeVariant)}, * most conveniently by code like * * 

     * writer.addTypeVariant("/dataSetPath", HDF5TimeUnit.SECONDS.getTypeVariant());
     *
* * @param objectPath The name (including path information) of the data set object in the file. * @param blockSize The block size (this will be the length of the long[] returned * if the data set is long enough). * @param blockNumber The number of the block to read (starting with 0, offset: multiply with * blockSize). * @return The data read from the data set. The length will be * min(size - blockSize*blockNumber, * blockSize). * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationArray readArrayBlock(String objectPath, int blockSize, long blockNumber) throws HDF5JavaException; /** * Reads a block of a time duration array (of rank 1) from the data set objectPath. * It needs to be tagged as one of the type variants that indicate a time duration, for example * {@link HDF5DataTypeVariant#TIME_DURATION_SECONDS}. *

* This tagging is done by the writer when using * {@link IHDF5Writer#writeTimeDuration(String, HDF5TimeDuration)} or can be done by calling * {@link IHDF5ObjectReadWriteInfoProviderHandler#setTypeVariant(String, HDF5DataTypeVariant)}, * most conveniently by code like * * 

     * writer.addTypeVariant("/dataSetPath", HDF5TimeUnit.SECONDS.getTypeVariant());
     *
* * @param objectPath The name (including path information) of the data set object in the file. * @param blockSize The block size (this will be the length of the long[] * returned). * @param offset The offset of the block in the data set to start reading from (starting with * 0). * @return The data block read from the data set. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationArray readArrayBlockWithOffset(String objectPath, int blockSize, long offset) throws HDF5JavaException; /** * Provides all natural blocks of this one-dimensional data set of time durations to iterate * over. * * @param objectPath The name (including path information) of the data set object in the file. * @see HDF5DataBlock * @throws HDF5JavaException If the data set is not of a time duration data type or not of rank * 1. */ public Iterable> getArrayNaturalBlocks(String objectPath) throws HDF5JavaException; /** * Reads a multi-dimensional array of time durations from the data set objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @return The data read from the data set. * @throws HDF5JavaException If the objectPath is not tagged as a type variant that * corresponds to a time duration. */ public HDF5TimeDurationMDArray readMDArray(String objectPath) throws HDF5JavaException; /** * Reads a multi-dimensional array of time durations from the data set objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @param blockDimensions The extent of the block in each dimension. * @param blockNumber The block number in each dimension (offset: multiply with the * blockDimensions in the according dimension). * @return The data block read from the data set. */ public HDF5TimeDurationMDArray readMDArrayBlock(String objectPath, int[] blockDimensions, long[] blockNumber) throws HDF5JavaException; /** * Reads a multi-dimensional array of time durations from the data set objectPath. * * @param objectPath The name (including path information) of the data set object in the file. * @param blockDimensions The extent of the block in each dimension. * @param offset The offset in the data set to start reading from in each dimension. * @return The data block read from the data set. */ public HDF5TimeDurationMDArray readMDArrayBlockWithOffset(String objectPath, int[] blockDimensions, long[] offset); /** * Reads a multi-dimensional array of time durations from the data set objectPath * into a given array in memory. * * @param objectPath The name (including path information) of the data set object in the file. * @param array The array to read the data into. * @param memoryOffset The offset in the array to write the data to. * @return The effective dimensions of the block in array that was filled. */ public int[] readToMDArrayWithOffset(String objectPath, HDF5TimeDurationMDArray array, int[] memoryOffset); /** * Reads a block of the multi-dimensional long array data set objectPath * into a given array in memory. * * @param objectPath The name (including path information) of the data set object in the file. * @param array The array to read the data into. * @param blockDimensions The size of the block to read along each axis. * @param offset The offset of the block in the data set. * @param memoryOffset The offset of the block in the array to write the data to. * @return The effective dimensions of the block in array that was filled. */ public int[] readToMDArrayBlockWithOffset(String objectPath, HDF5TimeDurationMDArray array, int[] blockDimensions, long[] offset, int[] memoryOffset); /** * Provides all natural blocks of this multi-dimensional data set to iterate over. * * @see HDF5MDDataBlock */ public Iterable> getMDArrayNaturalBlocks( String dataSetPath); }