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 RecordReader} cursor.
023 *
024 * <p>
025 * Implemented at <b>both</b> levels of the parser surface:
026 * <ul>
027 *    <li>the convenience {@link org.apache.juneau.marshall.parser.Parser Parser} subclass (the
028 *       object REST negotiation matches on) &mdash; a thin delegator that mirrors
029 *       {@link org.apache.juneau.marshall.parser.Parser#read(Object, Class) read(...)} by
030 *       forwarding to {@code getSession().readRecords(input)};
031 *    <li>the {@link org.apache.juneau.marshall.parser.ParserSession ParserSession} subclass (where
032 *       the live {@code BeanSession}/{@code MarshallingContext} is) &mdash; the real cursor
033 *       creation.
034 * </ul>
035 *
036 * <p>
037 * <b>Capability is detected via {@code instanceof}:</b> a parser supports the record-streaming
038 * surface exactly when it is an instance of this interface.  There is no separate capability enum
039 * or marker interface.
040 *
041 * <h5 class='section'>See Also:</h5><ul>
042 *    <li>{@link TokenReadable} &mdash; the structural-token extension (FULL formats).
043 *    <li>{@link RecordWritable} &mdash; the symmetric writer role.
044 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
045 * </ul>
046 */
047public interface RecordReadable {
048
049   /**
050    * Opens a low-level {@link RecordReader} cursor over the specified input.
051    *
052    * <p>
053    * When invoked on a convenience {@link org.apache.juneau.marshall.parser.Parser Parser} the
054    * cursor is opened with <b>default session args</b> (mirroring
055    * {@link org.apache.juneau.marshall.parser.Parser#read(Object, Class) read(...)}).  Callers
056    * that need request-derived configuration (locale, timezone, schema, swaps) should instead
057    * call {@code createSession(args).build()} and invoke this method on the resulting
058    * {@link org.apache.juneau.marshall.parser.ParserSession ParserSession} (which is also a
059    * {@code RecordReadable}).
060    *
061    * @param input The input.  Subtypes define the supported types (typically
062    *    {@link Reader} / {@link CharSequence} / {@link InputStream} / {@code byte[]} / {@link File}).
063    * @return A new {@link RecordReader} cursor.
064    * @throws IOException If a problem occurred reading the underlying input.
065    */
066   RecordReader readRecords(Object input) throws IOException;
067
068   /**
069    * Streaming-quality signal queryable <em>before</em> opening a cursor.
070    *
071    * @return <jk>true</jk> if {@link #readRecords(Object)} returns an O(1)-memory streaming
072    *    cursor; <jk>false</jk> for buffered (whole-value) formats backed by
073    *    {@link RecordAdapter}.
074    */
075   default boolean isRecordStreaming() { return true; }
076}