Uploaded image for project: 'Kuali Rice Development'
  1. Kuali Rice Development
  2. KULRICE-4503

Decide on and document process for how service contracts will be defined and maintained

    Details

    • Type: Task
    • Status: Closed
    • Priority: Critical
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.0
    • Labels:
      None
    • KAI Review Status:
      Not Required
    • KTI Review Status:
      Review Completed

      Description

      There were various discussions here regarding WSDL-first, vs. code-first.

      Jeff and Jason recommend WSDL first because it allows for the contract to be well-defined in it's intended target language as opposed to being generated from code. This helps with compatibility issues.

        Attachments

          Activity

          Hide
          ewestfal Eric Westfall added a comment -

          Here is a note from Eric on his thoughts regarding this subject:

          I've been reading the differing opinions on the subject out there from various people, and I'm starting to think that pure WSDL-first is going to be overkill for Kuali. It also doesn't fit well with our general philosophy on the Rice project since one of the main goals of the project is to speed up the development process. From looking through various WSDLs and reading about the experiences that others have with this approach I can't imagine that being the case. Also, because of the frequent turnover inherent in the way our projects are staffed, I don't see us being able to assign a single person to act as the WSDL expert (notwithstanding that code ownership is something I'm not a big fan of).

          So, that said, I'm wondering if we can consider an alternate approach. In one conversation I read what the author referred to as "code-first contract-aware". Meaning essentially (from what I gathered) that the contract is defined in code, but it is written in such away that the author is aware that they are coding to a contract that will eventually be published out to a WSDL. I think this is actually the approach we are already taking on the Kuali Rice project, so it would fit well with what we are used to.

          The one difference from my perspective is that we would need to establish some improved governance processes surrounding changes to our contracts as well as some rules surrounding when we need to actually reversion the code. I think that regardless of a code-first or contract-first approach we are going to need to do this anyway. It's just a matter of whether the wsdl is locked down or the code contracts from which the wsdl is generated are locked down.

          What I've been thinking about is a setup like the following, let me know what you think:

          1) All service "contracts" are defined as Java interfaces, using JAX-WS to annotate appropriately for the wsdl generation
          2) When generating WSDLs through Apache CXF, we will use the Aegis binding.
          3) All of the operations defined on these contracts will use simple data transfer objects which use types that are supported by default by the Aegis binding (or can be JAX-WS'd appropriately)
          4) DTOs will have no logic in them whatsoever and will simply be used as a wsdl-friendly data representation (we should already be doing this anyway)
          5) All of these contracts and DTOs will be included in a dedicated maven module (this is currently our api module in rice).
          6) The api module can then fall under the governance that we will establish to ensure the proper level of review for suggested or desired changes to the contracts.
          7) All wsdls will be generated statically and included in the Rice jars as well as being published at standard wsdl urls from the application (via the KSBDispatcherServlet). Note that this is one of the main differences between what I'm proposing and what we are doing currently. Right now the wsdl is generated dynamically when it is requested.

          Show
          ewestfal Eric Westfall added a comment - Here is a note from Eric on his thoughts regarding this subject: I've been reading the differing opinions on the subject out there from various people, and I'm starting to think that pure WSDL-first is going to be overkill for Kuali. It also doesn't fit well with our general philosophy on the Rice project since one of the main goals of the project is to speed up the development process. From looking through various WSDLs and reading about the experiences that others have with this approach I can't imagine that being the case. Also, because of the frequent turnover inherent in the way our projects are staffed, I don't see us being able to assign a single person to act as the WSDL expert (notwithstanding that code ownership is something I'm not a big fan of). So, that said, I'm wondering if we can consider an alternate approach. In one conversation I read what the author referred to as "code-first contract-aware". Meaning essentially (from what I gathered) that the contract is defined in code, but it is written in such away that the author is aware that they are coding to a contract that will eventually be published out to a WSDL. I think this is actually the approach we are already taking on the Kuali Rice project, so it would fit well with what we are used to. The one difference from my perspective is that we would need to establish some improved governance processes surrounding changes to our contracts as well as some rules surrounding when we need to actually reversion the code. I think that regardless of a code-first or contract-first approach we are going to need to do this anyway. It's just a matter of whether the wsdl is locked down or the code contracts from which the wsdl is generated are locked down. What I've been thinking about is a setup like the following, let me know what you think: 1) All service "contracts" are defined as Java interfaces, using JAX-WS to annotate appropriately for the wsdl generation 2) When generating WSDLs through Apache CXF, we will use the Aegis binding. 3) All of the operations defined on these contracts will use simple data transfer objects which use types that are supported by default by the Aegis binding (or can be JAX-WS'd appropriately) 4) DTOs will have no logic in them whatsoever and will simply be used as a wsdl-friendly data representation (we should already be doing this anyway) 5) All of these contracts and DTOs will be included in a dedicated maven module (this is currently our api module in rice). 6) The api module can then fall under the governance that we will establish to ensure the proper level of review for suggested or desired changes to the contracts. 7) All wsdls will be generated statically and included in the Rice jars as well as being published at standard wsdl urls from the application (via the KSBDispatcherServlet). Note that this is one of the main differences between what I'm proposing and what we are doing currently. Right now the wsdl is generated dynamically when it is requested.
          Hide
          ewestfal Eric Westfall added a comment -

          I think at this point a decision needs to be made as soon as possible regarding this. I will send a note out to the KTI members to get their thoughts on this subject as well.

          Show
          ewestfal Eric Westfall added a comment - I think at this point a decision needs to be made as soon as possible regarding this. I will send a note out to the KTI members to get their thoughts on this subject as well.
          Hide
          ewestfal Eric Westfall added a comment - - edited

          Note that I was also corrected on my usage of Aegis in this note. Apparently Aegis has it's own set of compatibility issues and a JAX-WS/JAXB approach should be preferred, so this seems like the way we should go here if going code to wsdl.

          Show
          ewestfal Eric Westfall added a comment - - edited Note that I was also corrected on my usage of Aegis in this note. Apparently Aegis has it's own set of compatibility issues and a JAX-WS/JAXB approach should be preferred, so this seems like the way we should go here if going code to wsdl.
          Show
          ewestfal Eric Westfall added a comment - Here are links to some articles I read on each of these subjects when researching this particular item: Articles on Contract-First vs. Code-First: Pro Contract-First: http://msdn.microsoft.com/en-us/magazine/cc163800.aspx http://www.jroller.com/habuma/entry/contract_first_i_do_not contract first does not necessarily mean wsdl-first, writes xsd by hand, generates wsdl using spring-ws http://static.springsource.org/spring-ws/sites/1.5/reference/html/why-contract-first.html Pro Code-First: http://tssblog.blogs.techtarget.com/contract-first-or-code-first-design-part-1/ http://www.infoq.com/articles/sosnoski-code-first http://cxf.apache.org/docs/defining-contract-first-webservices-with-wsdl-generation-from-java.html Neutral: http://wso2.org/library/articles/code-first-or-contract-first-wso2-wsas
          Hide
          ewestfal Eric Westfall added a comment - - edited

          Summarizing my thoughts on this some more, wsdl-first seems like the best and most pristine way to do this. I'm just concerned with the extra development overhead needed in order to support that when it seems to me like java with JAX-WS should be good enough and our development team can write contracts in a language which they are accustomed to. Since part of our goal with the Rice stuff is to make development easier and quicker as well as hiding as much of the gory detail as possible, if we can achieve compatibility via a code-first approach I feel like that is our best option but would like to discuss with the other KTI leads as well.

          Show
          ewestfal Eric Westfall added a comment - - edited Summarizing my thoughts on this some more, wsdl-first seems like the best and most pristine way to do this. I'm just concerned with the extra development overhead needed in order to support that when it seems to me like java with JAX-WS should be good enough and our development team can write contracts in a language which they are accustomed to. Since part of our goal with the Rice stuff is to make development easier and quicker as well as hiding as much of the gory detail as possible, if we can achieve compatibility via a code-first approach I feel like that is our best option but would like to discuss with the other KTI leads as well.
          Hide
          ewestfal Eric Westfall added a comment -

          Added Jeff as a watcher.

          Show
          ewestfal Eric Westfall added a comment - Added Jeff as a watcher.
          Hide
          jwhaley Jason Whaley (Inactive) added a comment -

          Based on the results of going code-first during the 09/01/2010 KTI discussion, should we mark this issue as resolved/closed for version 1.1?

          Show
          jwhaley Jason Whaley (Inactive) added a comment - Based on the results of going code-first during the 09/01/2010 KTI discussion, should we mark this issue as resolved/closed for version 1.1?
          Hide
          ewestfal Eric Westfall added a comment -

          This was reviewed at the KTI on September 1. Decision was to go with a code-first approach.

          Show
          ewestfal Eric Westfall added a comment - This was reviewed at the KTI on September 1. Decision was to go with a code-first approach.
          Hide
          ewestfal Eric Westfall added a comment -

          Resolving this issue as the decision has been made by the KTI working group.

          Show
          ewestfal Eric Westfall added a comment - Resolving this issue as the decision has been made by the KTI working group.

            People

            • Assignee:
              jwhaley Jason Whaley (Inactive)
              Reporter:
              ewestfal Eric Westfall
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: