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 objects that can open a whole-value {@link RecordWriter} cursor.
023 *
024 * <p>
025 * The symmetric writer-side counterpart of {@link RecordReadable}.  Implemented at <b>both</b>
026 * levels of the serializer surface:
027 * <ul>
028 *    <li>the convenience {@link org.apache.juneau.marshall.serializer.Serializer Serializer}
029 *       subclass &mdash; a thin delegator that mirrors
030 *       {@link org.apache.juneau.marshall.serializer.Serializer#write(Object) write(...)} by
031 *       forwarding to {@code getSession().writeRecords(output)};
032 *    <li>the {@link org.apache.juneau.marshall.serializer.SerializerSession SerializerSession}
033 *       subclass (where the live {@code BeanSession}/{@code MarshallingContext} is) &mdash; the real
034 *       cursor creation.
035 * </ul>
036 *
037 * <p>
038 * <b>Capability is detected via {@code instanceof}.</b>
039 *
040 * <h5 class='section'>See Also:</h5><ul>
041 *    <li>{@link TokenWritable} &mdash; the structural-token extension (FULL formats).
042 *    <li>{@link RecordReadable} &mdash; the symmetric reader role.
043 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
044 * </ul>
045 */
046public interface RecordWritable {
047
048   /**
049    * Opens a low-level {@link RecordWriter} cursor over the specified output.
050    *
051    * <p>
052    * When invoked on a convenience {@link org.apache.juneau.marshall.serializer.Serializer
053    * Serializer} the cursor is opened with <b>default session args</b> (mirroring
054    * {@link org.apache.juneau.marshall.serializer.Serializer#write(Object) write(...)}).
055    * Callers that need request-derived configuration should instead call
056    * {@code createSession(args).build()} and invoke this method on the resulting
057    * {@link org.apache.juneau.marshall.serializer.SerializerSession SerializerSession}.
058    *
059    * @param output The output.  Subtypes define the supported types (typically
060    *    {@link Writer} / {@link OutputStream} / {@link File} / {@link StringBuilder}).
061    * @return A new {@link RecordWriter} cursor.
062    * @throws IOException If a problem occurred opening the underlying output.
063    */
064   RecordWriter writeRecords(Object output) throws IOException;
065
066   /**
067    * Streaming-quality signal queryable <em>before</em> opening a cursor.
068    *
069    * @return <jk>true</jk> if {@link #writeRecords(Object)} returns an O(1)-memory streaming
070    *    cursor; <jk>false</jk> for buffered (whole-value) formats backed by
071    *    {@link RecordAdapter}.
072    */
073   default boolean isRecordStreaming() { return true; }
074}