in last 10 minutes
- C Contributing
- D Documentation and examples
- E Errors
- F Framework interoperability
- F.1 Axis
- G Glossary
- G.1 WSDL Styles
- I Installation (and the like)
- ID Interface descriptions
- SC Service contracts
- SI Service implementations
- T Testing
Issues related to contributing bug reports, debugging, code and documentation
I encountered an unexpected or even errorenous behaviour. How can I best report relevant details to trace the issue?
I encountered an unexpected or even errorenous behaviour. How can I best report relevant details to trace the issue?Attach the following detailed information to your narrative description:
- xorb version installed
- xosoap version installed
- xotcl-core + XOTcl version installed
- AOLserver environment: AOLServer version + thread extension (libthread) used.
- package parameter settings for xorb + xosoap
In addition, provide the following:
- Your code (ideally, in a stripped-down example) that might cause the observed behaviour.
- Switch to AOLServer debug mode (modify the relevant entry in your config.tcl), try to reproduce the behaviour and attach the error.log file to your bug report (you might want to send it along by email, as it might be too verbose for the OACS forums etc.)
Issues related to documentation work, examples provided etc.
Are there any demo services available?
If you browse through the manual , especially the quick start sections, you will find some examples. Those SOAP provider examples are automatically activated upon installation of the xotcl-soap protocol plug-in. Simply look at /xosoap/services to see what is listening. You then can use the consumer/ client examples that come with the manual to connect to the example services.
More advanced examples are provided by the implementation of the SoapInterop Lab test suites , see xotcl-soap/tcl/zz-demo/interop2-base-server-init.tcl etc. You will also find the services listening if you connect to /xosoap/services/.
Where can I find code examples related to the xosoap plug-in that go beyond the quick start tutorial?
Demo consumers/ clients are usually added to the xotcl-soap/www/demo directory. Just browse it or connect to the client scripts.
Take a look if you become victim of mysterious error (messages)
I got returned something saying like:
<message>can't read "arr(-parameters:required)": no such element in array</message>
Mapping non-positional arguments to positional ones failed.
If you just upgraded to 0.4, you probably missed the required changes to your service contract and service implementation code. Please, check out en:migration0.3 and, in particular, make sure that you get the part on ::xorb::Method and non-positional arguments right.
I encountered a weird behaviour which was reported as invocation
exception and the error stack says something like:
- "wrong # args: should be "save"- ::xorb::manager::Broker ::xorb::ServiceContract->save"
- "wrong # args: should be "stream"- ::xorb::manager::Broker ::xorb::ServiceContract->stream"
xorb uses a broker that resides in a persistent thread. it, therefore, requires explicit clean-up operations upon failure conditions etc. Since its very beginning, we missed out some crucial clean-up and the above errors document a stateful broker having been corrupted. We introduced necessary fixes in revision 112 of xorb and they will be shipped out with the upcoming 0.4.2 release. A straight-forward fix is the re-start of the AOLServer.
Issues pertaining to interworkings with established frameworks
Does xorb/ xosoap interoperate with the AXIS framework family?
We know of uses in interplay with AXIS 1 + 2, both consumer- and provider side. Within the feature set supported by xosoap, we do not know of any particular incompatibility.
Explaining terms and concepts related to xorb and its plug-ins
What are the WSDL styles supported by xosoap? What are WSDL styles anyway?
WSDL basically describes four aspects: 1-) A remote interface (operations, parameters etc.), 2-) "types" for these parameters (parameters are actually grouped in input and output messages), 3-) rules how to create the XML messages used to exchange operation calls between two ends, and 4-) interaction styles. The terms "RPC/Encoded", "RPC/Literal", and "Document/Literal" refer to this rule set, and describe two aspects:
- "Document" vs. "RPC": Document means, the XML message to expect from either side is "well-formed and valid XML document" you can not only throw in XML parsers but also validate against schema descriptions (RelaxNG, XML Schema). The opposite style is RPC, and in fact, the only difference (looking at XML messages in Document and RPC styles) is that in RPC, the name of the remote operation is part of the message, as an XML element. In Document style, it is not!!!! So what is the key difference now, well, how should the receiving end of this message now which local operation to invoke on??? So what the key difference here is that dispatch resolution needs to be handled differently (taking http header information, etc.)
What has been said so far reflects more or less practical aspects, especially looking at the (de-)marshaling of messages exchanged. Conceptually, however, there are major implications. RPC (or OO-RPC if we talk about objects) is about atomic operation calls that are handed back and forth. Document style is not bound to any concept of operation call, interactions need not to be as atomic as the somewhat distributed object system would imply. In fact, Document messages might be used to exchange batched operations or aggregated object states. Just to name some rough examples.
- "Literal" vs. "Encoded": Literal translates to "literal meaning" which means taking the XML message that comes in as is, a self-contained generic XML document. "Encoded", on the contrary, means that it is not generic XML, but a "dialect of XML" that one should expect. For instance, associatives arrays can be expressed differently (marshaled differently).
Issues related to installation, upgrades, and migration
How can I smoothly migrate from an existing 0.3 installation to 0.4?
There is some upgrade logic, at least in the sense of OpenACS (upgrade scripts, callbacks etc.). We, though, encourage you the make a complete re-install if you wish to migrate from 0.3 to 0.4. If you simply can't, you might follow these steps:
- Get the source code by means of your choice for xorb and xosoap and put it in place.
- Proceed with the APM upgrade
- You might now continue with a restart. However, be aware, that you might encounter errors (in the logs) due to changes in the way contracts and implementations are specified. To comply to the 0.4 interface for contract and implementation specifications, make sure, that you change your code along the following lines:
- Service contracts now need to be deployed explicitly. Therefore, add "deploy" calls to you specification objects, similarily to service implementations.
- As for ::xorb::Delegate, change "-proxies" to "-for"
- As for ::xorb::Method: Arguments are now handled as complete non-positional arguments as known by XOTcl. Make sure that you prepend single dashes ("-") in the argument declaration.
- Finally, do a restart and you should have successfully migrated to 0.4!
There are some minor limitations as the upgrade logic can't properly deal with some rare cases. However, they should not conflict with an operative 0.4 installation. Let me know if you encounter strange behaviour.
As in 0.3, I try to connect http://<some-service-uri>?wsdl, but I only get back an error message such as "::xosoap::exceptions::UIRequestException". What happened?
Starting with 0.4, xosoap has a more generic dispatcher. Try http://<some-service-uri>?s=wsdl instead and you should find what you are looking for. Anyway, try to connect to /xosoap/services/ and you will find a list of deployed and listening services, including pointers to the auto-generated wsdl for your convenience.
Issues pertaining to interface descriptions as used and provided by xorb and its plug-ins, namely WSDL.
Issues related to handling service contracts.
Once defined, how can I remove service contracts again?
In two simple steps:
- First, make sure that you comment out or remove the "deploy" call on your service contract specification object. This will cause the specification not to be materialsed as contract in the data base etc.
- Second, the remove the current materialisation of the service contract, direct your browser to /request-broker/admin and remove the service contract by clicking the delete button.
Issues related to handling service implementations
How can I remove my service implementation again, once I successfully defined it?
In two simple steps:
- First, make sure that you comment out or remove the "deploy" call on your service implementation specification object. This will cause the specification not to be materialised as implementation in the data base etc.
- Second, remove the current materialisation of the service implementation. Therefore, direct your browser to /request-broker/admin and remove the service implementation by clicking the delete button.
Questions related to testing your xorb code.
How can I test my newly created soap service?
You have various options at hand:
- For functional testing, you can use your service implementation, i.e. the specification object, as any XOTcl object that you might call directly. This is particular interesting for specification objects that are servants at the same time. Take the following example (referring to the example EchoServiceImpl in the quick start sections of the manual ):
set tester [EchoServiceImpl new]
$tester echoMe -inputFloat 1.2455
- For invocation testing, you might either build a soap consumer by means of xosoap (see manual or use third-party client/ consumer frameworks. The latter can make use of the auto-generated WSDL for the services deployed.
- Scaffold testing (i.e. having a UI representation of a soap client) will be available in upcoming releases.