# beetl-json

**Repository Path**: wowin/beetl-json

## Basic Information

- **Project Name**: beetl-json
- **Description**: json序列化另外一种实现方式
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 17
- **Created**: 2015-05-23
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


Beetl-JsonTool 作为beetl模板引擎的一个附属工具，提供了对象序列化成json技术。其原理是基于(Location:action)*，功能强大，扩展性强，而体积小，仅仅不到60K。

##例子:

* name:i 忽略name属性
* id:i,obj.id:i 忽略属性id,忽略属性obj对象的id的属性.可以将多个序列化策略组合在一起，用逗号分开
* ~d:f/yyyy-MM-dd/ 这个对象实例的日期类型格式化输出，符号~代表这个实例
* ~c:?emtpy->[],这个实例集合为null或者为空都输出[],->后可以是任何常量
* name:nn/myName/ 将属性name输出成myName
* ~*:o/name, age/ 这个对象实例排序输出，name,age 先输出，其他按照定义输出
* [1].date:f/yyyy-MM-dd/  列表第二项目的date属性格式化输出
* api 例子如下
	
		String json = JsonTool.serialize(user);	
		//排序	
		String json1 = JsonTool.serialize(user，"~*:o/age,name/"));	
		//忽略第二个元素
		String json2 = JsonTool.serialize(list，"[1]:i"));
	
##Location
定义了一个序列化的位置，比如最简单的location就是属性名称，或者是属性类型,如

* nane:nn/myName/ 遇到name属性，输出的是myName，nn是action指示，表示New Name
* ~ 代表当前实例:
	* ~d 遇到类型为日期的，格式化输出。d是Java.Util.Date的简称。
    * ~n 表示一个number类型
    * ，也可以忽略包名，JsonTool会根据配置自动找类（JsonTool.addImportPkg())，如果具体类名后有×，表示其子类也匹配
    * ~c 表示是一个集合
    * ~d 表示一个日期
* ~*：表示当前实例，如~*:o/age,name/，当前实例的属性，按照age,name先后顺序输出，其他保持不变
* ~L  表示后面是个具体类，如~L/java.util.Date/:f/yyyy-MM-dd/ 所有类型为Date的都进行格式，注意~L 同 ~* 不一样，前者表示序列化当前实例或者之后的任何对象，只要碰到 ~L 指定的类，都将采用指定的序列化策略，而~* 表示的是当前的对象实例。

locaton 可以是属性表达式

* obj.aaa.xx,指属性obj的属性aa的属性xx的位置
* obj[1].name ,指属性obj是个集合，位置是第二元素的name属性。
* obj[*].name ,指属性obj是个集合,位置是所有元素。
* ["key"].name ,指map的key项。
* obj.aaa.~* .指属性obj的属性aa,如obj.aaa.~*:i/users,orgs/  

注意，不支持[1][2]这种连续方式
 


##Action
定义了一个匹配动作的输出，有以下几种

* i:表示忽略，如name:i 遇到name属性，忽略. ~*:i/age,bir/ 忽略类的属性age,bir，[1]:i 表示忽略第2项，[name]:i 表示忽略key为name的项 
* o:表示排序，如~*:o/name, age/ 。name和age属性总是排在最前面.其他属性按顺序排（内置的AttributeComparator完成属性排序，原始类型排在最前，其次是pojo类型，再次是java类型，最后是集合类型）
* u:表示使用类的属性，如~*:u/name,age,bir/。 其他属性忽略 
* cu:出现循环引用，仅仅显示参数指定的字段，如{~L/Department/*:ci/name,id/} ,对于Department类，如果被重复引用，则只显示name和id，其他字段不显示。
* ci:出现循环引用，不显示参数指定的字段，如{~L/Department/*:ci/users/} ,对于Department类，如果被重复引用，则不显示users字段。
* nn 表示更改名字，{nane:nn/myName/}  将输出myName
* ? 代表一个if，如果满足条件，则指定一个输出，如xxList:?null->[],如果某集合xxList 为null，则输出一个[]
，?后年可以指定null，empty，以及某个数字。->表示输出
* $.xxx，用于调用当前位置对象的某个方法，如{ts:$.get},并不是输出ts,而是输出ts.get(). 调用后，可以使用->在使用一个Action，比如：
"~L/java.util.Calendar*/:$.getTime->f/yyyy-MM-dd/" 遇到Calendar和其子类，先获取Date类型，然后格式化
* f 用于格式化输出，如number:f/#.##/,也可以自定义格式化函数并注册，比如注册一个格式化函数Money,
则number:fMoney 则会调用money做输出
* ->  直接输出 ，比如 name:->unkown.


 

##API例子:

    //全局设定，对于所有对象都适用
	JsonTool.addLocationAction("~d","f/yyyy.MM.dd/");	
	JsonTool.addLocationAction("~L/java.util.Calendar*/","$.getTime->f/yyyy-MM-dd/");
	//类json格式的策略，用逗号分开多个locationAction
    JsonTool.addPolicy("~f:f/#.##/,~c:?null->[]");
	// 默认是紧凑输出，使用true，将换行和缩进	
	JsonTool.pretty = true;
	//序列化User
	String json = JsonTool.serialize(User);
	//or  指定一个序列化策略,age，name先输出，适合有特殊需求的对象或者无法注解（第三方）对象
    String json2 = JsonTool.serialize(User，"~*:o/age,name/"));
    // 同上策略，但name属性输出改为code
 	String json2 = JsonTool.serialize(User，"~*:o/age,name/,name:nn/code/"));
	// 同上策略，像api传递俩个策略
 	String json2 = JsonTool.serialize(User，"~*:o/age,name/","name:nn/code/"));
 	//序列化dept,Department跟SysUser是一对多关系，如果俩个类都重复引用，则忽略导致重复引用的dept字段和users字段
	String json1 = JsonTool.serialize(dept, "~L/SysUser/:ci/dept/,~L/Department/:ci/users/");

## 注解
默认情况下，也可以用注解来作为序列化策略。

	@Json(
		policys={
				@JsonPolicy(location="name", action="nn/newUserName/"),
				@JsonPolicy(location="deleteList", action="?empty->[]")						
		}
	)
	public class User{	
		String name="joel";
		int age =12;	
		double salary=12.32266;
		Customer  customer = new Customer();
		List<Customer>  list = new ArrayList<Customer>();
		List<Customer>  deleteList = null;
		//getter and setter 	方法必须有，在此忽略
	}



	@Json(
		policys={
				@JsonPolicy(location="name", action="nn/userName/")			
		}
	)
	class Customer{
		String name="lijz";
		int age=11;
		Date bir = new Date();
		//getter and setter 	方法必须有，在此忽略
	}


## 主要api：

* JsonTool.addLocationAction(String loc,String action)   :增加一个全局的序列化策略，如JsonTool.addLocationAction("~d","f/yyyy.MM.dd/");	
* JsonTool.pretty:默认是紧凑输出，改为true，则有缩进和换行
* JsonTool.serialize(Object o) :序列化对象，返回String
* JsonTool.serialize(Object o,Writer w) :序列化对象到Writer里
* JsonTool.serialize(Object o,String policy) :序列化对象，返回String,并使用额外的序列化策略
* JsonTool.serialize(Object o,String... policy) :序列化对象，使用多个序列化策略
* JsonTool.serialize(Object o,Writer w,String policy) :序列化对象到Writer里,并使用额外的序列化策略
* JsonTool.serialize(Object o,Writer w,String... policy) :序列化对象到Writer里,使用多个序列化策略

更多例子参考单元测试代码 https://git.oschina.net/xiandafu/beetl-json/tree/master/test


## 下一步：

* spring集成，nutz，jfinal集成* 
* 性能优化，争取前三
* 反序列化，总体大小不超过100k。