nom.tam.util.RandomAccessFileIO Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of nom-tam-fits Show documentation
Java library for reading and writing FITS files. FITS, the Flexible Image Transport System, is the format commonly used in the archiving and transport of astronomical data.
There is a newer version: 1.21.0
Show newest version
package nom.tam.util;

/*
 * #%L
 * nom.tam FITS library
 * %%
 * Copyright (C) 1996 - 2024 nom-tam-fits
 * %%
 * This is free and unencumbered software released into the public domain.
 *
 * Anyone is free to copy, modify, publish, use, compile, sell, or
 * distribute this software, either in source code form or as a compiled
 * binary, for any purpose, commercial or non-commercial, and by any
 * means.
 *
 * In jurisdictions that recognize copyright laws, the author or authors
 * of this software dedicate any and all copyright interest in the
 * software to the public domain. We make this dedication for the benefit
 * of the public at large and to the detriment of our heirs and
 * successors. We intend this dedication to be an overt act of
 * relinquishment in perpetuity of all present and future rights to this
 * software under copyright law.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 * #L%
 */

import java.io.Closeable;
import java.io.FileDescriptor;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.nio.channels.FileChannel;

/**
 * Interface for IO objects that support file-like random access. The methods defined here are those used by FitsFile to
 * access a RandomAccessFile. The RandomAccessFileExt class adds this interface to RandomAccessFile, but other systems
 * could provide an alternate implementation of this interface to access an arbitrary FITS data object.
 *
 * @author pdowler
 */
public interface RandomAccessFileIO extends ReadWriteAccess, Closeable {

    /**
     * Reads data, fully populating the supplied array.
     * 
     * @param  bytes       An array which to fill with data from the input
     * 
     * @return             The number of bytes read, which may be fewer than the destination array size.
     * 
     * @throws IOException if there was an error reading the requisite data from the input
     * 
     * @see                #read(byte[], int, int)
     * @see                #write(byte[])
     */
    default int read(byte[] bytes) throws IOException {
        return read(bytes, 0, bytes.length);
    }

    /**
     * See {@link RandomAccessFile#readUTF()} for a contract of this method.
     * 
     * @return             Reads a UTF string from the input, up to an EOL termination (with \n) or until
     *                         the end of file, whichever comes first.
     * 
     * @throws IOException if there was an error reading the requisite data from the input
     * 
     * @see                #writeUTF(String)
     * @see                RandomAccessFile#readUTF()
     */
    String readUTF() throws IOException;

    /**
     * Obtain the current FileChannel instance. For instances that do not use File backed sources
     *
     * @see    RandomAccessFile#getChannel()
     *
     * @return FileChannel instance, possibly null.
     */
    FileChannel getChannel();

    /**
     * Obtain the current FileDescriptor instance.
     *
     * @see                RandomAccessFile#getFD()
     *
     * @return             FileDescriptor instance, or possibly null.
     *
     * @throws IOException For any I/O errors.
     */
    FileDescriptor getFD() throws IOException;

    /**
     * Write all data from the the supplied array.
     * 
     * @param  bytes       the data array
     * 
     * @throws IOException if there was an error writing the data to the output
     * 
     * @see                #write(byte[], int, int)
     * @see                #read(byte[])
     */
    default void write(byte[] bytes) throws IOException {
        write(bytes, 0, bytes.length);
    }

    /**
     * See {@link RandomAccessFile#setLength(long)} for a contract of this method.
     * 
     * @param  length      The new file length.
     * 
     * @throws IOException if there was an error executing the request.
     * 
     * @see                RandomAccessFile#setLength(long)
     */
    void setLength(long length) throws IOException;

    /**
     * See {@link RandomAccessFile#writeUTF(String)} for a contract of this method.
     * 
     * @param  s           A java string.
     * 
     * @throws IOException if there was an error writing the requisite data to the output
     * 
     * @see                #readUTF()
     * @see                RandomAccessFile#writeUTF(String)
     */
    void writeUTF(String s) throws IOException;
}