新增代金券接口&字段上的单行注释调整为文档多行注释

2015-03-29 22:45:50 +08:00
parent 5557141b93
commit 464359ae7a
155 changed files with 3825 additions and 591 deletions
@@ -118,3 +118,7 @@ weixin4j-qy
  + **weixin4j-qy-api**: 新增企业应用设置接口
  
  + **weixin4j-qy-server**: 新增deploy.xml远程部署ant脚本
+  
+* 2015-03-29
+
+  + **weixin4j-qy-api**: 单行注释调整为多行文档注释
@@ -20,6 +20,8 @@ weixin4j-qy-api
  * NotifyApi `消息发送API`
  
  * AgentApi `应用设置API`
+  
+  * BatchApi `批量操作API`

 如何使用
 --------
@@ -87,3 +89,7 @@ weixin.properties说明
 * 2015-03-17
  
  + 新增企业应用设置接口
+
+* 2015-03-29
+
+  + 单行注释调整为多行文档注释
@@ -36,6 +36,11 @@ public class NotifyApi extends QyApi {

 	/**
 	 * 发送消息(需要管理员对应用有使用权限，对收件人touser、toparty、totag有查看权限，否则本次调用失败)
+	 * <p>
+	 * 1） 发送人员列表存在错误的userid：执行发送，开发者需注意返回结果说明</br>
+	 * 2）发送人员不在通讯录权限范围内：不执行发送任务，返回首个出错的userid</br>
+	 * 3）发送人员不在应用可见范围内：不执行发送任务，返回首个出错的userid</br>
+	 * </p>
 	 * 
 	 * @param notify
 	 *            客服消息对象
@@ -32,13 +32,31 @@ public class NotifyMessage implements Serializable {
 	private static final long serialVersionUID = 1219589414293000383L;
 	private static final String SEPARATOR = "|";

-	private String touser;// UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
-	private String toparty;// PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
-	private String totag;// TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
-	private int agentid;// 企业应用的id，整型。可在应用的设置页面查看
-	private int safe;// 表示是否是保密消息，0表示否，1表示是，默认0
+	/**
+	 * UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
+	 */
+	private String touser;
+	/**
+	 * PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
+	 */
+	private String toparty;
+	/**
+	 * TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
+	 */
+	private String totag;
+	/**
+	 * 企业应用的id，整型。可在应用的设置页面查看
+	 */
+	private int agentid;
+	/**
+	 * 表示是否是保密消息，0表示否，1表示是，默认0
+	 */
+	private int safe;
+	/**
+	 * 消息对象
+	 */
 	@JSONField(name = "%s")
-	private Base box;// 消息项
+	private Base box;

 	public NotifyMessage(Base box, int agentid) {
 		this(null, null, null, box, agentid, false);
@@ -17,17 +17,35 @@ public class AgentInfo extends AgentSetter {

 	private static final long serialVersionUID = -8975132919768696174L;

+	/**
+	 * 企业应用方形头像
+	 */
 	@JSONField(name = "square_logo_url")
-	private String squareLogoUrl;// 企业应用方形头像
+	private String squareLogoUrl;
+	/**
+	 * 企业应用圆形头像
+	 */
 	@JSONField(name = "round_logo_url")
-	private String roundLogoUrl;// 企业应用圆形头像
+	private String roundLogoUrl;
+	/**
+	 * 企业应用可见范围（人员），其中包括userid和关注状态state
+	 */
 	@JSONField(serialize = false)
-	private List<User> allowUsers;// 企业应用可见范围（人员），其中包括userid和关注状态state
+	private List<User> allowUsers;
+	/**
+	 * 企业应用可见范围（部门）
+	 */
 	@JSONField(serialize = false)
-	private List<Integer> allowPartys; // 企业应用可见范围（部门）
+	private List<Integer> allowPartys;
+	/**
+	 * 企业应用可见范围（标签）
+	 */
 	@JSONField(serialize = false)
-	private List<Integer> allowTags; // 企业应用可见范围（标签）
-	private boolean close; // 企业应用是否被禁用
+	private List<Integer> allowTags;
+	/**
+	 * 企业应用是否被禁用
+	 */
+	private boolean close;

 	public AgentInfo() {
 		super(0);
@@ -18,19 +18,43 @@ import com.foxinmy.weixin4j.qy.type.ReportLocationType;
 public class AgentSetter implements Serializable {
 	private static final long serialVersionUID = 5420335232308079801L;

-	private int agentid; // 企业应用的id
+	/**
+	 * 企业应用的id
+	 */
+	private int agentid;
+	/**
+	 * 企业应用是否打开地理位置上报
+	 */
 	@JSONField(name = "report_location_flag")
-	private ReportLocationType reportLocationType; // 企业应用是否打开地理位置上报
+	private ReportLocationType reportLocationType;
+	/**
+	 * 企业应用头像的mediaid，通过多媒体接口上传图片获得mediaid，上传后会自动裁剪成方形和圆形两个头像
+	 */
 	@JSONField(name = "logo_mediaid")
-	private String logoMediaid; // 企业应用头像的mediaid，通过多媒体接口上传图片获得mediaid，上传后会自动裁剪成方形和圆形两个头像
-	private String name; // 企业应用名称
-	private String description; // 企业应用详情
+	private String logoMediaid;
+	/**
+	 * 企业应用名称
+	 */
+	private String name;
+	/**
+	 * 企业应用详情
+	 */
+	private String description;
+	/**
+	 * 企业应用可信域名
+	 */
 	@JSONField(name = "redirect_domain")
-	private String redirectDomain; // 企业应用可信域名
+	private String redirectDomain;
+	/**
+	 * 是否接收用户变更通知。0：不接收；1：接收
+	 */
 	@JSONField(name = "isreportuser")
-	private int isReportUser; // 是否接收用户变更通知。0：不接收；1：接收
+	private int isReportUser;
+	/**
+	 * 是否上报用户进入应用事件。0：不接收；1：接收
+	 */
 	@JSONField(name = "isreportenter")
-	private int isReportEnter; // 是否上报用户进入应用事件。0：不接收；1：接收
+	private int isReportEnter;

 	public AgentSetter(int agentid) {
 		this.agentid = agentid;
@@ -15,10 +15,22 @@ import java.io.Serializable;
 public class Department implements Serializable {

 	private static final long serialVersionUID = -2567893218591084288L;
-	private int id; // 部门ID
-	private String name; // 部门名称。长度限制为1~64个字符
-	private int parentid;// 父亲部门id。根部门id为1
-	private int order;// 在父部门中的次序。从1开始，数字越大排序越靠后
+	/**
+	 * 部门ID
+	 */
+	private int id;
+	/**
+	 * 部门名称。长度限制为1~64个字符
+	 */
+	private String name;
+	/**
+	 * 父亲部门id。根部门id为1
+	 */
+	private int parentid;
+	/**
+	 * 在父部门中的次序。从1开始，数字越大排序越靠后
+	 */
+	private int order;

 	public Department() {

@@ -2,6 +2,14 @@ package com.foxinmy.weixin4j.qy.model;

 import java.io.Serializable;

+/**
+ * name-value
+ * @className NameValue
+ * @author jy
+ * @date 2015年3月29日
+ * @since JDK 1.7
+ * @see
+ */
 public class NameValue implements Serializable {

 	private static final long serialVersionUID = -348620146718819093L;
@@ -17,8 +17,14 @@ public class Tag implements Serializable {

 	private static final long serialVersionUID = 5204620476267654921L;

+	/**
+	 * 标签ID
+	 */
 	@JSONField(name = "tagid")
 	private int id;
+	/**
+	 * 标签名称
+	 */
 	@JSONField(name = "tagname")
 	private String name;

@@ -22,18 +22,54 @@ import com.foxinmy.weixin4j.qy.type.UserStatus;
 public class User implements Serializable {

 	private static final long serialVersionUID = 4747301605060801611L;
-	private String userid;// 是 员工UserID。对应管理端的帐号，企业内必须唯一。长度为1~64个字符
-	private String name;// 是 成员名称。长度为1~64个字符
-	private List<Integer> department;// 否 成员所属部门id列表。注意，每个部门的直属员工上限为1000个
-	private String position;// 否 职位信息。长度为0~64个字符
-	private String mobile;// 否 手机号码。企业内必须唯一，mobile/weixinid/email三者不能同时为空
-	private int gender;// 否 性别。gender=0表示男，=1表示女。默认gender=0
-	private String tel;// 否 办公电话。长度为0~64个字符
-	private String email;// 否 邮箱。长度为0~64个字符。企业内必须唯一
-	private String weixinid;// 否 微信号。企业内必须唯一
-	private String avatar;// 头像url。注：如果要获取小图将url最后的"/0"改成"/64"即可
-	private int status;// 关注状态: 1=已关注，2=已冻结，4=未关注
-	private List<NameValue> extattr;// 否 扩展属性。扩展属性需要在WEB管理端创建后才生效，否则忽略未知属性的赋值
+	/**
+	 * 必须 员工UserID。对应管理端的帐号，企业内必须唯一。长度为1~64个字符
+	 */
+	private String userid;
+	/**
+	 * 必须 成员名称。长度为1~64个字符
+	 */
+	private String name;
+	/**
+	 * 非必须 成员所属部门id列表。注意，每个部门的直属员工上限为1000个
+	 */
+	private List<Integer> department;
+	/**
+	 * 非必须 职位信息。长度为0~64个字符
+	 */
+	private String position;
+	/**
+	 * 非必须 手机号码。企业内必须唯一，mobile/weixinid/email三者不能同时为空
+	 */
+	private String mobile;
+	/**
+	 * 非必须 性别。gender=0表示男，=1表示女。默认gender=0
+	 */
+	private int gender;
+	/**
+	 * 非必须 办公电话。长度为0~64个字符
+	 */
+	private String tel;
+	/**
+	 * 非必须 邮箱。长度为0~64个字符。企业内必须唯一
+	 */
+	private String email;
+	/**
+	 * 非必须 微信号。企业内必须唯一
+	 */
+	private String weixinid;
+	/**
+	 * 头像url。注：如果要获取小图将url最后的"/0"改成"/64"即可
+	 */
+	private String avatar;
+	/**
+	 * 关注状态: 1=已关注，2=已冻结，4=未关注
+	 */
+	private int status;
+	/**
+	 * 非必须 扩展属性。扩展属性需要在WEB管理端创建后才生效，否则忽略未知属性的赋值
+	 */
+	private List<NameValue> extattr;

 	public User() {
 		this.extattr = new ArrayList<NameValue>();
@@ -47,10 +83,15 @@ public class User implements Serializable {
 	 * mobile/weixinid/email三者不能同时为空
 	 * 
 	 * @param userid
+	 *            用户ID
 	 * @param name
+	 *            用户昵称
 	 * @param tel
+	 *            号码
 	 * @param email
+	 *            邮箱
 	 * @param weixinid
+	 *            微信ID
 	 */
 	public User(String userid, String name, String tel, String email,
 			String weixinid) {
@@ -2,6 +2,7 @@ package com.foxinmy.weixin4j.qy.type;

 /**
 * 邀请类型
+ * 
 * @className InviteType
 * @author jy
 * @date 2015年1月15日
@@ -9,5 +10,12 @@ package com.foxinmy.weixin4j.qy.type;
 * @see
 */
 public enum InviteType {
-	WEIXIN, EMAIL
+	/**
+	 * 微信邀请
+	 */
+	WEIXIN,
+	/**
+	 * 邮件邀请
+	 */
+	EMAIL
 }
@@ -2,6 +2,7 @@ package com.foxinmy.weixin4j.qy.type;

 /**
 * 上报策略
+ * 
 * @className ReportLocationType
 * @author jy
 * @date 2015年3月16日
@@ -9,7 +10,16 @@ package com.foxinmy.weixin4j.qy.type;
 * @see
 */
 public enum ReportLocationType {
-	NOT, // 不上报
-	DIALOG, // 进入回话上报
-	PERSIST; // 持续上报
+	/**
+	 * 不上报
+	 */
+	NOT,
+	/**
+	 * 进入回话上报
+	 */
+	DIALOG,
+	/**
+	 * 持续上报
+	 */
+	PERSIST;
 }
@@ -10,10 +10,22 @@ package com.foxinmy.weixin4j.qy.type;
 * @see
 */
 public enum UserStatus {
-	BOTH(0), // 0=全部
-	FOLLOW(1), // 1=已关注
-	FROZEN(2), // 2=已冻结
-	UNFOLLOW(4);// 4=未关注
+	/**
+	 * 0=全部
+	 */
+	BOTH(0),
+	/**
+	 * 1=已关注
+	 */
+	FOLLOW(1),
+	/**
+	 * 2=已冻结
+	 */
+	FROZEN(2),
+	/**
+	 * 4=未关注
+	 */
+	UNFOLLOW(4);
 	private int val;

 	UserStatus(int val) {
@@ -45,7 +45,7 @@ weixin4j-qy-server

 > 1.服务的启动脚本[startup.sh](./src/main/startup.sh)需要被注意到,有`JAVA_HOME`和`APP_HOME`两个参数.
 
- > 2.其中`JAVA_HOME`参数值指的是java运行环境(jre|jdk)的安装根目录,如果与脚本中的值不一致,可以改更为实际的路径或者使用`ln -s target /usr/local/java`软链接命令创建期望的链接.
+ > 2.其中`JAVA_HOME`参数值指的是java运行环境(jre|jdk)的安装根目录,如果与脚本中的值不一致,可以改更为实际的路径或者使用`ln -s /usr/local/java target`软链接命令创建期望的链接.
 
 > 3.其中`APP_HOME`参数值指的是本服务的启动目录,此目录需要被正确事先创建好,同时[`deploy.xml`](./deploy.xml)远程部署命令也依赖于此.
 
@@ -69,6 +69,6 @@ weixin4j-qy-server
  
  + 调整回调模式下的首次验证的签名方式
  
- * 2015-03-25
+* 2015-03-25
 
  + 新增deploy.xml远程部署ant脚本