JAX-RS入門 四： 注入

一、Annotations

• @javax.ws.rs.PathParam： 從URI模板參數中提取數據
• @javax.ws.rs.MatrixParam：從URI中提取Matrix參數
• @javax.ws.rs.QueryParam：從URI中提取查詢參數
• @javax.ws.rs.FormParam：提取Post Form參數
• @javax.ws.rs.HeaderParam：提取HTTP請求頭信息
• @javax.ws.rs.CookieParam：提取客戶設置的cookie的信息
• @javax.ws.rs.core.Context：通用的注入annotation，允許注入各種幫助或者信息對象

通常這些註釋用在服務方法上，當JAX-RS收到一個請求會，就會去查找相應的服務方法，然後把方法需要的信息注入。

 

如果是 “每個請求一個對象”的模式，你可以將這些annotation用在變量、set方法或者是構造方法上；如果是單態模式，則不允許將這些annotation用在變量、或者set方法上，因爲對像會同時處理多個請求，如果將這些值用在變量或者set方法上，則多個請求會彼此衝突，陷入錯誤。

 

二、PathParam

public class CustomerResource {
	...
	@Path("{id}")
	@GET
	@Produces("application/xml")
	public StreamingOutput getCustomer(@PathParam("id") int id) {
		...
	}
}

 

此處，取得{id}的值，並試圖轉換成一個int型的值。

 

可以同時使用多個PathParam:

@Path("/customers")
public class CustomerResource {
	...
	@Path("{first}-{last}")
	@GET
	@Produces("application/xml")
	public StreamingOutput getCustomer(@PathParam("first") String firstName,
		@PathParam("last") String lastName) {
		...
	}
}

 

PathParam的範圍：總是引用最接近的PathParam的值，例如：

@Path("/customers/{id}")
public class CustomerResource {
	@Path("/address/{id}")
	@Produces("text/plain")
	@GET
	public String getAddress(@PathParam("id") String addressId) {...}
}

 

例如HTTP請求爲：GET /customers/123/address/456 , 則 addressId 的值爲456.

注入PathSegment

PathParam除了可以注入Path參數，也可以注入一個javax.ws.rs.core.PathSegment實便；PathSegment是一個特定Path片段的抽象，如下：

package javax.ws.rs.core;
public interface PathSegment {
	String getPath();   //具體的URI的path片段值，去除了所有的matrix參數
	MultivaluedMap<String, String> getMatrixParameters();  //該path片段擁有的所有的matrix值
}

然後如下使用：

@Path("/cars/{make}")
public class CarResource {
	@GET
	@Path("/{model}/{year}")
	@Produces("image/jpeg")
	public Jpeg getPicture(@PathParam("make") String make,
	@PathParam("model") PathSegment car,
	@PathParam("year") String year) {
		String carColor = car.getMatrixParameters().getFirst("color");
		...
	}
}

例如：GET /cars/mercedes/e55;color=black/2006。則 make是mercedes；model是e55；year是2006；color是black。

注入多個PathSegment

如果對對應有Path含有多個path片段，則需要注入多個PathSegments類，例如：

@Path("/cars/{make}")
public class CarResource {
	@GET
	@Path("/{model : .+}/year/{year}")
	@Produces("image/jpeg")
	public Jpeg getPicture(@PathParam("make") String make,
		@PathParam("model") List<PathSegment> car,
		@PathParam("year") String year) {
	}
}

其中請求可能是：GET /cars/mercedes/e55/amg/year/2006。這裏model對應的path片段爲：/e55/amg。所以car變量中含有兩個PathSegment對象。

用代碼獲取URI的信息

有時候可能想通過程序的方式獲取URI中的信息，而不使用PathParam註釋。這裏我們需要通過接口javax.ws.rs.core.UriInfo接口去獲取這些信息，UriInfo接口定義如下：

public interface UriInfo {
	public String getPath();  //返回匹配的相對uri路徑
	public String getPath(boolean decode); //返回解碼後的相對uri路徑
	public List<PathSegment> getPathSegments();  //返回path片段
	public List<PathSegment> getPathSegments(boolean decode); //返回解碼後的path片段
	public MultivaluedMap<String, String> getPathParameters(); //返回PathParam表
	public MultivaluedMap<String, String> getPathParameters(boolean decode); //同上
	...
}

要獲取UriInfo對象，就需要用到@javax.ws.rs.core.Context註釋了。例如：

@Path("/cars/{make}")
public class CarResource {
	@GET
	@Path("/{model}/{year}")
	@Produces("image/jpeg")
	public Jpeg getPicture(@Context UriInfo info) {
		String make = info.getPathParameters().getFirst("make");
		PathSegment model = info.getPathSegments().get(1);
		String color = model.getMatrixParameters().getFirst("color");
		...
	}
}

 

三、MatrixParam

 

除了上面介紹的使用PathSegment去獲取MatrixParam值外，我們也可以直接使用@MatrixParam去獲取值，這樣來得更直接、簡潔，例如：

@Path("/{make}")
public class CarResource {
	@GET
	@Path("/{model}/{year}")
	@Produces("image/jpeg")
	public Jpeg getPicture(@PathParam("make") String make,
		@PathParam("model") String model,
		@MatrixParam("color") String color) {
		...
	}
}

不過如果Path中含有多個同名的MatrixParam，則還是需要使用PathSegment來獲取，例如：GET /mercedes/e55;color=black/2006/interior;color=tan

四、@QueryParam

很顯然，QueryParam用來獲取查詢參數，對於 GET /customers?start=0&size=10 ，例如：

@Path("/customers")
public class CustomerResource {
	@GET
	@Produces("application/xml")
	public String getCustomers(@QueryParam("start") int start,
		@QueryParam("size") int size) {
		...
	}
}

這裏start爲0，size爲10.

同上面的PathParam，也可以用UriInfo去獲取QueryParam，例如：

@Path("/customers")
public class CustomerResource {
	@GET
	@Produces("application/xml")
	public String getCustomers(@Context UriInfo info) {
		String start = info.getQueryParameters().getFirst("start");
		String size = info.getQueryParameters().getFirst("size");
		...
	}
}

 

五、@FormParam

 

很自然，FormParam用於提取POST請求中的Form參數，其中Content-Type被假設爲application/x-www-formurlencoded。例如有以下Form請求

<FORM action="http://example.com/customers" method="post">
	<P>
		First name: <INPUT type="text" name="firstname"><BR>
		Last name: <INPUT type="text" name="lastname"><BR>
		<INPUT type="submit" value="Send">
	</P>
</FORM>

可以如下取值：

@Path("/customers")
public class CustomerResource {
	@POST
	public void createCustomer(@FormParam("firstname") String first,
		@FormParam("lastname") String last) {
			...
	}
}

 

六、HeaderParam

很直接，用來提取HTTP Header值的。例如：

@Path("/myservice")
public class MyService {
	@GET
	@Produces("text/html")
	public String get(@HeaderParam("Referer") String referer) {
		...
	}
}

如果想提取所有的header值，那就需要用到javax.ws.rs.core.HttpHeaders接口了：

public interface HttpHeaders {
public List<String> getRequestHeader(String name);
	public MultivaluedMap<String, String> getRequestHeaders();
	...
}

例如方法同上面的PathSegment，也是用context去獲取，例如：

@Path("/myservice")
public class MyService {
	@GET
	@Produces("text/html")
	public String get(@Context HttpHeaders headers) {
		String referer = headers.getRequestHeader("Referer").get(0);
		for (String header : headers.getRequestHeaders().keySet())
		{
			System.out.println("This header was set: " + header);
		}
		...
	}
}

 

七、@CookieParam

提取cookie信息，例如：

@Path("/myservice")
public class MyService {
	@GET
	@Produces("text/html")
	public String get(@CookieParam("customerId") int custId) {
		...
	}
}

 

這裏注入了的是一個cookie的值，如果想取得更多的信息，而不公公是基本值，則可以直接注入javax.ws.rs.core.Cookie對象，例如：

@Path("/myservice")
public class MyService {
	@GET
	@Produces("text/html")
	public String get(@CookieParam("customerId") Cookie custId) {
		...
	}
} 

Cookie類具有一些其他的方法可以用來獲取更多信息，例如：

package javax.ws.rs.core;
public class Cookie
{
	public String getName() {...}
	public String getValue() {...}
	public int getVersion() {...}
	public String getDomain() {...}
	public String getPath() {...}
	...
}

也可以用javax.ws.rs.core.HttpHeaders獲取所有的cookie：

public interface HttpHeaders {
	...
	public Map<String, Cookie> getCookies();
}

 

@Path("/myservice")
public class MyService {
	@GET
	@Produces("text/html")
	public String get(@Context HttpHeaders headers) {
		for (String name : headers.getCookies().keySet())
		{
			Cookie cookie = headers.getCookies().get(name);
			System.out.println("Cookie: " +
				name + "=" + cookie.getValue());
		}
		...
	}
}