cxf-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benson Margulies <bimargul...@gmail.com>
Subject Re: Best Practices for documenting service contracts
Date Thu, 21 Oct 2010 14:47:46 GMT
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
<fabio.nogueira.souza@gmail.com> 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 <anne.kuempel@tu-dresden.de> 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
>

Mime
View raw message