1. Client Integration

1.1. Generating Annotation RDF/XML

The following instructions describe the steps necessary for client integration using the Client Helper for either FP-Lite or FP-Medium and requires that at least one of these is deployed. The libraries (deployed to /usr/share/php as part of the deployments) for client integration with FilteredPush can be checked out via SVN:

$ svn checkout svn://svn.code.sf.net/p/filteredpush/svn/FP-Tools/FP-PHP-Library/ FP-PHP-Library

After configuring the libraries (see Client Helper Libraries and Configuration, copy the fp directory into your php includes directory.

$ sudo cp -r FP-PHP-Library/fp /usr/share/php/

FilteredPush expects annotations to be expressed as rdf/xml using terms from the FilteredPush vocabularies. The Annotation generation web service is a RESTful web service that can produce rdf/xml from XML or JSON representations of a data model. Objects in the model, as well as properties of those objects, can be mapped to terms in any given vocabulary via a configuration files for the Annotation Generator. Once configured, the Annotation Generator can be invoked via http POST and the annotation rdf/xml is returned in the http response.

The Annotation Generator frees the client programmer from having to worry about the details of the semantic web technologies or the vocabularies used and allows for very straight-forward generation of annotations using either multi-dimensional arrays or PHP objects. Additionally, reconfiguring the web service for use with a different model can be done entirely through edits to the model descriptor configuration of the generator.

The default deployment of the Annotation Generator and the model descriptors from the FP-SCAN project (deployed to /etc/filteredpush/model) have been preconfigured to produce annotation rdf/xml suitable for use with FilteredPush. If the value of RDFHANDLER_ENDPOINT in the PHP include fp/FPConfig.php is set to to point to the correct url of the Annotation Generator web service, then the FPNetworkFactory (fp/FPNetworkFactory.php) can be used to obtain a proxy object for the Annotation Generator. The service can then be invoked using the generateRdfXml($annotation) method of the object returned by the factory.

In the example presented below, the value of the $annotation argument is an array that contains the data for a new determination and the variable $rdf contains the response (as rdf/xml) from the annotation generation webservice:

//prepare new determination annotation for fp $annotator = new Array(); $annotator['name'] = 'Robert A. Morris'; $subject = new Array(); $subject['catalogNumber'] = '00107080'; $subject['collectionCode'] = 'A'; $subject['institutionCode'] = 'HUH'; $topic = new Array(); $topic['dateIdentified'] = '1990-11-23'; $topic['identifiedBy'] = 'C.H. Stirton'; $topic['scientificName'] = 'Ateleia gummifera'; $topic['scientificNameAuthorship'] = 'D. Dietrich'; $evidence['asText'] = 'Written on the sheet along with the annotation text "Flora Neotropica"'; $annotation = Array('annotator' => $annotator, 'subject' => $subject, 'topic' => $topic, 'evidence' => $evidence) // generate rdf/xml $generator = FPNetworkFactory::getAnnotationGenerator(); $rdf = $generator->generateRdfXml($annotation);

Behind the scenes the generateRdfXml function of the generator uses json_encode on the object passed in (either an array or PHP object) to produce JSON that the Annotation Generator is configured to interpret. It then uses curl to post this JSON to the web service url (set in the FPConfig.php file).

1.2. Submitting Annotations to FilteredPush

The integration for Symbiota is mostly contained in FP-PHP-Library/fp/includes/symbiotahelper.php and this code is invoked by Symbiota's OccurenceEditorDeterminations.php

Once the Annotation Generator has been invoked and it has returned an rdf/xml representation of your data, you can obtain a proxy object for the currently configured network node via FPNetworkFactory::getNetworkFacade(). The proxy object returned by the factory will allow you to inject an rdf/xml annotation into the network via its injectIntoFP($rdf) function:

// inject annotation into fp $network = FPNetworkFactory::getNetworkFacade(); $response = $network->injectIntoFP($rdf);

Depending on the configuration of the NETWORK_FACADE property in FPConfig.php, the correct network implementation (FP-Medium or FP-Lite) and the correct url will be determined automatically. The use of a factory object that returns a facade means that when we are ready to switch from the FP-Lite implementation to the FP-Medium one, the change only needs to be made in FPConfig.php and not in any client code. FPNetworkFactory::getNetworkFacade() will always return a proxy object that represents the currently configured implementation. Changing or creating new FilteredPush network node implemenations is a matter of reconfiguration and should not affect client code for Annotation Generation and submission to the network.