org.pasoa.util
Class ClientLib

java.lang.Object
  extended by org.pasoa.util.ClientLib

public class ClientLib
extends Object

ClientLib provides a number of convenience methods for recording, querying, (and hopefully in the future) managing provenance stores. The library takes care of serialization/deserialization from Java objects to SOAP.

The two methods of most use are probably record (Record rec, URL provenanceStore) which allows you to build a Record object and send that to a provenance store and query (String xquery, URL provenanceStore) which allows you to query a particular provenance store with an xquery string.

The documentation assumes you are familiar with the Provenance Modelling and Functionality section of the Architecture for Provenance Systems document.

Author:
pgroth

Constructor Summary
ClientLib()
           
 
Method Summary
 String makeRecordDocument(InteractionKey irid, String viewKind, Element asserter, String content)
          Generates a Record SOAP message from the given parameters.
 String makeRecordDocument(Record rec)
          Given a Record object generate a Record SOAP message
 Document provenanceQuery(String qdhXPath, String scopeXPath, Map namespaces, URL provenanceStore)
           
 Document query(String xquery, URL provenanceStore)
          Send an XQuery to the specified provenance store.
 Document record(Record rec, URL provenanceStore)
          Record a Record object in the specified provenance store.
 Document record(String soap, URL provenanceStore)
          Record an already generated Record SOAP message in the specified provenance store This SOAP message must conform to PRecord.wsdl
 Document xpath(String xpath, String root, String item, Map namespaces, URL provenanceStore)
          Send an XPath to the specified provenance store, specifying the form of the document returned.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ClientLib

public ClientLib()
Method Detail

record

public Document record(Record rec,
                       URL provenanceStore)
                throws Exception
Record a Record object in the specified provenance store.

Parameters:
rec - the Record object
provenanceStore - the URL of the provenance store
Returns:
a DOM Document containing the response from the provenance store
Throws:
Exception

record

public Document record(String soap,
                       URL provenanceStore)
                throws Exception
Record an already generated Record SOAP message in the specified provenance store This SOAP message must conform to PRecord.wsdl

Parameters:
soap - the record soap message to send to the provenance store
provenanceStore - the URL of the provenance store
Returns:
a DOM Document containg the response from the provenance store
Throws:
Exception

makeRecordDocument

public String makeRecordDocument(InteractionKey irid,
                                 String viewKind,
                                 Element asserter,
                                 String content)
Generates a Record SOAP message from the given parameters.

Parameters:
irid - the key that identifies the interaction
viewKind - the ViewKind as specified by Constants.CLIENT_VIEW or Constants.SERVICE_VIEW
asserter - the asserter as a DOM element
content - the content (i.e. interactionPAssertion, actorStatePassertion, relationshipPAssertion or submissionFinished) already seralized to XML
Returns:
a Record SOAP message as a string

makeRecordDocument

public String makeRecordDocument(Record rec)
Given a Record object generate a Record SOAP message

Parameters:
rec - a Record object
Returns:
a Record SOAP message as a String

query

public Document query(String xquery,
                      URL provenanceStore)
               throws Exception
Send an XQuery to the specified provenance store. See http://twiki.pasoa.ecs.soton.ac.uk/bin/view/PASOA/QueryDocumentation for full documentation on how to use this interface.

Parameters:
xquery - the xquery string
provenanceStore - the URL of the provenance store to query
Returns:
a DOM Document containing the results of the XQuery
Throws:
Exception

xpath

public Document xpath(String xpath,
                      String root,
                      String item,
                      Map namespaces,
                      URL provenanceStore)
               throws Exception
Send an XPath to the specified provenance store, specifying the form of the document returned. The root and item arguments specify the element names at the top level of the response document. For example, if the xpath is "/ps:interactionRecord/ps:interactionKey", the root is "ex:root" and the item is "ex:result", then the response takes the form:
   <ex:root>
     <ex:result>
       <ps:interactionKey> ...
     </ex:result>
     <ex:result>
       <ps:interactionKey> ...
     </ex:result>
     ...
   </ex:root>
 

Parameters:
xpath - the XPath string
root - the qname of the root element of the response document
item - the qname of the element surrounding each result in the response document
namespaces - a mapping of prefix to namespace used in the XPath or for root/item
provenanceStore - the URL of the provenance store to query
Returns:
a DOM Document containing the results of the XQuery
Throws:
Exception

provenanceQuery

public Document provenanceQuery(String qdhXPath,
                                String scopeXPath,
                                Map namespaces,
                                URL provenanceStore)
                         throws Exception
Throws:
Exception