wiki-archive/twiki/data/TAPIR/ThirdProposal.txt,v

head	1.34;
access;
symbols;
locks; strict;
comment	@# @;


1.34
date	2007.01.10.12.51.33;	author RicardoPereira;	state Exp;
branches;
next	1.33;

1.33
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.32;

1.32
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.31;

1.31
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.30;

1.30
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.29;

1.29
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.28;

1.28
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.27;

1.27
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.26;

1.26
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.25;

1.25
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.24;

1.24
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.23;

1.23
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.22;

1.22
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.21;

1.21
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.20;

1.20
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.19;

1.19
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.18;

1.18
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.17;

1.17
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.16;

1.16
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.15;

1.15
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.14;

1.14
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.13;

1.13
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.12;

1.12
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.11;

1.11
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.10;

1.10
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.9;

1.9
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.8;

1.8
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.7;

1.7
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.6;

1.6
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.5;

1.5
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.4;

1.4
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.3;

1.3
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.2;

1.2
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.1;

1.1
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	;


desc
@Initial revision
@


1.34
log
@none
@
text
@%META:TOPICINFO{author="RicardoPereira" date="1168433493" format="1.1" version="1.34"}%
---+ Third proposal, based on SOAP

---+++++ General strategy

To accommodate our needs to the SOAP standard, by using WSDL to define basic operations like GetMetadata and to create SpecificXMLRequests where simple parameters are not enough.
Following the SOAP standard will give us the possibility to use all the existing resources for it and will make a programmers life easier.
Most of our future needs, like access control, are being achieved by other communities using SOAP so we can take advantage of this.  

---+++++ Details

SOAP is a lightweight XML-based messaging protocol used to encode the information in Web service request and response messages before sending them over a network. SOAP messages are independent of any operating system or protocol and may be transported using a variety of Internet protocols, including SMTP, MIME, and HTTP (http://www.webopedia.com/TERM/S/SOAP.html).

I recommend you to go to http://www.bindingpoint.com/default.aspx see some examples of web services implemented with SOAP. That is much easier than going directly to the W3 specifications.

In a web service (for example http://ws.keyfortravel.com/webservices/k4thotelavail.asmx) you must define the different operations that you can do. This description of the different operations is done using the WSDL standard. So we would have to define our RequestMethods in WSDL.
For the simple ones like the MetadataRequest or the ScanRequest this is possible and easy because only simple parameters are transmitted. But for the SearchRequest we will have to continue defining our own format that will be defined as an ThirdProposalXmlRequest. This is something commonly done (look the example above).

Using SOAP and WSDL for defining the basic RequestMethods will make a very simple task to retrieve the metadata while it will not complicate more to do advance searches like the ones we are dealing already.



---+++++ Examples


*Example 1 SOAP 1.1 Request/Response via HTTP*

The next example, request and response, are based completly in the SecondProposal. From the WSDL file that are available above this messages are created automatically using a SOAP library.
This seach is invoking the doFullABCDSearch operation in the web serice, that is a FullDocumentSearch in the SecondProposal, that query using a filter and gets a full qualified ABCD document.

<verbatim>
POST http://dbio105.univ.trieste.it/biocase/databases/TSB/dbwrapper.py HTTP/1.1
Host: www.soapclient.com
Content-Type: text/xml; charset=utf-8
Content-Length: 678
SOAPAction: "http://dbio105.univ.trieste.it/biocase/databases/TSB/DoFullSearch"

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:DigirCase="http://www.gbif.org/schemas/protocol2">
        <soapenv:Header>
                <DigirCase:version>0.93</DigirCase:version>
                <DigirCase:sendTime>2001-09-11T09:30:47-05:00</DigirCase:sendTime>
                <DigirCase:source>192.168.1.105</DigirCase:source>
                <DigirCase:destination>http://www.collection.org/myCollection.py</DigirCase:destination>    
        </soapenv:Header>
        <soapenv:Body>
            <doFullABCDSearch xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">
                   <filter xmlns:abcd="http://www.tdwg.org/schemas/abcd/1.2">
                       <like "abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString">Bra%                         </like>
                   </filter>
                <start>0</start>
                <limit>10</limit>
                <count>0</count>
                <responseNS>http://www.tdwg.org/schemas/abcd/1.2</responseNS>
            </doFullABCDSearch>
        </soapenv:Body>
</soapenv:Envelope>
</verbatim>

<verbatim>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 763

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:DigirCase="http://www.gbif.org/schemas/protocol2"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <DigirCase:version software="Python Interpreter">2.3 (#46, Jul 29 2003, 18:54:32) [[MSC][v.1200 32 bit (Intel)]]</version> 
      <DigirCase:version software="Wrapper">1.3.6</version> 
      <DigirCase:sendTime>2004-07-05T12:22:15+02:00</sendTime> 
      <DigirCase:source>192.168.1.12</source> 
      <DigirCase:destination>192.168.1.174</destination>
   </soapenv:Header>
   <soapenv:Body>
      <content>
         <DataSets xmlns="http://www.tdwg.org/schemas/abcd/1.2">
               <Dataset>
                                 ....This is ABCD
                              </Dataset>
         </DataSets>
      </content>
                <recordStart>1</recordStart>
                <recordCount>10</recordCount>
                <recordDropped>0</recordDropped>
                <totalMatchedRecords>230</totalMatchedRecords>
   </soapenv:Body>
</soapenv:Envelope>
</verbatim>




---+++++ WSDL



WSDL stands for Web Services Description Language. http://www.w3.org/TR/wsdl

WSDL is a document written in XML. The document describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes.

So, the logic thing would be to create a WSDL that describes the function of the provider software, describing first of all the different services available in this data provider (follow the discussion about ProtocolFeatures/AccessPoint) and then the different operations that this services support (follow the ProtocolFeatures/RequestMethods discussion).

Basically in a WSDL file you define 4 major elements:
 
&lt;portType&gt;:      The operations performed by the web service

&lt;message&gt;:       The messages used by the web service 

&lt;types&gt;:         The data types used by the web service 

&lt;binding&gt;:       The communication protocols used by the web service 


Comparing in our case:
   
*&lt;portType&gt;*   

Definition of the ProtocolFeatures/RequestMethods .Operations that our web service can do. The &lt;portType&gt; element can be compared to a function library (or a module, or a class) in a traditional programming language.

*&lt;message&gt;*   

Messages that will be used in the web service, for example to do a scan. The message can contain <parts> that can be compared to the parameters of a function call in a traditional programming language. For example there could be a message called doScanRequest with a <part> (parameter) to specify the schema and antoher the concept.

*&lt;types&gt;*      

We will discuss this later. Probably is the most controversial part.

*&lt;bindings&gt;*      
In our case we are only working with HTTP and Digir or BioCASE protocol, but in SOAP is also posible to use SMTP or other protocols to transfer the data. In bindings you specify the different messages and protocols for every port. Most web services implement three protocols, SOAP, HTTPGet and HTTPPost, we could do the same, for example to access directly a Unit with a URL with a UnitID parameter.


Next a proposal of a WSDL file for a web service like our is shown (created with XMLSpy):

http://www.biocase.org/temp/diagram_wsdl.gif

Go to the next location to get the WSDL http://www.biocase.org/temp/wsdl_digircase.wsdl

You can try it on-line with QuickTry (http://www.bindingpoint.com/quicktryv2.aspx?wsdl=http://www.biocase.org/temp/wsdl_digircase.wsdl). This tool reads the WSDL file and create automatically forms to invoke the web service.

In the picture you can see that there are three Services in this Data Provider, let's take the BGBM as example. In the BGBM we have three databases, Bobo, HerbariumImages and Pontaurus. All the three services (databases conneced) supports to be access trough the Soap. In the bindings window is shown the relations between the communications protocols used by the web service.

You can see that all responses messages but doCustomDocumentSOAPout and doPartialXXXXSearchSoapOut have a type assigned so that they can be invoke in a RPC-Style. For this other two, the client is suposse to know what is the structure that he is asking for.
One question here is if it would be possible to make better the doPartialXXXXSearchSoapOut. This message will contain a piece of the schema, probably a complex type in the schema. The problem is that the type of the response depends on what is asked for so we can not asssined directly a type. I do not know if there is any solution for this, more research should be done. If is not possible it will have to be treate as the Custom structure.

You can see that the WSDL has declared 3 different schemas in its Type part. ABCD and Darwin Core for being able to return this kind of documents and another called protocol. The protocol schema is directly imported from Markus and Renato work on the proposal of the SecondProposal.
In this protocol are declared types that represent a filter, what a ping return, capabilities, etc...
For this SOAP approach there are some things that are not needed in this protocol schema, like the definition of the headers and the structure of the messages, this all done with WSDL in SOAP.


---++++ "Dynamic" WSDL

A central point in this proposal architecture is that the WSDL file for a data provider will be "dynamic". That means that if a data provider maps his database to ABCD then a new set of operations will be available from it (and consequently a change in the WSDL) because now the data provider can return ABCD documents. If later, this data provider map his database to Darwin Core the WSDL will have to be update again to expose the new operation that will be available. This was already mention before, for example could be doABCDFullSearch or doDCFullSearch.

In some way we are doing this already, at least in the BioCASE software, with the configuration tool. If a data provider is mapped to a new schema then we create a new mapping file for it and the data provider starts to be able to answer documents in this new schema. So the configuration tool will have to modify also the WSDL file of the data provider to include the new operations that are open.

---+++++ Integration with UDDI

WSDL is used to describe the interface of a web service. <tModel> UDDI documents provide metadata descriptions of a web service and pointers to specifications that describe their implementation. Given this provision, WSDL documents tie into the UDDI data structures in a couple of places:

   * A <tModel> document should be created for each WSDL document supported by a web service. The <tModel> describes the abstract service type, not the service instance; if appropriate, the WSDL file pointed to by the <tModel> should not contain the <service> and <port> elements. Omitting the <service> and <port> elements allows a WSDL document to describe many web services located in several different places. The WSDL document's URL should be listed as the value of the <overviewURL> element. A <tModel> that references a WSDL document should have a categorization taxonomy of uddi-org:types; a categorization value of wsdlSpec should be applied to it by using a <categoryBag> element. 

   * A <bindingTemplate> structure is created for each unique URL access point used by the web service. The <bindingTemplate> document references one or more <tModel> documents containing the WSDL definitions supported at this access point. 

   * A <businessService> document is created for each web service. The document contains one <bindingTemplate> for each of the access points supported by the web service. 

For example, if you implement one web service that has a single access point and is defined by a single WSDL document, you would create a single <tModel>, a single <bindingTemplate>, and a single <businessService>. Also, if you implement one web service that has two separate access points, each defined by a different WSDL document, you would create two <tModel> documents (one for each interface), two <bindingTemplate> documents (one for each access point), and a single <businessService> document. Each <bindingTemplate> document must point to the <tModel> that references its interface. 


---+++++ Java examples on consuming this service

   ** To be continued**

---+++++ Error handling with SOAP

Error handling is nice with SOAP. There is an element called Fault with an specific structure to define errors (take a look to the link below). Optionally inside this Fault structure you can create your own detail messages that can contain your own structure poiting to your schema, for example our protocol schema and even inside this we can include another structure for program specific errors (the errors from a Python wrapper could be different to the ones from a PHP wrapper).
Most of SOAP parsers take care already of the error messages.

http://www.vbip.com/books/1861005091/chapter_5091_03.asp

---+++++ Security mechanism in SOAP

http://www.nwfusion.com/news/tech/2002/1216techupdate.html

---+++++ Headers

The SOAP headers could be taken from the proposal


   ** To be continued**
Javier de la Torre (12/7/04)

-----
*Comments:*

@


1.33
log
@Revision 33
@
text
@d1 195
a195 194
---+ Third proposal, based on SOAP

---+++++ General strategy

To accommodate our needs to the SOAP standard, by using WSDL to define basic operations like GetMetadata and to create SpecificXMLRequests where simple parameters are not enough.
Following the SOAP standard will give us the possibility to use all the existing resources for it and will make a programmers life easier.
Most of our future needs, like access control, are being achieved by other communities using SOAP so we can take advantage of this.  

---+++++ Details

SOAP is a lightweight XML-based messaging protocol used to encode the information in Web service request and response messages before sending them over a network. SOAP messages are independent of any operating system or protocol and may be transported using a variety of Internet protocols, including SMTP, MIME, and HTTP (http://www.webopedia.com/TERM/S/SOAP.html).

I recommend you to go to http://www.bindingpoint.com/default.aspx see some examples of web services implemented with SOAP. That is much easier than going directly to the W3 specifications.

In a web service (for example http://ws.keyfortravel.com/webservices/k4thotelavail.asmx) you must define the different operations that you can do. This description of the different operations is done using the WSDL standard. So we would have to define our RequestMethods in WSDL.
For the simple ones like the MetadataRequest or the ScanRequest this is possible and easy because only simple parameters are transmitted. But for the SearchRequest we will have to continue defining our own format that will be defined as an ThirdProposalXmlRequest. This is something commonly done (look the example above).

Using SOAP and WSDL for defining the basic RequestMethods will make a very simple task to retrieve the metadata while it will not complicate more to do advance searches like the ones we are dealing already.



---+++++ Examples


*Example 1 SOAP 1.1 Request/Response via HTTP*

The next example, request and response, are based completly in the SecondProposal. From the WSDL file that are available above this messages are created automatically using a SOAP library.
This seach is invoking the doFullABCDSearch operation in the web serice, that is a FullDocumentSearch in the SecondProposal, that query using a filter and gets a full qualified ABCD document.

<verbatim>
POST http://dbio105.univ.trieste.it/biocase/databases/TSB/dbwrapper.py HTTP/1.1
Host: www.soapclient.com
Content-Type: text/xml; charset=utf-8
Content-Length: 678
SOAPAction: "http://dbio105.univ.trieste.it/biocase/databases/TSB/DoFullSearch"

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:DigirCase="http://www.gbif.org/schemas/protocol2">
        <soapenv:Header>
                <DigirCase:version>0.93</DigirCase:version>
                <DigirCase:sendTime>2001-09-11T09:30:47-05:00</DigirCase:sendTime>
                <DigirCase:source>192.168.1.105</DigirCase:source>
                <DigirCase:destination>http://www.collection.org/myCollection.py</DigirCase:destination>    
        </soapenv:Header>
        <soapenv:Body>
            <doFullABCDSearch xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">
                   <filter xmlns:abcd="http://www.tdwg.org/schemas/abcd/1.2">
                       <like "abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString">Bra%                         </like>
                   </filter>
                <start>0</start>
                <limit>10</limit>
                <count>0</count>
                <responseNS>http://www.tdwg.org/schemas/abcd/1.2</responseNS>
            </doFullABCDSearch>
        </soapenv:Body>
</soapenv:Envelope>
</verbatim>

<verbatim>
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 763

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:DigirCase="http://www.gbif.org/schemas/protocol2"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <DigirCase:version software="Python Interpreter">2.3 (#46, Jul 29 2003, 18:54:32) [[MSC][v.1200 32 bit (Intel)]]</version> 
      <DigirCase:version software="Wrapper">1.3.6</version> 
      <DigirCase:sendTime>2004-07-05T12:22:15+02:00</sendTime> 
      <DigirCase:source>192.168.1.12</source> 
      <DigirCase:destination>192.168.1.174</destination>
   </soapenv:Header>
   <soapenv:Body>
      <content>
         <DataSets xmlns="http://www.tdwg.org/schemas/abcd/1.2">
               <Dataset>
                                 ....This is ABCD
                              </Dataset>
         </DataSets>
      </content>
                <recordStart>1</recordStart>
                <recordCount>10</recordCount>
                <recordDropped>0</recordDropped>
                <totalMatchedRecords>230</totalMatchedRecords>
   </soapenv:Body>
</soapenv:Envelope>
</verbatim>




---+++++ WSDL



WSDL stands for Web Services Description Language. http://www.w3.org/TR/wsdl

WSDL is a document written in XML. The document describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes.

So, the logic thing would be to create a WSDL that describes the function of the provider software, describing first of all the different services available in this data provider (follow the discussion about ProtocolFeatures/AccessPoint) and then the different operations that this services support (follow the ProtocolFeatures/RequestMethods discussion).

Basically in a WSDL file you define 4 major elements:
 
&lt;portType&gt;:      The operations performed by the web service

&lt;message&gt;:       The messages used by the web service 

&lt;types&gt;:         The data types used by the web service 

<binding>:       The communication protocols used by the web service 


Comparing in our case:
   
*&lt;portType&gt;*   

Definition of the ProtocolFeatures/RequestMethods .Operations that our web service can do. The &lt;portType&gt; element can be compared to a function library (or a module, or a class) in a traditional programming language.

*&lt;message&gt;*   

Messages that will be used in the web service, for example to do a scan. The message can contain <parts> that can be compared to the parameters of a function call in a traditional programming language. For example there could be a message called doScanRequest with a <part> (parameter) to specify the schema and antoher the concept.

*&lt;types&gt;*      

We will discuss this later. Probably is the most controversial part.

*&lt;bindings&gt;*      
In our case we are only working with HTTP and Digir or BioCASE protocol, but in SOAP is also posible to use SMTP or other protocols to transfer the data. In bindings you specify the different messages and protocols for every port. Most web services implement three protocols, SOAP, HTTPGet and HTTPPost, we could do the same, for example to access directly a Unit with a URL with a UnitID parameter.


Next a proposal of a WSDL file for a web service like our is shown (created with XMLSpy):

http://www.biocase.org/temp/diagram_wsdl.gif

Go to the next location to get the WSDL http://www.biocase.org/temp/wsdl_digircase.wsdl

You can try it on-line with QuickTry (http://www.bindingpoint.com/quicktryv2.aspx?wsdl=http://www.biocase.org/temp/wsdl_digircase.wsdl). This tool reads the WSDL file and create automatically forms to invoke the web service.

In the picture you can see that there are three Services in this Data Provider, let's take the BGBM as example. In the BGBM we have three databases, Bobo, HerbariumImages and Pontaurus. All the three services (databases conneced) supports to be access trough the Soap. In the bindings window is shown the relations between the communications protocols used by the web service.

You can see that all responses messages but doCustomDocumentSOAPout and doPartialXXXXSearchSoapOut have a type assigned so that they can be invoke in a RPC-Style. For this other two, the client is suposse to know what is the structure that he is asking for.
One question here is if it would be possible to make better the doPartialXXXXSearchSoapOut. This message will contain a piece of the schema, probably a complex type in the schema. The problem is that the type of the response depends on what is asked for so we can not asssined directly a type. I do not know if there is any solution for this, more research should be done. If is not possible it will have to be treate as the Custom structure.

You can see that the WSDL has declared 3 different schemas in its Type part. ABCD and Darwin Core for being able to return this kind of documents and another called protocol. The protocol schema is directly imported from Markus and Renato work on the proposal of the SecondProposal.
In this protocol are declared types that represent a filter, what a ping return, capabilities, etc...
For this SOAP approach there are some things that are not needed in this protocol schema, like the definition of the headers and the structure of the messages, this all done with WSDL in SOAP.


---++++ "Dynamic" WSDL

A central point in this proposal architecture is that the WSDL file for a data provider will be "dynamic". That means that if a data provider maps his database to ABCD then a new set of operations will be available from it (and consequently a change in the WSDL) because now the data provider can return ABCD documents. If later, this data provider map his database to Darwin Core the WSDL will have to be update again to expose the new operation that will be available. This was already mention before, for example could be doABCDFullSearch or doDCFullSearch.

In some way we are doing this already, at least in the BioCASE software, with the configuration tool. If a data provider is mapped to a new schema then we create a new mapping file for it and the data provider starts to be able to answer documents in this new schema. So the configuration tool will have to modify also the WSDL file of the data provider to include the new operations that are open.

---+++++ Integration with UDDI

WSDL is used to describe the interface of a web service. <tModel> UDDI documents provide metadata descriptions of a web service and pointers to specifications that describe their implementation. Given this provision, WSDL documents tie into the UDDI data structures in a couple of places:

   * A <tModel> document should be created for each WSDL document supported by a web service. The <tModel> describes the abstract service type, not the service instance; if appropriate, the WSDL file pointed to by the <tModel> should not contain the <service> and <port> elements. Omitting the <service> and <port> elements allows a WSDL document to describe many web services located in several different places. The WSDL document's URL should be listed as the value of the <overviewURL> element. A <tModel> that references a WSDL document should have a categorization taxonomy of uddi-org:types; a categorization value of wsdlSpec should be applied to it by using a <categoryBag> element. 

   * A <bindingTemplate> structure is created for each unique URL access point used by the web service. The <bindingTemplate> document references one or more <tModel> documents containing the WSDL definitions supported at this access point. 

   * A <businessService> document is created for each web service. The document contains one <bindingTemplate> for each of the access points supported by the web service. 

For example, if you implement one web service that has a single access point and is defined by a single WSDL document, you would create a single <tModel>, a single <bindingTemplate>, and a single <businessService>. Also, if you implement one web service that has two separate access points, each defined by a different WSDL document, you would create two <tModel> documents (one for each interface), two <bindingTemplate> documents (one for each access point), and a single <businessService> document. Each <bindingTemplate> document must point to the <tModel> that references its interface. 


---+++++ Java examples on consuming this service

   ** To be continued**

---+++++ Error handling with SOAP

Error handling is nice with SOAP. There is an element called Fault with an specific structure to define errors (take a look to the link below). Optionally inside this Fault structure you can create your own detail messages that can contain your own structure poiting to your schema, for example our protocol schema and even inside this we can include another structure for program specific errors (the errors from a Python wrapper could be different to the ones from a PHP wrapper).
Most of SOAP parsers take care already of the error messages.

http://www.vbip.com/books/1861005091/chapter_5091_03.asp

---+++++ Security mechanism in SOAP

http://www.nwfusion.com/news/tech/2002/1216techupdate.html

---+++++ Headers

The SOAP headers could be taken from the proposal


   ** To be continued**
Javier de la Torre (12/7/04)

-----
*Comments:*

@


1.32
log
@Revision 32
@
text
@d38 1
a38 1
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
d40 4
a43 4
                <version xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">0.93</version>
                <sendTime xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">2001-09-11T09:30:47-05:00</sendTime>
                <source xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">192.168.1.105</source>
                <destination xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">http://www.collection.org/myCollection.py</destination>    
a46 1
                <Filter>
d48 1
a48 1
                      <like path="abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString">Bra%</like>
a49 1
                </Filter>
d65 1
a65 1
<soapenv:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:DigirCase="http://www.biocase.org/schemas/protocol/1.3"
d68 5
a72 5
      <version software="Python Interpreter"  xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">2.3 (#46, Jul 29 2003, 18:54:32) [[MSC][v.1200 32 bit (Intel)]]</version> 
      <version software="Wrapper" xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">1.3.6</version> 
      <sendTime xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">2004-07-05T12:22:15+02:00</sendTime> 
      <source xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">192.168.1.12</source> 
      <destination xmlns="http://www.gbif.org/GBIFDataProvider.wsdl">192.168.1.174</destination>
@


1.31
log
@Revision 31
@
text
@d40 4
a43 4
                <version>0.93</version>
                <sendTime>2001-09-11T09:30:47-05:00</sendTime>
                <source>192.168.1.105</source>
                <destination>http://www.collection.org/myCollection.py</destination>    
d70 5
a74 8
      <version software="Python Interpreter">2.3 (#46, Jul 29 2003, 18:54:32) [[MSC][v.1200 32 bit (Intel)]]</version> 
      <version software="Wrapper">1.3.6</version> 
      <version software="DB module">MS SQL Server module v0.95 using mxODBC 2.0.1</version> 
      <version software="OS">nt</version> 
      <sendTime>2004-07-05T12:22:15+02:00</sendTime> 
      <source>192.168.1.12</source> 
      <destination>192.168.1.174</destination> 
      <destination>192.168.1.105</destination>       
d78 1
a78 1
         <abcd:DataSets xmlns:abcd="http://www.tdwg.org/schemas/abcd/1.2">
d82 1
a82 1
         </abcd:DataSets>
@


1.30
log
@Revision 30
@
text
@d27 2
a28 1
The next example, request and response, are the first approach. Probably the header of the soap envelopes could be more standar defined. Also here is not described the error handeling that is pretty good in SOAP.
d38 1
a38 3
<soapenv:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:DigirCase="http://www.biocase.org/schemas/protocol/1.3"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
d46 11
a56 8
                <DigirCase:DoFullSearch xmlns:DigirCase="http://ww3.bgbm.org/schemas/NewProtocol">
                        <requestFormat>http://www.tdwg.org/schemas/abcd/1.2</requestFormat>
                        <responseFormat start="0" limit="10">http://www.tdwg.org/schemas/abcd/1.2</responseFormat>
                        <filter>
                                <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString" xsi:type="xsd:string">Ast*</like>
                        </filter>
                        <count>false</count>
                </DigirCase:DoFullSearch>
a58 1

d80 1
a80 1
      <DigirCase:FullSearchResponse xmlns:DigirCase="http://www.biocase.org/schemas/protocol/1.3" recordDropped="0" recordCount="1" recordStart="0" totalSearchHits="1">
d82 3
a84 1
            ABCD Document. or whatever other schema
d86 5
a90 1
      </DigirCase:FullSearchResponse>
@


1.29
log
@Revision 29
@
text
@d182 1
d184 1
@


1.28
log
@Revision 28
@
text
@d148 1
a148 1
==="Dynamic" WSDL===
@


1.27
log
@Revision 27
@
text
@d173 3
@


1.26
log
@Revision 26
@
text
@d156 10
a165 1
   ** To be continued**
d173 1
a173 1
   ** To be continued**
d177 1
a177 1
   ** To be continued**
@


1.25
log
@Revision 25
@
text
@d156 2
d160 2
d164 2
d168 1
a168 1

@


1.24
log
@Revision 24
@
text
@d154 1
a154 1
===Integration with UDDI===
d156 1
a156 1
===Java examples on consuming this service===
d158 1
a158 1
===Error handling with SOAP===
d160 1
a160 1
===Security mechanism in SOAP===
@


1.23
log
@Revision 23
@
text
@d148 1
a148 1
*"Dynamic" WSDL*
d154 1
a154 1
*Integration with UDDI*
d156 1
a156 1
*Java examples on consuming this service*
d158 1
a158 1
*Error handling with SOAP*
d160 1
a160 1
*Security mechanism in SOAP*
@


1.22
log
@Revision 22
@
text
@d154 1
d156 5
@


1.21
log
@Revision 21
@
text
@d138 1
a138 2
In the picture you can see that there are three Services in this Data Provider, let's take the BGBM as example. In the BGBM we have three databases, Bobo, HerbariumImages and Pontaurus. All the three services (databases conneced) supports to be access trough the Soap, HttpGet and HttpPost protocols. In the bindings window is shown the relations between the communications protocols used by the web service.
Then you can see that we have to separate again in the PortTypes between the different protocols that are supported. For SOAP and HttpPost is possible to do all available operations but for the HttpGet only capabilities and metadata. That is because we can not send complex request in the URLs therefore only GetMetadata and GetCapabilities are supported in this PortType.
d140 2
a141 1
In fact probably we would have to create a doABCDFullSearch or doDarwinCoreFullSearch because the outpu messages, the rsults from the operations will be of different types, one will be an ABCD document type and the other a Darwin Core one. In this cases we will be able to do RPC-Style invocations, in the case of a Self-defined structure request then we will have to use document-style invocations because we do not know the "type" (schema in fact) that we will return.
d143 3
a145 1
An RCP-style SOAP message carries method parameters and return types, and indicates the names of the methods to invoke. That could work fine when will be possible to have a schema for the answer from the wrapper.
a146 12
That happens when we do capabilities, metadata, scan and fullsearch (in the sense of what is written in the Wiki page). 
For this cases we can specify a schema for the answer from the wrapper, in the case of a fullsearch the result type for example would be abcd or Darwin core.

In the case of metadata, count, capabilities and scan that will be also possible. We know the schema of the result so we can use RPC-style invocation.

We can make RPC-style invocation work with ScanRequest,CountRequest, MetadataRequest, CapabilitiesRequest and finally with SearchRequest for full documents and partial documents.

The only one that will not be possible to use in a RPC way would be the self-defined documents.

*Parameters*

Other thing is about the parameters to send to the wrapper. For Metadata and capabilities it would be possible to query only using simple parameters (like the ones in a URL). For the rest of the queries we would have to define a different parameter called "DigirCaseXMLRequest" (or whatever) that will be our actual filtering part of the protocol. It is a common solution to do so when you need to do complicate searches. For this we can take a look at the XCQL (http://www.loc.gov/z3950/agency/zing/cql/xcql.html) or we can continue with our own.
@


1.20
log
@Revision 20
@
text
@d132 1
a132 1
http://ww3.bgbm.org/moin/protocol/images/wsdl_digircase.gif
d134 3
a136 1
Go to the next location to get the WSDL http://ww3.bgbm.org/moin/protocol/documents/wsdl_digircase.wsdl
@


1.19
log
@Revision 19
@
text
@d154 1
a154 1
Other thing is about the parameters to send to the wrapper. For Metadata and capabilities it would be possible to query only using simple parameters (like the ones in a URL). For the rest of the queries we would have to define a different parameter called "DigirCaseXMLRequest" (or whatever) that will be our actual filtering part of the protocol. It is a common solution to do so when you need to do complicate searches. For this we can take a look at the OpenGIS (http://www.opengis.org/docs/02-059.pdf) or we can continue with our own.
@


1.18
log
@Revision 18
@
text
@d170 1
a170 1
Javier de la Torre (6/7/04)
@


1.17
log
@Revision 17
@
text
@d152 1
a152 1
--- Parameters ---
d156 1
a156 1
--- "Dynamic" WSDL ---
@


1.16
log
@Revision 16
@
text
@d139 27
@


1.15
log
@Revision 15
@
text
@d144 4
@


1.14
log
@Revision 14
@
text
@d1 1
a1 1
---+ Third proposal
@


1.13
log
@Revision 13
@
text
@d137 1
a137 1
Then you can see that we have to separate again in the PortTypes between the different protocols that are supported and that for the SOAP and HttpPost is possible to do all available operations but for the HttpGet only capabilities and metadata. That is because we can not send complex request in the URLs therefore only GetMetadata and GetCapabilities are supported in this PortType.
@


1.12
log
@Revision 12
@
text
@d95 1
a95 1
WSDL stands for Web Services Description Language.
@


1.11
log
@Revision 11
@
text
@d5 3
a7 3
To accommodate our needs to the SOAP standard, by using WSDL to define the basic operations like GetMetadata and to create SpecificXMLRequest where is not enough with just parameters.
Following the SOAP standard will give us the possibility to use all the existing resources for it and will make the programmers life easier.
Most of our future needs, like access control, are being achieved by other communities using SOAP so we can take advance of this.  
d16 1
a16 1
For the simple ones like MetadataRequest or ScanRequest this is possible and easy because only simple parameters are transmitted. But for the SearchRequest we will have to continue defining our own format that will be defined as an ThirdProposalXmlRequest. This is something commonly done (look the example above).
@


1.10
log
@Revision 10
@
text
@d15 2
a16 2
In a web service (for example http://ws.keyfortravel.com/webservices/k4thotelavail.asmx) you must define the different operations that you can do. This description of the different operations is done using the WSDL standard. So we would have to define our ProtocolFeatures/RequestMethods in WSDL.
For the simple ones like ProtocolFeatures/RequestMethods/MetadataRequest or ProtocolFeatures/RequestMethods/ScanRequest this is possible and easy because only simple parameters are transmitted. But for the SearchRequest we will have to continue defining our own format that will be defined as an ThirdProposalXmlRequest. This is something commonly done (look the example above).
d18 1
a18 1
Using SOAP and WSDL for defining the basic ProtocolFeatures/RequestMethods will make a very simple task to retrieve the metadata while it will not complicate more to do advance searches like the ones we are dealing already.
a143 1

@


1.9
log
@Revision 9
@
text
@d136 4
@


1.8
log
@Revision 8
@
text
@d101 37
@


1.7
log
@Revision 7
@
text
@d88 16
@


1.6
log
@Revision 6
@
text
@d13 1
a13 1
I recommend you to go to http://www.bindingpoint.com/default.aspx to see some examples of web services implemented with SOAP. That is much easier than going directly to the W3 specifications.
d15 2
a16 2
In a web service (for example http://ws.keyfortravel.com/webservices/k4thotelavail.asmx) you must define the different operations that you can do. This description of the different operations is done using the WSDL standard. So we would have to define our RequestMethods in WSDL.
For the simple ones like MetadataRequest or ScanRequest this is possible and easy because only simple parameters are transmitted. But for the SearchRequest we will have to continue defining our own format that will be defined as an XmlRequest. This is something commonly done (look the example above).
d18 1
a18 1
Using SOAP and WSDL for defining the basic RequestMethods will make a very simple task to retrieve the metadata while it will not complicate more to do advance searches like the ones we are dealing already.
@


1.5
log
@Revision 5
@
text
@d67 1
a67 1
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
@


1.4
log
@Revision 4
@
text
@d27 1
a27 2
The next example is just demonstrating how to evelope the BioCASE protocol into SOAP, not taking care of defining the posible RequestMethods. Is just the starting point.

@


1.3
log
@Revision 3
@
text
@d39 1
a39 1
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:biocase="http://www.biocase.org/schemas/protocol/1.3"
d67 20
a86 28
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:biocase="http://www.biocase.org/schemas/protocol/1.3"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <biocase:response SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <return xsi:type="xsd:string">
         <header>
            <version software="Python Interpreter">2.3 (#46, Jul 29 2003, 18:54:32) [[MSC][v.1200 32 bit (Intel)]]</version> 
            <version software="Wrapper">1.3.6</version> 
            <version software="DB module">MS SQL Server module v0.95 using mxODBC 2.0.1</version> 
            <version software="OS">nt</version> 
            <sendTime>2004-07-05T12:22:15+02:00</sendTime> 
            <source>192.168.1.12</source> 
            <destination>192.168.1.174</destination> 
            <destination>192.168.1.105</destination> 
            <type>search</type> 
         </header>
         <content recordDropped="0" recordCount="1" recordStart="0" totalSearchHits="1">
                  ABCD!!!!!
         </content>
         <diagnostics>
            <diagnostic>OK</diagnostic> 
         </diagnostics>
      </return>
        </biocase:response>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

@


1.2
log
@Revision 2
@
text
@d41 16
a56 17
<soapenv:Envelope soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header>
      <version>0.93</version>
      <sendTime>2001-09-11T09:30:47-05:00</sendTime>
      <source>192.168.1.105</source>
      <destination>http://www.collection.org/myCollection.py</destination>   
   </soapenv:Header>
   <soapenv:Body>
      <DigirCase:DoFullSearch xmlns:DigirCase="http://ww3.bgbm.org/schemas/NewProtocol">
         <requestFormat>http://www.tdwg.org/schemas/abcd/1.2</requestFormat>
         <responseFormat start="0" limit="10">http://www.tdwg.org/schemas/abcd/1.2</responseFormat>
         <filter>
            <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString" xsi:type="xsd:string">Ast*</like>
         </filter>
         <count>false</count>
      </DoFullSearch>
   </soapenv:Body>
@


1.1
log
@Initial revision
@
text
@d35 1
a35 1
SOAPAction: "http://www.SoapClient.com/SQLDataSQL"
d41 16
a56 18
   <soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <biocase:request>
         <header>
            <version xsi:type="xsd:string">0.93</version>
            <sendTime xsi:type="xsd:date">2001-09-11T09:30:47-05:00</sendTime>
            <source xsi:type="xsd:string">192.168.1.105</source>
            <destination xsi:type="xsd:string">http://www.collection.org/myCollection.py</destination>
            <type xsi:type="xsd:string">search</type>
         </header>
         <search>
            <requestFormat xsi:type="xsd:string">http://www.tdwg.org/schemas/abcd/1.2</requestFormat>
            <responseFormat start="0" limit="10" xsi:type="xsd:string">http://www.tdwg.org/schemas/abcd/1.2</responseFormat>
            <filter>
               <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString" xsi:type="xsd:string">Ast*</like>
            </filter>
            <count>false</count>
         </search>
      </biocase:request>
a59 1

@