 |
 |
|
|
Code Samples and Tutorials Connection to NatureServe Web Services using REST and XSLT Introduction NatureServe provides several ways to access their data using Web Services. This tutorial covers how to access the NatureServe species data and display the data as HTML using REST-based Web Services, the Java programming language and the XSLT styling language. It assumes that you have some basic knowledge of what a Web Service is and how to program in Java. If you are interested in accessing the Web Services using the Soap front-end, please follow the links to the programmatic tutorial. Many users of NatureServe's species Web Service want to do nothing more than take the data provided in XML and display it in a browser using HTML. In this simple case, using a Java program to issue a SOAP call which is then compiled into Java objects before finally being converted to HTML can be over-kill. A simpler solution is to use XSLT to convert the output XML to HTML. XSLT is a styling language that is used to transform XML into other text based formats. Mostly it is used to turn XML into HTML. XSLT answers the question of how to turn the resulting XML into HTML, but it doesn't address the problem of actually making the request to the Web Service to actually retrieve the data. SOAP is a very complex protocol that requires a good deal of Web Services knowledge to use successfully. In addition to the SOAP-based species Web Service, NatureServe also provides a REST-based species Web Service which allows users to not have to use SOAP at all but instead use a standard URL to retrieve all of the data. By combining this REST interface with XSLT, it becomes possible to develop relatively simple ways to retrieve XML data from the species Web Service and display it in a browser using HTML. Software Requirements In order to work through this tutorial you need to have the following software downloaded and installed:
Step 1: Constructing the XSLT There are two distinct steps to formatting XML data using REST and XSLT. The first is building the XSLT that will theoretically turn data from XML into the format that you want, and the second is retrieving the data from the Web Service and applying the XSLT transformation to it. This section covers the creation of a simple XSLT style sheet that transforms data provided by the NatureServe species Web Service into a small HTML report that looks like the top of the NatureServe Explorer comprehensive report. The next section covers how to retrieve data through the REST interface and apply the XSLT. XSLT is meant to be a simple technology for transforming XML into anything that you like. The premise is that you create a template that looks like the output you want and then fill in references to the XML path you want to be inserted at each location. An example is the best way to illustrate this. Here is the top of the XSLT that will be used throughout this tutorial, for which complete content can be found here: <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:ns="http://services.natureserve.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xsl:output method="html" indent="yes"/> <xsl:template match="ns:globalSpecies"> <html> <head> <title>Comprehensive Report Species - <xsl:value-of select="ns:classification/ns:names/ns:scientificName/ns:unformattedName"/> </title> </head> ... This is top of the XSLT called SpeciesToNSExplorer.xsl, the first line is just a standard line that has to be included in every XSLT. The second line informs the XSLT that we are going to be outputting HTML. The third line tells the XSLT that we are going to be outputting the following HTML when the XML element 'globalSpecies', which is the root node of the XML document that will be returned by the species Web Service, is encountered. These first three lines act as a preamble to the actual content. They get things setup before the actual output content is declared. The next five lines are the beginning of the HTML document that is going to be generated. It looks just like a standard HTML document until you get to the title declaration. The title contains the first reference to any data from the species Web Service. This line says to output a standard title tag, followed by the text "Comprehensive Report Species - ", followed by a XSLT command. The XSLT commands are special XML tags embedded in the content that is being output that tell the XSLT processor, which is discussed more in the next section, to take some special action. In this case, the XSLT processor is being told that it should replace the xsl:value-of tag with the contents from the selected XML element. The XML node content that should be inserted can be found at the value of the select attribute, which is "ns:classification/ns:names/ns:scientificName/ns:unformattedName". If this node cannot be found in the globalSpecies XML document, then the xsl:value tag is replaced with nothing, if something is found then the contents of that node are used to replace the xsl:value-of tag. Please note that the value of the select attribute in the xsl:value-of tag can be any valid XPath statement. More information about XPath can be found here. This simple example is replicated throughout most of the SpeciesToNSExplorer.xsl XSLT, with xsl:value-of tags being used to reference pieces of XML that are part of the globalSpecies XML schema. Here is a slightly more complex portion of the XSLT that begins to show some of the real power of XSLT: .... <font face="Arial, Helvetica, sans-serif" size="2">Unique Identifier: <xsl:value-of select="@uid"/><br/></font> <font face="Arial, Helvetica, sans-serif" size="2">Element Code: <xsl:value-of select="@speciesCode"/><br/></font> <font face="Arial, Helvetica, sans-serif" size="2"> Informal Taxonomy: <xsl:for-each select="//ns:taxonomyName"> <xsl:if test="position() != 1"> <xsl:text> - </xsl:text> </xsl:if> <xsl:value-of select="@name"/> </xsl:for-each> </font> .... The resulting output of which, when rendered in a browser, looks like: Unique Identifier: ELEMENT_GLOBAL.2.101805 The XSLT code snippet looks to be just more of the same from the first example. First text is output, in a certain font, to say Unique Identifier followed by retrieving the actual unique identifier from the XML document. Next the same is done for Element Code. Outputting the informal taxonomy is more complex. In the globalSpecies XML the informal taxonomy looks like this: <informalTaxonomy> <taxonomyName name="Animals, Vertebrates"> <taxonomyName name="Mammals"> <taxonomyName name="Other Mammals"/> </taxonomyName> </taxonomyName> </informalTaxonomy> The resulting HTML wants to display all of the data contained in those three "taxonomyName" tags on a single line of output with dashes between the different informal taxonomies. In the snippet of XSLT that is shown, the xsl:for-each tag is used to accomplish this. The xsl:for-each tag loops over all of the XML nodes that match a XPath statement, in this case "//ns:taxonomyNames", so this for loop iterates over all of the taxonomyNames. This solves part of the problem by allowing the XSLT to output contents from multiple tags with the same name, but outputting the dashes between the informal taxonomies is still a problem because there are three elements but only two dashes. To solve this problem, the xsl:if and the xsl:text tags are used. The xsl:if tag is used to test a condition and if that condition is true, then the code within the tags are executed. The condition that is tested is "position() != 1", which tests if the taxonomyName that is being worked on is the first node or not. If it is not, then the code " The SpeciesToNSExplorer.xsl XSLT only uses four XSLT tags, xsl:value-of, xsl:text, xsl:if and xsl:for-each. These are the basic tags that you need to know in order to be able to do meaningful work with XSLT. Once you get the hang of these four tags, you can generate most HTML and text files that you need based on the globalSpecies XML. XSLT has a few hundred tags and much more information about both the tags and the template language itself can be found here. Step 2: Rendering the Output The XSLT processing model is very simple: XSLT + XML = Output. The first section of this tutorial introduced the concept of creating a simple XSLT, SpeciesToNSExplorer.xsl, that would build a HTML page based on certain pieces of XML data. This section deals with the details of how to retrieve the XML from the species Web Service using the REST based interface. Much more information on the REST-based interface can be found here, but in short the REST-based interface throws away the idea of a SOAP envelope and the extra overhead associated with it and works off of a URL and HTTP. The idea is that web-based HTTP traffic is already very mature, so why differ from the model. Parameters are passed to the REST-based interface in the same way they are to normal web pages, either appended to the end of the URL or in the HTTP header during a post. The URL for accessing the NatureServe species Web Service is: https://services.natureserve.org/idd/rest/globalSpecies?NSAccessKeyId=MY_ACCESS_KEY&uid=MY_UNIQUE_ID. The two bolded parameters need to be filled in, a NSAccessKeyId can be obtained here, and the UID should correspond to a NatureServe Unique Id that can be obtained off of NatureServe Exploror or by using the NatureServe name search Web Service. Once the two parameters are filled in, the URL can then be sent programatically or just entered into a normal web browser to view the data. The REST interface is a simple way to get at the XML, but it still takes a small program to combine the resulting XML with the SpiecesToNSExplorer.xsl XSLT. Here is a piece of sample code that uses the Apache Xalan transformation engine and Java 1.4 to read data from the REST-based interface and generate HTML based on the SpiecesToNSExplorer.xsl XSLT: /** * This is a sample class that is used to test the rest connection for accessing species data */ public class RestTestSpecies { public static void main( String[] args ) throws Exception { URL url = new URL( "https://services.natureserve.org/idd/rest/" + "globalSpecies?NSAccessKeyId=MY_ACCESS_CODE&" + "uid=ELEMENT_GLOBAL.2.101805"); InputStream data = url.openStream(); TransformerFactory tFactory = TransformerFactory.newInstance(); Transformer transformer = tFactory.newTransformer( new StreamSource( RestTestSpecies.class.getResourceAsStream( "/SpeciesToNSExplorer.xsl" ) ) ); transformer.transform(new StreamSource( data ), new StreamResult( System.out ) ); } } The full text of the program can be found here. This Java program opens a URL to the globalSpecies record for the American Pika. It then creates a XALAN transformer and loads the transformer with the SpiecesToNSExplorer.xsl XSLT. Please note that the XSLT must be in your classpath for this to work. Finally, the data is combined with the transformer and the result is outputted to the screen. This is a very simple example of using Java to combine an XSLT and XML data and routing the result to the screen. Conclusion This tutorial covers using XSLT and XML to produce a HTML page much like the NatureServe Explorer comprehensive report. The resulting Java program that is developed is very simple and only outputs data from a single URL to the screen. These same concepts can be used to create a set of Java classes or a servlet that does much more sophisticated manipulation and works in a more generic way. At NatureServe, most of the internal applications that use Web Services are built in this manner and it has proven to be a successful technique for easily and quickly retrieving and displaying data over the web. |
||||||
|
