source: TI01-discovery/branches/ws-Discovery2-upgrade/readme.txt @ 3983

ws-Discovery
------------

Build Info/Set up
--------------------
NB, completing the build here assumes you have both apache axis2 and ant installed.  The AXIS2_HOME environment variable
should be set to point to the top level directory of the axis2 install.  If you are deploying locally to tomcat, you need
to set CATALINA_HOME to the home dir of the tomcat install.

The build file, \srcgen\buildDiscovery.xml, now includes targets to run the WSDL2Java code generation and do all the setting up
described in the original instructions below.  Options for building include:
with no parameters, e.g.:

ant -f buildClient.xml jar.client - build the test client jar
ant -f buildClient.xml jar.server - build the server service jar
ant -f buildClient.xml deploy.client - build the service jar and deploy it to a local tomcat install
ant -f buildClient.xml deploy.client - build the service jar and deploy it to a local tomcat install + restart tomcat
ant -f buildClient.xml generatestubs - generate both client and server side stubs - and generate the XBeans jar using the client-side stubs
ant -f buildClient.xml - defaults to building the service jar

NB, to get the DiscoveryService.wsdl file to be generated properly, you may have to temporarily rename the jsr 
file, as mentioned below.  Also note that the WSDL2JAVA operation generates its own unique version of xmlbeans which is then
referenced by the generated code - as such you should be careful not to mix the xmlbeans code generated between doing client
and service jar builds.

Eclipse set up
-------------------
To remove build errors in the code, run the build with the 'generatestubs' target, and eclipse is refreshed to pick the
generated code.  Add all the jars in the resources dir to the build classpath and also add all the jars in the AXIS2_HOME/lib
dir.

Running tests
----------------
There are JUnit tests that can be ran to check the basic integrity of the web services.  For these to be ran from inside
eclipse, you'll need to add the generated XBeans-packaged.jar (in build/lib) to the build path.  The tests also assume that
the files test_file.xml and test_file2.xml, in resources, have been ingested to the postgres DB as badc files (i.e. put them
into the expected harvest directory (currently, /usr/local/jakarta-tomcat/webapps/oai/WEB-INF/harvested_records/badc-nerc-ac-uk-dif)
and run oai_document_ingester.py badc

Failing tests
----------------
There are currently 3 tests that fail:

i) validAuthorTermSearch
- this fails currently since unsure where the author data should be set and retrieved from

ii) nullDateStartRangeSearch
- Generated code is a little ropey atm; if a start date is not defined, this date range is automatically
not set - however if it is it will be - i.e. the end date is not consulted when setting up this object
- this makes it currently impossible to recognise the case where a start date is null and the end date is set
- NB, would be better to tighten up WSDL definition so that you can/cannot set things up wrongly

iii) basicPresentDIFFormatCompare
- This naively assumes the original format returned will equal the DIF format returned (since the original was in 
DIF format).  Clearly there are discrepancies introduced by the transform.

Trouble Shooting
------------------
i) The code was ran using the following versions (NB, problems were experienced with other combinations - so if the service is running
but cannot be reached/throws an exception upon initialisation it is worth trying different versions):

axis2 v1.4
java 1.6.0_06
tomcat 5.5.26

ii) Tomcat must be running with the same version of java as the code is build with - otherwise you'll likely get an error along the 
lines of:

java.lang.UnsupportedClassVersionError: Bad version number in .class file

when the webservice is deployed to tomcat.

iii) Be very careful when playing around with the Setsrid sql calls - the following apostrophes must be ' and not ` - NB, eclipse
may substitute these in which will cause problems which can be difficult to diagnose... 

To do
------------
i) Currently the time searches use only the 'overlaps' function - i.e. the 'temporalOperator' element of the WS is unused.  This
could be implemented to allow similar search types to the spatial operator - i.e. within, overlaps and no overlaps


Original, detailed instructions, are as follows (but you shouldn't have to use them!):

Client Side:
---------------
Instructions for building client (DiscoveryService-test-client.jar)

Do all the following in directory "srcgen"

1) Generate automatic code from wsdl :
%AXIS2_HOME%\bin\wsdl2java -d xmlbeans -uri ..\wsdl\Discovery.wsdl -o . -p ndg.clients.discovery

Edit file src\ndg\clients\discovery\DiscoveryServiceStub.java, after the line (around #104?)
        _serviceClient = new org.apache.axis2.client.ServiceClient(configurationContext,_service);
add the line
        _serviceClient.getOptions().setProperty(org.apache.axis2.transport.http.HTTPConstants.CHUNKED, false);

2) Use ant to compile client jar using custom buildfile
ant -buildfile buildDiscovery.xml jar.client

3) Use ant to run client
ant -buildfile buildClient.xml run.client

Server Side:
---------------
Instructions for building & deploying Axis2 web service archive (DiscoveryService.aar)

1. Run WSDL2Java to generate skeleton code and XMLBeans for data binding
(In srcgen directory)
%AXIS2_HOME%\bin\wsdl2java -ss -sd -d xmlbeans -uri ..\wsdl\Discovery.wsdl -o . -p ndg.services.discovery

NB, when running this command, you may get an error along the lines of:

Exception in thread "main" java.lang.NoSuchMethodError: javax.xml.stream.XMLOutputFactory.newInstance(Ljava/lang/String;Ljava/lang/ClassLoader;)Ljavax/xml/stream/XMLOutputFactory;
        at org.apache.axiom.om.util.StAXUtils.getXMLOutputFactory(StAXUtils.java:97)

- this occurs due to a mismatch in libraries between the versions of java and axis being used.  A
quick fix can be to temporarily hide jre/lib/ext/jsr173_1.0_api.jar.  NB, without this change, the
generated DiscoveryService.wsdl file is likely to be empty.

2. Build server side code (DiscoveryService.aar)
(In srcgen directory)
ant -buildfile buildDiscovery.xml jar.server
(output in build/lib)

3. Optionally build javadoc documentation
ant -buildfile buildDiscovery.xml javadoc

4. Deploy the service
 - Copy DiscoveryService.aar to <tomcat>/webapps/axis/WEB-INF/services (NB, for this step you need to have axis2
 installed in your tomcat server - just drop an axis2.war file into the webapps directory when the server is running)
 - Reload axis2 context within tomcat manager app, or restart tomcat



Code to edit for testing is in ..\src\ndg\services\discovery\DiscoveryServiceClient.java

Tested with Sun Java SDK 1.5.08 (problems with 1.6.03)