Using GroovyWS with the TerraService (Part 1)

I got recently a post on the difficulty of retrieving complex elements by some webservices, I will try to clarify some issues on this in this post using the Microsoft Terra webservice.
The TerraService is an WebService API which allows you to query the Microsoft TerraServer database of high resolution aerial imagery. Among other things, you can:

• Find Geographic and Image Coordinates by Place Name
• Convert coordinates from one projection system to another
• Fetch tile meta-data and image-data

Today, I will just concentrate on using the search API to show how to deal with arrays with GroovyWS.

If you look at the TerraService WSDL you will notice that some functions return arrays. This is clear from the following part of the WSDL:

<s:element name="GetPlaceList">
 <s:complexType>
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="placeName" type="s:string"/>
     <s:element minOccurs="1" maxOccurs="1" name="MaxItems" type="s:int"/>
     <s:element minOccurs="1" maxOccurs="1" name="imagePresence" type="s:boolean"/>
   </s:sequence>
 </s:complexType>
</s:element>

<s:element name="GetPlaceListResponse">
 <s:complexType>
   <s:sequence>
     <s:element minOccurs="0" maxOccurs="1" name="GetPlaceListResult" type="tns:ArrayOfPlaceFacts"/>
   </s:sequence>
 </s:complexType>
</s:element>
<s:complexType name="ArrayOfPlaceFacts">
 <s:sequence>
   <s:element minOccurs="0" maxOccurs="unbounded" name="PlaceFacts" type="tns:PlaceFacts"/>
 </s:sequence>
</s:complexType>

<wsdl:message name="GetPlaceListSoapIn">
 <wsdl:part name="parameters" element="tns:GetPlaceList"/>
</wsdl:message>
<wsdl:message name="GetPlaceListSoapOut">
 <wsdl:part name="parameters" element="tns:GetPlaceListResponse"/>
</wsdl:message>

<wsdl:operation name="GetPlaceList">
 <wsdl:input message="tns:GetPlaceListSoapIn"/>
 <wsdl:output message="tns:GetPlaceListSoapOut">
</wsdl:operation>

Therefore, the following call to GetPlaceList will return an object embedding an array of PlaceFacts.

def proxy = new WSClient("http://terraservice.net/TerraService.asmx?WSDL", this.class.classLoader)
def plist = proxy.GetPlaceList("mountain view", 5, true)

From this object, one can call getPlaceFacts to get the array. Here we asked for its size:

println plist.placeFacts.size()

Then one call go through all the places returned by the call to the TerraService:

for (pfact in plist.placeFacts) {
  println pfact.place.city
  println pfact.place.state
}

All this might look a bit cryptic, and it is probably. The fact is that there is no magic. When you want to call a remote service, you have to know its signature. If you don't have any manual then you have to read and understand the WSDL which represents the contract you are offered.

If you have any idea on how thing could be improved by GroovyWS for helping you in writing your scripts then do not hesitate to give your feedback.

Happy new year - Bonne année 2008

Quelques petites nouvelles de début d'année: 2007 s'est finie pour nous par un séjour de quelques jours à Malacca (Malaisie). Nul doute que soph postera prochainement une description plus complète de nos visites. J'en profite pour vous souhaitez une très bonne année 2008; quelle vous apporte surtout la santé (le reste suivra, j'en suis sûr).

Dans le chapître des bonnes résolutions (car point de nouvelle année sans de nouveaux objectifs), je vous dirais bien que j'essayerai d'être plus présent sur ces pages, que je prendrai plus de vacances, que je ferai le marathon de Singapour, .... M'enfin n'y croyez pas trop !

A toutes fins utiles, et pour ceux qui voudraient se joindre à moi, le marathon de Singapour aura lieu cette année le 7 décembre.

Sur ces bonnes résolutions, je vous laisse et n'hésitez pas à me communiquer vos bonnes résolutions en commentaires.