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