xotcl.wu-wien.ac.at
Begin main content
Search · Index
No registered users in community xorb-faq
in last 10 minutes

xorb faq

xorb faq


C Contributing

Issues related to contributing bug reports, debugging, code and documentation

C.1 How to debug and contribute bug reports

Question:

I encountered an unexpected or even errorenous behaviour. How can I best report relevant details to trace the issue?

Answer:

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.)

D Documentation and examples

Issues related to documentation work, examples provided etc. 

D.1 Demo services

Question:

Are there any demo services available? 

Answer:

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/.

D.2 SOAP examples

Question:

Where can I find code examples related to the xosoap plug-in that go beyond the quick start tutorial?

Answer:

Demo consumers/ clients are usually added to the xotcl-soap/www/demo directory. Just browse it or connect to the client scripts.

E Errors

Take a look if you become victim of mysterious error (messages) 

E.1 ArgumentTransformationException

Question:

I got returned something saying like:

<exception type="::xorb::exceptions::ArgumentTransformationException">
        <message>can't read "arr(-parameters:required)": no such element in array</message>
        <description>
    Mapping non-positional arguments to positional ones failed.
  </description>

Answer:

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.

E.2 ::xorb::manager::Broker: wrong # args

Question:

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"

Answer:

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.

F Framework interoperability

Issues pertaining to interworkings with established frameworks 

F.1 Axis

Question:

Does xorb/ xosoap interoperate with the AXIS framework family? 

Answer:

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.

G Glossary

Explaining terms and concepts related to xorb and its plug-ins

G.1 WSDL Styles

Question:

What are the WSDL styles supported by xosoap? What are WSDL styles anyway? 

Answer:

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).
 

I Installation (and the like)

Issues related to installation, upgrades, and migration

I.1 Migration from version 0.3 to 0.4

Question:

How can I smoothly migrate from an existing 0.3 installation to 0.4? 

Answer:

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.

I.2 Accessing auto-generated wsdl: Differences between 0.3 and 0.4

Question:

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?

Answer:

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.

ID Interface descriptions

Issues pertaining to interface descriptions as used and provided by xorb and its plug-ins, namely WSDL. 

SC Service contracts

Issues related to handling service contracts. 

SC.1 Removing service contracts

Question:

Once defined, how can I remove service contracts again?

Answer:

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.

SI Service implementations

Issues related to handling service implementations 

SI.1 Removing service implementations

Question:

How can I remove my service implementation again, once I successfully defined it? 

Answer:

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.
 

T Testing

Questions related to testing your xorb code.

T.1 Testing SOAP services/ providers

Question:

How can I test my newly created soap service? 

Answer:

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
    % 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.