cn.hutool.json.JSON Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hutool-all Show documentation
Hutool是一个小而全的Java工具类库，通过静态方法封装，降低相关API的学习成本，提高工作效率，使Java拥有函数式语言般的优雅，让Java语言也可以“甜甜的”。
There is a newer version: 5.8.34
package cn.hutool.json;

import cn.hutool.core.bean.BeanPath;
import cn.hutool.core.bean.copier.IJSONTypeConverter;
import cn.hutool.core.lang.TypeReference;

import java.io.Serializable;
import java.io.StringWriter;
import java.io.Writer;
import java.lang.reflect.Type;

/**
 * JSON接口
 *
 * @author Looly
 */
public interface JSON extends Cloneable, Serializable, IJSONTypeConverter {

	/**
	 * 获取JSON配置
	 *
	 * @return {@link JSONConfig}
	 * @since 5.8.6
	 */
	JSONConfig getConfig();

	/**
	 * 通过表达式获取JSON中嵌套的对象

	 * 
	 * .表达式，可以获取Bean对象中的属性（字段）值或者Map中key对应的值
	 * []表达式，可以获取集合等对象中对应index的值
	 * 
	 * 
	 * 表达式栗子：
	 *
	 * 
	 * persion
	 * persion.name
	 * persons[3]
	 * person.friends[5].name
	 * 
	 *
	 * @param expression 表达式
	 * @return 对象
	 * @see BeanPath#get(Object)
	 * @since 4.0.6
	 */
	Object getByPath(String expression);

	/**
	 * 设置表达式指定位置（或filed对应）的值

	 * 若表达式指向一个JSONArray则设置其坐标对应位置的值，若指向JSONObject则put对应key的值

	 * 注意：如果为JSONArray，设置值下标小于其长度，将替换原有值，否则追加新值

	 * 
	 * .表达式，可以获取Bean对象中的属性（字段）值或者Map中key对应的值
	 * []表达式，可以获取集合等对象中对应index的值
	 * 
	 * 
	 * 表达式栗子：
	 *
	 * 
	 * persion
	 * persion.name
	 * persons[3]
	 * person.friends[5].name
	 * 
	 *
	 * @param expression 表达式
	 * @param value      值
	 */
	void putByPath(String expression, Object value);

	/**
	 * 通过表达式获取JSON中嵌套的对象

	 * 
	 * .表达式，可以获取Bean对象中的属性（字段）值或者Map中key对应的值
	 * []表达式，可以获取集合等对象中对应index的值
	 * 
	 * 
	 * 表达式栗子：
	 *
	 * 
	 * persion
	 * persion.name
	 * persons[3]
	 * person.friends[5].name
	 * 
	 * 
	 * 获取表达式对应值后转换为对应类型的值
	 *
	 * @param         返回值类型
	 * @param expression 表达式
	 * @param resultType 返回值类型
	 * @return 对象
	 * @see BeanPath#get(Object)
	 * @since 4.0.6
	 */
	 T getByPath(String expression, Class resultType);

	/**
	 * 格式化打印JSON，缩进为4个空格
	 *
	 * @return 格式化后的JSON字符串
	 * @throws JSONException 包含非法数抛出此异常
	 * @since 3.0.9
	 */
	default String toStringPretty() throws JSONException {
		return this.toJSONString(4);
	}

	/**
	 * 格式化输出JSON字符串
	 *
	 * @param indentFactor 每层缩进空格数
	 * @return JSON字符串
	 * @throws JSONException 包含非法数抛出此异常
	 */
	default String toJSONString(int indentFactor) throws JSONException {
		final StringWriter sw = new StringWriter();
		return this.write(sw, indentFactor, 0).toString();
	}

	/**
	 * 将JSON内容写入Writer，无缩进

	 * Warning: This method assumes that the data structure is acyclical.
	 *
	 * @param writer Writer
	 * @return Writer
	 * @throws JSONException JSON相关异常
	 */
	default Writer write(Writer writer) throws JSONException {
		return this.write(writer, 0, 0);
	}

	/**
	 * 将JSON内容写入Writer

	 * Warning: This method assumes that the data structure is acyclical.
	 *
	 * @param writer       writer
	 * @param indentFactor 缩进因子，定义每一级别增加的缩进量
	 * @param indent       本级别缩进量
	 * @return Writer
	 * @throws JSONException JSON相关异常
	 */
	Writer write(Writer writer, int indentFactor, int indent) throws JSONException;

	/**
	 * 转为实体类对象，转换异常将被抛出
	 *
	 * @param    Bean类型
	 * @param clazz 实体类
	 * @return 实体类对象
	 */
	default  T toBean(Class clazz) {
		return toBean((Type) clazz);
	}

	/**
	 * 转为实体类对象，转换异常将被抛出
	 *
	 * @param        Bean类型
	 * @param reference {@link TypeReference}类型参考子类，可以获取其泛型参数中的Type类型
	 * @return 实体类对象
	 * @since 4.2.2
	 */
	default  T toBean(TypeReference reference) {
		return toBean(reference.getType());
	}

	/**
	 * 转为实体类对象
	 *
	 * @param   Bean类型
	 * @param type {@link Type}
	 * @return 实体类对象
	 * @since 3.0.8
	 */
	default  T toBean(Type type) {
		return JSONConverter.jsonConvert(type, this, getConfig());
	}

	/**
	 * 转为实体类对象
	 *
	 * @param          Bean类型
	 * @param type        {@link Type}
	 * @param ignoreError 是否忽略转换错误
	 * @return 实体类对象
	 * @since 4.3.2
	 * @deprecated 请使用 {@link #toBean(Type)}, ignoreError在JSONConfig中生效
	 */
	@Deprecated
	default  T toBean(Type type, boolean ignoreError) {
		return JSONConverter.jsonConvert(type, this, JSONConfig.create().setIgnoreError(ignoreError));
	}
}