[ http://issues.apache.org/jira/browse/AXIS2-917?page=comments#action_12433952 ] Derek Foster commented on AXIS2-917: ------------------------------------
Eran, I appreciate your desire to get Axis 1.1 working code into the hands of users. I think that your belief that documentation is of minimal importance, however, is misguided. Unfortunately, I have seen the above perspective among software developers many times. It comes, I think, from being so close to the code that we can easily forget how the code appears to those who are not close to it. Something I have to remind myself of periodically (usually by having a heated conversation with a very angry, frustrated user) is that documentation is often viewed by developers as an unfortunate "necessary evil" and last priority, but to users it is the PRIMARY INTERFACE TO THE CODE, and of critical importance. Documentation is what tells users what is supposed to be implemented, and how they are supposed to use it. There is very little difference, from a user's perspective, between a bug in the code and a bug in the documentation. Either will result in hours or days of trying to figure out what's going on before (hopefully) solving the problem. And missing documentation is in most cases just as bad as missing code -- the feature can't be used, so it might as well not have been written. I posted this bug because I have spent a couple of weeks trying to figure out fault handling on Axis2, and have still been unable to do so. This is despite hours of tinkering, communicating on the mailing lists, and so forth. I have seen other frustrated people posting to the mailing lists also having the same problems. I suspect that there are some bugs in Axis2 in how fault handling is implemented, which are at least part of the problem. AXIS2-1052 is one such. AXIS2-931, which you just fixed (thanks!) is another. There may be more. However, I can't be sure, because there is no documentation on how they are supposed to work, so I have nothing to compare against to state whether what I have seen happening is or is not erroneous behavior, or whether I'm just "trying to use it wrong." Trying to solve a problem this way is like trying to thread a needle in the dark. I have not been able to find a single working example of the simplest form of fault handling using WSDL2Java, namely, "report back to the user that error 'foo', described using the following text, has happened." Whether fault handling works at all in Axis2 is a matter of debate, which cannot be resolved until someone puts an example in the user guide or elsewhere of some code that is supposed to work, and then someone like me can try to run the code to verify whether it actually does work as it's supposed to. Thus, lack of documentation is preventing real bugs from being filed and fixed. I would be happy to contribute some documentation for fault handling once I have figured out how it is supposed to work. This has not yet happened. Everything plausible that I have tried so far has failed. The closest I have gotten to a working example is to be able to send a fault with no message back to my client. All the ways I have tried to specify a detail message produce no result, for no obvious reason. This is not a "minor" problem for me, as the new rating for this bug that you specified seems to imply. WSDL2Java-generated webservices need to be able to report errors back to their clients. According to its documentation, Axis2 has no way to do this. > User guide should give explanation and examples of fault handling > ----------------------------------------------------------------- > > Key: AXIS2-917 > URL: http://issues.apache.org/jira/browse/AXIS2-917 > Project: Apache Axis 2.0 (Axis2) > Issue Type: Wish > Components: samples, build,site & docs > Affects Versions: 1.0 > Reporter: Derek Foster > Assigned To: Eran Chinthaka > Priority: Minor > Attachments: sampleService-wsdl.rar > > > The Axis2 user guide provides no examples of: > 1) The WSDL to declare that a fault may be thrown from an operation > (suitable for passing into WSDL2Java) > 2) The server-side code for a fault exception, as generated by WSDL2Java > and modified as a user might be expected to modify it. > 3) The server-side code to throw the fault exception, including a tested > example of passing on a custom error message to be transmitted as part of a > SOAP fault (in the faultDetail) and received by the client. > 4) The client-side code for receiving and handling a fault. > Furthermore, what discussion of faults that there is seems fairly > contradictory. For instance, there are various suggestions that throwing an > AxisFault exception from a service is the way to issue a fault. However, > WSDL2Java does not generate service methods that are declared to throw > AxisFault, and there seems to be no way to declare such a fault in WSDL. (at > least, none that I can find). Fault generation from a service that was not > generated by WSDL2Java should be treated as a separate section, since it is > handled in a totally different manner by server code. I think that both kinds > of fault handling need to be documented clearly in the user guide. > I have been trying for weeks to figure out how this is supposed to work, and > still haven't gotten it to work quite right (my custom error message included > in the thrown fault exception is getting lost somewhere before the SOAP fault > is transmitted). This is a basic feature that should be documented clearly. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
