== Sampler - a caTissue API Client ==

The API is a way of extending the caTissue application. Jeff suspects the aim is to achieve more functionality within caTissue with less effort from the official development team.[[BR]]

The API client allows you to use caTissue's domain objects (like Participant or Specimen) within another application (the client). All of the domain objects are serializable Java classes. The modus operandi is for the client to create or retrieve one of these and pass back the object to caTissue. The object gets serialized over the network for this to work.

Here is some pseudo code of what a client must do to register a new participant, with comments:

  1. Locate caTissue application service.
  1. Start a session within caTissue. This is just like starting any other interaction. There is the possibility of time out with inactivity. Some degree of housekeeping and authentication is required.
  1. Use the application service to retrieve a local copy of the !CollectionProtocol.
  1. Create a local copy of the Participant and initialize it according to the !CollectionProtocol requirements. This is quite an involved process requiring detailed knowledge of the caTissue business model.
  1. Use the application service to pass the Participant back to caTissue. After this action, the Participant exists in the database. 

Notes on the above...

=== The Client and The User ===
The client API is invoked within an application entirely separate from the caTissue application. '''They are both separate applications that happen to talk to one another'''. The client will need to be written in Java if it is to use serialized Java domain objects. The client application has a user. How does the user interact with it:
  * Web browser?
  * Desktop gui?
  * Command line?
  * Two-d barcode reader?
This user interface will need designing and programming.[[BR]]
(Also see next point below, which is also relevant).

=== Domain Objects ===
This concerns point 4 in the pseudo code example. The use cases we need to cover will involve business objects (domain objects) like Participant, Collection Protocol, Collection, Specimen Collection Group, Specimen, and so on. We will need to understand how these relate to one another. The code that supports the use cases must support the relationship between these objects. It is possible the integrity of the objects will be checked by the caTissue application when the client finally interacts with it. But:
  * If it does, we need to handle error conditions. The examples I've seen are very rudimentary in dealing with errors.
  * If it does not, we risk data corruption unless our understanding is good and we programme defensively.

=== Transactions ===
This is partly an extension of the above points on Domain Objects.[[BR]]
Normally, a business action within an application is defined by one or more transactions. I cannot see a clear transaction boundary yet in the API. The following is a tidied up code example of updating a Specimen Collection Group. The client has already done steps 1, 2, and 3. What you see below covers steps 4 and 5.

{{{
private static void updateSCG() throws Exception {

	Participant participant = new Participant();
	participant.setLastName(PSRTICIPANT_LAST_NAME);
	String query = "some query stuff here";
	List scgList = appService.search( query, participant );

	Iterator<SpecimenCollectionGroup> scgItr = scgList.iterator();
	SpecimenCollectionGroup sprObj = null;
	Site site = BaseTestCaseUtility.initSite();
	site = (Site) appService.createObject(site);
        //
        // Here is a loop with an update invocation embedded within it.
        // Is each update a separate transaction?
        //
	while (scgItr.hasNext()) {
		sprObj = (SpecimenCollectionGroup) scgItr.next();
		sprObj.setCollectionStatus("Complete");
		sprObj.setSpecimenCollectionSite(site);
		setEventParameters(sprObj);
                //
                // Note that this update is within a loop!
                // Where is the transaction boundary?...
		SpecimenCollectionGroup scg = 
                         (SpecimenCollectionGroup) appService.updateObject( sprObj ) ;
	}

}
}}}

Note that it is not entirely clear where a transaction begins or ends. There is no declaration of transaction boundaries visible. The application service object supports a number of methods, amongst which are CRUD like functions: methods whose signatures begin "create", "get", "query", "register", "remove", "search" or "update". I would suspect each of these might be seen from the caTissue end as a separate transaction. If that is the case, the example above covers a number of separate transactions.

Having had a brief look at the options for communicating with the API there is an XML option [http://aurora.regenstrief.org/xcacore] further investigation is required but may have some legs.

=== GavW's excel mock up ===

Have attached an excel file which illustrates what kind of inputs the API processes are likely to receive.


=== Sampler 1.0 ===

The war file is at at http://mvn.briccs.org.uk/uk/org/briccs/sampler/sampler/

=== Installation Instructions ===

The war file needs to be unpacked into a directory for editing. The WEB-INF/classes/remoteService.xml file needs to be edited to contain the correct URL for the instance of CaTissue which is to be referenced by the API client (on LAMP v2 servers, the easiest way is to reference 'localhost:8080'). Additionally, index.jsp can be edited to give a specific 'legend' for the relevant installation ("TEST", or whatever). Then the war file needs recreating, using "jar cvf sampler.war *" in the root directory of the unpacked war file. Remember to delete the old war file first.

Then copy the new war file into the jboss deploy directory. Restart jboss.