/* Jackson JSON-processor.
*
* Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi
*
* Licensed under the License specified in file LICENSE, included with
* the source code and binary code bundles.
* You may not use this file except in compliance with the License.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.fasterxml.jackson.core;
import java.io.*;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Iterator;
import com.fasterxml.jackson.core.type.TypeReference;
/**
* Base class that defines public API for reading JSON content.
* Instances are created using factory methods of
* a {@link JsonFactory} instance.
*
* @author Tatu Saloranta
*/
public abstract class JsonParser
implements Closeable, Versioned
{
private final static int MIN_BYTE_I = (int) Byte.MIN_VALUE;
// as per [JACKSON-804], allow range up to and including 255
private final static int MAX_BYTE_I = (int) 255;
private final static int MIN_SHORT_I = (int) Short.MIN_VALUE;
private final static int MAX_SHORT_I = (int) Short.MAX_VALUE;
/**
* Enumeration of possible "native" (optimal) types that can be
* used for numbers.
*/
public enum NumberType {
INT, LONG, BIG_INTEGER, FLOAT, DOUBLE, BIG_DECIMAL
};
/**
* Enumeration that defines all on/off features for parsers.
*/
public enum Feature {
// // // Low-level I/O handling features:
/**
* Feature that determines whether parser will automatically
* close underlying input source that is NOT owned by the
* parser. If disabled, calling application has to separately
* close the underlying {@link InputStream} and {@link Reader}
* instances used to create the parser. If enabled, parser
* will handle closing, as long as parser itself gets closed:
* this happens when end-of-input is encountered, or parser
* is closed by a call to {@link JsonParser#close}.
*<p>
* Feature is enabled by default.
*/
AUTO_CLOSE_SOURCE(true),
// // // Support for non-standard data format constructs
/**
* Feature that determines whether parser will allow use
* of Java/C++ style comments (both '/'+'*' and
* '//' varieties) within parsed content or not.
*<p>
* Since JSON specification does not mention comments as legal
* construct,
* this is a non-standard feature; however, in the wild
* this is extensively used. As such, feature is
* <b>disabled by default</b> for parsers and must be
* explicitly enabled.
*/
ALLOW_COMMENTS(false),
/**
* Feature that determines whether parser will allow use
* of unquoted field names (which is allowed by Javascript,
* but not by JSON specification).
*<p>
* Since JSON specification requires use of double quotes for
* field names,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_UNQUOTED_FIELD_NAMES(false),
/**
* Feature that determines whether parser will allow use
* of single quotes (apostrophe, character '\'') for
* quoting Strings (names and String values). If so,
* this is in addition to other acceptabl markers.
* but not by JSON specification).
*<p>
* Since JSON specification requires use of double quotes for
* field names,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_SINGLE_QUOTES(false),
/**
* Feature that determines whether parser will allow
* JSON Strings to contain unquoted control characters
* (ASCII characters with value less than 32, including
* tab and line feed characters) or not.
* If feature is set false, an exception is thrown if such a
* character is encountered.
*<p>
* Since JSON specification requires quoting for all control characters,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_UNQUOTED_CONTROL_CHARS(false),
/**
* Feature that can be enabled to accept quoting of all character
* using backslash qooting mechanism: if not enabled, only characters
* that are explicitly listed by JSON specification can be thus
* escaped (see JSON spec for small list of these characters)
*<p>
* Since JSON specification requires quoting for all control characters,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER(false),
/**
* Feature that determines whether parser will allow
* JSON integral numbers to start with additional (ignorable)
* zeroes (like: 000001). If enabled, no exception is thrown, and extra
* nulls are silently ignored (and not included in textual representation
* exposed via {@link JsonParser#getText}).
*<p>
* Since JSON specification does not allow leading zeroes,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_NUMERIC_LEADING_ZEROS(false),
/**
* Feature that allows parser to recognize set of
* "Not-a-Number" (NaN) tokens as legal floating number
* values (similar to how many other data formats and
* programming language source code allows it).
* Specific subset contains values that
* <a href="http://www.w3.org/TR/xmlschema-2/">XML Schema</a>
* (see section 3.2.4.1, Lexical Representation)
* allows (tokens are quoted contents, not including quotes):
*<ul>
* <li>"INF" (for positive infinity), as well as alias of "Infinity"
* <li>"-INF" (for negative infinity), alias "-Infinity"
* <li>"NaN" (for other not-a-numbers, like result of division by zero)
*</ul>
*<p>
* Since JSON specification does not allow use of such values,
* this is a non-standard feature, and as such disabled by default.
*/
ALLOW_NON_NUMERIC_NUMBERS(false),
;
/**
* Whether feature is enabled or disabled by default.
*/
private final boolean _defaultState;
/**
* Method that calculates bit set (flags) of all features that
* are enabled by default.
*/
public static int collectDefaults()
{
int flags = 0;
for (Feature f : values()) {
if (f.enabledByDefault()) {
flags |= f.getMask();
}
}
return flags;
}
private Feature(boolean defaultState) {
_defaultState = defaultState;
}
public boolean enabledByDefault() { return _defaultState; }
// public boolean enabledIn(int flags) { return (flags & getMask()) != 0; }
public int getMask() { return (1 << ordinal()); }
}
/*
/**********************************************************
/* Minimal configuration state
/**********************************************************
*/
/**
* Bit flag composed of bits that indicate which
* {@link com.fasterxml.jackson.core.JsonParser.Feature}s
* are enabled.
*/
protected int _features;
/*
/**********************************************************
/* Construction, configuration, initialization
/**********************************************************
*/
protected JsonParser() { }
protected JsonParser(int features) {
_features = features;
}
/**
* Accessor for {@link ObjectCodec} associated with this
* parser, if any. Codec is used by {@link #readValueAs(Class)}
* method (and its variants).
*/
public abstract ObjectCodec getCodec();
/**
* Setter that allows defining {@link ObjectCodec} associated with this
* parser, if any. Codec is used by {@link #readValueAs(Class)}
* method (and its variants).
*/
public abstract void setCodec(ObjectCodec c);
/**
* Method to call to make this parser use specified schema. Method must
* be called before trying to parse any content, right after parser instance
* has been created.
* Note that not all parsers support schemas; and those that do usually only
* accept specific types of schemas: ones defined for data format parser can read.
*<p>
* If parser does not support specified schema, {@link UnsupportedOperationException}
* is thrown.
*
* @param schema Schema to use
*
* @throws UnsupportedOperationException if parser does not support schema
*/
public void setSchema(FormatSchema schema)
{
throw new UnsupportedOperationException("Parser of type "+getClass().getName()+" does not support schema of type '"
+schema.getSchemaType()+"'");
}
/**
* Method for accessing Schema that this parser uses, if any.
* Default implementation returns null.
*
* @since 2.1
*/
public FormatSchema getSchema() {
return null;
}
/**
* Method that can be used to verify that given schema can be used with
* this parser (using {@link #setSchema}).
*
* @param schema Schema to check
*
* @return True if this parser can use given schema; false if not
*/
public boolean canUseSchema(FormatSchema schema) {
return false;
}
/**
* Accessor for getting version of the core package, given a parser instance.
* Left for sub-classes to implement.
*/
// @Override
public abstract Version version();
/**
* Method that can be used to get access to object that is used
* to access input being parsed; this is usually either
* {@link InputStream} or {@link Reader}, depending on what
* parser was constructed with.
* Note that returned value may be null in some cases; including
* case where parser implementation does not want to exposed raw
* source to caller.
* In cases where input has been decorated, object returned here
* is the decorated version; this allows some level of interaction
* between users of parser and decorator object.
*<p>
* In general use of this accessor should be considered as
* "last effort", i.e. only used if no other mechanism is applicable.
*/
public Object getInputSource() {
return null;
}
/*
/**********************************************************
/* Closeable implementation
/**********************************************************
*/
/**
* Closes the parser so that no further iteration or data access
* can be made; will also close the underlying input source
* if parser either <b>owns</b> the input source, or feature
* {@link Feature#AUTO_CLOSE_SOURCE} is enabled.
* Whether parser owns the input source depends on factory
* method that was used to construct instance (so check
* {@link com.fasterxml.jackson.core.JsonFactory} for details,
* but the general
* idea is that if caller passes in closable resource (such
* as {@link InputStream} or {@link Reader}) parser does NOT
* own the source; but if it passes a reference (such as
* {@link java.io.File} or {@link java.net.URL} and creates
* stream or reader it does own them.
*/
// @Override
public abstract void close() throws IOException;
/*
/**********************************************************
/* Buffer handling
/**********************************************************
*/
/**
* Method that can be called to push back any content that
* has been read but not consumed by the parser. This is usually
* done after reading all content of interest using parser.
* Content is released by writing it to given stream if possible;
* if underlying input is byte-based it can released, if not (char-based)
* it can not.
*
* @return -1 if the underlying content source is not byte based
* (that is, input can not be sent to {@link OutputStream};
* otherwise number of bytes released (0 if there was nothing to release)
*
* @throws IOException if write to stream threw exception
*/
public int releaseBuffered(OutputStream out) throws IOException
{
return -1;
}
/**
* Method that can be called to push back any content that
* has been read but not consumed by the parser.
* This is usually
* done after reading all content of interest using parser.
* Content is released by writing it to given writer if possible;
* if underlying input is char-based it can released, if not (byte-based)
* it can not.
*
* @return -1 if the underlying content source is not char-based
* (that is, input can not be sent to {@link Writer};
* otherwise number of chars released (0 if there was nothing to release)
*
* @throws IOException if write using Writer threw exception
*/
public int releaseBuffered(Writer w) throws IOException
{
return -1;
}
/*
/***************************************************
/* Public API, configuration
/***************************************************
*/
/**
* Method for enabling specified parser feature
* (check {@link Feature} for list of features)
*/
public JsonParser enable(Feature f)
{
_features |= f.getMask();
return this;
}
/**
* Method for disabling specified feature
* (check {@link Feature} for list of features)
*/
public JsonParser disable(Feature f)
{
_features &= ~f.getMask();
return this;
}
/**
* Method for enabling or disabling specified feature
* (check {@link Feature} for list of features)
*/
public JsonParser configure(Feature f, boolean state)
{
if (state) {
enable(f);
} else {
disable(f);
}
return this;
}
/**
* Method for checking whether specified {@link Feature} is enabled.
*/
public boolean isEnabled(Feature f) {
return (_features & f.getMask()) != 0;
}
/*
/**********************************************************
/* Public API, traversal
/**********************************************************
*/
/**
* Main iteration method, which will advance stream enough
* to determine type of the next token, if any. If none
* remaining (stream has no content other than possible
* white space before ending), null will be returned.
*
* @return Next token from the stream, if any found, or null
* to indicate end-of-input
*/
public abstract JsonToken nextToken()
throws IOException, JsonParseException;
/**
* Iteration method that will advance stream enough
* to determine type of the next token that is a value type
* (including JSON Array and Object start/end markers).
* Or put another way, nextToken() will be called once,
* and if {@link JsonToken#FIELD_NAME} is returned, another
* time to get the value for the field.
* Method is most useful for iterating over value entries
* of JSON objects; field name will still be available
* by calling {@link #getCurrentName} when parser points to
* the value.
*
* @return Next non-field-name token from the stream, if any found,
* or null to indicate end-of-input (or, for non-blocking
* parsers, {@link JsonToken#NOT_AVAILABLE} if no tokens were
* available yet)
*/
public abstract JsonToken nextValue()
throws IOException, JsonParseException;
/**
* Method that fetches next token (as if calling {@link #nextToken}) and
* verifies whether it is {@link JsonToken#FIELD_NAME} with specified name
* and returns result of that comparison.
* It is functionally equivalent to:
*<pre>
* return (nextToken() == JsonToken.FIELD_NAME) && str.getValue().equals(getCurrentName());
*</pre>
* but may be faster for parser to verify, and can therefore be used if caller
* expects to get such a property name from input next.
*
* @param str Property name to compare next token to (if next token is <code>JsonToken.FIELD_NAME<code>)
*/
public boolean nextFieldName(SerializableString str)
throws IOException, JsonParseException
{
return (nextToken() == JsonToken.FIELD_NAME) && str.getValue().equals(getCurrentName());
}
/**
* Method that fetches next token (as if calling {@link #nextToken}) and
* if it is {@link JsonToken#VALUE_STRING} returns contained String value;
* otherwise returns null.
* It is functionally equivalent to:
*<pre>
* return (nextToken() == JsonToken.VALUE_STRING) ? getText() : null;
*</pre>
* but may be faster for parser to process, and can therefore be used if caller
* expects to get a String value next from input.
*/
public String nextTextValue()
throws IOException, JsonParseException
{
return (nextToken() == JsonToken.VALUE_STRING) ? getText() : null;
}
/**
* Method that fetches next token (as if calling {@link #nextToken}) and
* if it is {@link JsonToken#VALUE_NUMBER_INT} returns 32-bit int value;
* otherwise returns specified default value
* It is functionally equivalent to:
*<pre>
* return (nextToken() == JsonToken.VALUE_NUMBER_INT) ? getIntValue() : defaultValue;
*</pre>
* but may be faster for parser to process, and can therefore be used if caller
* expects to get a String value next from input.
*/
public int nextIntValue(int defaultValue)
throws IOException, JsonParseException
{
return (nextToken() == JsonToken.VALUE_NUMBER_INT) ? getIntValue() : defaultValue;
}
/**
* Method that fetches next token (as if calling {@link #nextToken}) and
* if it is {@link JsonToken#VALUE_NUMBER_INT} returns 64-bit long value;
* otherwise returns specified default value
* It is functionally equivalent to:
*<pre>
* return (nextToken() == JsonToken.VALUE_NUMBER_INT) ? getLongValue() : defaultValue;
*</pre>
* but may be faster for parser to process, and can therefore be used if caller
* expects to get a String value next from input.
*/
public long nextLongValue(long defaultValue)
throws IOException, JsonParseException
{
return (nextToken() == JsonToken.VALUE_NUMBER_INT) ? getLongValue() : defaultValue;
}
/**
* Method that fetches next token (as if calling {@link #nextToken}) and
* if it is {@link JsonToken#VALUE_TRUE} or {@link JsonToken#VALUE_FALSE}
* returns matching Boolean value; otherwise return null.
* It is functionally equivalent to:
*<pre>
* JsonToken t = nextToken();
* if (t == JsonToken.VALUE_TRUE) return Boolean.TRUE;
* if (t == JsonToken.VALUE_FALSE) return Boolean.FALSE;
* return null;
*</pre>
* but may be faster for parser to process, and can therefore be used if caller
* expects to get a String value next from input.
*/
public Boolean nextBooleanValue()
throws IOException, JsonParseException
{
switch (nextToken()) {
case VALUE_TRUE:
return Boolean.TRUE;
case VALUE_FALSE:
return Boolean.FALSE;
}
return null;
}
/**
* Method that will skip all child tokens of an array or
* object token that the parser currently points to,
* iff stream points to
* {@link JsonToken#START_OBJECT} or {@link JsonToken#START_ARRAY}.
* If not, it will do nothing.
* After skipping, stream will point to <b>matching</b>
* {@link JsonToken#END_OBJECT} or {@link JsonToken#END_ARRAY}
* (possibly skipping nested pairs of START/END OBJECT/ARRAY tokens
* as well as value tokens).
* The idea is that after calling this method, application
* will call {@link #nextToken} to point to the next
* available token, if any.
*/
public abstract JsonParser skipChildren()
throws IOException, JsonParseException;
/**
* Method that can be called to determine whether this parser
* is closed or not. If it is closed, no new tokens can be
* retrieved by calling {@link #nextToken} (and the underlying
* stream may be closed). Closing may be due to an explicit
* call to {@link #close} or because parser has encountered
* end of input.
*/
public abstract boolean isClosed();
/*
/**********************************************************
/* Public API, token accessors
/**********************************************************
*/
/**
* Accessor to find which token parser currently points to, if any;
* null will be returned if none.
* If return value is non-null, data associated with the token
* is available via other accessor methods.
*
* @return Type of the token this parser currently points to,
* if any: null before any tokens have been read, and
* after end-of-input has been encountered, as well as
* if the current token has been explicitly cleared.
*/
public abstract JsonToken getCurrentToken();
/**
* Method for checking whether parser currently points to
* a token (and data for that token is available).
* Equivalent to check for <code>parser.getCurrentToken() != null</code>.
*
* @return True if the parser just returned a valid
* token via {@link #nextToken}; false otherwise (parser
* was just constructed, encountered end-of-input
* and returned null from {@link #nextToken}, or the token
* has been consumed)
*/
public abstract boolean hasCurrentToken();
/**
* Method that can be called to get the name associated with
* the current token: for {@link JsonToken#FIELD_NAME}s it will
* be the same as what {@link #getText} returns;
* for field values it will be preceding field name;
* and for others (array values, root-level values) null.
*/
public abstract String getCurrentName()
throws IOException, JsonParseException;
/**
* Method that can be used to access current parsing context reader
* is in. There are 3 different types: root, array and object contexts,
* with slightly different available information. Contexts are
* hierarchically nested, and can be used for example for figuring
* out part of the input document that correspond to specific
* array or object (for highlighting purposes, or error reporting).
* Contexts can also be used for simple xpath-like matching of
* input, if so desired.
*/
public abstract JsonStreamContext getParsingContext();
/**
* Method that return the <b>starting</b> location of the current
* token; that is, position of the first character from input
* that starts the current token.
*/
public abstract JsonLocation getTokenLocation();
/**
* Method that returns location of the last processed character;
* usually for error reporting purposes.
*/
public abstract JsonLocation getCurrentLocation();
/**
* Specialized accessor that can be used to verify that the current
* token indicates start array (usually meaning that current token
* is {@link JsonToken#START_ARRAY}) when start array is expected.
* For some specialized parsers this can return true for other cases
* as well; this is usually done to emulate arrays.
*<p>
* Default implementation is equivalent to:
*<pre>
* getCurrentToken() == JsonToken.START_ARRAY
*</pre>
* but may be overridden by custom parser implementations.
*
* @return True if the current token can be considered as a
* start-array marker (such {@link JsonToken#START_ARRAY});
* false if not.
*/
public boolean isExpectedStartArrayToken() {
return getCurrentToken() == JsonToken.START_ARRAY;
}
/*
/**********************************************************
/* Public API, token state overrides
/**********************************************************
*/
/**
* Method called to "consume" the current token by effectively
* removing it so that {@link #hasCurrentToken} returns false, and
* {@link #getCurrentToken} null).
* Cleared token value can still be accessed by calling
* {@link #getLastClearedToken} (if absolutely needed), but
* usually isn't.
*<p>
* Method was added to be used by the optional data binder, since
* it has to be able to consume last token used for binding (so that
* it will not be used again).
*/
public abstract void clearCurrentToken();
/**
* Method that can be called to get the last token that was
* cleared using {@link #clearCurrentToken}. This is not necessarily
* the latest token read.
* Will return null if no tokens have been cleared,
* or if parser has been closed.
*/
public abstract JsonToken getLastClearedToken();
/**
* Method that can be used to change what is considered to be
* the current (field) name.
* May be needed to support non-JSON data formats or unusual binding
* conventions; not needed for typical processing.
*<p>
* Note that use of this method should only be done as sort of last
* resort, as it is a work-around for regular operation.
*
* @param name Name to use as the current name; may be null.
*
* @since 2.0
*/
public abstract void overrideCurrentName(String name);
/*
/**********************************************************
/* Public API, access to token information, text
/**********************************************************
*/
/**
* Method for accessing textual representation of the current token;
* if no current token (before first call to {@link #nextToken}, or
* after encountering end-of-input), returns null.
* Method can be called for any token type.
*/
public abstract String getText()
throws IOException, JsonParseException;
/**
* Method similar to {@link #getText}, but that will return
* underlying (unmodifiable) character array that contains
* textual value, instead of constructing a String object
* to contain this information.
* Note, however, that:
*<ul>
* <li>Textual contents are not guaranteed to start at
* index 0 (rather, call {@link #getTextOffset}) to
* know the actual offset
* </li>
* <li>Length of textual contents may be less than the
* length of returned buffer: call {@link #getTextLength}
* for actual length of returned content.
* </li>
* </ul>
*<p>
* Note that caller <b>MUST NOT</b> modify the returned
* character array in any way -- doing so may corrupt
* current parser state and render parser instance useless.
*<p>
* The only reason to call this method (over {@link #getText})
* is to avoid construction of a String object (which
* will make a copy of contents).
*/
public abstract char[] getTextCharacters()
throws IOException, JsonParseException;
/**
* Accessor used with {@link #getTextCharacters}, to know length
* of String stored in returned buffer.
*
* @return Number of characters within buffer returned
* by {@link #getTextCharacters} that are part of
* textual content of the current token.
*/
public abstract int getTextLength()
throws IOException, JsonParseException;
/**
* Accessor used with {@link #getTextCharacters}, to know offset
* of the first text content character within buffer.
*
* @return Offset of the first character within buffer returned
* by {@link #getTextCharacters} that is part of
* textual content of the current token.
*/
public abstract int getTextOffset()
throws IOException, JsonParseException;
/**
* Method that can be used to determine whether calling of
* {@link #getTextCharacters} would be the most efficient
* way to access textual content for the event parser currently
* points to.
*<p>
* Default implementation simply returns false since only actual
* implementation class has knowledge of its internal buffering
* state.
* Implementations are strongly encouraged to properly override
* this method, to allow efficient copying of content by other
* code.
*
* @return True if parser currently has character array that can
* be efficiently returned via {@link #getTextCharacters}; false
* means that it may or may not exist
*/
public abstract boolean hasTextCharacters();
/*
/**********************************************************
/* Public API, access to token information, numeric
/**********************************************************
*/
/**
* Generic number value accessor method that will work for
* all kinds of numeric values. It will return the optimal
* (simplest/smallest possible) wrapper object that can
* express the numeric value just parsed.
*/
public abstract Number getNumberValue()
throws IOException, JsonParseException;
/**
* If current token is of type
* {@link JsonToken#VALUE_NUMBER_INT} or
* {@link JsonToken#VALUE_NUMBER_FLOAT}, returns
* one of {@link NumberType} constants; otherwise returns null.
*/
public abstract NumberType getNumberType()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_INT} and
* it can be expressed as a value of Java byte primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_FLOAT};
* if so, it is equivalent to calling {@link #getDoubleValue}
* and then casting; except for possible overflow/underflow
* exception.
*<p>
* Note: if the resulting integer value falls outside range of
* Java byte, a {@link JsonParseException}
* will be thrown to indicate numeric overflow/underflow.
*/
public byte getByteValue()
throws IOException, JsonParseException
{
int value = getIntValue();
// So far so good: but does it fit?
// [JACKSON-804]: Let's actually allow range of [-128, 255], as those are uniquely mapped
// (instead of just signed range of [-128, 127])
if (value < MIN_BYTE_I || value > MAX_BYTE_I) {
throw _constructError("Numeric value ("+getText()+") out of range of Java byte");
}
return (byte) value;
}
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_INT} and
* it can be expressed as a value of Java short primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_FLOAT};
* if so, it is equivalent to calling {@link #getDoubleValue}
* and then casting; except for possible overflow/underflow
* exception.
*<p>
* Note: if the resulting integer value falls outside range of
* Java short, a {@link JsonParseException}
* will be thrown to indicate numeric overflow/underflow.
*/
public short getShortValue()
throws IOException, JsonParseException
{
int value = getIntValue();
if (value < MIN_SHORT_I || value > MAX_SHORT_I) {
throw _constructError("Numeric value ("+getText()+") out of range of Java short");
}
return (short) value;
}
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_INT} and
* it can be expressed as a value of Java int primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_FLOAT};
* if so, it is equivalent to calling {@link #getDoubleValue}
* and then casting; except for possible overflow/underflow
* exception.
*<p>
* Note: if the resulting integer value falls outside range of
* Java int, a {@link JsonParseException}
* may be thrown to indicate numeric overflow/underflow.
*/
public abstract int getIntValue()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_INT} and
* it can be expressed as a Java long primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_FLOAT};
* if so, it is equivalent to calling {@link #getDoubleValue}
* and then casting to int; except for possible overflow/underflow
* exception.
*<p>
* Note: if the token is an integer, but its value falls
* outside of range of Java long, a {@link JsonParseException}
* may be thrown to indicate numeric overflow/underflow.
*/
public abstract long getLongValue()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_INT} and
* it can not be used as a Java long primitive type due to its
* magnitude.
* It can also be called for {@link JsonToken#VALUE_NUMBER_FLOAT};
* if so, it is equivalent to calling {@link #getDecimalValue}
* and then constructing a {@link BigInteger} from that value.
*/
public abstract BigInteger getBigIntegerValue()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_FLOAT} and
* it can be expressed as a Java float primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_INT};
* if so, it is equivalent to calling {@link #getLongValue}
* and then casting; except for possible overflow/underflow
* exception.
*<p>
* Note: if the value falls
* outside of range of Java float, a {@link JsonParseException}
* will be thrown to indicate numeric overflow/underflow.
*/
public abstract float getFloatValue()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_FLOAT} and
* it can be expressed as a Java double primitive type.
* It can also be called for {@link JsonToken#VALUE_NUMBER_INT};
* if so, it is equivalent to calling {@link #getLongValue}
* and then casting; except for possible overflow/underflow
* exception.
*<p>
* Note: if the value falls
* outside of range of Java double, a {@link JsonParseException}
* will be thrown to indicate numeric overflow/underflow.
*/
public abstract double getDoubleValue()
throws IOException, JsonParseException;
/**
* Numeric accessor that can be called when the current
* token is of type {@link JsonToken#VALUE_NUMBER_FLOAT} or
* {@link JsonToken#VALUE_NUMBER_INT}. No under/overflow exceptions
* are ever thrown.
*/
public abstract BigDecimal getDecimalValue()
throws IOException, JsonParseException;
/*
/**********************************************************
/* Public API, access to token information, other
/**********************************************************
*/
/**
* Convenience accessor that can be called when the current
* token is {@link JsonToken#VALUE_TRUE} or
* {@link JsonToken#VALUE_FALSE}.
*<p>
* Note: if the token is not of above-mentioned boolean types,
an integer, but its value falls
* outside of range of Java long, a {@link JsonParseException}
* may be thrown to indicate numeric overflow/underflow.
*/
public boolean getBooleanValue()
throws IOException, JsonParseException
{
JsonToken t = getCurrentToken();
if (t == JsonToken.VALUE_TRUE) return true;
if (t == JsonToken.VALUE_FALSE) return false;
throw new JsonParseException("Current token ("+t+") not of boolean type", getCurrentLocation());
}
/**
* Accessor that can be called if (and only if) the current token
* is {@link JsonToken#VALUE_EMBEDDED_OBJECT}. For other token types,
* null is returned.
*<p>
* Note: only some specialized parser implementations support
* embedding of objects (usually ones that are facades on top
* of non-streaming sources, such as object trees).
*/
public abstract Object getEmbeddedObject()
throws IOException, JsonParseException;
/*
/**********************************************************
/* Public API, access to token information, binary
/**********************************************************
*/
/**
* Method that can be used to read (and consume -- results
* may not be accessible using other methods after the call)
* base64-encoded binary data
* included in the current textual JSON value.
* It works similar to getting String value via {@link #getText}
* and decoding result (except for decoding part),
* but should be significantly more performant.
*<p>
* Note that non-decoded textual contents of the current token
* are not guaranteed to be accessible after this method
* is called. Current implementation, for example, clears up
* textual content during decoding.
* Decoded binary content, however, will be retained until
* parser is advanced to the next event.
*
* @param b64variant Expected variant of base64 encoded
* content (see {@link Base64Variants} for definitions
* of "standard" variants).
*
* @return Decoded binary data
*/
public abstract byte[] getBinaryValue(Base64Variant b64variant) throws IOException, JsonParseException;
/**
* Convenience alternative to {@link #getBinaryValue(Base64Variant)}
* that defaults to using
* {@link Base64Variants#getDefaultVariant} as the default encoding.
*/
public byte[] getBinaryValue() throws IOException, JsonParseException {
return getBinaryValue(Base64Variants.getDefaultVariant());
}
/**
* Method that can be used as an alternative to {@link #getBigIntegerValue()},
* especially when value can be large. The main difference (beyond method
* of returning content using {@link OutputStream} instead of as byte array)
* is that content will NOT remain accessible after method returns: any content
* processed will be consumed and is not buffered in any way. If caller needs
* buffering, it has to implement it.
*
* @param out Output stream to use for passing decoded binary data
*
* @return Number of bytes that were decoded and written via {@link OutputStream}
*
* @since 2.1
*/
public int readBinaryValue(OutputStream out) throws IOException, JsonParseException {
return readBinaryValue(Base64Variants.getDefaultVariant(), out);
}
/**
* Similar to {@link #readBinaryValue(OutputStream)} but allows explicitly
* specifying base64 variant to use.
*
* @param b64variant base64 variant to use
* @param out Output stream to use for passing decoded binary data
*
* @return Number of bytes that were decoded and written via {@link OutputStream}
*
* @since 2.1
*/
public int readBinaryValue(Base64Variant b64variant, OutputStream out)
throws IOException, JsonParseException
{
_reportUnsupportedOperation();
return 0; // never gets here
}
/*
/**********************************************************
/* Public API, access to token information, coercion/conversion
/**********************************************************
*/
/**
* Method that will try to convert value of current token to a
* <b>int</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
* and 1 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured type
* markers like start/end Object/Array)
* default value of <b>0</b> will be returned; no exceptions are thrown.
*/
public int getValueAsInt() throws IOException, JsonParseException {
return getValueAsInt(0);
}
/**
* Method that will try to convert value of current token to a
* <b>int</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
* and 1 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured type
* markers like start/end Object/Array)
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public int getValueAsInt(int defaultValue) throws IOException, JsonParseException {
return defaultValue;
}
/**
* Method that will try to convert value of current token to a
* <b>long</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
* and 1 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured type
* markers like start/end Object/Array)
* default value of <b>0</b> will be returned; no exceptions are thrown.
*/
public long getValueAsLong() throws IOException, JsonParseException {
return getValueAsLong(0);
}
/**
* Method that will try to convert value of current token to a
* <b>long</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
* and 1 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured type
* markers like start/end Object/Array)
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public long getValueAsLong(long defaultValue) throws IOException, JsonParseException {
return defaultValue;
}
/**
* Method that will try to convert value of current token to a Java
* <b>double</b>.
* Numbers are coerced using default Java rules; booleans convert to 0.0 (false)
* and 1.0 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured types
* like Objects and Arrays),
* default value of <b>0.0</b> will be returned; no exceptions are thrown.
*/
public double getValueAsDouble() throws IOException, JsonParseException {
return getValueAsDouble(0.0);
}
/**
* Method that will try to convert value of current token to a
* Java <b>double</b>.
* Numbers are coerced using default Java rules; booleans convert to 0.0 (false)
* and 1.0 (true), and Strings are parsed using default Java language integer
* parsing rules.
*<p>
* If representation can not be converted to an int (including structured types
* like Objects and Arrays),
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public double getValueAsDouble(double defaultValue) throws IOException, JsonParseException {
return defaultValue;
}
/**
* Method that will try to convert value of current token to a
* <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation can not be converted to a boolean value (including structured types
* like Objects and Arrays),
* default value of <b>false</b> will be returned; no exceptions are thrown.
*/
public boolean getValueAsBoolean() throws IOException, JsonParseException {
return getValueAsBoolean(false);
}
/**
* Method that will try to convert value of current token to a
* <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation can not be converted to a boolean value (including structured types
* like Objects and Arrays),
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public boolean getValueAsBoolean(boolean defaultValue) throws IOException, JsonParseException {
return defaultValue;
}
/*
/**********************************************************
/* Public API, optional data binding functionality
/**********************************************************
*/
/**
* Method to deserialize JSON content into a non-container
* type (it can be an array type, however): typically a bean, array
* or a wrapper type (like {@link java.lang.Boolean}).
* <b>Note</b>: method can only be called if the parser has
* an object codec assigned; this is true for parsers constructed
* by <code>MappingJsonFactory</code> (from "jackson-databind" jar)
* but not for {@link JsonFactory} (unless its <code>setCodec</code>
* method has been explicitly called).
*<p>
* This method may advance the event stream, for structured types
* the current token will be the closing end marker (END_ARRAY,
* END_OBJECT) of the bound structure. For non-structured Json types
* (and for {@link JsonToken#VALUE_EMBEDDED_OBJECT})
* stream is not advanced.
*<p>
* Note: this method should NOT be used if the result type is a
* container ({@link java.util.Collection} or {@link java.util.Map}.
* The reason is that due to type erasure, key and value types
* can not be introspected when using this method.
*/
public <T> T readValueAs(Class<T> valueType)
throws IOException, JsonProcessingException
{
ObjectCodec codec = getCodec();
if (codec == null) {
throw new IllegalStateException("No ObjectCodec defined for the parser, can not deserialize JSON into Java objects");
}
return codec.readValue(this, valueType);
}
/**
* Method to deserialize JSON content into a Java type, reference
* to which is passed as argument. Type is passed using so-called
* "super type token"
* and specifically needs to be used if the root type is a
* parameterized (generic) container type.
* <b>Note</b>: method can only be called if the parser has
* an object codec assigned; this is true for parsers constructed
* by <code>MappingJsonFactory</code> (defined in 'jackson-databind' bundle)
* but not for {@link JsonFactory} (unless its <code>setCodec</code>
* method has been explicitly called).
*<p>
* This method may advance the event stream, for structured types
* the current token will be the closing end marker (END_ARRAY,
* END_OBJECT) of the bound structure. For non-structured Json types
* (and for {@link JsonToken#VALUE_EMBEDDED_OBJECT})
* stream is not advanced.
*/
@SuppressWarnings("unchecked")
public <T> T readValueAs(TypeReference<?> valueTypeRef)
throws IOException, JsonProcessingException
{
ObjectCodec codec = getCodec();
if (codec == null) {
throw new IllegalStateException("No ObjectCodec defined for the parser, can not deserialize JSON into Java objects");
}
/* Ugh. Stupid Java type erasure... can't just chain call,s
* must cast here also.
*/
return (T) codec.readValue(this, valueTypeRef);
}
/**
* Method for reading sequence of Objects from parser stream,
* all with same specified value type.
*/
public <T> Iterator<T> readValuesAs(Class<T> valueType)
throws IOException, JsonProcessingException
{
ObjectCodec codec = getCodec();
if (codec == null) {
throw new IllegalStateException("No ObjectCodec defined for the parser, can not deserialize JSON into Java objects");
}
return codec.readValues(this, valueType);
}
/**
* Method for reading sequence of Objects from parser stream,
* all with same specified value type.
*/
public <T> Iterator<T> readValuesAs(TypeReference<?> valueTypeRef)
throws IOException, JsonProcessingException
{
ObjectCodec codec = getCodec();
if (codec == null) {
throw new IllegalStateException("No ObjectCodec defined for the parser, can not deserialize JSON into Java objects");
}
return codec.readValues(this, valueTypeRef);
}
/**
* Method to deserialize JSON content into equivalent "tree model",
* represented by root {@link TreeNode} of resulting model.
* For JSON Arrays it will an array node (with child nodes),
* for objects object node (with child nodes), and for other types
* matching leaf node type
*/
@SuppressWarnings("unchecked")
public <T extends TreeNode> T readValueAsTree()
throws IOException, JsonProcessingException
{
ObjectCodec codec = getCodec();
if (codec == null) {
throw new IllegalStateException("No ObjectCodec defined for the parser, can not deserialize JSON into JsonNode tree");
}
return (T) codec.readTree(this);
}
/*
/**********************************************************
/* Internal methods
/**********************************************************
*/
/**
* Helper method for constructing {@link JsonParseException}s
* based on current state of the parser
*/
protected JsonParseException _constructError(String msg)
{
return new JsonParseException(msg, getCurrentLocation());
}
/**
* Helper method to call for operations that are not supported by
* parser implementation.
*
* @since 2.1
*/
protected void _reportUnsupportedOperation() {
throw new UnsupportedOperationException("Operation not supported by parser of type "+getClass().getName());
}
}