Package com.backblaze.b2.json

Class B2Json

  • public class B2Json
extends java.lang.Object

    JSON (de)serialization of Java objects.

    This class knows how to take a Java object and turn it into JSON, and then reverse the process and take JSON and create a Java object.

    A number of classes are built in to B2Json. In addition to all of the primitive types (byte, char, int, etc.) these classes are all handled: Byte, Character, Integer, Long, Float, Double, Boolean, String, LocalDate, LocalDateTime, and BigDecimal.

    For other classes to be used, you can either add a static getJsonTypeHandler() method to it or add annotations to the class to say how it should go to JSON. For classes without a getJsonTypeHandler() method, there must be a "required", "optional", or "ignored" annotation on every field. And there must be exactly one constructor with the "constructor" annotation.

    The selected constructor must take as arguments all of the non-ignored fields in the object. If any validation of values needs to happen during deserialization, it should happen in the constructor.

    During deserialization, an exception will be thrown if any required fields are missing or null. Optional fields are set to 0/false/null if they are not present in the JSON. If unexpected fields are present in the JSON, they will cause an exception unless ALLOW_EXTRA_FIELDS is selected.

    java.util.Map objects turn into JSON objects when serialized, and java.util.List and java.util.Set objects turn into JSON arrays. On deserialization, the values for Map fields are created as TreeMaps, the values for List fields are created as ArrayLists, and the values for Set fields are created as HashSets.

    The JSON produced is always "pretty", with newlines and indentation. Field names are always sorted alphabetically.

    B2Json objects are THREAD SAFE.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  B2Json.constructor
      Constructor annotation saying that this is the constructor B2Json should use.
      static interface  B2Json.defaultForInvalidEnumValue
      Field annotation that designates the enum value to use when the value in a field isn't one of the known values.
      static interface  B2Json.defaultForUnknownType
      Class annotation that applies to a class that is a @union.
      static interface  B2Json.firstVersion
      Annotation that says that a field exists in all versions at or after this one.
      static interface  B2Json.ignored
      Field annotation that says the field is not included in JSON.
      static interface  B2Json.optional
      Field annotation that says a field is optional.
      static interface  B2Json.optionalWithDefault
      Field annotation that says a field is optional.
      static interface  B2Json.required
      Field annotation that says a field is required to be present.
      static interface  B2Json.sensitive
      Annotation that says this is a sensitive field and should be redacted when outputting for logging
      static interface  B2Json.serializedName
      Annotation to declare that this member will be serialized to JSON with the specified name, instead of the field name in the Java class.
      static interface  B2Json.type
      Type annotation used to configure B2Json serialization/deserialization.
      static interface  B2Json.union
      Class annotation that says a class is the base class for a union type.
      static interface  B2Json.unionSubtypes
      Class annotation that applies to an interface that is a @union.
      static interface  B2Json.versionRange
      Annotation that says that a field exists in all versions in a range (inclusive).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int ALLOW_EXTRA_FIELDS
      Deprecated.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <T> T fromJson​(byte[] jsonUtf8Bytes, java.lang.Class<T> clazz)
      Parse JSON as an object of the given class.
      <T> T fromJson​(byte[] jsonUtf8Bytes, java.lang.Class<T> clazz, int optionFlags)
      Deprecated.
      <T> T fromJson​(byte[] jsonUtf8Bytes, java.lang.Class<T> clazz, B2JsonOptions options)  
      <T> T fromJson​(java.io.InputStream in, java.lang.Class<T> clazz)
      Parse JSON as an object of the given class with the given options.
      <T> T fromJson​(java.io.InputStream in, java.lang.Class<T> clazz, int optionFlags)
      Deprecated.
      <T> T fromJson​(java.io.InputStream in, java.lang.reflect.Type type, B2JsonOptions options)
      Parse the bytes from an InputStream as JSON using the supplied options, returning the parsed object.
      <T> T fromJson​(java.io.Reader reader, java.lang.Class<T> clazz)
      Parse JSON as an object of the given class with the given options.
      <T> T fromJson​(java.io.Reader reader, java.lang.reflect.Type type, B2JsonOptions options)
      Parse the bytes from a Reader as JSON using the supplied options, returning the parsed object.
      <T> T fromJson​(java.lang.String json, java.lang.Class<T> clazz)
      Parse JSON as an object of the given class.
      <T> T fromJson​(java.lang.String json, java.lang.Class<T> clazz, int optionFlags)
      Deprecated.
      <T> T fromJson​(java.lang.String json, java.lang.Class<T> clazz, B2JsonOptions options)  
      static <T> T fromJsonOrThrowRuntime​(java.lang.String json, java.lang.Class<T> clazz)
      Parse an assumed JSON string into a defined class.
      static <T> T fromJsonOrThrowRuntime​(java.lang.String json, java.lang.Class<T> clazz, B2JsonOptions options)  
      <T> T fromJsonUntilEof​(java.io.InputStream in, java.lang.Class<T> clazz)
      Parse JSON as an object of the given class with the given options, reading from the input stream until reaching EOF.
      <T> T fromJsonUntilEof​(java.io.InputStream in, java.lang.Class<T> clazz, int optionFlags)
      Deprecated.
      <T> T fromJsonUntilEof​(java.io.InputStream in, java.lang.Class<T> clazz, B2JsonOptions options)  
      <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap, java.lang.Class<T> clazz)
      Parse a URL parameter map as an object of the given class.
      <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap, java.lang.Class<T> clazz, int optionFlags)
      Deprecated.
      <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap, java.lang.Class<T> clazz, B2JsonOptions options)  
      static B2Json get()  
      <V> java.util.List<V> listFromJson​(java.lang.String json, java.lang.Class<V> valueClass)
      Parses a JSON object into a map.
      <V> java.util.List<V> listFromJson​(java.lang.String json, java.lang.Class<V> valueClass, B2JsonOptions options)  
      java.lang.String listToJson​(java.util.List<?> list, java.lang.Class<?> valueClass)
      Turn a map into JSON, returning the result as a string.
      java.lang.String listToJson​(java.util.List<?> list, java.lang.Class<?> valueClass, B2JsonOptions options)  
      <K,​V>
      java.util.Map<K,​V>      		 mapFromJson​(java.lang.String json, java.lang.Class<K> keyClass, java.lang.Class<V> valueClass)
      Parses a JSON object into a map.
      <K,​V>
      java.util.Map<K,​V>      		 mapFromJson​(java.lang.String json, java.lang.Class<K> keyClass, java.lang.Class<V> valueClass, B2JsonOptions options)  
      java.lang.String mapToJson​(java.util.Map<?,​?> map, java.lang.Class<?> keyClass, java.lang.Class<?> valueClass)
      Turn a map into JSON, returning the result as a string.
      java.lang.String mapToJson​(java.util.Map<?,​?> map, java.lang.Class<?> keyClass, java.lang.Class<?> valueClass, B2JsonOptions options)  
      java.lang.String toJson​(java.lang.Object obj)
      Turn an object into JSON, returning the result as a string.
      java.lang.String toJson​(java.lang.Object obj, B2JsonOptions options)  
      void toJson​(java.lang.Object obj, B2JsonOptions options, java.io.OutputStream out)
      Turn an object into JSON, writing the results to given output stream and using the supplied options.
      void toJson​(java.lang.Object obj, B2JsonOptions options, java.io.OutputStream out, java.lang.reflect.Type objTypeOrNull)
      Turn an object into JSON, writing the results to given output stream.
      void toJson​(java.lang.Object obj, java.io.OutputStream out)
      Turn an object into JSON, writing the results to given output stream.
      static java.lang.String toJsonOrThrowRuntime​(java.lang.Object obj)
      Turn an object into JSON, returning the result as a string.
      static java.lang.String toJsonOrThrowRuntime​(java.lang.Object obj, B2JsonOptions options)  
      byte[] toJsonUtf8Bytes​(java.lang.Object obj)
      Turn an object into JSON, returning the result as an array of UTF-8 bytes.
      byte[] toJsonUtf8Bytes​(java.lang.Object obj, B2JsonOptions options)  
      byte[] toJsonUtf8BytesWithNewline​(java.lang.Object obj)
      Turn an object into JSON, returning the result as an array of UTF-8 bytes.
      byte[] toJsonUtf8BytesWithNewline​(java.lang.Object obj, B2JsonOptions options)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • ALLOW_EXTRA_FIELDS

        @Deprecated
public static final int ALLOW_EXTRA_FIELDS
        Deprecated.
        Bit map values for the options parameter to the constructor.

        Deprecated in favor of using B2JsonOptions.

        See Also:
        Constant Field Values

    • Method Detail

      • get

        public static B2Json get()
        Returns:
        A shared instance.

      • toJsonUtf8Bytes

        public byte[] toJsonUtf8Bytes​(java.lang.Object obj)
                       throws B2JsonException
        Turn an object into JSON, returning the result as an array of UTF-8 bytes.
        Throws:
        B2JsonException

      • toJsonUtf8BytesWithNewline

        public byte[] toJsonUtf8BytesWithNewline​(java.lang.Object obj)
                                  throws B2JsonException
        Turn an object into JSON, returning the result as an array of UTF-8 bytes.
        Throws:
        B2JsonException

      • toJson

        public void toJson​(java.lang.Object obj,
                   java.io.OutputStream out)
            throws java.io.IOException,
                   B2JsonException
        Turn an object into JSON, writing the results to given output stream.
        Throws:
        java.io.IOException
        B2JsonException

      • toJson

        public void toJson​(java.lang.Object obj,
                   B2JsonOptions options,
                   java.io.OutputStream out)
            throws java.io.IOException,
                   B2JsonException
        Turn an object into JSON, writing the results to given output stream and using the supplied options.
        Throws:
        java.io.IOException
        B2JsonException

      • toJson

        public void toJson​(java.lang.Object obj,
                   B2JsonOptions options,
                   java.io.OutputStream out,
                   java.lang.reflect.Type objTypeOrNull)
            throws java.io.IOException,
                   B2JsonException
        Turn an object into JSON, writing the results to given output stream.

        objTypeOrNull can be set to null if obj is not a parameterized class. However, if obj contains type parameters (like if obj is a List<String>, then you will need to pass in its type information via objTypeOrNull. This will instruct B2Json to derive the B2JsonTypeHandler from the type information instead of the object's class.

        Getting the Type of obj can be done in at least two ways: 1. If it is a member of an enclosing class, EnclosingClass.getDeclaredField(...).getGenericType() 2. By constructing a class that implements Type.

        Note that the output stream is NOT closed as a side-effect of calling this. It was a bug that it was being closed in version 1.1.1 and earlier.

        Throws:
        java.io.IOException
        B2JsonException

      • toJson

        public java.lang.String toJson​(java.lang.Object obj)
                        throws B2JsonException
        Turn an object into JSON, returning the result as a string.
        Throws:
        B2JsonException

      • toJsonOrThrowRuntime

        public static java.lang.String toJsonOrThrowRuntime​(java.lang.Object obj)
        Turn an object into JSON, returning the result as a string. This throws a RuntimeException instead of a B2JsonException, so use it carefully.

      • toJsonOrThrowRuntime

        public static java.lang.String toJsonOrThrowRuntime​(java.lang.Object obj,
                                                    B2JsonOptions options)

      • fromJsonOrThrowRuntime

        public static <T> T fromJsonOrThrowRuntime​(java.lang.String json,
                                           java.lang.Class<T> clazz)
        Parse an assumed JSON string into a defined class. This throws a RuntimeException instead of a B2JsonException, so use it carefully.
        Type Parameters:
        T - The deserialized object casted to the specific type from clazz
        Parameters:
        json - JSON String to try and parse
        clazz - Class to map the JSON String to.
        Returns:
        the object deserialized from the JSON String

      • fromJsonOrThrowRuntime

        public static <T> T fromJsonOrThrowRuntime​(java.lang.String json,
                                           java.lang.Class<T> clazz,
                                           B2JsonOptions options)

      • mapToJson

        public java.lang.String mapToJson​(java.util.Map<?,​?> map,
                                  java.lang.Class<?> keyClass,
                                  java.lang.Class<?> valueClass)
                           throws B2JsonException
        Turn a map into JSON, returning the result as a string.
        Throws:
        B2JsonException

      • mapFromJson

        public <K,​V> java.util.Map<K,​V> mapFromJson​(java.lang.String json,
                                                        java.lang.Class<K> keyClass,
                                                        java.lang.Class<V> valueClass)
                                                 throws B2JsonException
        Parses a JSON object into a map.
        Throws:
        B2JsonException

      • mapFromJson

        public <K,​V> java.util.Map<K,​V> mapFromJson​(java.lang.String json,
                                                        java.lang.Class<K> keyClass,
                                                        java.lang.Class<V> valueClass,
                                                        B2JsonOptions options)
                                                 throws B2JsonException
        Throws:
        B2JsonException

      • listToJson

        public java.lang.String listToJson​(java.util.List<?> list,
                                   java.lang.Class<?> valueClass)
                            throws B2JsonException
        Turn a map into JSON, returning the result as a string.
        Throws:
        B2JsonException

      • listFromJson

        public <V> java.util.List<V> listFromJson​(java.lang.String json,
                                          java.lang.Class<V> valueClass)
                                   throws B2JsonException
        Parses a JSON object into a map.
        Throws:
        B2JsonException

      • fromJsonUntilEof

        public <T> T fromJsonUntilEof​(java.io.InputStream in,
                              java.lang.Class<T> clazz)
                       throws java.io.IOException,
                              B2JsonException
        Parse JSON as an object of the given class with the given options, reading from the input stream until reaching EOF. Throws an error if there is anything but whitespace after the JSON value.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJsonUntilEof

        @Deprecated
public <T> T fromJsonUntilEof​(java.io.InputStream in,
                              java.lang.Class<T> clazz,
                              int optionFlags)
                       throws java.io.IOException,
                              B2JsonException
        Deprecated.
        Use the call that takes B2JsonOptions, no this one with 'int optionFlags'.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJsonUntilEof

        public <T> T fromJsonUntilEof​(java.io.InputStream in,
                              java.lang.Class<T> clazz,
                              B2JsonOptions options)
                       throws java.io.IOException,
                              B2JsonException
        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        public <T> T fromJson​(java.io.InputStream in,
                      java.lang.Class<T> clazz)
               throws java.io.IOException,
                      B2JsonException
        Parse JSON as an object of the given class with the given options.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        @Deprecated
public <T> T fromJson​(java.io.InputStream in,
                      java.lang.Class<T> clazz,
                      int optionFlags)
               throws java.io.IOException,
                      B2JsonException
        Deprecated.
        Use the call that takes B2JsonOptions, no this one with 'int optionFlags'.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        public <T> T fromJson​(java.io.InputStream in,
                      java.lang.reflect.Type type,
                      B2JsonOptions options)
               throws java.io.IOException,
                      B2JsonException
        Parse the bytes from an InputStream as JSON using the supplied options, returning the parsed object.

        The Type parameter will usually be a class, which is straightforward to supply. However, if you are trying to deserialize a parameterized type (like if obj is a List<String>, then you will need to supply a proper Type instance.

        Getting the Type can be done in at least two ways: 1. If it is a member of an enclosing class, EnclosingClass.getDeclaredField(...).getGenericType() 2. By constructing a class that implements Type.

        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        public <T> T fromJson​(java.io.Reader reader,
                      java.lang.Class<T> clazz)
               throws java.io.IOException,
                      B2JsonException
        Parse JSON as an object of the given class with the given options.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        public <T> T fromJson​(java.io.Reader reader,
                      java.lang.reflect.Type type,
                      B2JsonOptions options)
               throws java.io.IOException,
                      B2JsonException
        Parse the bytes from a Reader as JSON using the supplied options, returning the parsed object.

        The Type parameter will usually be a class, which is straightforward to supply. However, if you are trying to deserialize a parameterized type (for instance, if the object is a List<String>), then you will need to supply a proper Type instance.

        Getting the Type can be done in at least two ways: 1. If it is a member of an enclosing class, EnclosingClass.getDeclaredField(...).getGenericType() 2. By constructing a class that implements Type.

        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        public <T> T fromJson​(java.lang.String json,
                      java.lang.Class<T> clazz)
               throws B2JsonException
        Parse JSON as an object of the given class.
        Throws:
        B2JsonException

      • fromJson

        @Deprecated
public <T> T fromJson​(java.lang.String json,
                      java.lang.Class<T> clazz,
                      int optionFlags)
               throws B2JsonException
        Deprecated.
        Use the call that takes B2JsonOptions, no this one with 'int optionFlags'.
        Throws:
        B2JsonException

      • fromJson

        public <T> T fromJson​(byte[] jsonUtf8Bytes,
                      java.lang.Class<T> clazz)
               throws java.io.IOException,
                      B2JsonException
        Parse JSON as an object of the given class.
        Throws:
        java.io.IOException
        B2JsonException

      • fromJson

        @Deprecated
public <T> T fromJson​(byte[] jsonUtf8Bytes,
                      java.lang.Class<T> clazz,
                      int optionFlags)
               throws java.io.IOException,
                      B2JsonException
        Deprecated.
        Use the call that takes B2JsonOptions, no this one with 'int optionFlags'.
        Throws:
        java.io.IOException
        B2JsonException

      • fromUrlParameterMap

        public <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap,
                                 java.lang.Class<T> clazz)
                          throws java.io.IOException,
                                 B2JsonException
        Parse a URL parameter map as an object of the given class.

        The values in the map are the values that will be used in the object. The caller is responsible for URL-decoding them before passing them to this method.

        Throws:
        java.io.IOException
        B2JsonException

      • fromUrlParameterMap

        @Deprecated
public <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap,
                                 java.lang.Class<T> clazz,
                                 int optionFlags)
                          throws java.io.IOException,
                                 B2JsonException
        Deprecated.
        Use the call that takes B2JsonOptions, no this one with 'int optionFlags'.
        Throws:
        java.io.IOException
        B2JsonException

      • fromUrlParameterMap

        public <T> T fromUrlParameterMap​(java.util.Map<java.lang.String,​java.lang.String> parameterMap,
                                 java.lang.Class<T> clazz,
                                 B2JsonOptions options)
                          throws java.io.IOException,
                                 B2JsonException
        Throws:
        java.io.IOException
        B2JsonException