概覽
CXF frontends 是一組編程的API看铆,被用來開發(fā)和發(fā)布webservice沾瓦。CXF支持兩種類型的frontend--JAX-WS和簡單frontend褥伴。這章將對JAX-WS frontend提供更加詳細的解釋返吻。我們同樣也會展示如何使用簡單frontend API來構(gòu)建一個webservice萧恕。這個章節(jié)將會關(guān)注使用如下兩種frontend來開發(fā)基于SOAP的web服務(wù):
- JAX-WS frontend
- 簡單 frontend
關(guān)于JAX-WS frontend刚梭,我們將說明如下內(nèi)容:
- 使用編碼優(yōu)先的開發(fā)方式來開發(fā)webservice
- 使用契約優(yōu)先的開發(fā)方式來開發(fā)webservice
- 構(gòu)建一個動態(tài)客戶端或消費者
- 基于Provider and Dispatch的實現(xiàn)
- 理解webservice上下文
JAX-WS frontend
CXF支持由Java Community Process(JCP)提供的JAX-WS 2.0 API 規(guī)范肠阱。JAX-WS是一個由JCP制訂的正式規(guī)范,它定義了API用來構(gòu)建朴读,開發(fā)和部署webservice屹徘。CXF提供了它自己的JAX-WS實現(xiàn)來附加在JAX-WS標準規(guī)范上。CXF JAX-WS frontend為構(gòu)建不同種類的webservice提供了不公的API衅金。拋開提供標準的基于WSDL的開發(fā)不講噪伊,它還在Provider and Dispatch接口的形式中提供了用于構(gòu)建基于XML服務(wù)的API。
有兩種方式來開發(fā)基于SOAP的JAX-WS webservice-編碼優(yōu)先和契約優(yōu)先氮唯。正如名字顯示的那樣鉴吹,在編碼優(yōu)先的開發(fā)模式中,你將從編碼開始惩琉,然后將它轉(zhuǎn)化成WSDL豆励。編碼優(yōu)先的開發(fā)方式適用于:在實現(xiàn)方法的輸入和輸出的對象格式較簡單時,并且你想要將它們快速地暴露為webservice的時候瞒渠。編碼優(yōu)先的開發(fā)方式是更簡單的良蒸,因為你將從Java對象開始,而不必考慮如何生成WSDL和XSD在孝,而這個過程會在Java對象無法被按照你的意愿映射到XML元素的時候?qū)е乱恍﹩栴}诚啃。注意,像CXF Java2WSDL 這樣基于實現(xiàn)方法的輸入輸出格式的工具私沮,將會生成契約始赎,包括為你生成XSD格式。比如仔燕,你不能暴露一個Map或者Collection作為一個輸出信息格式造垛,因為沒有標準的做法將它映射到XML schema,而這將會導致交互上的問題晰搀。
在契約優(yōu)先的開發(fā)方式中五辽,開發(fā)者從一個已經(jīng)存在的WSDL artifact來構(gòu)建webservice。契約優(yōu)先的開發(fā)方式適用于:當你已經(jīng)有了一個XML schema為webservice的操作定義了輸入輸出消息的格式的時候外恕,或者想要更好的控制XML如何被映射到Java對象的時候杆逗。契約優(yōu)先的開發(fā)方式需要你很精通XSD和WSDL契約,因為你將使用這些契約開始創(chuàng)建你的model鳞疲。如果你在創(chuàng)建基于工業(yè)標準的服務(wù)罪郊,你或許需要從契約優(yōu)先的開發(fā)方式開始,因為工業(yè)消息的格式通常是XML schema的尚洽。
如果兩種方式你都熟悉悔橄,并且知道對象是如何映射到XML的,你可以使用編碼優(yōu)先的開發(fā)方式。CXF不僅支持這些開發(fā)方式癣疟,而且為多種數(shù)據(jù)綁定機制提供了支持挣柬,這些機制將幫助你把Java對象映射到XML。
我們將從編碼優(yōu)先的開發(fā)方式開始睛挚。
編碼優(yōu)先的開發(fā)方式
在這個部分邪蛔,我們將以開發(fā)一個Java類,并且通過注解它將它轉(zhuǎn)化成一個service類開始竞川。你將遵循如下的步驟完成webservice的開發(fā):
- 創(chuàng)建Service Endpoint Interface(SEI)
- 添加Java注解
- 發(fā)布服務(wù)
- 開發(fā)一個消費者
- 運行編碼優(yōu)先的例子
創(chuàng)建Service Endpoint Interface(SEI)
Service Endpoint Interface是一個Java接口店溢,它定義了一個被用來暴露為服務(wù)的業(yè)務(wù)方法。這個服務(wù)方法被一個服務(wù)類實現(xiàn)委乌。一個SEI可以通過兩種不同的方式來構(gòu)建:
- 從零構(gòu)建一個SEI組件
- 將存在的業(yè)務(wù)功能轉(zhuǎn)化成基于服務(wù)的組件
第一個方式--從零構(gòu)建一個SEI組件的方式是指床牧,開發(fā)一個全新的webservice而不依賴于任何已經(jīng)存在的代碼或WSDL契約。它推薦你從寫服務(wù)接口開始遭贸,然后創(chuàng)建這個服務(wù)的實現(xiàn)類戈咳。寫服務(wù)接口總是好的實踐,因為它為你的服務(wù)方法提供了一個適當?shù)目蛻舳艘晥D壕吹。之后著蛙,實現(xiàn)類可以實現(xiàn)定義在接口中的方法。
第二個方式是指耳贬,拿到已經(jīng)存在的業(yè)務(wù)功能踏堡,然后把它轉(zhuǎn)化成基于服務(wù)的組件。大多數(shù)時候咒劲,你已經(jīng)開發(fā)過了業(yè)務(wù)邏輯顷蟆,你只是想把它們作為服務(wù)方法暴露出去。你可以通過如下的方式來完成這個過程:開發(fā)一個SEI腐魂,并只定義那些你想要暴露成為一個服務(wù)方法的業(yè)務(wù)方法帐偎,然后使已經(jīng)存在的Java代碼實現(xiàn)那個SEI。另一個常用的方式是:創(chuàng)建包裝后的SEI和一個實現(xiàn)類蛔屹,這個實現(xiàn)類可以使用已經(jīng)存在的實現(xiàn)類來完成自己的功能削樊。
我們將從零創(chuàng)建一個SEI組件開始。我們開發(fā)一個OrderProcess
SEI并且實現(xiàn)它兔毒。下面的代碼顯示了這個OrderProcess
SEI:
package demo.order;
public interface OrderProcess {
String processOrder(Order order);
}
你可以看到漫贞,上面的代碼是一個簡單的POJO接口。它定義了一個抽象方法processOrder
育叁,它接收一個Order
bean作為一個參數(shù)绕辖。OrderProcessImpl
實現(xiàn)類實現(xiàn)了processOrder
方法,并且這個方法將在之后作為一個webservice方法暴露出來擂红。
我們接下來將實現(xiàn)這個接口的業(yè)務(wù)邏輯。你將要寫這個OrderProcessImpl
來實現(xiàn)OrderProcess
SEI。下面的代碼顯示這個OrderProcessImpl
類:
package demo.order;
public class OrderProcessImpl implements OrderProcess {
public String processOrder(Order order) {
System.out.println("Processing order...");
String orderID = validate(order);
return orderID;
}
}
上面的代碼是一個簡單的POJO實現(xiàn)類昵骤,它實現(xiàn)類processOrder
方法树碱。這個方法簡單地校驗了訂單,并返回一個唯一的訂單ID变秦。簡單起見成榜,我們返回了一個靜態(tài)的訂單ID作為我們實現(xiàn)的一部分。在下一個部分蹦玫,我們將通過注解它們的方式把SEI和實現(xiàn)類轉(zhuǎn)化成為webservice組件赎婚。
添加Java注解
Webservice注解被添加到一個Java類用來將其暴露成為一個服務(wù)組件。JAX-WS使用Java 5注解樱溉,它是Web Services Metadata為Java Platform規(guī)范(JSR-181)提供的挣输,用來將一個組件轉(zhuǎn)化成為一個webservice。這些注解簡單地標記福贞,被用來為一個特定的組件或者方法定義一個特定上下文撩嚼。每一個注解被一個或多個上下文的屬性所支持。在這個部分挖帘,我們將向我們的OrderProcess
SEI和實現(xiàn)類添加注解完丽,并將它們轉(zhuǎn)化成一個服務(wù)組件。在這個部分拇舀,我們將覆蓋如下的webservice注解:
- javax.jws.WebService
- javax.jws.soap.SOAPBinding
javax.jws.WebService
一個Java組件可以通過添加一個@WebService
注解的方式被轉(zhuǎn)化成為一個服務(wù)逻族。這個注解必須被同時定義在SEI和實現(xiàn)類中。@WebService
注解被定義在javax.jws.WebService
接口骄崩。
@WebService
注解支持如下的屬性:
讓我們注解我們的OrderProcess
SEI和OrderProcessImpl
實現(xiàn)類聘鳞。下面的代碼展示了@WebService
注解的使用:
package demo.order;
import javax.jws.WebService;
@WebService
public interface OrderProcess {
String processOrder(Order order);
}
@WebService
被直接聲明在接口或者類之上。它注解了這個類或者接口作為一個webservice的類或者接口刁赖。在上面的代碼中搁痛,OrderProcess
接口通過@WebService
注解,來被定義成為一個webservice接口宇弛。
讓我們看一下OrderProcessImpl
實現(xiàn)類鸡典。下面的代碼展示了被注解的OrderProcessImpl
實現(xiàn)類:
package demo.order;
import javax.jws.WebService;
@WebService(serviceName="OrderProcessService",
portName="OrderProcessPort")
public class OrderProcessImpl implements OrderProcess {
public String processOrder(Order order) {
System.out.println("Processing order...");
String orderID = validate(order);
return orderID;
}
}
和SEI類似,你在類之上聲明@WebService
枪芒。你將定義兩個屬性--serviceName
和portName
彻况。serviceName
屬性被賦值為OrderProcessService
。這個服務(wù)名稱被消費者用來獲取遠程接口的句柄來調(diào)用服務(wù)方法舅踪。端口名稱簽名了endpoint名稱纽甘。服務(wù)的endpoint也同樣作為一個服務(wù)端口在服務(wù)發(fā)布的地方被調(diào)用。這里的名字是OrderProcessPort
抽碌。
有許多其它可選的注解被用來和@WebService
搭配使用悍赢,用來更加完整地描述一個webservice。其它注解可以添加更精細的細節(jié)到一個服務(wù)上∽笕ǎ總是推薦你使用這些注解來描述你的webservice皮胡,以便于生成的WSDL文檔有更多的被這些注解指定的細節(jié)。如果你沒有使用這些可選的注解赏迟,那么WSDL將被按照默認的規(guī)則生成屡贺,正如前面表格中討論的一樣。
javax.jws.soap.SOAPBinding
@SOAPBinding
注解被定義在javax.jws.soap.SOAPBinding
接口中锌杀。這個注解在你想要為你的服務(wù)制定SOAP綁定的時候使用甩栈。
這個注解支持如下的屬性:
SOAP綁定在webservice交互中扮演著重要的角色。讓我們更加詳細地看看兩種風格的SOAP綁定糕再。
RPC 風格 v.s Document 風格
Webservice的SOAP交互風格在服務(wù)提供者和消費者之間交互SOAP XML消息中扮演著重要的角色量没。有兩種SOAP消息風格--Document和RPC。SOAP消息的風格被作為SOAP綁定定義在WSDL文檔中亿鲜。一個SOAP綁定能夠擁有一個基于編碼的使用(encoded use) 或者 基于字面的使用(encoded use or a literal use)允蜈。編碼,這個詞暗示了消息將使用某種格式被編碼蒿柳,而字面的表示使用純文本消息饶套,而不做任何編碼邏輯。
正如名字顯示的那樣垒探,Document風格將XML文檔作為有效的載荷來添加到定義良好的契約中妓蛮,通常的做法是使用XML schema定義來創(chuàng)建。XML schema格式指定了被消費者調(diào)用的服務(wù)消息的契約圾叼。XML schema定義了服務(wù)提供者和服務(wù)消費者之間的request和response消息的格式蛤克。這些消息的格式可以被服務(wù)的提供者和消費者驗證為合法。Document literal風格對webservice交互來完成協(xié)作來說是更受歡迎的方式夷蚊。
另一方面构挤,RPC(Remote Procedure Call)風格表明了SOAP主體包含一個XML的方法展示。為了序列化方法的參數(shù)到SOAP消息惕鼓,以便于它能夠被任何webservice實現(xiàn)反序列化筋现。SOAP規(guī)范定義了一系列的編碼規(guī)則。由于RPC通常被用在連接SOAP的編碼規(guī)則箱歧,這個連接將被引用為RPC/encoded矾飞。你用養(yǎng)有一種RPC/literal交互風格模式,這種模式中你沒有任何的編碼格式呀邢,但是消息依然受限于RPC 基于方法的交互洒沦,這種方式下,消息不能被驗證為合法的价淌,因為他們與任何XML schema定義之間都沒有關(guān)聯(lián)申眼。你或許應該避免開發(fā)RPC風格的webservice瞒津,因為它們有許多協(xié)作性上的問題。
下面的代碼展示了@SOAPBinding
注解的使用:
@WebService(name="OrderProcess")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface OrderProcess {
String processOrder(Order order);
}
javax.jws.WebMethod
@WebMethod
注解被定義在javax.jws.WebMethod
接口中豺型。這個注解被用來自定義webservice的操作仲智。@WebMethod
注解提供了operation的name
和action
屬性,這兩個屬性分別被用來自定義在WSDL文檔中的<wsdl:operation>
元素的name
屬性和<soap:operation>
元素的soapAction
屬性姻氨。@WebMethod
注解被放置在服務(wù)方法聲明的上面。
@WebMethod
注解支持如下的屬性:
下面的代碼片段展示了@WebMethod
注解的使用:
@WebMethod (name="processOrder")
public String processOrder(Order order) {
// ...
}
JAX-WS webservice注解支持一系列的其它注解剪验,比如:@RequestWrapper
, @ResponseWrapper
, @Oneway
等等肴焊。它們中的一些將稍后解釋。
發(fā)布服務(wù)
發(fā)布服務(wù)意味著將服務(wù)組件注冊到服務(wù)器上功戚,并且通過endpoint URL使其可以被消費者使用娶眷。你將把OrderProcess
webservice發(fā)布到一個特定的endpoint URL上。在本例中的endpoint URL將會是http://localhost:8080/OrderProcess
啸臀。你將開發(fā)一個服務(wù)器組件來發(fā)布你的OrderProcess
服務(wù)届宠。對這個例子來說,我們將使用Java 5提供的輕量級的web服務(wù)器來發(fā)布我們的服務(wù)乘粒。CXF提供了它自己獨立的服務(wù)器組件--JaxWsServerFactoryBean
來發(fā)布webservice豌注。
下面的代碼展示了服務(wù)器代碼:
import javax.xml.ws.Endpoint;
public class Server {
protected Server() throws Exception {
System.out.println("Starting Server ...");
OrderProcessImpl orderProcessImpl = new OrderProcessImpl();
String address = "http://localhost:8080/OrderProcess";
Endpoint.publish(address, orderProcessImpl);
}
public static void main(String[] args) {
new Server();
Thread.sleep(50000);
System.exit(0);
}
}
用于發(fā)布Endpoint
類的靜態(tài)方法提供了一個簡便的方式來發(fā)布和測試JAX-WS webservice。這個方法接受endpoint URL和一個OrderProcessImpl
類對象作為參數(shù)灯萍。這個publish
方法在URL http://localhost:8080/OrderProcess
上創(chuàng)建一個輕量級的web服務(wù)器轧铁,并且在那個位置部署這個服務(wù)。這個輕量級的web服務(wù)器在JVM中運行一分鐘然后自動終止旦棉。一種能夠看到服務(wù)的WSDL契約的方法是在web瀏覽器中訪問這個URL:
http://localhost:8080/OrderProcess?wsdl
開發(fā)一個消費者
webservice的消費者調(diào)用服務(wù)方法來獲得需要的結(jié)果齿风。在這一部分,我們將開發(fā)一個Client
類來查找我們的OrderProcess
服務(wù)绑洛,并且調(diào)用它的processOrder
方法救斑。下面的代碼展示了服務(wù)消費者組件:
public class Client {
private static final QName SERVICE_NAME =
new QName("http://order.demo/", "OrderProcessService");
private static final QName PORT_NAME =
new QName("http://order.demo/", "OrderProcessPort");
private static final String WSDL_LOCATION =
"http://localhost:8080/OrderProcess?wsdl";
public static void main(String args[]) throws Exception {
URL wsdlURL = new URL(WSDL_LOCATION);
Service service = Service.create(wsdlURL, SERVICE_NAME);
OrderProcess port = service.getPort(PORT_NAME, OrderProcess.class);
Order order = new Order();
order.setCustomerID("C001");
order.setItemID("I001");
order.setPrice(100.00);
order.setQty(20);
String result = port.processOrder(order);
System.out.println("The order ID is " + result);
}
}
客戶端的代碼做了以下的事情:
- 它首先創(chuàng)建了WSDL URL。這個WSDL URL是
http://localhost:8080/OrderProcess?wsdl
真屯。這個URL表明了WSDL 文檔的位置脸候。
在運行客戶端程序之前,你可以通過訪問以上的URL來驗證這個服務(wù)是否可用讨跟。如果你能夠看見WSDL纪他,那么就意味著這個
OrderProcess
服務(wù)被成功地發(fā)布了。
- 接下來創(chuàng)建了
Service
對象晾匠。這個Service
對象使用了靜態(tài)的create
方法被創(chuàng)建茶袒。這個方法接受WSDL URL和服務(wù)名稱作為參數(shù)。這個服務(wù)名稱OrderProcessService
是一個QName
凉馆,并且在WSDL文檔中被映射到<wsdl:service>
元素薪寓。<wsdl:service>
元素定義了服務(wù)的endpoint亡资。 - 使用
Service
對象,你通過調(diào)用getPort
方法獲得SEI句柄的代理組件向叉。getPort
方法接受port name和SEI類作為參數(shù)锥腻。接口名稱OrderProcessPort
是一個QName
,并且在WSDL文檔中被映射到<wsdl:port>
元素母谎。這個SEI類是OrderProcess
瘦黑。 - 代理組件在接下來被用來調(diào)用服務(wù)方法
processOrder
。在調(diào)用方法之前奇唤,你必須安置好Order
bean幸斥,并把它傳給processOrder
方法。這個方法在服務(wù)器上被調(diào)用咬扇,并返回訂單ID甲葬。