Built into the BioCASe Provider Software is the BioCASe Protocol, which defines the rules for querying a BioCASe web service. This hard-coded protocol is responsible for a successful communication between the Provider Software and any client application (usually a network component). The protocol is schema-agnostic, meaning it it indepent of the payload data that is queried and transmitted. It defines certain activities or methods that are understood by the wrapper and the client applications.
The following diagram shows the central role of the protocol and how the main components interact.
As mentioned above, the BioCASe protocol is schema-agnostic, so it can be used in conjunction with any custom-defined XML schema. In contect of the current biodiversity networks, this is usually the ABCD schema (Access to Biological Collections Data) or one of its extension schemas like ABCD-EFG (Extension For Geosciences) or ABCD-GGBN (Global Genome Biodiversity Network). Read more on schemas...
The protocol defines several different activities in the <type> element of its header section:
<?xml version="1.0" encoding="UTF-8" ?> <request xmlns="http://www.biocase.org/schemas/protocol/1.3" ...> <header> <type>search</type> </header> ... </request>The BioCASe protocol defines three types of requests: Search, Scan and Capabilities:
A capabilities request allows a client to get information about the schemas supported by the web service and the mapped concepts. This request type returns a list of xpaths identifying all mapped concepts.
<request> <header> ... <type>capabilities</type> </header> </request>
Take a look at the examples to see a capabilities response document.
A Scan request takes one concept referenced by an xpath as an argument and returns a list of all distinct values for this element found in the database (technically, it's the result of a SELECT DISTINCT query). Here is the abbreviated scan request that would return a list of scientific names found in the database:
<header> ... <type>scan</type> </header> <scan> <requestFormat>http://www.tdwg.org/schemas/abcd/2.06</requestFormat> <concept>/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/ TaxonIdentified/ScientificName/FullScientificNameString</concept> </scan>
This is the main method. It allows to retrieve all data published for a given data schema. It can be used to get all records (by paging through the results) or just the records that match a given filter. The example below, for example, will return the first 500 records with the taxon's scientific name starting with "Abies":
<request> <header> ... <type>search</type> </header> <search> <requestFormat>http://www.tdwg.org/schemas/abcd/2.06</requestFormat> <responseFormat start="0" limit="500">http://www.tdwg.org/schemas/abcd/2.06</responseFormat> <filter> <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/ TaxonIdentified/ScientificName/FullScientificNameString">Abies*</like> </filter> <count>false</count> </search> </request>
The concept schema the search filter is based on is defined by the element <requestFormat>. The concept schema to be used to return the result is defined by <responseFormat> and does not have to be the same as the requested format. For example you can query using the Darwin core standard but return a full ABCD document.
The search is stateful. So it is possible to limit the number of returned records and to define a record number to start from.
The <filter> wraps the WHERE clause of an SQL statement. It is a nested structure using different combinations of logical and comparison operators. Following operators are supported (XML is case sensitive!):
binary comparison operators
unary comparison operators
comparison operators for multiple arguments
unary logical operators
binary logical operators
Here is a more complex filter example illustrating several conditions based on ABCD:
<filter> <and> <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/ TaxonIdentified/ScientificName/FullScientificNameString">Abies*</like> <or> <like path="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/ TaxonIdentified/HigherTaxa/HigherTaxon">Pinace*</like> <and> <like path="/DataSets/DataSet/Units/Unit/Gathering/Country/Name">*Russia*</like> <greaterThan path="/DataSets/DataSet/Units/Unit/Gathering/DateTime/ISODateTimeBegin"> 2002-04</greaterThan> </and> </or> </and> </filter>
The response will deliver an XML document based on the protocol which envelopes an XML document based on the concept schema containing the records (see diagram above). It also gives information about the number of returned records, the number of dropped records (that is records that matched your request filter, but did contain sufficient data to produce a valid XML document based on the concept schema) and the number of records in the database that matched the query.
Take a look at the examples to see a scan response document.