|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.codehaus.jackson.JsonParser
public abstract class JsonParser
Base class that defines public API for reading JSON content.
Instances are created using factory methods of
a JsonFactory
instance.
Nested Class Summary | |
---|---|
static class |
JsonParser.Feature
Enumeration that defines all togglable features for parsers. |
static class |
JsonParser.NumberType
Enumeration of possible "native" (optimal) types that can be used for numbers. |
Field Summary | |
---|---|
protected JsonToken |
_currToken
Last token retrieved via nextToken() , if any. |
protected int |
_features
Bit flag composed of bits that indicate which JsonParser.Feature s
are enabled. |
protected JsonToken |
_lastClearedToken
Last cleared token, if any: that is, value that was in effect when clearCurrentToken() was called. |
Constructor Summary | |
---|---|
protected |
JsonParser()
|
Method Summary | ||
---|---|---|
protected JsonParseException |
_constructError(String msg)
Helper method for constructing JsonParseException s
based on current state of the parser |
|
void |
clearCurrentToken()
Method called to "consume" the current token by effectively removing it so that hasCurrentToken() returns false, and
getCurrentToken() null). |
|
abstract void |
close()
Closes the parser so that no further iteration or data access can be made; will also close the underlying input source if parser either owns the input source, or feature JsonParser.Feature.AUTO_CLOSE_SOURCE is enabled. |
|
JsonParser |
configure(JsonParser.Feature f,
boolean state)
Method for enabling or disabling specified feature (check JsonParser.Feature for list of features) |
|
JsonParser |
disable(JsonParser.Feature f)
Method for disabling specified feature (check JsonParser.Feature for list of features) |
|
void |
disableFeature(JsonParser.Feature f)
Deprecated. Use disable(Feature) instead |
|
JsonParser |
enable(JsonParser.Feature f)
Method for enabling specified parser feature (check JsonParser.Feature for list of features) |
|
void |
enableFeature(JsonParser.Feature f)
Deprecated. Use enable(Feature) instead |
|
abstract BigInteger |
getBigIntegerValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_INT and
it can not be used as a Java long primitive type due to its
magnitude. |
|
byte[] |
getBinaryValue()
Convenience alternative to getBinaryValue(Base64Variant)
that defaults to using
Base64Variants.getDefaultVariant() as the default encoding. |
|
abstract byte[] |
getBinaryValue(Base64Variant b64variant)
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. |
|
boolean |
getBooleanValue()
Convenience accessor that can be called when the current token is JsonToken.VALUE_TRUE or
JsonToken.VALUE_FALSE . |
|
byte |
getByteValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_INT and
it can be expressed as a value of Java byte primitive type. |
|
abstract ObjectCodec |
getCodec()
Accessor for ObjectCodec associated with this
parser, if any. |
|
abstract JsonLocation |
getCurrentLocation()
Method that returns location of the last processed character; usually for error reporting purposes. |
|
abstract String |
getCurrentName()
Method that can be called to get the name associated with the current token: for JsonToken.FIELD_NAME s it will
be the same as what getText() returns;
for field values it will be preceding field name;
and for others (array values, root-level values) null. |
|
JsonToken |
getCurrentToken()
Accessor to find which token parser currently points to, if any; null will be returned if none. |
|
abstract BigDecimal |
getDecimalValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_FLOAT or
JsonToken.VALUE_NUMBER_INT . |
|
abstract double |
getDoubleValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_FLOAT and
it can be expressed as a Java double primitive type. |
|
Object |
getEmbeddedObject()
Accessor that can be called if (and only if) the current token is JsonToken.VALUE_EMBEDDED_OBJECT . |
|
abstract float |
getFloatValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_FLOAT and
it can be expressed as a Java float primitive type. |
|
abstract int |
getIntValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_INT and
it can be expressed as a value of Java int primitive type. |
|
JsonToken |
getLastClearedToken()
Method that can be called to get the last token that was cleared using clearCurrentToken() . |
|
abstract long |
getLongValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_INT and
it can be expressed as a Java long primitive type. |
|
abstract JsonParser.NumberType |
getNumberType()
If current token is of type JsonToken.VALUE_NUMBER_INT or
JsonToken.VALUE_NUMBER_FLOAT , returns
one of JsonParser.NumberType constants; otherwise returns null. |
|
abstract Number |
getNumberValue()
Generic number value accessor method that will work for all kinds of numeric values. |
|
abstract JsonStreamContext |
getParsingContext()
Method that can be used to access current parsing context reader is in. |
|
short |
getShortValue()
Numeric accessor that can be called when the current token is of type JsonToken.VALUE_NUMBER_INT and
it can be expressed as a value of Java short primitive type. |
|
abstract String |
getText()
Method for accessing textual representation of the current token; if no current token (before first call to nextToken() , or
after encountering end-of-input), returns null. |
|
abstract char[] |
getTextCharacters()
Method similar to getText() , but that will return
underlying (unmodifiable) character array that contains
textual value, instead of constructing a String object
to contain this information. |
|
abstract int |
getTextLength()
Accessor used with getTextCharacters() , to know length
of String stored in returned buffer. |
|
abstract int |
getTextOffset()
Accessor used with getTextCharacters() , to know offset
of the first text content character within buffer. |
|
abstract JsonLocation |
getTokenLocation()
Method that return the starting location of the current token; that is, position of the first character from input that starts the current token. |
|
boolean |
hasCurrentToken()
Method for checking whether parser currently points to a token (and data for that token is available). |
|
abstract boolean |
isClosed()
Method that can be called to determine whether this parser is closed or not. |
|
boolean |
isEnabled(JsonParser.Feature f)
Method for checking whether specified JsonParser.Feature
is enabled. |
|
boolean |
isFeatureEnabled(JsonParser.Feature f)
Deprecated. Use isEnabled(Feature) instead |
|
abstract JsonToken |
nextToken()
Main iteration method, which will advance stream enough to determine type of the next token, if any. |
|
JsonToken |
nextValue()
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). |
|
|
readValueAs(Class<T> valueType)
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 Boolean ). |
|
|
readValueAs(TypeReference<?> valueTypeRef)
Method to deserialize Json content into a Java type, reference to which is passed as argument. |
|
JsonNode |
readValueAsTree()
Method to deserialize Json content into equivalent "tree model", represented by root JsonNode of resulting model. |
|
abstract void |
setCodec(ObjectCodec c)
Setter that allows defining ObjectCodec associated with this
parser, if any. |
|
void |
setFeature(JsonParser.Feature f,
boolean state)
Deprecated. Use configure(org.codehaus.jackson.JsonParser.Feature, boolean) instead |
|
abstract JsonParser |
skipChildren()
Method that will skip all child tokens of an array or object token that the parser currently points to, iff stream points to JsonToken.START_OBJECT or JsonToken.START_ARRAY . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected int _features
JsonParser.Feature
s
are enabled.
protected JsonToken _currToken
nextToken()
, if any.
Null before the first call to nextToken()
,
as well as if token has been explicitly cleared
(by call to clearCurrentToken()
)
protected JsonToken _lastClearedToken
clearCurrentToken()
was called.
Constructor Detail |
---|
protected JsonParser()
Method Detail |
---|
public abstract ObjectCodec getCodec()
ObjectCodec
associated with this
parser, if any. Codec is used by readValueAs(Class)
method (and its variants).
public abstract void setCodec(ObjectCodec c)
ObjectCodec
associated with this
parser, if any. Codec is used by readValueAs(Class)
method (and its variants).
public abstract void close() throws IOException
JsonParser.Feature.AUTO_CLOSE_SOURCE
is enabled.
Whether parser owns the input source depends on factory
method that was used to construct instance (so check
JsonFactory
for details,
but the general
idea is that if caller passes in closable resource (such
as InputStream
or Reader
) parser does NOT
own the source; but if it passes a reference (such as
File
or URL
and creates
stream or reader it does own them.
close
in interface Closeable
IOException
public JsonParser enable(JsonParser.Feature f)
JsonParser.Feature
for list of features)
public JsonParser disable(JsonParser.Feature f)
JsonParser.Feature
for list of features)
public JsonParser configure(JsonParser.Feature f, boolean state)
JsonParser.Feature
for list of features)
public boolean isEnabled(JsonParser.Feature f)
JsonParser.Feature
is enabled.
public void setFeature(JsonParser.Feature f, boolean state)
configure(org.codehaus.jackson.JsonParser.Feature, boolean)
instead
public void enableFeature(JsonParser.Feature f)
enable(Feature)
instead
public void disableFeature(JsonParser.Feature f)
disable(Feature)
instead
public final boolean isFeatureEnabled(JsonParser.Feature f)
isEnabled(Feature)
instead
public abstract JsonToken nextToken() throws IOException, JsonParseException
IOException
JsonParseException
public JsonToken nextValue() throws IOException, JsonParseException
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 getCurrentName()
when parser points to
the value.
JsonToken.NOT_AVAILABLE
if no tokens were
available yet)
IOException
JsonParseException
public abstract JsonParser skipChildren() throws IOException, JsonParseException
JsonToken.START_OBJECT
or JsonToken.START_ARRAY
.
If not, it will do nothing.
After skipping, stream will point to matching
JsonToken.END_OBJECT
or 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 nextToken()
to point to the next
available token, if any.
IOException
JsonParseException
public abstract boolean isClosed()
nextToken()
(and the underlying
stream may be closed). Closing may be due to an explicit
call to close()
or because parser has encountered
end of input.
public JsonToken getCurrentToken()
public boolean hasCurrentToken()
parser.getCurrentToken() != null
.
nextToken()
; false otherwise (parser
was just constructed, encountered end-of-input
and returned null from nextToken()
, or the token
has been consumed)public void clearCurrentToken()
hasCurrentToken()
returns false, and
getCurrentToken()
null).
Cleared token value can still be accessed by calling
getLastClearedToken()
(if absolutely needed), but
usually isn't.
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 String getCurrentName() throws IOException, JsonParseException
JsonToken.FIELD_NAME
s it will
be the same as what getText()
returns;
for field values it will be preceding field name;
and for others (array values, root-level values) null.
IOException
JsonParseException
public abstract JsonStreamContext getParsingContext()
public abstract JsonLocation getTokenLocation()
public abstract JsonLocation getCurrentLocation()
public JsonToken getLastClearedToken()
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 String getText() throws IOException, JsonParseException
nextToken()
, or
after encountering end-of-input), returns null.
Method can be called for any token type.
IOException
JsonParseException
public abstract char[] getTextCharacters() throws IOException, JsonParseException
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:
getTextOffset()
) to
know the actual offset
getTextLength()
for actual length of returned content.
Note that caller MUST NOT modify the returned character array in any way -- doing so may corrupt current parser state and render parser instance useless.
The only reason to call this method (over getText()
)
is to avoid construction of a String object (which
will make a copy of contents).
IOException
JsonParseException
public abstract int getTextLength() throws IOException, JsonParseException
getTextCharacters()
, to know length
of String stored in returned buffer.
getTextCharacters()
that are part of
textual content of the current token.
IOException
JsonParseException
public abstract int getTextOffset() throws IOException, JsonParseException
getTextCharacters()
, to know offset
of the first text content character within buffer.
getTextCharacters()
that is part of
textual content of the current token.
IOException
JsonParseException
public abstract Number getNumberValue() throws IOException, JsonParseException
IOException
JsonParseException
public abstract JsonParser.NumberType getNumberType() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_INT
or
JsonToken.VALUE_NUMBER_FLOAT
, returns
one of JsonParser.NumberType
constants; otherwise returns null.
IOException
JsonParseException
public byte getByteValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_INT
and
it can be expressed as a value of Java byte primitive type.
It can also be called for JsonToken.VALUE_NUMBER_FLOAT
;
if so, it is equivalent to calling getDoubleValue()
and then casting; except for possible overflow/underflow
exception.
Note: if the resulting integer value falls outside range of
Java byte, a JsonParseException
will be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public short getShortValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_INT
and
it can be expressed as a value of Java short primitive type.
It can also be called for JsonToken.VALUE_NUMBER_FLOAT
;
if so, it is equivalent to calling getDoubleValue()
and then casting; except for possible overflow/underflow
exception.
Note: if the resulting integer value falls outside range of
Java short, a JsonParseException
will be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public abstract int getIntValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_INT
and
it can be expressed as a value of Java int primitive type.
It can also be called for JsonToken.VALUE_NUMBER_FLOAT
;
if so, it is equivalent to calling getDoubleValue()
and then casting; except for possible overflow/underflow
exception.
Note: if the resulting integer value falls outside range of
Java int, a JsonParseException
may be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public abstract long getLongValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_INT
and
it can be expressed as a Java long primitive type.
It can also be called for JsonToken.VALUE_NUMBER_FLOAT
;
if so, it is equivalent to calling getDoubleValue()
and then casting to int; except for possible overflow/underflow
exception.
Note: if the token is an integer, but its value falls
outside of range of Java long, a JsonParseException
may be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public abstract BigInteger getBigIntegerValue() throws IOException, JsonParseException
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 JsonToken.VALUE_NUMBER_FLOAT
;
if so, it is equivalent to calling getDecimalValue()
and then constructing a BigInteger
from that value.
IOException
JsonParseException
public abstract float getFloatValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_FLOAT
and
it can be expressed as a Java float primitive type.
It can also be called for JsonToken.VALUE_NUMBER_INT
;
if so, it is equivalent to calling getLongValue()
and then casting; except for possible overflow/underflow
exception.
Note: if the value falls
outside of range of Java float, a JsonParseException
will be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public abstract double getDoubleValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_FLOAT
and
it can be expressed as a Java double primitive type.
It can also be called for JsonToken.VALUE_NUMBER_INT
;
if so, it is equivalent to calling getLongValue()
and then casting; except for possible overflow/underflow
exception.
Note: if the value falls
outside of range of Java double, a JsonParseException
will be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public abstract BigDecimal getDecimalValue() throws IOException, JsonParseException
JsonToken.VALUE_NUMBER_FLOAT
or
JsonToken.VALUE_NUMBER_INT
. No under/overflow exceptions
are ever thrown.
IOException
JsonParseException
public boolean getBooleanValue() throws IOException, JsonParseException
JsonToken.VALUE_TRUE
or
JsonToken.VALUE_FALSE
.
Note: if the token is not of above-mentioned boolean types,
an integer, but its value falls
outside of range of Java long, a JsonParseException
may be thrown to indicate numeric overflow/underflow.
IOException
JsonParseException
public Object getEmbeddedObject() throws IOException, JsonParseException
JsonToken.VALUE_EMBEDDED_OBJECT
. For other token types,
null is returned.
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).
IOException
JsonParseException
public abstract byte[] getBinaryValue(Base64Variant b64variant) throws IOException, JsonParseException
getText()
and decoding result (except for decoding part),
but should be significantly more performant.
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.
b64variant
- Expected variant of base64 encoded
content (see Base64Variants
for definitions
of "standard" variants).
IOException
JsonParseException
public byte[] getBinaryValue() throws IOException, JsonParseException
getBinaryValue(Base64Variant)
that defaults to using
Base64Variants.getDefaultVariant()
as the default encoding.
IOException
JsonParseException
public <T> T readValueAs(Class<T> valueType) throws IOException, JsonProcessingException
Boolean
).
Note: method can only be called if the parser has
an object codec assigned; this is true for parsers constructed
by MappingJsonFactory
but
not for JsonFactory
(unless its setCodec
method has been explicitly called).
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 JsonToken.VALUE_EMBEDDED_OBJECT
)
stream is not advanced.
Note: this method should NOT be used if the result type is a
container (Collection
or Map
.
The reason is that due to type erasure, key and value types
can not be introspected when using this method.
IOException
JsonProcessingException
public <T> T readValueAs(TypeReference<?> valueTypeRef) throws IOException, JsonProcessingException
MappingJsonFactory
but
not for JsonFactory
(unless its setCodec
method has been explicitly called).
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 JsonToken.VALUE_EMBEDDED_OBJECT
)
stream is not advanced.
IOException
JsonProcessingException
public JsonNode readValueAsTree() throws IOException, JsonProcessingException
JsonNode
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
IOException
JsonProcessingException
protected JsonParseException _constructError(String msg)
JsonParseException
s
based on current state of the parser
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |