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

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI01-discovery/branches/ws-Discovery2-upgrade/readme.txt@4142
Revision 4142, 7.2 KB checked in by cbyrom, 12 years ago (diff)

Update Discovery service documentation + restructure packages, creating
common package to store Utilities class + fix build to work with the
new structure.

Line 
1ws-Discovery
2------------
3
4Build Info/Set up
5--------------------
6NB, completing the build here assumes you have both apache axis2 and ant installed.  The AXIS2_HOME environment variable
7should be set to point to the top level directory of the axis2 install.  If you are deploying locally to tomcat, you need
8to set CATALINA_HOME to the home dir of the tomcat install.
9
10The build file, \srcgen\buildDiscovery.xml, now includes targets to run the WSDL2Java code generation and do all the setting up
11described in the original instructions below.  Options for building include:
12with no parameters, e.g.:
13
14ant -f buildDiscovery.xml jar.client - build the test client jar
15ant -f buildDiscovery.xml run.client - build the test client jar and then run it
16ant -f buildDiscovery.xml jar.server - build the server service jar
17ant -f buildDiscovery.xml deploy.server - build the service jar and deploy it to a local tomcat install
18ant -f buildDiscovery.xml reload - build the service jar and deploy it to a local tomcat install + restart tomcat
19ant -f buildDiscovery.xml generatestubs - generate both client and server side stubs - and generate the XBeans jar using the client-side stubs
20ant -f buildDiscovery.xml - defaults to building the service jar
21
22NB, to get the DiscoveryService.wsdl file to be generated properly, you may have to temporarily rename the jsr
23file, as mentioned below.  Also note that the WSDL2JAVA operation generates its own unique version of xmlbeans which is then
24referenced by the generated code - as such you should be careful not to mix the xmlbeans code generated between doing client
25and service jar builds.
26
27To quickly get things up and running, try the following:
281. ant -f buildDiscovery.xml reload
292. If this completes successfully, run the test client:
30ant -f buildDiscovery.xml run.client
313. For a fuller check, run the various unit test cases - which can be done from
32eclipse following the instructions below.
33
34
35Eclipse set up
36-------------------
37To remove build errors in the code, run the build with the 'generatestubs' target, and eclipse is refreshed to pick the
38generated code.  Add all the jars in the resources dir to the build classpath and also add all the jars in the AXIS2_HOME/lib
39dir.
40
41Running tests
42----------------
43There are JUnit tests that can be ran to check the basic integrity of the web services.  For these to be ran from inside
44eclipse, you'll need to add the generated XBeans-packaged.jar (in build/lib) to the build path.  The tests also assume that
45the files test_file.xml and test_file2.xml, in resources, have been ingested to the postgres DB as badc files (i.e. put them
46into the expected harvest directory (currently, /usr/local/jakarta-tomcat/webapps/oai/WEB-INF/harvested_records/badc-nerc-ac-uk-dif)
47and run oai_document_ingester.py badc
48
49Failing tests
50----------------
51There are currently 3 tests that fail:
52
53i) validAuthorTermSearch
54- this fails currently since unsure where the author data should be set and retrieved from
55
56ii) nullDateStartRangeSearch
57- Generated code is a little ropey atm; if a start date is not defined, this date range is automatically
58not set - however if it is it will be - i.e. the end date is not consulted when setting up this object
59- this makes it currently impossible to recognise the case where a start date is null and the end date is set
60- NB, would be better to tighten up WSDL definition so that you can/cannot set things up wrongly
61
62iii) basicPresentDIFFormatCompare
63- This naively assumes the original format returned will equal the DIF format returned (since the original was in
64DIF format).  Clearly there are discrepancies introduced by the transform.
65
66Trouble Shooting
67------------------
68i) The code was ran using the following versions (NB, problems were experienced with other combinations - so if the service is running
69but cannot be reached/throws an exception upon initialisation it is worth trying different versions):
70
71axis2 v1.4
72java 1.6.0_06
73tomcat 5.5.26
74
75ii) 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
76lines of:
77
78java.lang.UnsupportedClassVersionError: Bad version number in .class file
79
80when the webservice is deployed to tomcat.
81
82iii) Be very careful when playing around with the Setsrid sql calls - the following apostrophes must be ' and not ` - NB, eclipse
83may substitute these in which will cause problems which can be difficult to diagnose...
84
85To do
86------------
87i) Currently the time searches use only the 'overlaps' function - i.e. the 'temporalOperator' element of the WS is unused.  This
88could be implemented to allow similar search types to the spatial operator - i.e. within, overlaps and no overlaps
89
90
91Original, detailed instructions, are as follows (but you shouldn't have to use them!):
92
93Client Side:
94---------------
95Instructions for building client (DiscoveryService-test-client.jar)
96
97Do all the following in directory "srcgen"
98
991) Generate automatic code from wsdl :
100%AXIS2_HOME%\bin\wsdl2java -d xmlbeans -uri ..\wsdl\Discovery.wsdl -o . -p ndg.clients.discovery
101
102Edit file src\ndg\clients\discovery\DiscoveryServiceStub.java, after the line (around #104?)
103        _serviceClient = new org.apache.axis2.client.ServiceClient(configurationContext,_service);
104add the line
105        _serviceClient.getOptions().setProperty(org.apache.axis2.transport.http.HTTPConstants.CHUNKED, false);
106
1072) Use ant to compile client jar using custom buildfile
108ant -buildfile buildDiscovery.xml jar.client
109
1103) Use ant to run client
111ant -buildfile buildDiscovery.xml run.client
112
113Server Side:
114---------------
115Instructions for building & deploying Axis2 web service archive (DiscoveryService.aar)
116
1171. Run WSDL2Java to generate skeleton code and XMLBeans for data binding
118(In srcgen directory)
119%AXIS2_HOME%\bin\wsdl2java -ss -sd -d xmlbeans -uri ..\wsdl\Discovery.wsdl -o . -p ndg.services.discovery
120
121NB, when running this command, you may get an error along the lines of:
122
123Exception in thread "main" java.lang.NoSuchMethodError: javax.xml.stream.XMLOutputFactory.newInstance(Ljava/lang/String;Ljava/lang/ClassLoader;)Ljavax/xml/stream/XMLOutputFactory;
124        at org.apache.axiom.om.util.StAXUtils.getXMLOutputFactory(StAXUtils.java:97)
125
126- this occurs due to a mismatch in libraries between the versions of java and axis being used.  A
127quick fix can be to temporarily hide jre/lib/ext/jsr173_1.0_api.jar.  NB, without this change, the
128generated DiscoveryService.wsdl file is likely to be empty.
129
1302. Build server side code (DiscoveryService.aar)
131(In srcgen directory)
132ant -buildfile buildDiscovery.xml jar.server
133(output in build/lib)
134
1353. Optionally build javadoc documentation
136ant -buildfile buildDiscovery.xml javadoc
137
1384. Deploy the service
139 - Copy DiscoveryService.aar to <tomcat>/webapps/axis/WEB-INF/services (NB, for this step you need to have axis2
140 installed in your tomcat server - just drop an axis2.war file into the webapps directory when the server is running)
141 - Reload axis2 context within tomcat manager app, or restart tomcat
142
143
144
145Code to edit for testing is in ..\src\ndg\services\discovery\DiscoveryServiceClient.java
146
147Tested with Sun Java SDK 1.5.08 (problems with 1.6.03)
Note: See TracBrowser for help on using the repository browser.