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.parser;
018
019import static org.apache.juneau.commons.utils.AssertionUtils.*;
020import static org.apache.juneau.commons.utils.Utils.*;
021
022import java.lang.annotation.*;
023import java.util.*;
024
025import org.apache.juneau.*;
026import org.apache.juneau.commons.collections.*;
027import org.apache.juneau.commons.function.*;
028import org.apache.juneau.commons.reflect.*;
029
030/**
031 * Subclass of {@link Parser} for byte-based parsers.
032 *
033 * <h5 class='topic'>Description</h5>
034 * <p>
035 * This class is typically the parent class of all character-based parsers.
036 * It has 1 abstract method to implement on the session object...
037 * <ul>
038 *    <li><c>parse(ParserSession, ClassMeta)</c>
039 * </ul>
040 *
041 * <h5 class='section'>Notes:</h5><ul>
042 *    <li class='note'>This class is thread safe and reusable.
043 * </ul>
044 *
045 * <h5 class='section'>See Also:</h5><ul>
046 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>
047
048 * </ul>
049 */
050public class InputStreamParser extends Parser {
051   /**
052    * Builder class.
053    */
054   public static class Builder extends Parser.Builder {
055
056      private BinaryFormat binaryFormat;
057
058      /**
059       * Constructor, default settings.
060       */
061      protected Builder() {
062         binaryFormat = env("InputStreamParser.binaryFormat", BinaryFormat.HEX);
063      }
064
065      /**
066       * Copy constructor.
067       *
068       * @param copyFrom The builder to copy from.
069       *    <br>Cannot be <jk>null</jk>.
070       */
071      protected Builder(Builder copyFrom) {
072         super(assertArgNotNull("copyFrom", copyFrom));
073         binaryFormat = copyFrom.binaryFormat;
074      }
075
076      /**
077       * Copy constructor.
078       *
079       * @param copyFrom The bean to copy from.
080       *    <br>Cannot be <jk>null</jk>.
081       */
082      protected Builder(InputStreamParser copyFrom) {
083         super(assertArgNotNull("copyFrom", copyFrom));
084         binaryFormat = copyFrom.binaryFormat;
085      }
086
087      @Override /* Overridden from Builder */
088      public Builder annotations(Annotation...values) {
089         super.annotations(values);
090         return this;
091      }
092
093      @Override /* Overridden from Builder */
094      public Builder apply(AnnotationWorkList work) {
095         super.apply(work);
096         return this;
097      }
098
099      @Override /* Overridden from Builder */
100      public Builder applyAnnotations(Class<?>...from) {
101         super.applyAnnotations(from);
102         return this;
103      }
104
105      @Override /* Overridden from Builder */
106      public Builder applyAnnotations(Object...from) {
107         super.applyAnnotations(from);
108         return this;
109      }
110
111      @Override /* Overridden from Builder */
112      public Builder autoCloseStreams() {
113         super.autoCloseStreams();
114         return this;
115      }
116
117      @Override /* Overridden from Builder */
118      public Builder autoCloseStreams(boolean value) {
119         super.autoCloseStreams(value);
120         return this;
121      }
122
123      @Override /* Overridden from Builder */
124      public Builder beanClassVisibility(Visibility value) {
125         super.beanClassVisibility(value);
126         return this;
127      }
128
129      @Override /* Overridden from Builder */
130      public Builder beanConstructorVisibility(Visibility value) {
131         super.beanConstructorVisibility(value);
132         return this;
133      }
134
135      @Override /* Overridden from Builder */
136      public Builder beanContext(BeanContext value) {
137         super.beanContext(value);
138         return this;
139      }
140
141      @Override /* Overridden from Builder */
142      public Builder beanContext(BeanContext.Builder value) {
143         super.beanContext(value);
144         return this;
145      }
146
147      @Override /* Overridden from Builder */
148      public Builder beanDictionary(java.lang.Class<?>...values) {
149         super.beanDictionary(values);
150         return this;
151      }
152
153      @Override /* Overridden from Builder */
154      public Builder beanFieldVisibility(Visibility value) {
155         super.beanFieldVisibility(value);
156         return this;
157      }
158
159      @Override /* Overridden from Builder */
160      public Builder beanInterceptor(Class<?> on, Class<? extends org.apache.juneau.swap.BeanInterceptor<?>> value) {
161         super.beanInterceptor(on, value);
162         return this;
163      }
164
165      @Override /* Overridden from Builder */
166      public Builder beanMapPutReturnsOldValue() {
167         super.beanMapPutReturnsOldValue();
168         return this;
169      }
170
171      @Override /* Overridden from Builder */
172      public Builder beanMethodVisibility(Visibility value) {
173         super.beanMethodVisibility(value);
174         return this;
175      }
176
177      @Override /* Overridden from Builder */
178      public Builder beanProperties(Class<?> beanClass, String properties) {
179         super.beanProperties(beanClass, properties);
180         return this;
181      }
182
183      @Override /* Overridden from Builder */
184      public Builder beanProperties(Map<String,Object> values) {
185         super.beanProperties(values);
186         return this;
187      }
188
189      @Override /* Overridden from Builder */
190      public Builder beanProperties(String beanClassName, String properties) {
191         super.beanProperties(beanClassName, properties);
192         return this;
193      }
194
195      @Override /* Overridden from Builder */
196      public Builder beanPropertiesExcludes(Class<?> beanClass, String properties) {
197         super.beanPropertiesExcludes(beanClass, properties);
198         return this;
199      }
200
201      @Override /* Overridden from Builder */
202      public Builder beanPropertiesExcludes(Map<String,Object> values) {
203         super.beanPropertiesExcludes(values);
204         return this;
205      }
206
207      @Override /* Overridden from Builder */
208      public Builder beanPropertiesExcludes(String beanClassName, String properties) {
209         super.beanPropertiesExcludes(beanClassName, properties);
210         return this;
211      }
212
213      @Override /* Overridden from Builder */
214      public Builder beanPropertiesReadOnly(Class<?> beanClass, String properties) {
215         super.beanPropertiesReadOnly(beanClass, properties);
216         return this;
217      }
218
219      @Override /* Overridden from Builder */
220      public Builder beanPropertiesReadOnly(Map<String,Object> values) {
221         super.beanPropertiesReadOnly(values);
222         return this;
223      }
224
225      @Override /* Overridden from Builder */
226      public Builder beanPropertiesReadOnly(String beanClassName, String properties) {
227         super.beanPropertiesReadOnly(beanClassName, properties);
228         return this;
229      }
230
231      @Override /* Overridden from Builder */
232      public Builder beanPropertiesWriteOnly(Class<?> beanClass, String properties) {
233         super.beanPropertiesWriteOnly(beanClass, properties);
234         return this;
235      }
236
237      @Override /* Overridden from Builder */
238      public Builder beanPropertiesWriteOnly(Map<String,Object> values) {
239         super.beanPropertiesWriteOnly(values);
240         return this;
241      }
242
243      @Override /* Overridden from Builder */
244      public Builder beanPropertiesWriteOnly(String beanClassName, String properties) {
245         super.beanPropertiesWriteOnly(beanClassName, properties);
246         return this;
247      }
248
249      @Override /* Overridden from Builder */
250      public Builder beansRequireDefaultConstructor() {
251         super.beansRequireDefaultConstructor();
252         return this;
253      }
254
255      @Override /* Overridden from Builder */
256      public Builder beansRequireSerializable() {
257         super.beansRequireSerializable();
258         return this;
259      }
260
261      @Override /* Overridden from Builder */
262      public Builder beansRequireSettersForGetters() {
263         super.beansRequireSettersForGetters();
264         return this;
265      }
266
267      /**
268       * <i><l>InputStreamParser</l> configuration property:&emsp;</i>  Binary input format.
269       *
270       * <p>
271       * When using the {@link InputStreamParser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
272       * when converting the string into a byte array.
273       *
274       * <h5 class='section'>Example:</h5>
275       * <p class='bjava'>
276       *    <jc>// Create a parser that parses from BASE64.</jc>
277       *    InputStreamParser <jv>parser</jv> = MsgPackParser
278       *       .<jsm>create</jsm>()
279       *       .binaryFormat(<jsf>BASE64</jsf>)
280       *       .build();
281       *
282       *    String <jv>input</jv> = <js>"base64-encoded-string"</js>;
283       *
284       *    MyBean <jv>myBean</jv> = <jv>parser</jv>.parse(<jv>input</jv> , MyBean.<jk>class</jk>);
285       * </p>
286       *
287       * @param value
288       *    The new value for this property.
289       *    <br>The default value is {@link BinaryFormat#HEX}.
290       *    <br>Cannot be <jk>null</jk>.
291       * @return This object.
292       */
293      public Builder binaryFormat(BinaryFormat value) {
294         binaryFormat = assertArgNotNull("value", value);
295         return this;
296      }
297
298      @Override /* Overridden from Context.Builder */
299      public InputStreamParser build() {
300         return build(InputStreamParser.class);
301      }
302
303      @Override /* Overridden from Builder */
304      public Builder cache(Cache<HashKey,? extends org.apache.juneau.Context> value) {
305         super.cache(value);
306         return this;
307      }
308
309      @Override /* Overridden from Builder */
310      public Builder consumes(String value) {
311         super.consumes(value);
312         return this;
313      }
314
315      @Override /* Overridden from Context.Builder */
316      public Builder copy() {
317         return new Builder(this);
318      }
319
320      @Override /* Overridden from Builder */
321      public Builder debug() {
322         super.debug();
323         return this;
324      }
325
326      @Override /* Overridden from Builder */
327      public Builder debug(boolean value) {
328         super.debug(value);
329         return this;
330      }
331
332      @Override /* Overridden from Builder */
333      public Builder debugOutputLines(int value) {
334         super.debugOutputLines(value);
335         return this;
336      }
337
338      @Override /* Overridden from Builder */
339      public Builder dictionaryOn(Class<?> on, java.lang.Class<?>...values) {
340         super.dictionaryOn(on, values);
341         return this;
342      }
343
344      @Override /* Overridden from Builder */
345      public Builder disableBeansRequireSomeProperties() {
346         super.disableBeansRequireSomeProperties();
347         return this;
348      }
349
350      @Override /* Overridden from Builder */
351      public Builder disableIgnoreMissingSetters() {
352         super.disableIgnoreMissingSetters();
353         return this;
354      }
355
356      @Override /* Overridden from Builder */
357      public Builder disableIgnoreTransientFields() {
358         super.disableIgnoreTransientFields();
359         return this;
360      }
361
362      @Override /* Overridden from Builder */
363      public Builder disableIgnoreUnknownNullBeanProperties() {
364         super.disableIgnoreUnknownNullBeanProperties();
365         return this;
366      }
367
368      @Override /* Overridden from Builder */
369      public Builder disableInterfaceProxies() {
370         super.disableInterfaceProxies();
371         return this;
372      }
373
374      @Override /* Overridden from Builder */
375      public <T> Builder example(Class<T> pojoClass, String json) {
376         super.example(pojoClass, json);
377         return this;
378      }
379
380      @Override /* Overridden from Builder */
381      public <T> Builder example(Class<T> pojoClass, T o) {
382         super.example(pojoClass, o);
383         return this;
384      }
385
386      @Override /* Overridden from Builder */
387      public Builder findFluentSetters() {
388         super.findFluentSetters();
389         return this;
390      }
391
392      @Override /* Overridden from Builder */
393      public Builder findFluentSetters(Class<?> on) {
394         super.findFluentSetters(on);
395         return this;
396      }
397
398      @Override /* Overridden from Context.Builder */
399      public HashKey hashKey() {
400         return HashKey.of(super.hashKey(), binaryFormat);
401      }
402
403      @Override /* Overridden from Builder */
404      public Builder ignoreInvocationExceptionsOnGetters() {
405         super.ignoreInvocationExceptionsOnGetters();
406         return this;
407      }
408
409      @Override /* Overridden from Builder */
410      public Builder ignoreInvocationExceptionsOnSetters() {
411         super.ignoreInvocationExceptionsOnSetters();
412         return this;
413      }
414
415      @Override /* Overridden from Builder */
416      public Builder ignoreUnknownBeanProperties() {
417         super.ignoreUnknownBeanProperties();
418         return this;
419      }
420
421      @Override /* Overridden from Builder */
422      public Builder ignoreUnknownEnumValues() {
423         super.ignoreUnknownEnumValues();
424         return this;
425      }
426
427      @Override /* Overridden from Builder */
428      public Builder impl(Context value) {
429         super.impl(value);
430         return this;
431      }
432
433      @Override /* Overridden from Builder */
434      public Builder implClass(Class<?> interfaceClass, Class<?> implClass) {
435         super.implClass(interfaceClass, implClass);
436         return this;
437      }
438
439      @Override /* Overridden from Builder */
440      public Builder implClasses(Map<Class<?>,Class<?>> values) {
441         super.implClasses(values);
442         return this;
443      }
444
445      @Override /* Overridden from Builder */
446      public Builder interfaceClass(Class<?> on, Class<?> value) {
447         super.interfaceClass(on, value);
448         return this;
449      }
450
451      @Override /* Overridden from Builder */
452      public Builder interfaces(java.lang.Class<?>...value) {
453         super.interfaces(value);
454         return this;
455      }
456
457      @Override /* Overridden from Builder */
458      public Builder listener(Class<? extends org.apache.juneau.parser.ParserListener> value) {
459         super.listener(value);
460         return this;
461      }
462
463      @Override /* Overridden from Builder */
464      public Builder locale(Locale value) {
465         super.locale(value);
466         return this;
467      }
468
469      @Override /* Overridden from Builder */
470      public Builder mediaType(MediaType value) {
471         super.mediaType(value);
472         return this;
473      }
474
475      @Override /* Overridden from Builder */
476      public Builder notBeanClasses(java.lang.Class<?>...values) {
477         super.notBeanClasses(values);
478         return this;
479      }
480
481      @Override /* Overridden from Builder */
482      public Builder notBeanPackages(String...values) {
483         super.notBeanPackages(values);
484         return this;
485      }
486
487      @Override /* Overridden from Builder */
488      public Builder propertyNamer(Class<?> on, Class<? extends org.apache.juneau.PropertyNamer> value) {
489         super.propertyNamer(on, value);
490         return this;
491      }
492
493      @Override /* Overridden from Builder */
494      public Builder propertyNamer(Class<? extends org.apache.juneau.PropertyNamer> value) {
495         super.propertyNamer(value);
496         return this;
497      }
498
499      @Override /* Overridden from Builder */
500      public Builder sortProperties() {
501         super.sortProperties();
502         return this;
503      }
504
505      @Override /* Overridden from Builder */
506      public Builder sortProperties(java.lang.Class<?>...on) {
507         super.sortProperties(on);
508         return this;
509      }
510
511      @Override /* Overridden from Builder */
512      public Builder stopClass(Class<?> on, Class<?> value) {
513         super.stopClass(on, value);
514         return this;
515      }
516
517      @Override /* Overridden from Builder */
518      public Builder strict() {
519         super.strict();
520         return this;
521      }
522
523      @Override /* Overridden from Builder */
524      public Builder strict(boolean value) {
525         super.strict(value);
526         return this;
527      }
528
529      @Override /* Overridden from Builder */
530      public <T,S> Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction) {
531         super.swap(normalClass, swappedClass, swapFunction);
532         return this;
533      }
534
535      @Override /* Overridden from Builder */
536      public <T,S> Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction, ThrowingFunction<S,T> unswapFunction) {
537         super.swap(normalClass, swappedClass, swapFunction, unswapFunction);
538         return this;
539      }
540
541      @Override /* Overridden from Builder */
542      public Builder swaps(Class<?>...values) {
543         super.swaps(values);
544         return this;
545      }
546
547      @Override /* Overridden from Builder */
548      public Builder swaps(Object...values) {
549         super.swaps(values);
550         return this;
551      }
552
553      @Override /* Overridden from Builder */
554      public Builder timeZone(TimeZone value) {
555         super.timeZone(value);
556         return this;
557      }
558
559      @Override /* Overridden from Builder */
560      public Builder trimStrings() {
561         super.trimStrings();
562         return this;
563      }
564
565      @Override /* Overridden from Builder */
566      public Builder trimStrings(boolean value) {
567         super.trimStrings(value);
568         return this;
569      }
570
571      @Override /* Overridden from Builder */
572      public Builder type(Class<? extends org.apache.juneau.Context> value) {
573         super.type(value);
574         return this;
575      }
576
577      @Override /* Overridden from Builder */
578      public Builder typeName(Class<?> on, String value) {
579         super.typeName(on, value);
580         return this;
581      }
582
583      @Override /* Overridden from Builder */
584      public Builder typePropertyName(Class<?> on, String value) {
585         super.typePropertyName(on, value);
586         return this;
587      }
588
589      @Override /* Overridden from Builder */
590      public Builder typePropertyName(String value) {
591         super.typePropertyName(value);
592         return this;
593      }
594
595      @Override /* Overridden from Builder */
596      public Builder unbuffered() {
597         super.unbuffered();
598         return this;
599      }
600
601      @Override /* Overridden from Builder */
602      public Builder unbuffered(boolean value) {
603         super.unbuffered(value);
604         return this;
605      }
606
607      @Override /* Overridden from Builder */
608      public Builder useEnumNames() {
609         super.useEnumNames();
610         return this;
611      }
612
613      @Override /* Overridden from Builder */
614      public Builder useJavaBeanIntrospector() {
615         super.useJavaBeanIntrospector();
616         return this;
617      }
618   }
619
620   /**
621    * Creates a new builder for this object.
622    *
623    * @return A new builder.
624    */
625   public static Builder create() {
626      return new Builder();
627   }
628
629   protected final BinaryFormat binaryFormat;
630
631   /**
632    * Constructor.
633    *
634    * @param builder The builder for this object.
635    */
636   protected InputStreamParser(Builder builder) {
637      super(builder);
638      binaryFormat = builder.binaryFormat;
639   }
640
641   @Override /* Overridden from Context */
642   public InputStreamParserSession.Builder createSession() {
643      return InputStreamParserSession.create(this);
644   }
645
646   @Override /* Overridden from Context */
647   public InputStreamParserSession getSession() { return createSession().build(); }
648
649   @Override /* Overridden from Parser */
650   public final boolean isReaderParser() { return false; }
651
652   /**
653    * Binary input format.
654    *
655    * @see Builder#binaryFormat(BinaryFormat)
656    * @return
657    *    The format to use when converting strings to byte arrays.
658    */
659   protected final BinaryFormat getBinaryFormat() { return binaryFormat; }
660
661   @Override /* Overridden from Parser */
662   protected FluentMap<String,Object> properties() {
663      return super.properties()
664         .a("binaryFormat", binaryFormat);
665   }
666}