com.fasterxml.jackson.core.io

Class IOContext

java.lang.Object

com.fasterxml.jackson.core.io.IOContext

All Implemented Interfaces:

AutoCloseable

public class IOContext
extends Object
implements AutoCloseable

To limit number of configuration and state objects to pass, all contextual objects that need to be passed by the factory to readers and writers are combined under this object. One instance is created for each reader and writer.

NOTE: non-final since 2.4, to allow sub-classing.

Field Summary

Fields

Modifier and Type	Field and Description
protected byte[]	_base64Buffer Reference to the buffer allocated for temporary use with base64 encoding or decoding.
protected BufferRecycler	_bufferRecycler Recycler used for actual allocation/deallocation/reuse
protected char[]	_concatCBuffer Reference to the buffer allocated for buffering it for output, before being encoded: generally this means concatenating output, then encoding when buffer fills up.
protected ContentReference	_contentReference Reference to the source object, which can be used for displaying location information
protected JsonEncoding	_encoding Encoding used by the underlying stream, if known.
protected ErrorReportConfiguration	_errorReportConfiguration
protected boolean	_managedResource Flag that indicates whether underlying input/output source/target object is fully managed by the owner of this context (parser or generator).
protected char[]	_nameCopyBuffer Reference temporary buffer Parser instances need if calling app decides it wants to access name via 'getTextCharacters' method.
protected byte[]	_readIOBuffer Reference to the allocated I/O buffer for low-level input reading, if any allocated.
protected boolean	_releaseRecycler Flag that indicates whether this context instance should release configured _bufferRecycler or not: if it does, it needs to call (via BufferRecycler.releaseToPool() when closed; if not, should do nothing (recycler life-cycle is externally managed)
protected Object	_sourceRef Deprecated. Since 2.13, use _contentReference instead
protected StreamReadConstraints	_streamReadConstraints
protected StreamWriteConstraints	_streamWriteConstraints
protected char[]	_tokenCBuffer Reference to the buffer allocated for tokenization purposes, in which character input is read, and from which it can be further returned.
protected byte[]	_writeEncodingBuffer Reference to the allocated I/O buffer used for low-level encoding-related buffering.

Constructor Summary

Constructors

Constructor and Description
IOContext(BufferRecycler br, ContentReference contentRef, boolean managedResource) Deprecated. Since 2.15. Use IOContext(StreamReadConstraints, StreamWriteConstraints, ErrorReportConfiguration, BufferRecycler, ContentReference, boolean) instead.
IOContext(BufferRecycler br, Object rawContent, boolean managedResource) Deprecated.
IOContext(StreamReadConstraints src, BufferRecycler br, ContentReference contentRef, boolean managedResource) Deprecated. Since 2.16. Use IOContext(StreamReadConstraints, StreamWriteConstraints, ErrorReportConfiguration, BufferRecycler, ContentReference, boolean) instead.
IOContext(StreamReadConstraints src, StreamWriteConstraints swc, ErrorReportConfiguration erc, BufferRecycler br, ContentReference contentRef, boolean managedResource) Main constructor to use.

Method Summary

Modifier and Type	Method and Description
protected void	_verifyAlloc(Object buffer)
protected void	_verifyRelease(byte[] toRelease, byte[] src)
protected void	_verifyRelease(char[] toRelease, char[] src)
byte[]	allocBase64Buffer() Method for recycling or allocation byte buffer of "base 64 encode/decode" type.
byte[]	allocBase64Buffer(int minSize) Variant of allocBase64Buffer() that specifies smallest acceptable buffer size.
char[]	allocConcatBuffer()
char[]	allocNameCopyBuffer(int minSize)
byte[]	allocReadIOBuffer() Method for recycling or allocation byte buffer of "read I/O" type.
byte[]	allocReadIOBuffer(int minSize) Variant of allocReadIOBuffer() that specifies smallest acceptable buffer size.
char[]	allocTokenBuffer()
char[]	allocTokenBuffer(int minSize)
byte[]	allocWriteEncodingBuffer() Method for recycling or allocation byte buffer of "write encoding" type.
byte[]	allocWriteEncodingBuffer(int minSize) Variant of allocWriteEncodingBuffer() that specifies smallest acceptable buffer size.
BufferRecycler	bufferRecycler()
void	close()
TextBuffer	constructReadConstrainedTextBuffer()
TextBuffer	constructTextBuffer()
ContentReference	contentReference() Accessor for getting (some) information about input source, mostly usable for error reporting purposes.
ErrorReportConfiguration	errorReportConfiguration()
JsonEncoding	getEncoding()
Object	getSourceReference() Deprecated. Since 2.13, use contentReference() instead
boolean	isResourceManaged()
IOContext	markBufferRecyclerReleased() Method to call to prevent _bufferRecycler release upon close(): called when _bufferRecycler life-cycle is externally managed.
void	releaseBase64Buffer(byte[] buf)
void	releaseConcatBuffer(char[] buf)
void	releaseNameCopyBuffer(char[] buf)
void	releaseReadIOBuffer(byte[] buf) Method to call when all the processing buffers can be safely recycled.
void	releaseTokenBuffer(char[] buf)
void	releaseWriteEncodingBuffer(byte[] buf)
void	setEncoding(JsonEncoding enc)
StreamReadConstraints	streamReadConstraints()
StreamWriteConstraints	streamWriteConstraints()
IOContext	withEncoding(JsonEncoding enc)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_contentReference

protected final ContentReference _contentReference

Reference to the source object, which can be used for displaying location information

_sourceRef

@Deprecated
protected final Object _sourceRef

Deprecated. Since 2.13, use _contentReference instead

Old, deprecated "raw" reference to input source.

_encoding

protected JsonEncoding _encoding

Encoding used by the underlying stream, if known.

_managedResource

protected final boolean _managedResource

Flag that indicates whether underlying input/output source/target object is fully managed by the owner of this context (parser or generator). If true, it is, and is to be closed by parser/generator; if false, calling application has to do closing (unless auto-closing feature is enabled for the parser/generator in question; in which case it acts like the owner).

_bufferRecycler

protected final BufferRecycler _bufferRecycler

Recycler used for actual allocation/deallocation/reuse

_releaseRecycler

protected boolean _releaseRecycler

Flag that indicates whether this context instance should release configured _bufferRecycler or not: if it does, it needs to call (via BufferRecycler.releaseToPool() when closed; if not, should do nothing (recycler life-cycle is externally managed)

Since:

2.17

_streamReadConstraints

protected final StreamReadConstraints _streamReadConstraints

Since:

2.15

_streamWriteConstraints

protected final StreamWriteConstraints _streamWriteConstraints

Since:

2.16

_errorReportConfiguration

protected final ErrorReportConfiguration _errorReportConfiguration

Since:

2.16

_readIOBuffer

protected byte[] _readIOBuffer

Reference to the allocated I/O buffer for low-level input reading, if any allocated.

_writeEncodingBuffer

protected byte[] _writeEncodingBuffer

Reference to the allocated I/O buffer used for low-level encoding-related buffering.

_base64Buffer

protected byte[] _base64Buffer

Reference to the buffer allocated for temporary use with base64 encoding or decoding.

_tokenCBuffer

protected char[] _tokenCBuffer

Reference to the buffer allocated for tokenization purposes, in which character input is read, and from which it can be further returned.

_concatCBuffer

protected char[] _concatCBuffer

Reference to the buffer allocated for buffering it for output, before being encoded: generally this means concatenating output, then encoding when buffer fills up.

_nameCopyBuffer

protected char[] _nameCopyBuffer

Reference temporary buffer Parser instances need if calling app decides it wants to access name via 'getTextCharacters' method. Regular text buffer can not be used as it may contain textual representation of the value token.

Constructor Detail

IOContext

public IOContext(StreamReadConstraints src,
                 StreamWriteConstraints swc,
                 ErrorReportConfiguration erc,
                 BufferRecycler br,
                 ContentReference contentRef,
                 boolean managedResource)

Main constructor to use.

Parameters:

src - constraints for streaming reads

swc - constraints for streaming writes

br - BufferRecycler to use, if any (null if none)

contentRef - Input source reference for location reporting

managedResource - Whether input source is managed (owned) by Jackson library

erc - Error report configuration to use

Since:

2.16

IOContext

@Deprecated
public IOContext(StreamReadConstraints src,
                             BufferRecycler br,
                             ContentReference contentRef,
                             boolean managedResource)

Deprecated. Since 2.16. Use IOContext(StreamReadConstraints, StreamWriteConstraints, ErrorReportConfiguration, BufferRecycler, ContentReference, boolean) instead.

Deprecated legacy constructor.

Parameters:

src - constraints for streaming reads

br - BufferRecycler to use, if any (null if none)

contentRef - Input source reference for location reporting

managedResource - Whether input source is managed (owned) by Jackson library

Since:

2.15

IOContext

@Deprecated
public IOContext(BufferRecycler br,
                             ContentReference contentRef,
                             boolean managedResource)

Deprecated. Since 2.15. Use IOContext(StreamReadConstraints, StreamWriteConstraints, ErrorReportConfiguration, BufferRecycler, ContentReference, boolean) instead.

Deprecated legacy constructor.

Parameters:

br - BufferRecycler to use, if any (null if none)

contentRef - Input source reference for location reporting

managedResource - Whether input source is managed (owned) by Jackson library

Since:

2.13

IOContext

@Deprecated
public IOContext(BufferRecycler br,
                             Object rawContent,
                             boolean managedResource)

Deprecated.

Method Detail

markBufferRecyclerReleased

public IOContext markBufferRecyclerReleased()

Method to call to prevent _bufferRecycler release upon close(): called when _bufferRecycler life-cycle is externally managed.

Returns:

This context instance, for call chaining

Since:

2.17

streamReadConstraints

public StreamReadConstraints streamReadConstraints()

Returns:

Constraints to use for streaming reads

Since:

2.15

streamWriteConstraints

public StreamWriteConstraints streamWriteConstraints()

Returns:

constraints for streaming writes

Since:

2.16

errorReportConfiguration

public ErrorReportConfiguration errorReportConfiguration()

Returns:

Configured ErrorReportConfiguration, containing configured values for handling error reporting.

Since:

2.16

setEncoding

public void setEncoding(JsonEncoding enc)

withEncoding

public IOContext withEncoding(JsonEncoding enc)

getEncoding

public JsonEncoding getEncoding()

isResourceManaged

public boolean isResourceManaged()

contentReference

public ContentReference contentReference()

Accessor for getting (some) information about input source, mostly usable for error reporting purposes.

Returns:

Reference to input source

Since:

2.13

getSourceReference

@Deprecated
public Object getSourceReference()

Deprecated. Since 2.13, use contentReference() instead

Returns:

"Raw" source reference

bufferRecycler

public BufferRecycler bufferRecycler()

constructTextBuffer

public TextBuffer constructTextBuffer()

constructReadConstrainedTextBuffer

public TextBuffer constructReadConstrainedTextBuffer()

allocReadIOBuffer

public byte[] allocReadIOBuffer()

Method for recycling or allocation byte buffer of "read I/O" type.

Note: the method can only be called once during its life cycle. This is to protect against accidental sharing.

Returns:

Allocated or recycled byte buffer

allocReadIOBuffer

public byte[] allocReadIOBuffer(int minSize)

Variant of allocReadIOBuffer() that specifies smallest acceptable buffer size.

Parameters:

minSize - Minimum size of the buffer to recycle or allocate

Returns:

Allocated or recycled byte buffer

Since:

2.4

allocWriteEncodingBuffer

public byte[] allocWriteEncodingBuffer()

Method for recycling or allocation byte buffer of "write encoding" type.

Note: the method can only be called once during its life cycle. This is to protect against accidental sharing.

Returns:

Allocated or recycled byte buffer

allocWriteEncodingBuffer

public byte[] allocWriteEncodingBuffer(int minSize)

Variant of allocWriteEncodingBuffer() that specifies smallest acceptable buffer size.

Parameters:

minSize - Minimum size of the buffer to recycle or allocate

Returns:

Allocated or recycled byte buffer

Since:

2.4

allocBase64Buffer

public byte[] allocBase64Buffer()

Method for recycling or allocation byte buffer of "base 64 encode/decode" type.

Note: the method can only be called once during its life cycle. This is to protect against accidental sharing.

Returns:

Allocated or recycled byte buffer

allocBase64Buffer

public byte[] allocBase64Buffer(int minSize)

Variant of allocBase64Buffer() that specifies smallest acceptable buffer size.

Parameters:

minSize - Minimum size of the buffer to recycle or allocate

Returns:

Allocated or recycled byte buffer

Since:

2.9

allocTokenBuffer

public char[] allocTokenBuffer()

allocTokenBuffer

public char[] allocTokenBuffer(int minSize)

allocConcatBuffer

public char[] allocConcatBuffer()

allocNameCopyBuffer

public char[] allocNameCopyBuffer(int minSize)

releaseReadIOBuffer

public void releaseReadIOBuffer(byte[] buf)

Method to call when all the processing buffers can be safely recycled.

Parameters:

buf - Buffer instance to release (return for recycling)

releaseWriteEncodingBuffer

public void releaseWriteEncodingBuffer(byte[] buf)

releaseBase64Buffer

public void releaseBase64Buffer(byte[] buf)

releaseTokenBuffer

public void releaseTokenBuffer(char[] buf)

releaseConcatBuffer

public void releaseConcatBuffer(char[] buf)

releaseNameCopyBuffer

public void releaseNameCopyBuffer(char[] buf)

_verifyAlloc

protected final void _verifyAlloc(Object buffer)

_verifyRelease

protected final void _verifyRelease(byte[] toRelease,
                                    byte[] src)

_verifyRelease

protected final void _verifyRelease(char[] toRelease,
                                    char[] src)

close

public void close()

Specified by:

close in interface AutoCloseable