# Java 7+/Android JSON parser/generator, MIT (c) 2020-2024 miktim@mail.ru

Release notes:
  - Java SE 7+/Android RFC 8259 compliant package
    (see: https://datatracker.ietf.org/doc/rfc8259/?include_text=1 );
  - no external dependencies.

package org.miktim.json

Overview:

  Class JSON.

    Contains static parse/generate JSON text functions.
    - parser converts JSON text to Java objects:
      Json object, String, Number (Double or Long), Boolean, null, Object[] array of listed types;
    - Json object members (name/value pairs) are stored in order of appearance/creation;
    - when the names within an object are not unique, parser stores the last value only;
    - in addition to listed types, the generator converts Java Lists, Sets to JSON arrays, Java Maps to JSON objects.
      The null key is converted to a "null" member name.
      Other Java objects are converted to string representation;

      static Object fromJSON(String jsonText)
        throws IOException, ParseException;
        // parse JSON text
      public static Object fromJSON(InputStream in, String charsetName) 
        throws IOException, ParseException;

      static String toJSON(Object obj) throws IOException;
        // generate JSON text as single line
      static String toJSON(Object obj, int space) throws IOException;
        // space is the number of spaces in the indentation
      static <T>T toJSON(T obj, OutputStream out, int space, String charsetName)
        throws IOException;

      static String escapeString(String s);
      static String unescapeString(String s) throws ParseException;
        // returns escaped/unescaped string (RFC 8259 7.)
      static Number toNumber(String number) throws NumberFormatException;
        // returns Double or Long

      Converting a JSON-supported objects to a Java primitive or an array of Java primitives.
      - sample must be initialized;
      - casting numbers may involve rounding or truncation;
      - casting null to a Java primitive returns corresponding initial value;
      - casting null to an array returns an empty array;
      - casting null to String returns "null";
      - casting null to other Java objects returns null;
      - casting to null returns null.

      static <T> T cast(Object obj, T sample);
        // cast Java object or by sample
      static <T> T cast(Object obj, Class <T> cls);
        // cast Java object by class

  Class Json extends LinkedHashMap<String, Object>.

    Java representation of a JSON object
    - Json members:
      Json object, String, Number (BigDecimal), Boolean, null, Object[] array of listed types;
    - Json object members (name/value pairs) are stored in creation/appearance order;
   
    Put, set, get notes:
    - Json object setters accept any Java object, all Java primitives and primitive arrays;
    - RFC 8259 does not recommend using Java BigDecimal and BigInteger as Json member values;
    - AVOID RECURSION!;
    - put, set methods cast Java primitives to the corresponding objects.
      Java objects and arrays are stored "as is" (as reference). 
      For example: float -> Float, int[][] -> int[][], String[] -> String[]
    - after JSON text parsing or normalization, they are stored as:
      Double, Object[]{Object[]{Long,...}, Object[]{Long,...}}, Object[] {String,...};
    - getters return null if the member does not exist.

    Constructors:
      Json(Object... members) throws IndexOutOfBoundsException;
        // members is a name,value pairs
      Json(String jsonText) throws IOException, ParseException;
      Json(InputStream inStream) throws IOException, ParseException;
        // inStream is a UTF-8 encoded JSON text

    Methods:

      String[] listNames(); // returns list of member names
      boolean exists(String memberName); // alias of the inherited containsKey()
      Object put(String memberName, Object value); // inherited
      Json set(Object memberName, Object value);   // create or replace member
      Object get(String memberName);    // inherited
      Object remove(String memberName); // inherited

      Object get(String memberName, int... indices); // returns value or array element
        throws IndexOutOfBoundsException;
      Json getJson(String memberName, int... indices)
        throws ClassCastException, IndexOutOfBoundsException;
      String getString(String memberName, int... indices)
        throws ClassCastException, IndexOutOfBoundsException;
      Number getNumber(String memberName, int... indices)
        throws ClassCastException, IndexOutOfBoundsException;
      Boolean getBoolean(String memberName, int... indices)
        throws ClassCastException, IndexOutOfBoundsException;
      Object[] getArray(String memberName, int... indices)
        throws ClassCastException, IndexOutOfBoundsException;

      <T> T castMember(T sample, String memberName, int... indices);
        // casting Json Member value or array element by sample
      <T> T castMember(Class <T> cls, String memberName, int... indices);
        // casting Json member value or array element by Class
        // see notes for a JSON.cast methods

      Json normalize() throws IOException, ParseException;
        // not required to generate JSON text

      String toString(); 
        // overridden. Returns JSON text as single line
      String toJSON();
        // stringify Json object as single line
      String toJSON(String memberName, int... indices); 
        // stringify member value or array element as single line
      Json toJSON(OutputStream outStream) throws IOException;
        // outStream is UTF-8 encoded single line JSON text


  JsonObject and JsonAdapter classes unload/load visible fields of a Java object to/from a Json object or JSON text.
    - Java transient fields are ignored;
    - Java final fields are unloaded, but not initialized at load;
    - the accessible fields of the object MUST(?) be initialized;
    - see Json set/get/cast rules for Java object fields in the notes for Json object and JsonAdapter;
    - arrays of custom objects and collections MUST be managed using replacer/reviewer.
  
  abstract class ObjectConverter;  

    Constants:
      protected static final transient Object IGNORED; 
         // returns from replacer/reviver to skip the field

    Methods:
      protected Object replacer(String name, Object value);
         - applies on unloading; 
         - name is object field name, value is object field value;
         - first call with the target object class name and the target object as the value;
         - returns Json-supported object or IGNORED

      protected Object reviver(String name, Object value);
         - applies on loading;
         - name is object field name, value is Json-supported object
         - first call with the target object class name and Json object as value
         - returns a value that is compatible with the object field or IGNORED

      static boolean isClassName(String name);
      protected <T> T castMember(String memberName, Json jsonObj, T sample);
         // returns the sample if Json member does not exists or is null

      protected final void setIgnored(String[] fldNames); 
         // set ignored field names
      protected final void addIgnored(String[] fldNames); 
         // add ignored field names
      protected final String[] getIgnored()
      protected final boolean isIgnored(String fldName);

  abstract class JsonObject extends ObjectConverter;
    Java new object extender.

    Methods:
      String toJSON()
        throws IllegalArgumentException, IllegalAccessException
         // returns JSON text as one line
      Object toJson()
        throws IllegalArgumentException, IllegalAccessException;
         // returns Json object

      Object fromJSON(String jsonText)
        throws IOException, ParseException, IllegalArgumentException, IllegalAccessException 
         // returns this object
      Object fromJson(Json jsonObj)
        throws IllegalArgumentException, IllegalAccessException;
         // returns this object
  
  class JsonAdapter extends ObjectConverter;
    Java objects to/from Json converter

    Fields:
      static JsonAdapter defaultAdapter;

    Methods:
      <T>T fromJSON(T object, String jsonText)
        throws IOException, ParseException, IllegalArgumentException, IllegalAccessException 
         // returns object loaded from JSON text 
      <T>T fromJson(T object, Json json)
        throws IllegalArgumentException, IllegalAccessException;
         // returns object loaded from Json object

      Json toJson(Object Object)
         // unload object to Json
 
Usage see:  
  ./test/json/JsonTest.java  
  ./test/json/JsonCastTest.java  
  ./test/json/JsonObjectTest.java