翻譯: zilong3927 原文地址: http://docs.codehaus.org/display/XFIRE/Mapping+collections
調用 Web Services 時,經常需要返回集合( collection )作為結果,或者接受 collection 型的參數。 SOAP 本身就支持這一點。
但是這一機制的問題在于, java 語言的 collections 是無類型的( untyped ) . 因此,如果要在 Java 1.4 當中支持 collections , 就需要做一些額外的工作。
首先而且是推薦的做法是在 JDK5 當中使用范型( generics )。范型能夠使你在代碼當中為你的 collections 指定類型信息, 從而允許 xfire 自動地推導出 collection 類型,生成正確的 wsdl 等等。
下面示例了如何寫這樣的一個方法:
有些情況下并不總能夠使用范型( generics ) . 例如,如果你的部署環境使用 JDK 1.4 , 或者你想暴露一些遺留的服務,而同時又不打算修改任何代碼也不打算進行移植。
對于這樣的一些情況而言, 你需要生成一個 xml 映射文件,來指定方法和它們對應的集合類型( collection types ) .
這個 xml 文件的名字必須是 <className>.aegis.xml , 其中 className 是你的服務( service )的接口類( unqualified class )的名字。
下面最好通過一個例子來展示這個 xml 文件的格式。 我們想要展現的服務有這樣的一個接口 :
String getFoo();
Collection getCollection();
void setList( int id , java.util.List);
}
既然代碼中的 collections 沒有指定類型, 我們劇需要生成一個 xml 文件來指定所需要的類型。 這個文件的路徑應該和 MyService1.class 在同一個包( package )當中, 并且它的名字應該是 MyService1.aegis.xml
對于這個接口來說,一個最簡單的映射文件如下 :
<mapping>
<method name= "getCollection" >
<return-type componentType= "java.lang.String" />
</method>
<method name= "setList" >
<parameter index= "1" componentType= "java.lang.String" />
</method>
</mapping>
</mappings>
注意這個映射文件確切地指定了所需要的信息,不包含任何冗余。 例如, getFoo 方法沒有被指定,這是由于它沒有包含任何 collections ,因此能夠在沒有任何映射信息的情況下暴露給使用者。
其次, setCollection 方法沒有指定索引為 0 的參數。 這是由于該參數類型為 int ,因此不需要任何映射
如果我們有多個方法,都匹配指定的映射又該怎么辦 ? 這種情況下, 映射就對所有匹配的方法均有效。
所以,如果在我們的接口中增加以下的方法:
那么現在我們的映射定義對于兩個 setList 方法都有作用。這種情況下, 我們不必為額外的參數(譯者注:此處指 boolean persist )指定兩次映射 . 映射文件就指定了所有那些第二個參數為 List 的方法,并假定 List 中包含的都是 strings 。
如果我們想讓那個具有 3 個參數的方法,其中的 list 不包含 Strings , 而是實際上包含 Dates? 這種情況下, 就需要一個更確切的映射來覆蓋( override )原先那個更一般的, 所以我們的映射文件需要添加下面這個定義 :
<parameter index= "1" componentType= "java.lang.String" />
<parameter index= "2" class= "boolean" />
</method>
注意一下類型屬性。 現在這個映射將對所有那些第二個參數為 List ,第三個參數為 boolean 型的方法適用。 在我們的接口當中,這個映射唯一地確定了一個特定的方法,使用這個映射就能夠解釋方法當中的 List 參數。
在優先順序方面, 更確切的映射總是優先于更一般的。
讓我們考慮下面這個復雜一些的例子 :
{
Collection getCollection(); //method 1
Collection getCollection( int id); //method 2
Collection getCollection( String id); //method 3
Collection getCollectionForValues( int value , Collection c); //method 4
Collection getCollectionForValues( String id , Collection c); //method 5
}
映射文件的內容為 :
<mapping>
<!-- mapping 1 -->
<method name= "getCollection" >
<return-type componentType= "java.lang.Double" />
</method>
<!-- mapping 2 -->
<method name= "getCollection" >
<return-type componentType= "java.lang.Float" />
<parameter index= "0" class= "int" />
</method>
<!-- mapping 3 -->
<method name= "getCollectionForValues" >
<return-type componentType= "java.math.BigDecimal" />
</method>
<!-- mapping 4 -->
<method name= "getCollectionForValues" >
<parameter index= "0" class= "java.lang.String" />
<parameter index= "1" componentType= "java.util.Date" />
</method>
<!-- mapping 5 -->
<method name= "getCollectionForValues" >
<return-type componentType= "java.util.Calendar" />
<parameter index= "0" class= "int" />
<parameter index= "1" componentType= "java.lang.Bit" />
</method>
</mapping>
</mappings>
這個文件的格式是不需要做過多解釋的。但有幾點還是需要加以說明。
先來看一下第一個映射 (mapping 1) 。 這個映射指定了所有 getCollection 方法所返回的 collections contain 均包含 java.lang.Doubles 。 如果沒有指定其他的 getCollection 映射, 那么這個映射將對方法 1 , 2 , 3 都適用。
但是,第二個映射更加明確地指定了它所適用的方法。即如果 getCollection 方法的第一個參數是 int 型,那么該方法所返回的 collection 包含的是 Float 型。 由于這條規則更加明確,它將為方法 2 覆蓋掉第一個映射,這是滿足映射約束標準的。
使用以上的規則,不難推導出方法 4 和方法 5 返回的 collections 結果的組件類型( component types )。
對于使用 collections 的 java beans 來說,語法也是類似的。 例如,比方說我們有一個 Company bean ,包含了一個 List , 其中的對象是 employees:
{
private Collection employees;
Collection getEmployees() { return employees; }
public void setEmployees(Collection employees) { this .employees = employees };
}
除了可以使用 <method> & <parameter> 元素外, 也可以使用 <property> 元素 :
<mapping>
<property componentType= "org.codehaus.xfire.Employee" />
</mapping>
</mappings>
Java Maps 并不能很好地映射到 XML Schema (no pun intended) ,因為 XML Schema 中沒有 Map 的概念,客戶端也是這樣, Maps 被轉換成 {key , value} 元組的集合。 除了要提供 value 的類型以外,你還必須為 Aegis 提供 key 的類型 :
Map getGiftList() { /* returns a map of NiceChild => Present */ }
}
映射文件應該像下面這樣 :
<mapping>
<method name= "getGiftList" >
<return-type keyType= "org.codehaus.xfire.NiceChild" componentType= "org.codehaus.xfire.Present" >
</method>
</mapping>
</mappings>
這將生成下面的類型 :
<xsd:sequence>
<xsd:element name= "entry" minOccurs= "0" maxOccurs= "unbounded" >
<xsd:complexType>
<xsd:sequence>
<xsd:element name= "key" type= "ns1:NiceChild" minOccurs= "0" maxOccurs= "1" />
<xsd:element name= "value" type= "ns1:Present" minOccurs= "0" maxOccurs= "1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
在某些情況下,你可能想要傳遞 Collections of Collections 。比方說你有一個返回 List of a List of Doubles 的服務 ( 不要問為什么你要做這樣一件事情 ...):
{
public List getListOfListOfDoubles
{
List l = new ArrayList();
List doubles = new ArrayList();
doubles.add( new Double (1.0));
l.add(doubles);
return l;
}
}
要處理這種情況,我們需要引進一個新的 <component> 元素。 下面是一個很好的例子 :
<mapping>
<method name= "getListofListofDoubles" >
<return-type componentType= "#someDoubles" />
</method>
<component name= "someDoubles" class= "java.util.List" componentType= "java.lang.Double" />
</mapping>
</mappings>
正像你在這里所看到的,返回類型的 componentType 是一個指向 <component> 的引用,而不是一個類。組件類型 "#someDoubles" 引用到名字為 "someDoubles" 的 <component> 。
Aegis 將會自動給這些 collections 命名為 ArrayOfDouble 和 ArrayOfArrayOfDouble 。 你也可以改變這些名字。 要設置你自己的名字, 提供一個 "typeName" 屬性即可 :
<mapping>
<method name= "getListofListofDoubles" >
<return-type componentType= "#someDoubles" typeName= "LotsOfDoubles" />
</method>
<component name= "someDoubles" class= "java.util.List" typeName= "SomeDoubles" componentType= "java.lang.Double" />
</mapping>
</mappings>