JsonArrayBuilder、JsonObjectBuilder、JsonBuilderFactory源码翻译

package javax.json;

import java.math.BigDecimal;
import java.math.BigInteger;

/**
 * 目的：创建JsonArray对象，并且是空的JSON数组
 * 
 * <p>构建一个{@link JsonArray}模型。该接口初始化一个空的JSON数组并提供添加元素的方法和
 * 返回这个数组。增加多种值到这个数组。
 * 
 * <p>{@link javax.json.Json}能够构建JsonArray对象，如下所以构建一个空的JSON数组：
 * 		JsonArray array = Json.createArrayBuilder().build();
 * 
 * <p>{@link JsonBuilderFactory}能够获取{@code JsonArrayBuilder}实例，
 * 从而创建JsonArray对象，如下所示：
 * 		JsonBuilderFactory factory = Json.createBuilderFactory(config);
 * 		JsonArray value = factory.createArrayBuilder()
 *     		.add(factory.createObjectBuilder()
 *         		.add("type", "home")
 *         		.add("number", "212 555-1234"))
 *     		.add(factory.createObjectBuilder()
 *         		.add("type", "fax")
 *         		.add("number", "646 555-4567"))
 *     		.build();
 *     
 * <p>注意：该接口创建JSON数组时，NULL值不能被使用。
 * @author TCM
 * @create 2017年11月6日上午9:24:40
 */
public interface JsonArrayBuilder {

    JsonArrayBuilder add(JsonValue value);
    JsonArrayBuilder add(String value);
    JsonArrayBuilder add(BigDecimal value);
    JsonArrayBuilder add(BigInteger value);
    JsonArrayBuilder add(int value);
    JsonArrayBuilder add(long value);
    JsonArrayBuilder add(double value);
    JsonArrayBuilder add(boolean value);
    JsonArrayBuilder addNull();
    
    /*
     * JSON数组元素是JsonObject或是JsonArray
     */
    JsonArrayBuilder add(JsonObjectBuilder builder);
    JsonArrayBuilder add(JsonArrayBuilder builder);
    JsonArray build();

}

package javax.json;

import java.math.BigDecimal;
import java.math.BigInteger;

/**
 * 目的：创建JsonObject对象，并且是空的JSON对象
 * 
 * <p>构建一个{@link JsonObject}模型。该接口初始化一个空的JSON对象并提供添加元素的方法和
 * 返回这个对象。增加多种值到这个对象。
 * 
 * <p>创建方法：
 *   a. JsonObject object = Json.createObjectBuilder().build();
 *   b. JsonBuilderFactory factory = Json.createBuilderFactory(config);
 * 		JsonObject value = factory.createObjectBuilder()
 *     		.add("firstName", "John")
 *     		.add("lastName", "Smith")
 *     		.add("age", 25)
 *     		.add("address", factory.createObjectBuilder()
 *         		.add("streetAddress", "21 2nd Street")
 *         		.add("city", "New York")
 *         		.add("state", "NY")
 *         		.add("postalCode", "10021"))
 *     		.add("phoneNumber", factory.createArrayBuilder()
 *         		.add(factory.createObjectBuilder()
 *             		.add("type", "home")
 *             		.add("number", "212 555-1234"))
 *         		.add(factory.createObjectBuilder()
 *             		.add("type", "fax")
 *             		.add("number", "646 555-4567")))
 *     		.build();
 * @author TCM
 * @create 2017年11月6日上午10:07:52
 */
public interface JsonObjectBuilder {

    JsonObjectBuilder add(String name, JsonValue value);
    JsonObjectBuilder add(String name, String value);
    JsonObjectBuilder add(String name, BigInteger value);
    JsonObjectBuilder add(String name, BigDecimal value);
    JsonObjectBuilder add(String name, int value);
    JsonObjectBuilder add(String name, long value);
    JsonObjectBuilder add(String name, double value);
    JsonObjectBuilder add(String name, boolean value);
    JsonObjectBuilder addNull(String name);
    
    /*
     * JSON对象属性是JsonObject或是JsonArray
     */
    JsonObjectBuilder add(String name, JsonObjectBuilder builder);
    JsonObjectBuilder add(String name, JsonArrayBuilder builder);
    JsonObject build();

}

package javax.json;

import java.util.Map;

/**
 * 目的：工厂创建{@link JsonObjectBuilder}和{@link JsonArrayBuilder}实例
 * 
 * <p>工厂创建JsonObjectBuilder和JsonArrayBuilder实例。工厂实例具有相同的
 * 配置，使用配置来创建构建器实例。
 * 
 * <p>JsonObjectBuilder和JsonArrayBuilder也可以使用{@link Json}'s方法
 * 来创建实例。如果创建多个实例，则优先使用工厂方式创建实例。例如：
 * 	JsonBuilderFactory factory = Json.createBuilderFactory(...);
 * 	JsonArray value = factory.createArrayBuilder()
 *     .add(factory.createObjectBuilder()
 *         .add("type", "home")
 *         .add("number", "212 555-1234"))
 *     .add(factory.createObjectBuilder()
 *         .add("type", "fax")
 *         .add("number", "646 555-4567"))
 *     .build();
 *     
 * <p>这个类的方法都是线程安全的，可以使用多线程并发。
 * @author TCM
 * @create 2017年11月6日上午10:12:45
 */
public interface JsonBuilderFactory {

	//创建一个JsonObjectBuilder实例来创建{@link JsonObject}
    JsonObjectBuilder createObjectBuilder();

    //创建一个JsonArrayBuilder实例来创建{@link JsonArray}
    JsonArrayBuilder createArrayBuilder();

    //获取JSON构建器的配置属性（只读的映射）
    Map<String, ?> getConfigInUse();

}