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

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

Extend trouble shooting section of docs to include the various errors
encountered when installing the service on glue.

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