DataSource.java
/* Copyright 2002-2024 CS GROUP
* Licensed to CS GROUP (CS) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* CS licenses this file to You 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 org.orekit.data;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.net.URI;
import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
/** Container associating a name with a stream or reader that can be opened <em>lazily</em>.
* <p>
* This association and the lazy-opening are useful in different cases:
* <ul>
* <li>when {@link DirectoryCrawler crawling} a directory tree to select data
* to be loaded by a {@link DataLoader}, the files that are not meaningful for
* the loader can be ignored and not opened at all</li>
* <li>when {@link DataFilter data filtering} is used, the raw stream can
* be opened by the filter only if the upper level filtered stream is opened</li>
* <li>when opening a stream for loading the data it provides, the opening
* and closing actions can be grouped in Orekit internal code using a {@code try
* with resources} clause so closing is done properly even in case of exception</li>
* <li>if some pre-reading of the first few bytes or characters are needed to decide how to
* load data (as in {@link org.orekit.files.ccsds.utils.lexical.LexicalAnalyzerSelector}),
* then the stream can be opened, buffered and rewound and a fake open method used
* to return the already open stream so a {@code try with resources} clause
* elsewhere works properly for closing the stream</li>
* </ul>
* <p>
* Beware that the purpose of this class is only to delay this opening (or not open
* the stream or reader at all), it is <em>not</em> intended to open the stream several
* times and <em>not</em> intended to open both the binary stream and the characters reader.
* Some implementations may fail if the {@link #getOpener() opener}'s
* {@link Opener#openStreamOnce() openStreamOnce} or {@link Opener#openReaderOnce() openReaderOnce}
* methods are called several times or are both called separately. This is particularly
* true for network-based streams.
* </p>
* @see DataFilter
* @author Luc Maisonobe
* @since 9.2
*/
public class DataSource {
/** Name of the data (file name, zip entry name...). */
private final String name;
/** Supplier for data stream. */
private final Opener opener;
/** Complete constructor.
* @param name data name
* @param streamOpener opener for the data stream
*/
public DataSource(final String name, final StreamOpener streamOpener) {
this.name = name;
this.opener = new BinaryBasedOpener(streamOpener);
}
/** Complete constructor.
* @param name data name
* @param readerOpener opener for characters reader
*/
public DataSource(final String name, final ReaderOpener readerOpener) {
this.name = name;
this.opener = new ReaderBasedOpener(readerOpener);
}
/** Build an instance from file name only.
* @param fileName name of the file
* @since 11.0
*/
public DataSource(final String fileName) {
this(fileName, () -> Files.newInputStream(Paths.get(fileName)));
}
/** Build an instance from a file on the local file system.
* @param file file
* @since 11.0
*/
public DataSource(final File file) {
this(file.getName(), () -> new FileInputStream(file));
}
/** Build an instance from URI only.
* @param uri URI of the file
* @since 11.0
*/
public DataSource(final URI uri) {
this(Paths.get(uri).toFile());
}
/** Get the name of the data.
* @return name of the data
*/
public String getName() {
return name;
}
/** Get the data stream opener.
* @return data stream opener
*/
public Opener getOpener() {
return opener;
}
/** Interface for lazy-opening a binary stream one time. */
public interface StreamOpener {
/** Open the stream once.
* <p>
* Beware that this interface is only intended for <em>lazy</em> opening a
* stream, i.e. to delay this opening (or not open the stream at all).
* It is <em>not</em> intended to open the stream several times. Some
* implementations may fail if an attempt to open a stream several
* times is made. This is particularly true for network-based streams.
* </p>
* @return opened stream
* @exception IOException if stream cannot be opened
*/
InputStream openOnce() throws IOException;
}
/** Interface for lazy-opening a characters stream one time. */
public interface ReaderOpener {
/** Open the stream once.
* <p>
* Beware that this interface is only intended for <em>lazy</em> opening a
* stream, i.e. to delay this opening (or not open the stream at all).
* It is <em>not</em> intended to open the stream several times. Some
* implementations may fail if an attempt to open a stream several
* times is made. This is particularly true for network-based streams.
* </p>
* @return opened stream
* @exception IOException if stream cannot be opened
*/
Reader openOnce() throws IOException;
}
/** Interface for lazy-opening data streams one time. */
public interface Opener {
/** Check if the raw data is binary.
* <p>
* The raw data may be either binary or characters. In both cases,
* either {@link #openStreamOnce()} or {@link #openReaderOnce()} may
* be called, but one will be more efficient than the other as one
* will supply data as is and the other one will convert raw data
* before providing it. If conversion is needed, it will also be done
* using {@link StandardCharsets#UTF_8 UTF8 encoding}, which may not
* be suitable. This method helps the data consumer to either choose
* the more efficient method or avoid wrong encoding conversion.
* </p>
* @return true if raw data is binary, false if raw data is characters
*/
boolean rawDataIsBinary();
/** Open a bytes stream once.
* <p>
* Beware that this interface is only intended for <em>lazy</em> opening a
* stream, i.e. to delay this opening (or not open the stream at all).
* It is <em>not</em> intended to open the stream several times and not
* intended to open both the {@link #openStreamOnce() binary stream} and
* the {@link #openReaderOnce() characters stream} separately (but opening
* the reader may be implemented by opening the binary stream or vice-versa).
* Implementations may fail if an attempt to open a stream several times is
* made. This is particularly true for network-based streams.
* </p>
* @return opened stream or null if there are no data streams at all
* @exception IOException if stream cannot be opened
*/
InputStream openStreamOnce() throws IOException;
/** Open a characters stream reader once.
* <p>
* Beware that this interface is only intended for <em>lazy</em> opening a
* stream, i.e. to delay this opening (or not open the stream at all).
* It is <em>not</em> intended to open the stream several times and not
* intended to open both the {@link #openStreamOnce() binary stream} and
* the {@link #openReaderOnce() characters stream} separately (but opening
* the reader may be implemented by opening the binary stream or vice-versa).
* Implementations may fail if an attempt to open a stream several times is
* made. This is particularly true for network-based streams.
* </p>
* @return opened reader or null if there are no data streams at all
* @exception IOException if stream cannot be opened
*/
Reader openReaderOnce() throws IOException;
}
/** Opener based on a binary stream. */
private static class BinaryBasedOpener implements Opener {
/** Opener for the data stream. */
private final StreamOpener streamOpener;
/** Simple constructor.
* @param streamOpener opener for the data stream
*/
BinaryBasedOpener(final StreamOpener streamOpener) {
this.streamOpener = streamOpener;
}
/** {@inheritDoc} */
@Override
public boolean rawDataIsBinary() {
return true;
}
/** {@inheritDoc} */
@Override
public InputStream openStreamOnce() throws IOException {
return streamOpener.openOnce();
}
/** {@inheritDoc} */
@Override
public Reader openReaderOnce() throws IOException {
// convert bytes to characters
final InputStream is = openStreamOnce();
return (is == null) ? null : new InputStreamReader(is, StandardCharsets.UTF_8);
}
}
/** Opener based on a reader. */
private static class ReaderBasedOpener implements Opener {
/** Size of the characters buffer. */
private static final int BUFFER_SIZE = 4096;
/** Opener for characters reader. */
private final ReaderOpener readerOpener;
/** Simple constructor.
* @param readerOpener opener for characters reader
*/
ReaderBasedOpener(final ReaderOpener readerOpener) {
this.readerOpener = readerOpener;
}
/** {@inheritDoc} */
@Override
public boolean rawDataIsBinary() {
return false;
}
/** {@inheritDoc} */
@Override
public InputStream openStreamOnce() throws IOException {
// open the underlying reader
final Reader reader = openReaderOnce();
if (reader == null) {
return null;
}
// set up a stream that convert characters to bytes
return new InputStream() {
private ByteBuffer buffer = null;
/** {@inheritDoc} */
@Override
public int read() throws IOException {
if (buffer == null || !buffer.hasRemaining()) {
// we need to refill the array
// get characters from the reader
final CharBuffer cb = CharBuffer.allocate(BUFFER_SIZE);
final int read = reader.read(cb);
if (read < 0) {
// end of data
return read;
}
// convert the characters read into bytes
final int last = cb.position();
cb.rewind();
buffer = StandardCharsets.UTF_8.encode(cb.subSequence(0, last));
}
// return next byte
return buffer.get();
}
};
}
/** {@inheritDoc} */
@Override
public Reader openReaderOnce() throws IOException {
return readerOpener.openOnce();
}
}
}