/* * 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 java.util.Date; import ch.systemsx.cisd.base.mdarray.MDArray; import ch.systemsx.cisd.base.mdarray.MDLongArray; /** * An interface that provides methods for writing time and date values from HDF5 files. *

* Obtain an object implementing this interface by calling {@link IHDF5Writer#time()}. * * @author Bernd Rinn */ public interface IHDF5DateTimeWriter extends IHDF5DateTimeReader { // ///////////////////// // Attributes // ///////////////////// /** * Set a date value as attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param attributeName The name of the attribute. * @param date The value of the attribute. */ public void setAttr(String objectPath, String attributeName, Date date); /** * Set a date array value as attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param attributeName The name of the attribute. * @param dates The value of the attribute. */ public void setArrayAttr(String objectPath, String attributeName, Date[] dates); /** * Set a time stamp value as attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param attributeName The name of the attribute. * @param timeStamp The value of the attribute. */ public void setAttr(String objectPath, String attributeName, long timeStamp); /** * Set a time stamp array value as attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param attributeName The name of the attribute. * @param timeStamps The value of the attribute. */ public void setArrayAttr(String objectPath, String attributeName, long[] timeStamps); /** * Sets a multi-dimensional timestamp array attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param name The name of the attribute. * @param value The value of the attribute. */ public void setMDArrayAttr(String objectPath, String name, MDLongArray value); /** * Sets a multi-dimensional timestamp array attribute on the referenced object. *

* The referenced object must exist, that is it need to have been written before by one of the * write() methods. * * @param objectPath The name of the object to add the attribute to. * @param name The name of the attribute. * @param value The value of the attribute. */ public void setMDArrayAttr(String objectPath, String name, MDArray value); // ///////////////////// // Data Sets // ///////////////////// /** * Writes out a time stamp value. The data set will be tagged as type variant * {@link HDF5DataTypeVariant#TIMESTAMP_MILLISECONDS_SINCE_START_OF_THE_EPOCH}. *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param timeStamp The timestamp to write as number of milliseconds since January 1, 1970, * 00:00:00 GMT. */ public void write(String objectPath, long timeStamp); /** * Creates a time stamp array (of rank 1). *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param size The length of the data set to create. * @param blockSize The size of one block (for block-wise IO). Ignored if no extendable data * sets are used (see {@link IHDF5WriterConfigurator#dontUseExtendableDataTypes()}) * and deflate == false. */ public void createArray(String objectPath, long size, int blockSize); /** * Creates a time stamp array (of rank 1). *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param size The size of the byte array to create. This will be the total size for * non-extendable data sets and the size of one chunk for extendable (chunked) data * sets. For extendable data sets the initial size of the array will be 0, see * {@link ch.systemsx.cisd.hdf5.IHDF5WriterConfigurator#dontUseExtendableDataTypes}. */ public void createArray(String objectPath, int size); /** * Creates a time stamp array (of rank 1). *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param size The length of the data set to create. * @param blockSize The size of one block (for block-wise IO). Ignored if no extendable data * sets are used (see {@link IHDF5WriterConfigurator#dontUseExtendableDataTypes()}) * and deflate == false. * @param features The storage features of the data set. */ public void createArray(String objectPath, long size, int blockSize, HDF5GenericStorageFeatures features); /** * Creates a time stamp array (of rank 1). *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param size The size of the array to create. This will be the total size for non-extendable * data sets and the size of one chunk for extendable (chunked) data sets. For * extendable data sets the initial size of the array will be 0, see * {@link HDF5GenericStorageFeatures}. * @param features The storage features of the data set. */ public void createArray(String objectPath, int size, HDF5GenericStorageFeatures features); /** * Writes out a time stamp array (of rank 1). The data set will be tagged as type variant * {@link HDF5DataTypeVariant#TIMESTAMP_MILLISECONDS_SINCE_START_OF_THE_EPOCH}. *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param timeStamps The timestamps to write as number of milliseconds since January 1, 1970, * 00:00:00 GMT. */ public void writeArray(String objectPath, long[] timeStamps); /** * Writes out a time stamp array (of rank 1). The data set will be tagged as type variant * {@link HDF5DataTypeVariant#TIMESTAMP_MILLISECONDS_SINCE_START_OF_THE_EPOCH}. *

* Note: Time stamps are stored as long values. * * @param objectPath The name (including path information) of the data set object in the file. * @param timeStamps The timestamps to write as number of milliseconds since January 1, 1970, * 00:00:00 GMT. * @param features The storage features of the data set. */ public void writeArray(String objectPath, long[] timeStamps, HDF5GenericStorageFeatures features); /** * Writes out a block of a time stamp array (which is stored as a long array of * rank 1). The data set needs to have been created by * {@link #createArray(String, long, int, HDF5GenericStorageFeatures)} beforehand. *

* Note: For best performance, the block size in this method should be chosen to be equal * to the blockSize argument of the * {@link IHDF5LongWriter#createArray(String, long, int, HDF5IntStorageFeatures)} call that * was used to create the data set. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. The length defines the block size. Must not be * null or of length 0. * @param blockNumber The number of the block to write. */ public void writeArrayBlock(String objectPath, long[] data, long blockNumber); /** * Writes out a block of a time stamp array (which is stored as a long array of * rank 1). The data set needs to have been created by * {@link #createArray(String, long, int, HDF5GenericStorageFeatures)} beforehand. *

* Use this method instead of {@link #writeArrayBlock(String, long[], long)} if the * total size of the data set is not a multiple of the block size. *

* Note: For best performance, the typical dataSize in this method should be * chosen to be equal to the blockSize argument of the * {@link IHDF5LongWriter#createArray(String, long, int, HDF5IntStorageFeatures)} call that * was used to create the data set. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. The length defines the block size. Must not be * null or of length 0. * @param dataSize The (real) size of data (needs to be <= data.length * ) * @param offset The offset in the data set to start writing to. */ public void writeArrayBlockWithOffset(String objectPath, long[] data, int dataSize, long offset); /** * Writes out a time stamp value provided as a {@link Date}. *

* Note: The time stamp is stored as long array and tagged as the according * type variant. * * @param objectPath The name (including path information) of the data set object in the file. * @param date The date to write. * @see #write(String, long) */ public void write(String objectPath, Date date); /** * Writes out a {@link Date} array (of rank 1). *

* Note: Time stamps are stored as long[] arrays and tagged as the according * type variant. * * @param objectPath The name (including path information) of the data set object in the file. * @param dates The dates to write. * @see #writeArray(String, long[]) */ public void writeArray(String objectPath, Date[] dates); /** * Writes out a {@link Date} array (of rank 1). *

* Note: Time date is stored as long[] arrays and tagged as the according * type variant. * * @param objectPath The name (including path information) of the data set object in the file. * @param dates The dates to write. * @param features The storage features of the data set. * @see #writeArray(String, long[], HDF5GenericStorageFeatures) */ public void writeArray(String objectPath, Date[] dates, HDF5GenericStorageFeatures features); /** * Writes out a multi-dimensional array of time stamps. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param features The storage features of the data set. */ public void writeMDArray(String objectPath, MDLongArray data, HDF5IntStorageFeatures features); /** * Creates a multi-dimensional array of time stamps / dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param dimensions When the writer is configured to use extendable data types (see * {@link IHDF5WriterConfigurator#dontUseExtendableDataTypes()}), the initial dimensions * and the dimensions of a chunk of the array will be dimensions. When the * writer is configured to enforce a on-extendable data set, the initial dimensions * equal the dimensions and will be dimensions. */ public void createMDArray(String objectPath, int[] dimensions); /** * Creates a multi-dimensional array of time stamps / dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param dimensions The dimensions of the array. * @param blockDimensions The dimensions of one block (chunk) of the array. */ public void createMDArray(String objectPath, long[] dimensions, int[] blockDimensions); /** * Creates a multi-dimensional array of time stamps / dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param dimensions The dimensions of the long array to create. When requesting * a chunked data set (e.g. {@link HDF5IntStorageFeatures#INT_CHUNKED}), * the initial size of the array will be 0 and the chunk size will be dimensions. * When allowing a chunked data set (e.g. * {@link HDF5IntStorageFeatures#INT_NO_COMPRESSION} when the writer is * not configured to avoid extendable data types, see * {@link IHDF5WriterConfigurator#dontUseExtendableDataTypes()}), the initial size * and the chunk size of the array will be dimensions. When enforcing a * on-extendable data set (e.g. * {@link HDF5IntStorageFeatures#INT_CONTIGUOUS}), the initial size equals * the total size and will be dimensions. * @param features The storage features of the data set. */ public void createMDArray(String objectPath, int[] dimensions, HDF5IntStorageFeatures features); /** * Creates a multi-dimensional array of time stamps / dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param dimensions The dimensions of the array. * @param blockDimensions The dimensions of one block (chunk) of the array. * @param features The storage features of the data set. */ public void createMDArray(String objectPath, long[] dimensions, int[] blockDimensions, HDF5IntStorageFeatures features); /** * Writes out a block of a multi-dimensional array of time stamps. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param blockNumber The block number in each dimension (offset: multiply with the extend in * the according dimension). */ public void writeMDArrayBlock(String objectPath, MDLongArray data, long[] blockNumber); /** * Writes out a block of a multi-dimensional array of time stamps. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param offset The offset in the data set to start writing to in each dimension. */ public void writeMDArrayBlockWithOffset(String objectPath, MDLongArray data, long[] offset); /** * Writes out a block of a multi-dimensional array of time stamps. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. * @param blockDimensions The dimensions of the block to write to the data set. * @param offset The offset of the block in the data set to start writing to in each dimension. * @param memoryOffset The offset of the block in the data array. */ public void writeMDArrayBlockWithOffset(String objectPath, MDLongArray data, int[] blockDimensions, long[] offset, int[] memoryOffset); /** * Writes out a multi-dimensional array of dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param features The storage features of the data set. */ public void writeMDArray(String objectPath, MDArray data, HDF5IntStorageFeatures features); /** * Writes out a block of a multi-dimensional array of dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param blockNumber The block number in each dimension (offset: multiply with the extend in * the according dimension). */ public void writeMDArrayBlock(String objectPath, MDArray data, long[] blockNumber); /** * Writes out a block of a multi-dimensional array of daates. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. All columns need to have the * same length. * @param offset The offset in the data set to start writing to in each dimension. */ public void writeMDArrayBlockWithOffset(String objectPath, MDArray data, long[] offset); /** * Writes out a block of a multi-dimensional array of dates. * * @param objectPath The name (including path information) of the data set object in the file. * @param data The data to write. Must not be null. * @param blockDimensions The dimensions of the block to write to the data set. * @param offset The offset of the block in the data set to start writing to in each dimension. * @param memoryOffset The offset of the block in the data array. */ public void writeMDArrayBlockWithOffset(String objectPath, MDArray data, int[] blockDimensions, long[] offset, int[] memoryOffset); }