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 serializers that can emit each element of a top-level wire array as a
023 * separate record.
024 *
025 * <p>
026 * The symmetric writer-side counterpart of {@link ArrayRecordReadable}.  Capability is detected
027 * via {@code instanceof}.
028 *
029 * <h5 class='section'>See Also:</h5><ul>
030 *    <li>{@link ArrayRecordReadable} &mdash; the symmetric reader role.
031 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
032 * </ul>
033 */
034@SuppressWarnings({
035   "resource" // Cursor methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
036})
037public interface ArrayRecordWritable {
038
039   /**
040    * Opens a {@link RecordWriter} that wraps each {@link RecordWriter#write(Object) write(...)}
041    * call as one element of a top-level wire array.
042    *
043    * @param output The output.
044    * @return A new element-streamed {@link RecordWriter}.
045    * @throws IOException If a problem occurred opening the underlying output.
046    */
047   RecordWriter writeArrayRecords(Object output) throws IOException;
048
049   /**
050    * Variant of {@link #writeArrayRecords(Object)} for length-prefixed binary formats that
051    * require the element count up front (msgpack, bson).  Other formats may ignore the count and
052    * behave the same as {@link #writeArrayRecords(Object)}.
053    *
054    * @param output The output.
055    * @param expectedCount The number of elements that will be written.  Must match the number of
056    *    {@link RecordWriter#write(Object)} calls before {@link RecordWriter#close()}.
057    * @return A new element-streamed {@link RecordWriter}.
058    * @throws IOException If a problem occurred opening the underlying output.
059    */
060   default RecordWriter writeArrayRecords(Object output, int expectedCount) throws IOException {
061      return writeArrayRecords(output);
062   }
063
064   /**
065    * Streaming-quality signal queryable <em>before</em> opening a cursor.
066    *
067    * @return <jk>true</jk> for true element streaming (json/cbor/msgpack); <jk>false</jk> for the
068    *    buffered {@link RecordAdapter#arrayWriter}-backed formats (yaml, parquet, bson).
069    */
070   default boolean isArrayRecordStreaming() { return true; }
071}