This is an old revision of the document!
WildPassport is the name of a generic patterning data system implemented by the Shepherd Project. Using this system, any type of pattern-matching data can be saved and retrieved from photos (or other media files) attached to an encounter. The fundamental structure used in WildPassport is the PatterningPassport, which is simply an XML file consisting mostly of patterning data.
The Shepherd Project instance will store the XML pattern data in a database and as XML files alongside the associated media files. The actual schema of the patterning data XML is of no concern to the Shepherd Project instance, as long as it doesn't use
patterningPassport as its root node name. The pattern processing and storage is only connected to the Shepherd Project server by communication through the WildPassport servlets.
For every photo or media file attached to an Encounter, there is a Patterning Passport (PP). The PP is a set of XML data in two parts: the ID Data and the Pattern Data. The structure of the XML file is as follows:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <patterningPassport> <idData> <encounterId>12345678</encounterId> <mediaId>1</mediaId> <encounterUrl>http://shepherd.foo.org/ProjectXYZ/encounters/encounter.jsp?number=12345678</encounterUrl> <mediaSourceUrl>http://shepherd.foo.org/shepherd_data_dir/encounters/12345678/fooBar.png</mediaSourceUrl> <passportXmlUrl>http://shepherd.foo.org/shepherd_data_dir/encounters/12345678/1_pp.xml</passportXmlUrl> </idData> <customXmlNode note="This node contains all pattern matching data for the referenced media."> <testnode1>Foo</testnode1> <testnode2>Bar</testnode2> </customXmlNode> </patterningPassport>
Note that, when creating or updating a PatterningPassport on the Shepherd Project instance, the only required XML is the pattern matching data itself (marked as “customXmlNode” here). The document wrapper (“patterningPassport”) and meta-data (“idData”) are created automatically by the WildPassport system.
To set a new PP or update an existing PP, use the EncounterSetPatterningPassport servlet. Setting a PP requires three parameters:
The format of the call to the servelet is:
The recognized parameters in the request are: encounterId (String), mediaId (String), and patterningPassportData (File).
Note: Only one file should be attached, and it must be a well-formed XML file.
A web interface is provided for testing and convenience, see uploadPatterningPassport.jsp.
Failure to satisfy these requirements will result in a set failure.
* A valid combination of
mediaId must be provided.
* The XML file provided must be well-formed.
Response from the EncounterSetPatterningPassport servlet is in XML, taking one of the following forms:
There are two ways to update an existing PP:
The second method is available just as a convenience and it's usually better to use the first method. A use case for this would be to download a set of XML files, tweak them slightly with a script, then send them back up wholesale.
The first method will regenerate the site-based metadata (e.g. the
idData node) based on the latest server settings. And the second method will simply save what XML it is given, provided it is well-formed.
To invoke the direct PP XML overwrite, simply include the full PP XML file as the patterningPassportData (File) parameter when accessing the servlet. Strictly speaking, anything with a base node with the node name
patterningPassport will be treated as a verbatim passport.
Use the EncounterGetPatterningPassport servlet to retrieve a single PP. This servlet accepts three parameters:
If there is a matching PP, the XML file will be returned. Otherwise, an XML-formatted response will return an empty set.
As with retrieving a single PP, use the EncounterGetPatterningPassport servlet.
To retrieve all PPs – leave all three parameters blank.
To retrieve all PPs for a single encounter – leave all but the
To retrieve all PPs matching a query – use a JDOQL string as the
Responses will be in the form of an XML list in the following format:
<response> <patterningPassport encounterId="12345" mediaId="1" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/1_pp.xml"/> <patterningPassport encounterId="12345" mediaId="2" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/2_pp.xml"/> <patterningPassport encounterId="12345" mediaId="3" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/3_pp.xml"/> <patterningPassport encounterId="678910" mediaId="1" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/678910/1_pp.xml"/> <patterningPassport encounterId="678910" mediaId="2" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/678910/2_pp.xml"/> </response>
Note that there is a node named
response containing child nodes for each of the matching PP objects on the server. Included as properties on each of those
patterningPassport child nodes are the
mediaId, and the
patterningPassportXmlUrl. The latter is used to retrieve the full XML of the PP.
The PatterningPassport object is persisted in the database as a property of every SinglePhotoVideo object. The XML data for the PatterningPassport is stored in the object and as a separate XML file in the data directory of the Shepherd Project instance.
org.ecocean.PatterningPassport class governs the structure of the XML, and of course the variables of the object. The most important method of this class is
makeNewPassportXml, which puts together the XML file that will both be stored in the database and written to the file system.
The filename for the XML is determined by the ID (not the filename) of the media with which it is associated. By default, this file is stored in the same directory as the image/media itself. For example, if the ID of the photo is “99”, the photo may be stored as “99.png” and the PP XML would be “99_pp.xml”.
In standard configuration of the Shepherd Project, these files would be in a directory called
…\shepherd_data_dir\encounters\12345678 (if “12345678” is the encounter ID).