完善注释，增加许可信息

hsweb-web-controller/src/main/java/org/hsweb/web/controller/GenericController.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2015-2016 https://github.com/hs-web
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.hsweb.web.controller;
 
 import com.alibaba.fastjson.JSON;
@@ -16,23 +32,21 @@ import org.springframework.web.bind.annotation.*;
 import org.hsweb.commons.ClassUtils;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 
 /**
- * 通用Controller，使用RESTful和json进行数据提交及访问。
- * 如果要进行权限控制，可以在方法上注解{@link Authorize}
- * <br/>所有Controller应继承改类，并手动注解@Controller 以及@RequestMapping
- * <br/>json解析使用fastJson
- * Created by 浩 on 2015-07-28 0028.
+ * 通用控制器,此控制器实现了通用的增删改查功能
+ * 需要提供一个实现了{@link GenericService}接口的实现类
  */
 public abstract class GenericController<PO, PK> {
 
     protected Logger logger = LoggerFactory.getLogger(this.getClass());
 
     /**
-     * 获取此Controller 需要的服务类
+     * 获取此Controller需要的服务类,由子类实现
      *
-     * @return
+     * @return 通用服务类
      */
     protected abstract GenericService<PO, PK> getService();
 
@@ -57,8 +71,9 @@ public abstract class GenericController<PO, PK> {
     /**
      * 查询列表,并返回查询结果
      *
-     * @param param 查询参数
-     * @return 返回请求结果
+     * @param param 查询参数 {@link QueryParam}
+     * @return 查询结果, 如果参数指定了分页(默认指定)将返回格式如:{total:数据总数,data:[{}]}的数据.
+     * 否则返回格式[{}]
      */
     @RequestMapping(method = RequestMethod.GET)
     @AccessLogger("查询列表")
@@ -81,6 +96,7 @@ public abstract class GenericController<PO, PK> {
      *
      * @param id 主键
      * @return 请求结果
+     * @throws NotFoundException 要查询的数据不存在
      */
     @RequestMapping(value = "/{id}", method = RequestMethod.GET)
     @AccessLogger("查询明细")
@@ -88,7 +104,7 @@ public abstract class GenericController<PO, PK> {
     public ResponseMessage info(@PathVariable("id") PK id) {
         PO po = getService().selectByPk(id);
         if (po == null)
-            throw new BusinessException("data is not found!", 404);
+            throw new NotFoundException("data is not found!");
         return ResponseMessage.ok(po);
     }
 
@@ -108,16 +124,17 @@ public abstract class GenericController<PO, PK> {
     }
 
     /**
-     * 请求添加数据，请求必须以POST方式，必要参数为：json
+     * 请求添加数据，请求必须以POST方式
      *
-     * @param object 前端请求的对象
-     * @return 请求结果
+     * @param object 请求添加的对象
+     * @return 被添加数据的主键值
+     * @throws javax.validation.ValidationException 验证数据格式错误
      */
     @RequestMapping(method = RequestMethod.POST)
     @AccessLogger("新增")
     @Authorize(action = "C")
     @ResponseStatus(HttpStatus.CREATED)
-    public ResponseMessage add(@RequestBody PO object) {
+    public ResponseMessage add(@RequestBody(required = true) PO object) {
         PK pk = getService().insert(object);
         return ResponseMessage.created(pk);
     }
@@ -126,30 +143,33 @@ public abstract class GenericController<PO, PK> {
      * 请求删除指定id的数据，请求方式为DELETE，使用rest风格，如请求 /delete/1 ，将删除id为1的数据
      *
      * @param id 要删除的id标识
-     * @return 请求结果
+     * @return 删除结果
+     * @throws NotFoundException 要删除的数据不存在
      */
     @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
     @AccessLogger("删除")
     @Authorize(action = "D")
     public ResponseMessage delete(@PathVariable("id") PK id) {
         PO old = getService().selectByPk(id);
-        if (old == null) throw new NotFoundException("data is not found!");
-        int number = getService().delete(id);
-        return ResponseMessage.ok(number);
+        assertFound(old, "data is not found!");
+        getService().delete(id);
+        return ResponseMessage.ok();
     }
 
     /**
-     * 请求更新数据，请求必须以PUT方式
+     * 根据主键修改数据
      *
-     * @param object 前端请求的对象
+     * @param id     要修改数据的主键值
+     * @param object 要修改的数据
      * @return 请求结果
+     * @throws NotFoundException 要修改的数据不存在
      */
     @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
     @AccessLogger("修改")
     @Authorize(action = "U")
     public ResponseMessage update(@PathVariable("id") PK id, @RequestBody(required = true) PO object) {
         PO old = getService().selectByPk(id);
-        if (old == null) throw new NotFoundException("data is not found!");
+        assertFound(old, "data is not found!");
         if (object instanceof GenericPo) {
             ((GenericPo) object).setId(id);
         }
@@ -158,10 +178,11 @@ public abstract class GenericController<PO, PK> {
     }
 
     /**
-     * 请求更新数据，请求必须以PUT方式，必要参数为：json
+     * 批量修改数据.
      *
-     * @param json 前端请求的对象
-     * @return 请求结果
+     * @param json 请求修改的数据 json格式
+     * @return 被修改数据的条数
+     * @throws BusinessException 请求的数据格式错误
      */
     @RequestMapping(method = RequestMethod.PUT)
     @AccessLogger("批量修改")
@@ -169,16 +190,22 @@ public abstract class GenericController<PO, PK> {
     public ResponseMessage update(@RequestBody(required = true) String json) {
         int number;
         if (json.startsWith("[")) {
-            List<PO> datas = JSON.parseArray(json, getPOType());
-            number = getService().update(datas);
+            number = getService().update(JSON.parseArray(json, getPOType()));
         } else if (json.startsWith("{")) {
-            PO data = JSON.parseObject(json, getPOType());
-            List<PO> datas = new ArrayList<>();
-            datas.add(data);
-            number = getService().update(datas);
+            number = getService().update(Arrays.asList(JSON.parseObject(json, getPOType())));
         } else {
             throw new BusinessException("请求数据格式错误!");
         }
         return ResponseMessage.ok(number);
     }
+
+    /**
+     * 判断对象是否为空,如果为空将抛出 {@link NotFoundException}
+     *
+     * @param obj 要判断的对象
+     * @param msg 为null时异常消息
+     */
+    public void assertFound(Object obj, String msg) {
+        if (obj == null) throw new NotFoundException(msg);
+    }
 }