| /* |
| * 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.nifi.serialization; |
| |
| import org.apache.nifi.serialization.record.Record; |
| import org.apache.nifi.serialization.record.RecordSchema; |
| import org.apache.nifi.serialization.record.RecordSet; |
| |
| import java.io.Closeable; |
| import java.io.IOException; |
| |
| /** |
| * <p> |
| * A RowRecordReader is responsible for parsing data and returning a record at a time |
| * in order to allow the caller to iterate over the records individually. |
| * </p> |
| * |
| * <p> |
| * PLEASE NOTE: This interface is still considered 'unstable' and may change in a non-backward-compatible |
| * manner between minor or incremental releases of NiFi. |
| * </p> |
| */ |
| public interface RecordReader extends Closeable { |
| |
| /** |
| * Returns the next record in the stream or <code>null</code> if no more records are available. Types will be coerced and any unknown fields will be dropped. |
| * |
| * @return the next record in the stream or <code>null</code> if no more records are available. |
| * |
| * @throws IOException if unable to read from the underlying data |
| * @throws MalformedRecordException if an unrecoverable failure occurs when trying to parse a record |
| * @throws SchemaValidationException if a Record contains a field that violates the schema and cannot be coerced into the appropriate field type. |
| */ |
| default Record nextRecord() throws IOException, MalformedRecordException { |
| return nextRecord(true, false); |
| } |
| |
| /** |
| * Reads the next record from the underlying stream. If type coercion is enabled, then any field in the Record whose type does not |
| * match the schema will be coerced to the correct type and a MalformedRecordException will be thrown if unable to coerce the data into |
| * the correct type. If type coercion is disabled, then no type coercion will occur. As a result, calling |
| * {@link Record#getValue(org.apache.nifi.serialization.record.RecordField)} |
| * may return any type of Object, such as a String or another Record, even though the schema indicates that the field must be an integer. |
| * |
| * @param coerceTypes whether or not fields in the Record should be validated against the schema and coerced when necessary |
| * @param dropUnknownFields if <code>true</code>, any field that is found in the data that is not present in the schema will be dropped. If <code>false</code>, |
| * those fields will still be part of the Record (though their type cannot be coerced, since the schema does not provide a type for it). |
| * |
| * @return the next record in the stream or <code>null</code> if no more records are available |
| * @throws IOException if unable to read from the underlying data |
| * @throws MalformedRecordException if an unrecoverable failure occurs when trying to parse a record, or a Record contains a field |
| * that violates the schema and cannot be coerced into the appropriate field type. |
| * @throws SchemaValidationException if a Record contains a field that violates the schema and cannot be coerced into the appropriate |
| * field type and schema enforcement is enabled |
| */ |
| Record nextRecord(boolean coerceTypes, boolean dropUnknownFields) throws IOException, MalformedRecordException; |
| |
| /** |
| * @return a RecordSchema that is appropriate for the records in the stream |
| * @throws MalformedRecordException if an unrecoverable failure occurs when trying to parse the underlying data |
| */ |
| RecordSchema getSchema() throws MalformedRecordException; |
| |
| /** |
| * @return a RecordSet that returns the records in this Record Reader in a streaming fashion |
| */ |
| default RecordSet createRecordSet() { |
| return new RecordSet() { |
| @Override |
| public RecordSchema getSchema() throws IOException { |
| try { |
| return RecordReader.this.getSchema(); |
| } catch (final MalformedRecordException mre) { |
| throw new IOException(mre); |
| } |
| } |
| |
| @Override |
| public Record next() throws IOException { |
| try { |
| return RecordReader.this.nextRecord(); |
| } catch (final MalformedRecordException mre) { |
| throw new IOException(mre); |
| } |
| } |
| }; |
| } |
| } |