Module tools.jackson.core
Package tools.jackson.core.filter

Class FilteringParserDelegate

java.lang.Object
tools.jackson.core.JsonParser
tools.jackson.core.util.JsonParserDelegate
tools.jackson.core.filter.FilteringParserDelegate
All Implemented Interfaces:
Closeable, AutoCloseable, Versioned
public class FilteringParserDelegate extends JsonParserDelegate
Specialized JsonParserDelegate that allows use of TokenFilter for outputting a subset of content that is visible to caller

  • Field Details

    • rootFilter

      protected TokenFilter rootFilter
      Object consulted to determine whether to write parts of content generator is asked to write or not.

    • _allowMultipleMatches

      protected boolean _allowMultipleMatches
      Flag that determines whether filtering will continue after the first match is indicated or not: if `false`, output is based on just the first full match (returning TokenFilter.INCLUDE_ALL) and no more checks are made; if `true` then filtering will be applied as necessary until end of content.

    • _inclusion

      protected TokenFilter.Inclusion _inclusion
      Flag that determines whether path leading up to included content should also be automatically included or not. If `false`, no path inclusion is done and only explicitly included entries are output; if `true` then path from main level down to match is also included as necessary.

    • _currToken

      protected JsonToken _currToken
      Last token retrieved via nextToken(), if any. Null before the first call to nextToken(), as well as if token has been explicitly cleared

    • _lastClearedToken

      protected JsonToken _lastClearedToken
      Last cleared token, if any: that is, value that was in effect when clearCurrentToken() was called.

    • _headContext

      protected TokenFilterContext _headContext
      During traversal this is the actual "open" parse tree, which sometimes is the same as _exposedContext, and at other times is ahead of it. Note that this context is never null.

    • _exposedContext

      protected TokenFilterContext _exposedContext
      In cases where _headContext is "ahead" of context exposed to caller, this context points to what is currently exposed to caller. When the two are in sync, this context reference will be null.

    • _itemFilter

      protected TokenFilter _itemFilter
      State that applies to the item within container, used where applicable. Specifically used to pass inclusion state between property name and property, and also used for array elements.

    • _matchCount

      protected int _matchCount
      Number of tokens for which TokenFilter.INCLUDE_ALL has been returned.

  • Constructor Details

    • FilteringParserDelegate

      public FilteringParserDelegate(JsonParser p, TokenFilter f, TokenFilter.Inclusion inclusion, boolean allowMultipleMatches)
      Parameters:
      p - Parser to delegate calls to
      f - Filter to use
      inclusion - Definition of inclusion criteria
      allowMultipleMatches - Whether to allow multiple matches
      Throws:
      IllegalArgumentException - if non-blocking (async) parser (for which parser.canParseAsync() returns `true`) is used -- doing so requires use of different constructor: FilteringParserDelegate(JsonParser, TokenFilter, TokenFilter.Inclusion, boolean, boolean)

    • FilteringParserDelegate

      public FilteringParserDelegate(JsonParser p, TokenFilter f, TokenFilter.Inclusion inclusion, boolean allowMultipleMatches, boolean allowNonBlockingParser)
      Parameters:
      p - Parser to delegate calls to
      f - Filter to use
      inclusion - Definition of inclusion criteria
      allowMultipleMatches - Whether to allow multiple matches
      allowNonBlockingParser - If true, allows use of NonBlockingJsonParser: must also feed all input to parser before calling nextToken on this delegate
      Throws:
      IllegalArgumentException - if NonBlockingJsonParser is used without explicit permission

  • Method Details

    • getFilter

      public TokenFilter getFilter()

    • getMatchCount

      public int getMatchCount()
      Accessor for finding number of matches, where specific token and sub-tree starting (if structured type) are passed.
      Returns:
      Number of matches

    • currentToken

      public JsonToken currentToken()
      Description copied from class: JsonParser
      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.
      Overrides:
      currentToken in class JsonParserDelegate
      Returns:
      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.

    • currentTokenId

      public final int currentTokenId()
      Description copied from class: JsonParser
      Method similar to JsonParser.currentToken() but that returns an int instead of JsonToken (enum value).

      Use of int directly is typically more efficient on switch statements, so this method may be useful when building low-overhead codecs. Note, however, that effect may not be big enough to matter: make sure to profile performance before deciding to use this method.

      Overrides:
      currentTokenId in class JsonParserDelegate
      Returns:
      int matching one of constants from JsonTokenId.

    • hasCurrentToken

      public boolean hasCurrentToken()
      Description copied from class: JsonParser
      Method for checking whether parser currently points to a token (and data for that token is available). Equivalent to check for parser.getCurrentToken() != null.
      Overrides:
      hasCurrentToken in class JsonParserDelegate
      Returns:
      True if the parser just returned a valid token via JsonParser.nextToken(); false otherwise (parser was just constructed, encountered end-of-input and returned null from JsonParser.nextToken(), or the token has been consumed)

    • hasTokenId

      public boolean hasTokenId(int id)
      Description copied from class: JsonParser
      Method that is functionally equivalent to: return currentTokenId() == id but may be more efficiently implemented.

      Note that no traversal or conversion is performed; so in some cases calling method like JsonParser.isExpectedStartArrayToken() is necessary instead.

      Overrides:
      hasTokenId in class JsonParserDelegate
      Parameters:
      id - Token id to match (from (@link JsonTokenId})
      Returns:
      True if the parser current points to specified token

    • hasToken

      public final boolean hasToken(JsonToken t)
      Description copied from class: JsonParser
      Method that is functionally equivalent to: return currentToken() == t but may be more efficiently implemented.

      Note that no traversal or conversion is performed; so in some cases calling method like JsonParser.isExpectedStartArrayToken() is necessary instead.

      Overrides:
      hasToken in class JsonParserDelegate
      Parameters:
      t - Token to match
      Returns:
      True if the parser current points to specified token

    • isExpectedStartArrayToken

      public boolean isExpectedStartArrayToken()
      Description copied from class: JsonParser
      Specialized accessor that can be used to verify that the current token indicates start array (usually meaning that current token is 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 in cases underlying format is ambiguous (XML, for example, has no format-level difference between Objects and Arrays; it just has elements).

      Default implementation is equivalent to: 

         currentToken() == JsonToken.START_ARRAY
      but may be overridden by custom parser implementations.
      Overrides:
      isExpectedStartArrayToken in class JsonParserDelegate
      Returns:
      True if the current token can be considered as a start-array marker (such JsonToken.START_ARRAY); false if not

    • isExpectedStartObjectToken

      public boolean isExpectedStartObjectToken()
      Description copied from class: JsonParser
      Similar to JsonParser.isExpectedStartArrayToken(), but checks whether stream currently points to JsonToken.START_OBJECT.
      Overrides:
      isExpectedStartObjectToken in class JsonParserDelegate
      Returns:
      True if the current token can be considered as a start-array marker (such JsonToken.START_OBJECT); false if not

    • currentLocation

      public TokenStreamLocation currentLocation()
      Description copied from class: JsonParser
      Method that returns location of the last processed character; usually for error reporting purposes.

      Note that the location is not guaranteed to be accurate (although most implementation will try their best): some implementations may only report specific boundary locations (start or end locations of tokens) and others only return TokenStreamLocation.NA due to not having access to input location information (when delegating actual decoding work to other library).

      Overrides:
      currentLocation in class JsonParserDelegate
      Returns:
      Location of the last processed input unit (byte or character)

    • streamReadContext

      public TokenStreamContext streamReadContext()
      Description copied from class: JsonParser
      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.

      NOTE: method was called getParsingContext() in Jackson 2.x

      Overrides:
      streamReadContext in class JsonParserDelegate
      Returns:
      Stream output context (TokenStreamContext) associated with this parser

    • currentName

      public String currentName()
      Description copied from class: JsonParser
      Method that can be called to get the name associated with the current token: for JsonToken.PROPERTY_NAMEs it will be the same as what JsonParser.getString() returns; for Object property values it will be the preceding property name; and for others (array element, root-level values) null.
      Overrides:
      currentName in class JsonParserDelegate
      Returns:
      Name of the current property name, if any, in the parsing context (null if none)

    • clearCurrentToken

      public void clearCurrentToken()
      Description copied from class: JsonParser
      Method called to "consume" the current token by effectively removing it so that JsonParser.hasCurrentToken() returns false, and JsonParser.currentToken() null). Cleared token value can still be accessed by calling JsonParser.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).

      Overrides:
      clearCurrentToken in class JsonParserDelegate

    • getLastClearedToken

      public JsonToken getLastClearedToken()
      Description copied from class: JsonParser
      Method that can be called to get the last token that was cleared using JsonParser.clearCurrentToken(). This is not necessarily the latest token read. Will return null if no tokens have been cleared, or if parser has been closed.
      Overrides:
      getLastClearedToken in class JsonParserDelegate
      Returns:
      Last cleared token, if any; null otherwise

    • nextToken

      public JsonToken nextToken() throws JacksonException
      Description copied from class: JsonParser
      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.
      Overrides:
      nextToken in class JsonParserDelegate
      Returns:
      Next token from the stream, if any found, or null to indicate end-of-input
      Throws:
      JacksonException - for low-level read issues
      StreamReadException - for decoding problems

    • _nextToken2

      protected final JsonToken _nextToken2() throws JacksonException
      Throws:
      JacksonException

    • _nextTokenWithBuffering

      protected final JsonToken _nextTokenWithBuffering(TokenFilterContext buffRoot) throws JacksonException
      Throws:
      JacksonException

    • nextValue

      public JsonToken nextValue() throws JacksonException
      Description copied from class: JsonParser
      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 JsonToken.PROPERTY_NAME is returned, another time to get the value of the property. Method is most useful for iterating over value entries of JSON objects; Object property name will still be available by calling JsonParser.currentName() when parser points to the value.
      Overrides:
      nextValue in class JsonParserDelegate
      Returns:
      Next non-field-name token from the stream, if any found, or null to indicate end-of-input (or, for non-blocking parsers, JsonToken.NOT_AVAILABLE if no tokens were available yet)
      Throws:
      JacksonException - for low-level read issues
      StreamReadException - for decoding problems

    • skipChildren

      public JsonParser skipChildren() throws JacksonException
      Need to override, re-implement similar to how method defined in ParserMinimalBase, to keep state correct here.
      Overrides:
      skipChildren in class JsonParserDelegate
      Returns:
      This parser, to allow call chaining
      Throws:
      JacksonException - for low-level read issues
      StreamReadException - for decoding problems

    • getString

      public String getString() throws JacksonException
      Description copied from class: JsonParser
      Method for accessing textual representation of the current token; if no current token (before first call to JsonParser.nextToken(), or after encountering end-of-input), returns null. Method can be called for any token type.
      Overrides:
      getString in class JsonParserDelegate
      Returns:
      String value associated with the current token (one returned by JsonParser.nextToken() or other iteration methods)
      Throws:
      JacksonIOException - for low-level read issues
      StreamReadException - for decoding problems
      JacksonException

    • hasStringCharacters

      public boolean hasStringCharacters()
      Description copied from class: JsonParser
      Method that can be used to determine whether calling of JsonParser.getStringCharacters() would be the most efficient way to access String value for the event parser currently points to (compared to JsonParser.getString()).
      Overrides:
      hasStringCharacters in class JsonParserDelegate
      Returns:
      True if parser currently has character array that can be efficiently returned via JsonParser.getStringCharacters(); false means that it may or may not exist

    • getStringCharacters

      public char[] getStringCharacters() throws JacksonException
      Description copied from class: JsonParser
      Method similar to JsonParser.getString(), 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:

      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 JsonParser.getString()) is to avoid construction of a String object (which will make a copy of contents).

      Overrides:
      getStringCharacters in class JsonParserDelegate
      Returns:
      Buffer that contains the current textual value (but not necessarily at offset 0, and not necessarily until the end of buffer)
      Throws:
      JacksonIOException - for low-level read issues
      StreamReadException - for decoding problems
      JacksonException

    • getStringLength

      public int getStringLength() throws JacksonException
      Description copied from class: JsonParser
      Accessor used with JsonParser.getStringCharacters(), to know length of String stored in returned buffer.
      Overrides:
      getStringLength in class JsonParserDelegate
      Returns:
      Number of characters within buffer returned by JsonParser.getStringCharacters() that are part of textual content of the current token.
      Throws:
      JacksonIOException - for low-level read issues
      StreamReadException - for decoding problems
      JacksonException

    • getStringOffset

      public int getStringOffset() throws JacksonException
      Description copied from class: JsonParser
      Accessor used with JsonParser.getStringCharacters(), to know offset of the first text content character within buffer.
      Overrides:
      getStringOffset in class JsonParserDelegate
      Returns:
      Offset of the first character within buffer returned by JsonParser.getStringCharacters() that is part of textual content of the current token.
      Throws:
      JacksonIOException - for low-level read issues
      StreamReadException - for decoding problems
      JacksonException

    • getValueAsString

      public String getValueAsString() throws JacksonException
      Description copied from class: JsonParser
      Method that will try to convert value of current token to a String. JSON Strings map naturally; scalar values get converted to their textual representation. If representation cannot be converted to a String value (including structured types like Objects and Arrays and null token), default value of null will be returned; no exceptions are thrown.
      Overrides:
      getValueAsString in class JsonParserDelegate
      Returns:
      String value current token is converted to, if possible; null otherwise
      Throws:
      JacksonException

    • getValueAsString

      public String getValueAsString(String defaultValue) throws JacksonException
      Description copied from class: JsonParser
      Method that will try to convert value of current token to a String. JSON Strings map naturally; scalar values get converted to their textual representation. If representation cannot be converted to a String value (including structured types like Objects and Arrays and null token), specified default value will be returned; no exceptions are thrown.
      Overrides:
      getValueAsString in class JsonParserDelegate
      Parameters:
      defaultValue - Default value to return if conversion to String is not possible
      Returns:
      String value current token is converted to, if possible; def otherwise
      Throws:
      JacksonException

    • nextName

      public String nextName() throws JacksonException
      Description copied from class: JsonParser
      Method that fetches next token (as if calling JsonParser.nextToken()) and verifies whether it is JsonToken.PROPERTY_NAME; if it is, returns same as JsonParser.currentName(), otherwise null.

      NOTE: in Jackson 2.x method was called nextFieldName()

      Overrides:
      nextName in class JsonParserDelegate
      Returns:
      Name of the the JsonToken.PROPERTY_NAME parser advanced to, if any; null if next token is of some other type
      Throws:
      JacksonException - for low-level read issues
      StreamReadException - for decoding problems

    • nextName

      public boolean nextName(SerializableString str) throws JacksonException
      Description copied from class: JsonParser
      Method that fetches next token (as if calling JsonParser.nextToken()) and verifies whether it is JsonToken.PROPERTY_NAME with specified name and returns result of that comparison. It is functionally equivalent to: 
        return (nextToken() == JsonToken.PROPERTY_NAME) && str.getValue().equals(currentName());
      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.

      NOTE: in Jackson 2.x method was called nextFieldName()

      Overrides:
      nextName in class JsonParserDelegate
      Parameters:
      str - Property name to compare next token to (if next token is JsonToken.PROPERTY_NAME)
      Returns:
      True if parser advanced to JsonToken.PROPERTY_NAME with specified name; false otherwise (different token or non-matching name)
      Throws:
      JacksonException - for low-level read issues
      StreamReadException - for decoding problems

    • nextNameMatch

      public int nextNameMatch(PropertyNameMatcher matcher) throws JacksonException
      Description copied from class: JsonParser
      Method that tries to match next token from stream as JsonToken.PROPERTY_NAME, and if so, further match it to one of pre-specified (field) names. If match succeeds, property index (non-negative `int`) is returned; otherwise one of marker constants from PropertyNameMatcher.
      Overrides:
      nextNameMatch in class JsonParserDelegate
      Parameters:
      matcher - Matcher that will handle actual matching
      Returns:
      Index of the matched property name, if non-negative, or a negative error code otherwise (see PropertyNameMatcher for details)
      Throws:
      JacksonIOException - for low-level read issues
      StreamReadException - for decoding problems
      JacksonException

    • _filterContext

      protected TokenStreamContext _filterContext()