RESTful Web Services -- JAX-RS中的注解

RESTful Web Services -- JAX-RS中的注解

1）javax.ws.rs包下的注解：

	javax.ws.rs.GET、javax.ws.rs.Post、javax.ws.rs.Consumes、javax.ws.rs.Produces、javax.ws.rs.Path

		@GET	表示(被@GET注解修饰的)方法将处理(响应)来自HTTP的GET请求
		@POST
		@PUT
		@DELETE
		@HEAD
	
		@Consumes：表示一个资源类或方法可以接受的MIME类型。
			说明：MIME类型可以有多个。
			举例：@Consumes({MediaType.MULTIPART_FORM_DATA, MediaType.APPLICATION_OCTET_STREAM, MediaType.TEXT_PLAIN})
			注意：MediaType的类型为javax.ws.rs.core.MediaType
			
		@Produces：表示一个资源类或方法可以返回的MIME类型。
			说明：可以同时返回多种类型，但具体生成结果时使用哪种格式取决于ContentType。CXF默认返回的是JSON字符串。
	
		@Path：用来标注资源类或方法的相对路径
			说明：value值可以包含文本字符、变量或具有定制正则表达式的变量。
			举例：@Path("/helloworld/{username}") 
			
	javax.ws.rs.PathParam、javax.ws.rs.QueryParam、javax.ws.rs.FormParam、javax.ws.rs.BeanParam、javax.ws.rs.core.Context
			
		@PathParam：标注方法的参数来自于请求的URL路径，参数的名称和@Path注解中定义的变量名对应
			举例：
				接口URL：/helloworld/xiaoning
				
				@POST
				@Path("/helloworld/{username}")
				public String hello((@PathParam("username")String username);
		
		@QueryParam：标注方法的参数来自于请求的URL的查询参数，即用来获取URL中的查询参数。
			举例：
				接口URL：/downloadExcel?fileId=77&username=xiaoning
				
				@GET
				@Path("/downloadExcel")
				@Consumes({"application/octet-stream"})
				@Produces("application/vnd.ms-excel")
				public Response downloadExcel(@QueryParam("fileId")Integer fileId ,@QueryParam("username")String username);
		
		@FormParam：用来获取POST请求中的表单参数，请求的MIME类型为"application/x-www-form-urlencoded"
			举例：
				接口URL：/getAccountInfo
				
				@POST
				@Path("/getAccountInfo")
				@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
				@Produces(MediaType.APPLICATION_JSON)
				public String getAccountInfo((@FormParam("username")String username);
		
		@BeanParam：自定义参数组合，BeanParam使得REST方法可以使用简洁的参数形式完成复杂的接口设计。
			说明：
				1>@BeanParam注解修饰的类是用来封装请求中的多个参数
				2>通过在@BeanParam注解修饰的类的属性上添加@FormParam、@QueryParam、@PathParam等注解来获取请求参数的值
			举例：
				接口URL：/getUserInfo

				@POST
				@Path("/getUserInfo")
				@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
				@Produces(MediaType.APPLICATION_JSON)
				public String getUserInfo(@BeanParam ReqGetUserInfoDTO req); 
	
				public class ReqGetAccountInfoByIdDTO {
					@FormParam("username")
					private String username;
					
					@FormParam("password")
					private String password;
				}

		@Context：用来获取上下文参数
			举例：
				接口URL：/uploadFile
			
				import javax.servlet.http.HttpServletRequest;
				import javax.ws.rs.core.UriInfo;
				import javax.ws.rs.core.HttpHeaders;
				
				@POST
				@Path("/uploadFile")
				@Consumes({MediaType.MULTIPART_FORM_DATA, MediaType.APPLICATION_OCTET_STREAM, MediaType.TEXT_PLAIN})
				@Produces(MediaType.APPLICATION_JSON)
				public String uploadFile(@Context final HttpServletRequest servletRequest, @Context final UriInfo uriInfo, @Context final HttpHeaders httpHeaders);
						
						
				接口URL：/exportPlanData 
				
				@GET
				@Path("/exportPlanData")
				public Response exportPlanData(@BeanParam ReqGetPlanRtDataDTO reqGetPlanRtDataDTO, @Context HttpServletResponse response);
				
				// 实现以流的方式导出数据：
				//	SXSSFWorkbook wb = new SXSSFWorkbook();
				//  SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
				//  String fileName = format.format(new Date()) + "_计划报表.xlsx";
				//  ServletOutputStream outputStream = response.getOutputStream();
				//  wb.write(outputStream);
				//  response.setHeader("content-disposition", "attachment;filename=" + URLEncoder.encode(fileName, "UTF-8"));
				//  response.setContentType("application/vnd.ms-excel");
				//  outputStream.close();
				//  return Response.status(Response.Status.OK).entity(null).build();

				
				
		@HeaderParam：用来获取HTTP请求的头信息
		
		@CookieParam：用来获取HTTP请求的Cookie信息

		@MatrixParam：用来从路径段中获取参数信息

		@PathVariable：是用来获得请求url中的动态参数
	
	说明：多个注解同时存在时，按照优先级来确定从哪里获取参数的值。	

	
	例子：
	
		前端REST接口测试request：
			company		"google"
			userList	{name:"jack",age:17}
			userList	{name:"jack2",age:18}
			userList	{name:"jack3",age:19}

			
		后端接口：
			@POST
			@Path("/getUserInfo")
			public Result getUserInfo(@BeanParam UserInfo req);
			

			import java.util.List;
			import javax.ws.rs.FormParam;
			
			public class UserInfo {

				@FormParam("company")
				private String company;

				@FormParam("userList")
				private List<User> userList;

				// setter and getter
			}

			public class User {

				private String name;
				private Long age;
				
				public User() {
				}
				
				/**
				 * 需要一个构造方法来实现json串到javaBean的转换，该构造方法的参数是一个字符串。
				 * @param paramStr
				 */
				public User(String paramStr) {
					// 将json串转换为javaBean
					JSONObject jsonObject = JSONObject.fromObject(paramStr);
					this.name = jsonObject.getString("name");
					this.age = Long.parseLong(jsonObject.getString("age"));
				}
				// setter and getter
			}

			

2）CFX中的注解：

	org.apache.cxf.jaxrs.ext.multipart.Multipart
	
		@Multipart：Annotate a JAX-RS function parameter to receive data from a multipart 'part'
		说明：
			import org.apache.cxf.jaxrs.ext.multipart.Attachment;
			
			@Consumes(MediaType.MULTIPART_FORM_DATA)
			public String uploadExcel(@Multipart(value="file")Attachment uploadFile, @Multipart(value="userId")Integer userId);