Hi Benson, where does the style sheet fetch the documentation? From the java code, the xslt or an external source? In any case a xslt solution should allow integration into the build process of the wsdl so this could also work for us.
Do you do any further documentation like in wiki? Thanks Christian Christian Schneider Informationsverarbeitung Business Solutions Handel und Dispatching Tel : +49-(0)721-63-15482 EnBW Systeme Infrastruktur Support GmbH Sitz der Gesellschaft: Karlsruhe Handelsregister: Amtsgericht Mannheim HRB 108550 Vorsitzender des Aufsichtsrats: Dr. Bernhard Beck Geschäftsführer: Jochen Adenau, Hans-Günther Meier -----Ursprüngliche Nachricht----- Von: Benson Margulies [mailto:[email protected]] Gesendet: Donnerstag, 21. Oktober 2010 16:48 An: [email protected] Betreff: Re: Best Practices for documenting service contracts Our Doc person wrote an XSLT stylesheet that would add doc elements to a from-java wsdl. On Thu, Oct 21, 2010 at 9:27 AM, Fabio souza <[email protected]> wrote: > Hi Anne, > > I am also very interested in this topic. Just like you, I am > researching this area from an academical point of view. My focus is on > QoS based dynamic service composition. The idea is to propose a > solution that supports some kind of QoS negotiation and partner > selection based on QoS parameters. To do that, it is essential to > monitor QoS aspects. In my case, I am considering doing that in an > heterogeneous environment on which the idea of services includes WS > but OSGi too. Currently, I am studying how to do the monitoring part. > Maybe we could exchange some references and ideas. > > Best regards, > > Fábio > > > > > On Thu, Oct 21, 2010 at 4:24 AM, Anne Kümpel <[email protected]> > wrote: >> Hi all, >> >> I working in the research area of services, SLA, monitoring of QoS and so >> on. This topic is really interesting for me. While in the academical >> environment we look for formalize and automate the Service Level Agreements >> and all this around, but how far I know in the companies, in the real world >> ;) , the SLA are normally plain text documents. >> >> So, how is your handling around this, how you negotiate, create and document >> SLA, you use or tried to use any SLA formalization like WSLA, WSAG, SLAng or >> what ever and what further documents (Price schema f.e.) you have or how >> Christian allready ask "how people do the further documentation that lives >> outside the wsdl." >> >> Thanks and best regards >> Anne >> >> Am 21.10.2010 08:35, schrieb Christian Schneider: >>> >>> I know that the wsdl stuff like methods can be documented. The real >>> interesting stuff is the schema though. As you said documentation for >>> the schema depends on jaxb. So I guess the jaxb team has to add the >>> feature. >>> I just checked their issues and found some: >>> https://jaxb.dev.java.net/issues/show_bug.cgi?id=273 >>> https://jaxb.dev.java.net/issues/show_bug.cgi?id=369 >>> https://jaxb.dev.java.net/issues/show_bug.cgi?id=460 >>> >>> Anyway I am more interested in how people do the further documentation >>> that lives outside the wsdl. I guess anyone who seriously uses services >>> has a lot more documentation than only the wsdl. >>> >>> Best Regards >>> >>> Christian >>> >>> >>> Am 20.10.2010 20:57, schrieb Daniel Kulp: >>>> >>>> On Wednesday 20 October 2010 9:42:35 am Schneider Christian wrote: >>>>> >>>>> Hi All, >>>>> >>>>> I am currently making a concept how to do service documentation at my >>>>> company. One of the problems is documenting the service contract. >>>>> >>>>> At the moment we use a wiki where we create one page per service with >>>>> some >>>>> technical and business documentation. Of course the WSDL is linked >>>>> the but >>>>> it only shows the syntax not the semantic. So we additionally document >>>>> each method and data structure in the wiki. The problem is that the wiki >>>>> will not notice when the structure of the contract changes so it is >>>>> quite >>>>> tedious manual work to keep them in sync. A nice addition we recently >>>>> did >>>>> is to refrence the wsdl viewer xslt from tomi vanek in our wsdls >>>>> (http://tomi.vanek.sk/index.php?page=wsdl-viewer). This formats the wsdl >>>>> as a web page that you can even show the business people. >>>>> >>>>> We could also add documentation elements to the wsdl but this has two >>>>> problems. The first is that we generate the wsdls out of java code >>>>> (as it >>>>> is easier than writing wsdls by hand) and the generation does not >>>>> support >>>>> generating documentation. >>>> >>>> Well, if you upgrade to CXF 2.3.0, we DO have the @WSDLDocumentation >>>> annotations to allow you to provide additional documentation into the >>>> generated WSDL. It only allows into the wsdl constructs and not the >>>> schema >>>> stuff (generated from the databinding such as JAXB), but that would >>>> provide >>>> some documentation. >>>> >>>> Dan >>>> >>>> >>>>> The other and bigger problem is that the >>>>> dcoumentation in the wsdl is much more difficult to change especially >>>>> comapred with the ease of use of a wiki. >>>>> >>>>> So my question is: How do you document your services? Do you use some >>>>> clever low tech solutions? Did you write your own kind of repository >>>>> or do >>>>> you use a commercial or open source product? >>>>> >>>>> Thanks >>>>> >>>>> Christian >>>>> >>>>> >>>>> >>>>> >>>>> Christian Schneider >>>>> Informationsverarbeitung >>>>> Business Solutions >>>>> Handel und Dispatching >>>>> >>>>> Tel : +49-(0)721-63-15482 >>>>> >>>>> EnBW Systeme Infrastruktur Support GmbH >>>>> Sitz der Gesellschaft: Karlsruhe >>>>> Handelsregister: Amtsgericht Mannheim - HRB 108550 >>>>> Vorsitzender des Aufsichtsrats: Dr. Bernhard Beck >>>>> Geschäftsführer: Jochen Adenau, Hans-Günther Meier >>> >> > > > > -- > Fábio >
