Web 服務 meta 資料註釋 (JSR 181)

利用 JSR 181 規格中的註釋,您可以標註 Web 服務實作類別或 Web 服務介面。然後您可以使用精靈或將應用程式發佈至伺服器,來產生 Web 服務。

註: 含有 JSR 181 標準中之每一項註釋的 Java™ 類別會命名為 javax.jws.xxx,其中 xxx 是 '@' 字元後的註釋名稱。例如,對應至 @WebService 的 Java 類別名稱是 javax.jws.webservice。
名稱: 說明: 內容: 定義:
@WebService 此註釋會將 Java 類別或服務端點介面 (SEI) 標示成實作 Web 服務介面。

此註釋中有三個內容只能與 JavaBeans 端點的服務端點實作類別搭配使用。這些內容分別是 serviceName、portName 和 endpointInterface。

如果註釋透過 endpointInterface 屬性來參照 SEI,則 SEI 也要有 @WebService 註釋。

依預設,如果類別指定了 @WebService 註釋,則其所有的公用方法都會顯露在 Web 服務中。

  • 註釋目標:類型
  • 內容:
    name
    wsdl:portType 的名稱。name 內容會對映至 SEI 或 Java 實作類別。預設值是不完整的 Java 介面或類別名稱。(字串)
    targetNamespace
    指定從 Web 服務產生之 WSDL 和 XML 元素的 XML 名稱空間。
    • 如果 @WebService.targetNamespace 註釋位於服務端點介面中,targetNamespace 會用於 wsdl:portType(和相關聯 XML 元素)的名稱空間。
    • 如果 @WebService.targetNamespace 註釋位於服務實作 Bean 中,且該實作 Bean 不會參照服務端點介面 (透過 endpointInterface 註釋元素),則 targetNamespace 會同時用於 wsdl:portType 和 wsdl:service(及相關聯的 XML 元素)。
    • 如果 @WebService.targetNamespace 註釋位於服務實作 Bean 中,且該實作 Bean 會參照服務端點介面 (透過 endpointInterface 註釋元素),則 targetNamespace 只會用於 wsdl:service(及相關聯的 XML 元素)。

    預設值是從套件名稱(包含 Web 服務)對映的名稱空間。(字串)

    serviceName
    指定 Web 服務的服務名稱:wsdl:service。端點介面中不容許使用這個內容。預設值是 Java 類別簡稱 + Service。(字串)
    endpointInterface
    指定定義服務之抽象 Web 服務合約的服務端點介面完整名稱。若有指定,會使用該服務端點介面來決定抽象 WSDL 合約。(字串)
    portName
    wsdl:portName。portName 內容是端點埠的名稱。預設值是 WebService.name +Port。(字串)
    wsdlLocation
    指定定義了 Web 服務之 WSDL 文件的網址。網址可以是相對或絕對。(字串)
@Retention(value = RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface WebService{
	String name() default “”;
	String targetNamespace() default “”;
	String serviceName() default “”';
	String wsdlLocation() default “”;
	String endpointInterface() default “”;
	String portName() default “”;
};
@WebMethod 此註釋用來表示方法,而該方法是一項 Web 服務作業。

您可以將此註釋套用至用戶端或伺服器之「服務端點介面 (SEI)」中的公用方法,或 JavaBeans 端點之服務端點實作類別中的公用方法。

只有具有 @WebService 註釋的類別中,才支援 @WebMethod 註釋。

  • 註釋目標:方法
  • 內容:
    operationName
    指定符合此方法之 wsdl:operation 的名稱。預設值是 Java 方法的名稱。(字串)
    action
    定義此作業的動作。若為 SOAP 連結,此值會決定 SOAPAction 標頭的值。(字串)
    exclude
    指定是否在 Web 服務中排除方法。這個內容只能與實作類別搭配使用。用來阻止將繼承方法顯露成這項 Web 服務的一部分。如果指定這個元素,就不得為 @WebMethod 指定其他元素。端點介面中不容許使用這個內容。

    預設值是 false。(布林)

@Retention(value = RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface WebMethod{
	String operationName() default “”;
	String action() default “”;
	boolean exclude() default false;
};
@Oneway 此註釋用來將方法表示成 Web 服務的單向作業。它有輸入訊息,但沒有輸出訊息。此註釋只能用於沒有回覆值的方法上。

您可以將此註釋套用至用戶端或伺服器之「服務端點介面 (SEI)」中的公用方法,或 JavaBeans 端點之服務端點實作類別中的公用方法。

  • 註釋目標:方法
  • OneWay 註釋中沒有內容。
@Retention(value = RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface OneWay{
};
@WebParam 此註釋用來自訂個別參數至 Web 服務訊息組件和 XML 元素的對映。

您可以將此註釋套用至用戶端或伺服器之「服務端點介面 (SEI)」中的公用方法,或 JavaBeans 端點之服務端點實作類別中的公用方法。

  • 註釋目標:參數
  • 內容:
    name
    如果該作業是遠端程序呼叫 (RPC) 樣式,且沒有指定 partName 屬性,則這是代表該參數之 wsdl:part 屬性的名稱。如果該作業是文件樣式,或者參數會對映至標頭,則 name 是代表該參數之 XML 元素的本端名稱。如果該作業是文件樣式,參數樣式是 BARE,模式是 OUT 或 INOUT,則需要這個屬性。如果指定 partName 屬性,則會忽略 name 屬性。(字串)
    partName
    定義代表這個參數之 wsdl:part 屬性的名稱。只有在該作業是 RPC 樣式,或者該作業是文件樣式,且參數樣式是 BARE 時,才會使用此項。(字串)
    targetNamespace
    指定該參數之 XML 元素的 XML 名稱空間。當屬性會對映至 XML 元素時,它只適用於文件連結。預設值是 Web 服務的 targetNamespace。(字串)
    mode
    此值代表此方法的參數流程方向。有效值是 IN、INOUT 和 OUT。(字串)
    header
    指定該參數是否位於訊息標頭中,而不是訊息內文中。預設值是 false。(布林)
@Retention(value = RetentionPolicy.RUNTIME)
@Target({PARAMETER})
public @interface WebParam{
	public enum Mode{
		IN,
		OUT,
		INOUT
	};
	String name() default “”;
	String partName() default "";
	String targetNamespace() default “”;
	Mode mode() default Mode.IN
	boolean header() default false;
};
@WebResult 此註釋用來自訂如何將回覆值對映至 WSDL 組件或 XML 元素。

您可以將此註釋套用至用戶端或伺服器之「服務端點介面 (SEI)」中的公用方法,或 JavaBeans 端點之服務端點實作類別中的公用方法。

  • 註釋目標:方法
  • 內容:
    name
    指定 WSDL 檔所列出及在網路訊息中找到之回覆值的名稱。若為 RPC 連結,這是代表回覆值之 wsdl:part 屬性的名稱。若為文件連結,name 參數是代表回覆值之 XML 元素的本端名稱。若為 RPC 和 DOCUMENT/WRAPPED 連結,預設值是 return。若為 DOCUMENT/BARE 連結,預設值是方法名稱 + Response。(字串)
    targetNamespace
    指定回覆值的 XML 名稱空間。當回覆值會對映至 XML 元素時,此註釋只能用於文件連結。預設值是 Web 服務的 targetNamespace。(字串)
    header
    指定標頭中是否附帶結果。預設值是 false。(字串)
    partName
    指定含有 RPC 或 DOCUMENT/BARE 作業之結果的組件名稱。預設值是 @WebResult.name。(布林)
@Retention(value = RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface WebResult{
	String name() default “return”;
	String targetNamespace default() “”;
	boolean header() default false;	
	String partName() default "";
};
@HandlerChain 此註釋會使 Web 服務與外部定義的處理程式鏈產生關聯。如果該處理程式配置必須供多項 Web 服務共用,且應用程式原始檔中內含的處理程式配置效用不佳,您可以使用這項註釋。

此註釋可套用至用戶端或伺服器的「服務端點介面 (SEI)」,或套用至 JavaBeans 端點的服務端點實作類別。

  • 註釋目標:類型
  • 內容:
    file
    指定處理程式鏈檔案的位置。檔案位置可以是外部表單中的絕對 java.net.URL,或是原始檔或類別檔中的相對路徑。(字串)
    name
    指定配置檔中的處理程式鏈名稱。(字串)
@Retention(value = RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface HandlerChain{
	String file();
	String name();
};
@SOAPBinding 此註釋指定 Web 服務至 SOAP 訊息通訊協定的對映。

您可以將此註釋套用至用戶端或伺服器之「服務端點介面 (SEI)」中的類型或公用方法,或 Java Bean 端點之服務端點實作類別中的類型或公用方法。

方法層次的註釋受它所能指定的內容限制。style 內容的值必須是 DOCUMENT,才會使用此註釋。如果沒有指定方法層次的註釋,會使用類型中的 @SOAPBinding 行為。

  • 註釋目標:類型或方法
  • 內容:
    style
    定義與 Web 服務間之往來訊息的編碼樣式。有效值是 DOCUMENT 和 RPC。預設值是 DOCUMENT。(字串)
    use
    定義與 Web 服務間之往來訊息所用的編碼。預設值是 LITERAL。不支援值 ENCODED。(字串)
    parameterStyle
    決定方法的參數是否代表整個訊息內文,或者參數是否為封裝在最上層元素(以作業命名)內的元素。有效值是 WRAPPED 或 BARE。BARE 值可與 DOCUMENT 樣式連結搭配使用。預設值是 WRAPPED。(字串)
@Retention(value = RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface SOAPBinding{
	public enum Style{
		DOCUMENT,
		RPC
	};
	public enum Use{
		LITERAL,
	};
	public enum ParameterStyle{
		BARE,
		WRAPPED
	};
	Style style() default Style.DOCUMENT
	Use use() default Use.LITERAL
	ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;
};
Icon that indicates the type of topic Reference topic
Timestamp icon Last updated: last_date

File name: rwsandoc003.html