Class JsonParser

  • Direct Known Subclasses:
    MockJsonParser

    public abstract class JsonParser
    extends Object
    Abstract low-level JSON parser. See https://code.google.com/p/google-http-java-client/wiki/JSON

    Implementation has no fields and therefore thread-safe, but sub-classes are not necessarily thread-safe.

    If a JSON map is encountered while using a destination class of type Map, then an ArrayMap is used by default for the parsed values.

    Since:
    1.3
    Author:
    Yaniv Inbar
    • Constructor Summary

      Constructors 
      Constructor Description
      JsonParser()  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void close()
      Closes the parser and the underlying input stream or reader, and releases any memory associated with it.
      abstract BigInteger getBigIntegerValue()
      Returns the BigInteger value of the current token.
      abstract byte getByteValue()
      Returns the byte value of the current token.
      abstract String getCurrentName()
      Returns the most recent field name or null for array values or for root-level values.
      abstract JsonToken getCurrentToken()
      Returns the token the parser currently points to or null for none (at start of input or after end of input).
      abstract BigDecimal getDecimalValue()
      Returns the BigDecimal value of the current token.
      abstract double getDoubleValue()
      Returns the double value of the current token.
      abstract JsonFactory getFactory()
      Returns the JSON factory from which this generator was created.
      abstract float getFloatValue()
      Returns the float value of the current token.
      abstract int getIntValue()
      Returns the int value of the current token.
      abstract long getLongValue()
      Returns the long value of the current token.
      abstract short getShortValue()
      Returns the short value of the current token.
      abstract String getText()
      Returns a textual representation of the current token or null if getCurrentToken() is null.
      abstract JsonToken nextToken()
      Returns the next token from the stream or null to indicate end of input.
      <T> T parse​(Class<T> destinationClass)
      Parse a JSON object, array, or value into a new instance of the given destination class.
      <T> T parse​(Class<T> destinationClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON object, array, or value into a new instance of the given destination class, optionally using the given parser customizer.
      void parse​(Object destination)
      Parse a JSON object from the given JSON parser into the given destination object.
      void parse​(Object destination, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON object from the given JSON parser into the given destination object, optionally using the given parser customizer.
      Object parse​(Type dataType, boolean close)
      Parse a JSON object, array, or value into a new instance of the given destination class.
      Object parse​(Type dataType, boolean close, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON object, array, or value into a new instance of the given destination class, optionally using the given parser customizer.
      <T> T parseAndClose​(Class<T> destinationClass)
      Parse a JSON object, array, or value into a new instance of the given destination class, and then closes the parser.
      <T> T parseAndClose​(Class<T> destinationClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON object, array, or value into a new instance of the given destination class using parse(Class, CustomizeJsonParser), and then closes the parser.
      void parseAndClose​(Object destination)
      Parse a JSON Object from the given JSON parser -- which is closed after parsing completes -- into the given destination object.
      void parseAndClose​(Object destination, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON Object from the given JSON parser -- which is closed after parsing completes -- into the given destination object, optionally using the given parser customizer.
      <T> Collection<T> parseArray​(Class<?> destinationCollectionClass, Class<T> destinationItemClass)
      Parse a JSON Array from the given JSON parser into the given destination collection.
      <T> Collection<T> parseArray​(Class<?> destinationCollectionClass, Class<T> destinationItemClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON Array from the given JSON parser into the given destination collection, optionally using the given parser customizer.
      <T> void parseArray​(Collection<? super T> destinationCollection, Class<T> destinationItemClass)
      Parse a JSON Array from the given JSON parser into the given destination collection.
      <T> void parseArray​(Collection<? super T> destinationCollection, Class<T> destinationItemClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON Array from the given JSON parser into the given destination collection, optionally using the given parser customizer.
      <T> Collection<T> parseArrayAndClose​(Class<?> destinationCollectionClass, Class<T> destinationItemClass)
      Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection.
      <T> Collection<T> parseArrayAndClose​(Class<?> destinationCollectionClass, Class<T> destinationItemClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection, optionally using the given parser customizer.
      <T> void parseArrayAndClose​(Collection<? super T> destinationCollection, Class<T> destinationItemClass)
      Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection.
      <T> void parseArrayAndClose​(Collection<? super T> destinationCollection, Class<T> destinationItemClass, CustomizeJsonParser customizeParser)
      Beta
      Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection, optionally using the given parser customizer.
      abstract JsonParser skipChildren()
      Skips to the matching JsonToken.END_ARRAY if current token is JsonToken.START_ARRAY, the matching JsonToken.END_OBJECT if the current token is JsonToken.START_OBJECT, else does nothing.
      void skipToKey​(String keyToFind)
      Skips the values of all keys in the current object until it finds the given key.
      String skipToKey​(Set<String> keysToFind)
      Skips the values of all keys in the current object until it finds one of the given keys.
    • Constructor Detail

      • JsonParser

        public JsonParser()
    • Method Detail

      • getFactory

        public abstract JsonFactory getFactory()
        Returns the JSON factory from which this generator was created.
      • close

        public abstract void close()
                            throws IOException
        Closes the parser and the underlying input stream or reader, and releases any memory associated with it.
        Throws:
        IOException
      • nextToken

        public abstract JsonToken nextToken()
                                     throws IOException
        Returns the next token from the stream or null to indicate end of input.
        Throws:
        IOException
      • getCurrentToken

        public abstract JsonToken getCurrentToken()
        Returns the token the parser currently points to or null for none (at start of input or after end of input).
      • getCurrentName

        public abstract String getCurrentName()
                                       throws IOException
        Returns the most recent field name or null for array values or for root-level values.
        Throws:
        IOException
      • getByteValue

        public abstract byte getByteValue()
                                   throws IOException
        Returns the byte value of the current token.
        Throws:
        IOException
      • getShortValue

        public abstract short getShortValue()
                                     throws IOException
        Returns the short value of the current token.
        Throws:
        IOException
      • getIntValue

        public abstract int getIntValue()
                                 throws IOException
        Returns the int value of the current token.
        Throws:
        IOException
      • getFloatValue

        public abstract float getFloatValue()
                                     throws IOException
        Returns the float value of the current token.
        Throws:
        IOException
      • getLongValue

        public abstract long getLongValue()
                                   throws IOException
        Returns the long value of the current token.
        Throws:
        IOException
      • getDoubleValue

        public abstract double getDoubleValue()
                                       throws IOException
        Returns the double value of the current token.
        Throws:
        IOException
      • parseAndClose

        public final <T> T parseAndClose​(Class<T> destinationClass)
                                  throws IOException
        Parse a JSON object, array, or value into a new instance of the given destination class, and then closes the parser.
        Type Parameters:
        T - destination class
        Parameters:
        destinationClass - destination class that has a public default constructor to use to create a new instance
        Returns:
        new instance of the parsed destination class
        Throws:
        IOException
        Since:
        1.15
      • parseAndClose

        @Beta
        public final <T> T parseAndClose​(Class<T> destinationClass,
                                         CustomizeJsonParser customizeParser)
                                  throws IOException
        Beta
        Parse a JSON object, array, or value into a new instance of the given destination class using parse(Class, CustomizeJsonParser), and then closes the parser.
        Type Parameters:
        T - destination class
        Parameters:
        destinationClass - destination class that has a public default constructor to use to create a new instance
        customizeParser - optional parser customizer or null for none
        Returns:
        new instance of the parsed destination class
        Throws:
        IOException
      • skipToKey

        public final void skipToKey​(String keyToFind)
                             throws IOException
        Skips the values of all keys in the current object until it finds the given key.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name. After this method ends, the current token will either be the JsonToken.END_OBJECT of the current object if the key is not found, or the value of the key that was found.

        Parameters:
        keyToFind - key to find
        Throws:
        IOException
      • skipToKey

        public final String skipToKey​(Set<String> keysToFind)
                               throws IOException
        Skips the values of all keys in the current object until it finds one of the given keys.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name. After this method ends, the current token will either be the JsonToken.END_OBJECT of the current object if no matching key is found, or the value of the key that was found.

        Parameters:
        keysToFind - set of keys to look for
        Returns:
        name of the first matching key found or null if no match was found
        Throws:
        IOException
        Since:
        1.10
      • parseAndClose

        public final void parseAndClose​(Object destination)
                                 throws IOException
        Parse a JSON Object from the given JSON parser -- which is closed after parsing completes -- into the given destination object.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name.

        Parameters:
        destination - destination object
        Throws:
        IOException
        Since:
        1.15
      • parseAndClose

        @Beta
        public final void parseAndClose​(Object destination,
                                        CustomizeJsonParser customizeParser)
                                 throws IOException
        Beta
        Parse a JSON Object from the given JSON parser -- which is closed after parsing completes -- into the given destination object, optionally using the given parser customizer.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name.

        Parameters:
        destination - destination object
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException
      • parse

        public final <T> T parse​(Class<T> destinationClass)
                          throws IOException
        Parse a JSON object, array, or value into a new instance of the given destination class.

        If it parses an object, after this method ends, the current token will be the object's ending JsonToken.END_OBJECT. If it parses an array, after this method ends, the current token will be the array's ending JsonToken.END_ARRAY.

        Type Parameters:
        T - destination class
        Parameters:
        destinationClass - destination class that has a public default constructor to use to create a new instance
        Returns:
        new instance of the parsed destination class
        Throws:
        IOException
        Since:
        1.15
      • parse

        @Beta
        public final <T> T parse​(Class<T> destinationClass,
                                 CustomizeJsonParser customizeParser)
                          throws IOException
        Beta
        Parse a JSON object, array, or value into a new instance of the given destination class, optionally using the given parser customizer.

        If it parses an object, after this method ends, the current token will be the object's ending JsonToken.END_OBJECT. If it parses an array, after this method ends, the current token will be the array's ending JsonToken.END_ARRAY.

        Type Parameters:
        T - destination class
        Parameters:
        destinationClass - destination class that has a public default constructor to use to create a new instance
        customizeParser - optional parser customizer or null for none
        Returns:
        new instance of the parsed destination class
        Throws:
        IOException
      • parse

        public Object parse​(Type dataType,
                            boolean close)
                     throws IOException
        Parse a JSON object, array, or value into a new instance of the given destination class.

        If it parses an object, after this method ends, the current token will be the object's ending JsonToken.END_OBJECT. If it parses an array, after this method ends, the current token will be the array's ending JsonToken.END_ARRAY.

        Parameters:
        dataType - Type into which the JSON should be parsed
        close - true if close() should be called after parsing
        Returns:
        new instance of the parsed dataType
        Throws:
        IOException
        Since:
        1.15
      • parse

        @Beta
        public Object parse​(Type dataType,
                            boolean close,
                            CustomizeJsonParser customizeParser)
                     throws IOException
        Beta
        Parse a JSON object, array, or value into a new instance of the given destination class, optionally using the given parser customizer.

        If it parses an object, after this method ends, the current token will be the object's ending JsonToken.END_OBJECT. If it parses an array, after this method ends, the current token will be the array's ending JsonToken.END_ARRAY.

        Parameters:
        dataType - Type into which the JSON should be parsed
        close - true if close() should be called after parsing
        customizeParser - optional parser customizer or null for none
        Returns:
        new instance of the parsed dataType
        Throws:
        IOException
        Since:
        1.10
      • parse

        public final void parse​(Object destination)
                         throws IOException
        Parse a JSON object from the given JSON parser into the given destination object.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name. After this method ends, the current token will be the JsonToken.END_OBJECT of the current object.

        Parameters:
        destination - destination object
        Throws:
        IOException
        Since:
        1.15
      • parse

        @Beta
        public final void parse​(Object destination,
                                CustomizeJsonParser customizeParser)
                         throws IOException
        Beta
        Parse a JSON object from the given JSON parser into the given destination object, optionally using the given parser customizer.

        Before this method is called, the parser must either point to the start or end of a JSON object or to a field name. After this method ends, the current token will be the JsonToken.END_OBJECT of the current object.

        Parameters:
        destination - destination object
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException
      • parseArrayAndClose

        public final <T> Collection<T> parseArrayAndClose​(Class<?> destinationCollectionClass,
                                                          Class<T> destinationItemClass)
                                                   throws IOException
        Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection.
        Parameters:
        destinationCollectionClass - class of destination collection (must have a public default constructor)
        destinationItemClass - class of destination collection item (must have a public default constructor)
        Throws:
        IOException
        Since:
        1.15
      • parseArrayAndClose

        @Beta
        public final <T> Collection<T> parseArrayAndClose​(Class<?> destinationCollectionClass,
                                                          Class<T> destinationItemClass,
                                                          CustomizeJsonParser customizeParser)
                                                   throws IOException
        Beta
        Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection, optionally using the given parser customizer.
        Parameters:
        destinationCollectionClass - class of destination collection (must have a public default constructor)
        destinationItemClass - class of destination collection item (must have a public default constructor)
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException
      • parseArrayAndClose

        public final <T> void parseArrayAndClose​(Collection<? super T> destinationCollection,
                                                 Class<T> destinationItemClass)
                                          throws IOException
        Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection.
        Parameters:
        destinationCollection - destination collection
        destinationItemClass - class of destination collection item (must have a public default constructor)
        Throws:
        IOException
        Since:
        1.15
      • parseArrayAndClose

        @Beta
        public final <T> void parseArrayAndClose​(Collection<? super T> destinationCollection,
                                                 Class<T> destinationItemClass,
                                                 CustomizeJsonParser customizeParser)
                                          throws IOException
        Beta
        Parse a JSON Array from the given JSON parser (which is closed after parsing completes) into the given destination collection, optionally using the given parser customizer.
        Parameters:
        destinationCollection - destination collection
        destinationItemClass - class of destination collection item (must have a public default constructor)
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException
      • parseArray

        public final <T> Collection<T> parseArray​(Class<?> destinationCollectionClass,
                                                  Class<T> destinationItemClass)
                                           throws IOException
        Parse a JSON Array from the given JSON parser into the given destination collection.
        Parameters:
        destinationCollectionClass - class of destination collection (must have a public default constructor)
        destinationItemClass - class of destination collection item (must have a public default constructor)
        Throws:
        IOException
        Since:
        1.15
      • parseArray

        @Beta
        public final <T> Collection<T> parseArray​(Class<?> destinationCollectionClass,
                                                  Class<T> destinationItemClass,
                                                  CustomizeJsonParser customizeParser)
                                           throws IOException
        Beta
        Parse a JSON Array from the given JSON parser into the given destination collection, optionally using the given parser customizer.
        Parameters:
        destinationCollectionClass - class of destination collection (must have a public default constructor)
        destinationItemClass - class of destination collection item (must have a public default constructor)
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException
      • parseArray

        public final <T> void parseArray​(Collection<? super T> destinationCollection,
                                         Class<T> destinationItemClass)
                                  throws IOException
        Parse a JSON Array from the given JSON parser into the given destination collection.
        Parameters:
        destinationCollection - destination collection
        destinationItemClass - class of destination collection item (must have a public default constructor)
        Throws:
        IOException
        Since:
        1.15
      • parseArray

        @Beta
        public final <T> void parseArray​(Collection<? super T> destinationCollection,
                                         Class<T> destinationItemClass,
                                         CustomizeJsonParser customizeParser)
                                  throws IOException
        Beta
        Parse a JSON Array from the given JSON parser into the given destination collection, optionally using the given parser customizer.
        Parameters:
        destinationCollection - destination collection
        destinationItemClass - class of destination collection item (must have a public default constructor)
        customizeParser - optional parser customizer or null for none
        Throws:
        IOException