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.parser;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import org.apache.juneau.marshall.*;
022
023/**
024 * Subclass of {@link Parser} for byte-based parsers.
025 *
026 * <h5 class='topic'>Description</h5>
027 * <p>
028 * This class is typically the parent class of all byte-based parsers.
029 * It has 1 abstract method to implement on the session object...
030 * <ul>
031 *    <li>{@link ParserSession#doRead(ParserPipe, ClassMeta)}
032 * </ul>
033 *
034 * <h5 class='section'>Notes:</h5><ul>
035 *    <li class='note'>This class is thread safe and reusable.
036 * </ul>
037 *
038 * <h5 class='section'>See Also:</h5><ul>
039 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
040
041 * </ul>
042 */
043@SuppressWarnings({
044   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
045   "java:S9149" // Per-format static factories intentionally shadow the parent's.
046})
047public class InputStreamParser extends Parser {
048
049   /**
050    * Builder class.
051    */
052   @SuppressWarnings({
053      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
054   })
055   public abstract static class Builder<SELF extends Builder<SELF>> extends Parser.Builder<SELF> {
056
057      /**
058       * Constructor, default settings.
059       */
060      protected Builder() {}
061
062      /**
063       * Copy constructor.
064       *
065       * @param copyFrom The builder to copy from.
066       *    <br>Cannot be <jk>null</jk>.
067       */
068      protected Builder(Builder<?> copyFrom) {
069         super(reqnn("copyFrom", copyFrom));
070      }
071
072      /**
073       * Copy constructor.
074       *
075       * @param copyFrom The bean to copy from.
076       *    <br>Cannot be <jk>null</jk>.
077       */
078      protected Builder(InputStreamParser copyFrom) {
079         super(reqnn("copyFrom", copyFrom));
080      }
081
082      @Override /* Overridden from Context.Builder<?> */
083      public InputStreamParser build() {
084         return build(InputStreamParser.class);
085      }
086
087      @Override /* Overridden from Context.Builder<?> */
088      public abstract SELF copy();
089
090
091   }
092
093   /**
094    * Concrete default builder leaf for the non-subclassed {@link InputStreamParser#create()} / {@link InputStreamParser#copy()} path.
095    */
096   public static final class DefaultBuilder extends Builder<DefaultBuilder> {
097
098      DefaultBuilder() {}
099
100      DefaultBuilder(InputStreamParser copyFrom) {
101         super(copyFrom);
102      }
103
104      DefaultBuilder(Builder<?> copyFrom) {
105         super(copyFrom);
106      }
107
108      @Override /* Overridden from Context.Builder<?> */
109      public DefaultBuilder copy() {
110         return new DefaultBuilder(this);
111      }
112   }
113
114   /**
115    * Creates a new builder for this object.
116    *
117    * @return A new builder.
118    */
119   @SuppressWarnings({
120      "java:S1452" // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type
121   })
122   public static Builder<?> create() {
123      return new DefaultBuilder();
124   }
125
126   /**
127    * Constructor.
128    *
129    * @param builder The builder for this object.
130    *    <br>Cannot be <jk>null</jk>.
131    */
132   protected InputStreamParser(Builder<?> builder) {
133      super(builder);
134   }
135
136   @Override /* Overridden from Context */
137   public InputStreamParserSession.Builder<?> createSession() {
138      return InputStreamParserSession.create(this);
139   }
140
141   @Override /* Overridden from Context */
142   public InputStreamParserSession getSession() { return createSession().build(); }
143
144   @Override /* Overridden from Parser */
145   public final boolean isReaderParser() { return false; }
146
147   /**
148    * Binary input format.
149    *
150    * <p>
151    * Resolves from the configured {@link MarshallingContext#getBinaryFormat()}.
152    *
153    * @return The binary wire format used by this parser.
154    */
155   protected final BinaryFormat getBinaryFormat() { return getMarshallingContext().getBinaryFormat(); }
156}