Package io.avaje.jsonb

Interface Jsonb

  • public interface Jsonb
    Provides access to json adapters by type.

    Initialise with defaults

    
   Jsonb jsonb = Jsonb.builder().build();

    Initialise with some configuration

    
   Jsonb jsonb = Jsonb.builder()
     .serializeNulls(true)
     .serializeEmpty(true)
     .failOnUnknown(true)
     .build();

    Initialise using Jackson core with configuration

    We need to include the dependency io.avaje:avaje-jsonb-jackson to do this. This will use Jackson core JsonParser and JsonGenerator to do the underlying parsing and generation. 

    

   // create the Jackson JsonFactory
   JsonFactory customFactory = ...;

   var jacksonAdapter = JacksonAdapter.builder()
     .serializeNulls(true)
     .jsonFactory(customFactory)
     .build();

   Jsonb jsonb = Jsonb.builder()
     .adapter(jacksonAdapter)
     .build();

    fromJson

    Read json content from: String, byte[], Reader, InputStream, JsonReader 

    

  JsonType<Customer> customerType = jsonb.type(Customer.class);

  Customer customer = customerType.fromJson(content);

    toJson

    Write json content to: String, byte[], Writer, OutputStream, JsonWriter 

    

  JsonType<Customer> customerType = jsonb.type(Customer.class);

  String asJson = customerType.toJson(customer);

    • Method Detail

      • builder

        static Jsonb.Builder builder()
        Create a new Jsonb.Builder to configure and build the Jsonb instance.

        We can register JsonAdapter's to use for specific types before building and returning the Jsonb instance to use.

        Note that JsonAdapter's that are generated are automatically registered via service loading so there is no need to explicitly register those generated JsonAdapters. 

        

   Jsonb jsonb = Jsonb.builder()
     .serializeNulls(true)
     .serializeEmpty(true)
     .failOnUnknown(true)
     .build();

      • toJson

        String toJson​(Object any)
        Return json content for the given object.

        This is a convenience method for jsonb.type(Object.class).toJson(any)

        Parameters:
        any - The object to return as json string
        Returns:
        Return json content for the given object.

      • toJsonPretty

        String toJsonPretty​(Object any)
        Return json content in pretty format for the given object.

        This is a convenience method for jsonb.type(Object.class).toJsonPretty(any)

        Parameters:
        any - The object to return as json string in pretty format
        Returns:
        Return json content in pretty format for the given object.

      • toJsonBytes

        byte[] toJsonBytes​(Object any)
        Return the value as json content in bytes form.

        This is a convenience method for jsonb.type(Object.class).toJsonBytes(any)

      • toJson

        void toJson​(Object any,
            Writer writer)
        Write to the given writer.

        This is a convenience method for jsonb.type(Object.class).toJson(any, writer)

      • toJson

        void toJson​(Object any,
            OutputStream outputStream)
        Write to the given outputStream.

        This is a convenience method for jsonb.type(Object.class).toJsonBytes(any, outputStream)

      • toJson

        void toJson​(Object any,
            JsonWriter jsonWriter)
        Write to the given writer.

        This is a convenience method for jsonb.type(Object.class).toJson(any, writer)

      • type

        <T> JsonType<T> type​(Class<T> cls)
        Return the JsonType used to read and write json for the given class.

        fromJson() example

        

   Customer customer = jsonb
     .type(Customer.class)
     .fromJson(jsonContent);


   // list
   List<Customer> customers = jsonb
     .type(Customer.class)
     .list()
     .fromJson(jsonContent);

        toJson() example

        

   Object anything = ...
   String jsonContent = jsonb.toJson(anything);

   Customer customer = ...

   // any type toJson()
   String jsonContent = jsonb.toJson(customer);

   // or use .type(Customer.class) if we like
   String jsonContent = jsonb
     .type(Customer.class)
     .toJson(customer);

        Using Object.class

        We can use type(Object.class) when we don't know the specific type that is being written toJson or read fromJson.

        Object toJson()

        

   Object any = ...

   String jsonContent = jsonb
     .type(Object.class)
     .toJson(any);

   // which is the same as
   String jsonContent = jsonb.toJson(any);

        When using Object.class and writing toJson() then the underlying JsonAdapter is determined dynamically based on the type of the object value passed in.

        When using Object.class and reading fromJson() then the java types used in the result are determined dynamically based on the json types being read and the resulting java types are ArrayList, LinkedHashMap, String, boolean, and double.

      • type

        <T> JsonType<T> type​(Type type)
        Return the JsonType used to read and write json for the given type.

        We can use Types to obtain common generic types for List, Set, Map, Array etc.

        Example

        

   JsonType<List<String>> listOfStringType = jsonb.type(Types.listOf(String.class))

   JsonType<List<Customer>> listOfCustomerType = jsonb.type(Types.listOf(Customer.class))

   JsonType<Map<String,Integer>> adapter = jsonb.type(Types.mapOf(Integer.class))

        Using Object.class

        We can use type(Object.class) when we don't know the specific type that is being written toJson or read fromJson.

        Object toJson()

        

   Object any = ...

   String jsonContent = jsonb
     .type(Object.class)
     .toJson(any);

   // the same as
   String jsonContent = jsonb.toJson(any);

        When using Object.class and writing toJson() then the underlying JsonAdapter is determined dynamically based on the type of the object value passed in.

        When using Object.class and reading fromJson() then the java types used in the result are determined dynamically based on the json types being read and the resulting java types are ArrayList, LinkedHashMap, String, boolean, and double.

      • typeOf

        <T> JsonType<T> typeOf​(Object value)
        Return the JsonType for the given value using the class of the value being passed in.

        This is a helper method that supports returning an inferred generic type.

        Type Parameters:
        T - The inferred generic parameter type
        Parameters:
        value - The value of the given type
        Returns:
        JsonType for the given value

      • reader

        JsonReader reader​(String json)
        Return the JsonReader used to read the given json content.

      • reader

        JsonReader reader​(byte[] jsonBytes)
        Return the JsonReader used to read the given json content in bytes.

      • reader

        JsonReader reader​(Reader reader)
        Return the JsonReader used to read the json content from the given reader.

      • reader

        JsonReader reader​(InputStream inputStream)
        Return the JsonReader used to read the json content from the given inputStream.

      • writer

        JsonWriter writer​(Writer writer)
        Return the JsonWriter used to write json to the given writer.

      • writer

        JsonWriter writer​(OutputStream outputStream)
        Return the JsonWriter used to write json to the given outputStream.

      • properties

        PropertyNames properties​(String... names)
        Return the property names as PropertyNames.

        Provides the option of optimising the writing of json for property names by having them already escaped and encoded rather than as plain strings.

      • adapter

        <T> JsonAdapter<T> adapter​(Class<T> cls)
        Return the JsonAdapter used to read and write json for the given class.

        JsonAdapter is generally used by generated code and your application code is expected to use type(Class) and JsonType instead.

      • adapter

        <T> JsonAdapter<T> adapter​(Type type)
        Return the JsonAdapter used to read and write json for the given type.

        JsonAdapter is generally used by generated code and your application code is expected to use type(Type) and JsonType instead.