1 package com.fasterxml.jackson.core.io;
2 
3 import java.io.*;
4 
5 /**
6  * Handler class that can be used to decorate input sources.
7  * Typical use is to use a filter abstraction (filtered stream,
8  * reader) around original input source, and apply additional
9  * processing during read operations.
10  */
11 public abstract class InputDecorator
12     implements java.io.Serializable // since 2.1
13 {
14     private static final long serialVersionUID = 1L;
15 
16     /**
17      * Method called by {@link com.fasterxml.jackson.core.JsonFactory} instance when
18      * creating parser given an {@link InputStream}, when this decorator
19      * has been registered.
20      *
21      * @param ctxt IO context in use (provides access to declared encoding).
22      *   NOTE: at this point context may not have all information initialized;
23      *   specifically auto-detected encoding is only available once parsing starts,
24      *   which may occur only after this method is called.
25      * @param in Original input source
26      *
27      * @return InputStream to use; either 'in' as is, or decorator
28      *   version that typically delogates to 'in'
29      */
decorate(IOContext ctxt, InputStream in)30     public abstract InputStream decorate(IOContext ctxt, InputStream in)
31         throws IOException;
32 
33     /**
34      * Method called by {@link com.fasterxml.jackson.core.JsonFactory} instance when
35      * creating parser on given "raw" byte source.
36      * Method can either construct a {@link InputStream} for reading; or return
37      * null to indicate that no wrapping should occur.
38      *
39      * @param ctxt IO context in use (provides access to declared encoding)
40      *   NOTE: at this point context may not have all information initialized;
41      *   specifically auto-detected encoding is only available once parsing starts,
42      *   which may occur only after this method is called.
43      * @param src Input buffer that contains contents to parse
44      * @param offset Offset of the first available byte in the input buffer
45      * @param length Number of bytes available in the input buffer
46      *
47      * @return Either {@link InputStream} to use as input source; or null to indicate
48      *   that contents are to be processed as-is by caller
49      */
decorate(IOContext ctxt, byte[] src, int offset, int length)50     public abstract InputStream decorate(IOContext ctxt, byte[] src, int offset, int length)
51         throws IOException;
52 
53     /**
54      * Method called by {@link com.fasterxml.jackson.core.JsonFactory} instance when
55      * creating parser given an {@link DataInput}, when this decorator
56      * has been registered.
57      *<p>
58      * Default implementation simply throws {@link UnsupportedOperationException}
59      *
60      * @param ctxt IO context in use (provides access to declared encoding).
61      *   NOTE: at this point context may not have all information initialized;
62      *   specifically auto-detected encoding is only available once parsing starts,
63      *   which may occur only after this method is called.
64      * @param input Original input source
65      *
66      * @return InputStream to use; either 'input' as is, or decorator
67      *   version that typically delogates to 'input'
68      *
69      * @since 2.8
70      */
decorate(IOContext ctxt, DataInput input)71     public DataInput decorate(IOContext ctxt, DataInput input)
72         throws IOException {
73         throw new UnsupportedOperationException();
74     }
75 
76     /**
77      * Method called by {@link com.fasterxml.jackson.core.JsonFactory} instance when
78      * creating parser given an {@link Reader}, when this decorator
79      * has been registered.
80      *
81      * @param ctxt IO context in use (provides access to declared encoding)
82      *   NOTE: at this point context may not have all information initialized;
83      *   specifically auto-detected encoding is only available once parsing starts,
84      *   which may occur only after this method is called.
85      * @param r Original reader
86      *
87      * @return Reader to use; either passed in argument, or something that
88      *   calls it (for example, a {@link FilterReader})
89      */
decorate(IOContext ctxt, Reader r)90     public abstract Reader decorate(IOContext ctxt, Reader r) throws IOException;
91 }
92