StephanEwen commented on a change in pull request #13401: URL: https://github.com/apache/flink/pull/13401#discussion_r491952145
########## File path: flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/src/reader/BulkFormat.java ########## @@ -0,0 +1,158 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF 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.apache.flink.connector.file.src.reader; + +import org.apache.flink.api.common.typeinfo.TypeInformation; +import org.apache.flink.configuration.Configuration; +import org.apache.flink.connector.file.src.util.MutableRecordAndPosition; +import org.apache.flink.connector.file.src.util.RecordAndPosition; +import org.apache.flink.core.fs.Path; + +import javax.annotation.Nullable; + +import java.io.Closeable; +import java.io.IOException; +import java.io.Serializable; + +/** + * The {@code BulkFormat} reads and decodes batches of records at a time. Examples of bulk formats + * are formats like ORC or Parquet. + * + * <p>The actual reading is done by the {@link BulkFormat.Reader}, which is created in the + * {@link BulkFormat#createReader(Configuration, Path, long, long)} or + * {@link BulkFormat#createReader(Configuration, Path, long, long, long)} methods. + * The outer class acts mainly as a configuration holder and factory for the reader. + * + * <h2>Checkpointing</h2> + * + * <p>The bulk reader returns an iterator structure per batch. The iterator produces records together + * with a position. That position is the point from where the reading can be resumed AFTER + * the records was emitted. So that position points effectively to the record AFTER the current record. + * + * <p>The simplest way to return this position information is to always assume a zero offset in the file + * and simply increment the record count. Note that in this case the fist record would be returned with + * a record count of one, the second one with a record count of two, etc. + * + * <p>Formats that have the ability to efficiently seek to a record (or to every n-th record) by offset + * in the file can work with the position field to avoid having to read and discard many records on recovery. + * + * <h2>Serializable</h2> + * + * <p>Like many other API classes in Flink, the outer class is serializable to support sending instances + * to distributed workers for parallel execution. This is purely short-term serialization for RPC and + * no instance of this will be long-term persisted in a serialized form. + * + * <h2>Record Batching</h2> + * + * <p>Internally in the file source, the readers pass batches of records from the reading + * threads (that perform the typically blocking I/O operations) to the async mailbox threads that + * do the streaming and batch data processing. Passing records in batches (rather than one-at-a-time) + * much reduce the thread-to-thread handover overhead. + * + * <p>For the {@code BulkFormat}, one batch (as returned by {@link BulkFormat.Reader#readBatch()}) is + * handed over as one. + */ +public interface BulkFormat<T> extends Serializable { + + /** + * Creates a new reader that reads from {@code filePath} starting at {@code offset} and reads + * until {@code length} bytes after the offset. + */ + default BulkFormat.Reader<T> createReader(Configuration config, Path filePath, long offset, long length) throws IOException { + return createReader(config, filePath, offset, length, 0L); + } + + /** + * Creates a new reader that reads from {@code filePath} starting at {@code offset} and reads + * until {@code length} bytes after the offset. A number of {@code recordsToSkip} records should be + * read and discarded after the offset. This is typically part of restoring a reader to a checkpointed + * position. + */ + BulkFormat.Reader<T> createReader(Configuration config, Path filePath, long offset, long length, long recordsToSkip) throws IOException; + + /** + * Gets the type produced by this format. This type will be the type produced by the file + * source as a whole. + */ + TypeInformation<T> getProducedType(); Review comment: I think you are right. It makes sense to add the interface. I guess my main reservation was that the name `ResultTypeQueryable` is not a great name. But that shouldn't stop anything here. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
