On Thu, Oct 21, 2010 at 11:07 AM, Schneider Christian <[email protected]> wrote: > Hi Benson, > > where does the style sheet fetch the documentation? From the java code, the > xslt or an external source?
He designed a custom XML schema that attached the doc to identifiers that XSLT could match up with the WSDL. I'll ask him for more details. > 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 >> >
