001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.stream;
018
019import java.io.*;
020
021/**
022 * Capability role for parsers that can stream the elements of a top-level wire array, yielding
023 * each element as a separate record.
024 *
025 * <p>
026 * Implemented by formats with a meaningful "stream the elements of a top-level array" semantic
027 * (json, json5, cbor, msgpack &mdash; true element streaming; yaml, parquet, bson, xml, html
028 * &mdash; buffered via {@link RecordAdapter#arrayReader}).  Capability is detected via
029 * {@code instanceof}.
030 *
031 * <h5 class='section'>See Also:</h5><ul>
032 *    <li>{@link ArrayRecordWritable} &mdash; the symmetric writer role.
033 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
034 * </ul>
035 */
036@SuppressWarnings({
037   "resource" // Cursor methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
038})
039public interface ArrayRecordReadable {
040
041   /**
042    * Opens a {@link RecordReader} that yields each element of a top-level wire array as a
043    * separate record.
044    *
045    * @param input The input.
046    * @return A new element-streamed {@link RecordReader}.
047    * @throws IOException If a problem occurred reading the underlying input.
048    */
049   RecordReader readArrayRecords(Object input) throws IOException;
050
051   /**
052    * Variant of {@link #readArrayRecords(Object)} that accepts a caller-specified root element
053    * name.  Used by HTML/XML when the wire format is e.g. {@code <items><item>...} and the caller
054    * needs to declare which child element is the array element.
055    *
056    * <p>
057    * The default ignores the root name and delegates to {@link #readArrayRecords(Object)}.
058    *
059    * @param input The input.
060    * @param rootElementName The element name whose children are array elements.  May be
061    *    <jk>null</jk> for auto-detection.
062    * @return A new element-streamed {@link RecordReader}.
063    * @throws IOException If a problem occurred reading the underlying input.
064    */
065   default RecordReader readArrayRecords(Object input, String rootElementName) throws IOException {
066      return readArrayRecords(input);
067   }
068
069   /**
070    * Streaming-quality signal queryable <em>before</em> opening a cursor.
071    *
072    * @return <jk>true</jk> for true element streaming (json/cbor/msgpack); <jk>false</jk> for the
073    *    buffered {@link RecordAdapter#arrayReader}-backed formats (xml, html, yaml, parquet, bson).
074    */
075   default boolean isArrayRecordStreaming() { return true; }
076}