Woden
  1. Woden
  2. WODEN-20

Component model API needs modifiers

    Details

    • Type: New Feature New Feature
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: 1.0
    • Component/s: Parser
    • Labels:

      Description

      A Woden 'client' - eg a tool such as java2wsdl - might want to:

      1 introspect a tree of java classes / interfaces
      2 create an org.apache.woden.wsdl20.Interface for each - adding to the Description object along the way
      3 serialize to disk.

      Today it is only possible to modify the object form of the WSDL through the Element model API. This requires the client app to understand WSDL at the file level.

      For step 2 addInterface() is required on Description. Of course Interface.addInterfaceOperation() is then required and so on...
      For step 3 a 'strategy' is needed to map from the Component model to the Element model's representation of the WSDL in file form. e.g. do all the <interface> elements go in the same WSDL file or do all the <interface> elements in the same namespace go in one file etc. Also, do the <service> elements go in separately included/imported WSDL files as is typically the best practice with WSDL 1.1. All these options could be represented using a strategy pattern.

      1. WodenProposal_Dilshan.pdf
        36 kB
        Dilshan Edirisuriya
      2. EditablePackage.patch
        12 kB
        Dilshan Edirisuriya
      3. woden-api.patch
        33 kB
        Dilshan Edirisuriya
      4. woden-commons.patch
        27 kB
        Dilshan Edirisuriya

        Activity

        Hide
        Arthur Ryman added a comment -

        I'd like to see this as a separate interface, i.e. create a read-write interface that extends the read-only interface. The read-write interface will need additional methods to control the placement of components in documents, and other serialization details. We don't want to make the current read-only interface overly complex so it's best to separate this function into a new read-write interface.

        Show
        Arthur Ryman added a comment - I'd like to see this as a separate interface, i.e. create a read-write interface that extends the read-only interface. The read-write interface will need additional methods to control the placement of components in documents, and other serialization details. We don't want to make the current read-only interface overly complex so it's best to separate this function into a new read-write interface.
        Hide
        Arthur Ryman added a comment -

        This is not required for the W3C Test Suite so let's defer this until after the spec is completed.

        Show
        Arthur Ryman added a comment - This is not required for the W3C Test Suite so let's defer this until after the spec is completed.
        Hide
        Dilshan Edirisuriya added a comment -

        Proposed design for this issue

        Show
        Dilshan Edirisuriya added a comment - Proposed design for this issue
        Hide
        Arthur Ryman added a comment -

        Dilshan, nice writeup. I have a few comments.

        1. Naming if new interfaces. You prefixed all the component model names with "Editable" which makes them long. Perhaps you could keep the existing names, but but them in a new "editable" package.

        2. The file serialization strategy relies and naming conventions to generate the file names. This means you can't handle the important use case of editing an existing set of WSDL 2.0 files. Suppose you start with a set of WSDL 2.0 files and want to modify them. You should serialize them back into the same files. This works unless the user creates new top-level components. In this case the user should be able to specify the name of the file. So I think the interface for creating a new top-level component should let to specify the name the file, or maybe an output stream.

        Show
        Arthur Ryman added a comment - Dilshan, nice writeup. I have a few comments. 1. Naming if new interfaces. You prefixed all the component model names with "Editable" which makes them long. Perhaps you could keep the existing names, but but them in a new "editable" package. 2. The file serialization strategy relies and naming conventions to generate the file names. This means you can't handle the important use case of editing an existing set of WSDL 2.0 files. Suppose you start with a set of WSDL 2.0 files and want to modify them. You should serialize them back into the same files. This works unless the user creates new top-level components. In this case the user should be able to specify the name of the file. So I think the interface for creating a new top-level component should let to specify the name the file, or maybe an output stream.
        Hide
        Dilshan Edirisuriya added a comment -

        Thanks Arthur for your valuable comments. I have following doubts.

        1) Most of the time people don't use qualified names within the body of the classes. When it refers to classes as there can be multiple classes with the same name people can get confused. So is this a good approach. What do you think?

        2) At the moment I don't have a clear idea to handle this use case. May be I can come up with a good solution later.

        Any suggestion is welcome.

        Show
        Dilshan Edirisuriya added a comment - Thanks Arthur for your valuable comments. I have following doubts. 1) Most of the time people don't use qualified names within the body of the classes. When it refers to classes as there can be multiple classes with the same name people can get confused. So is this a good approach. What do you think? 2) At the moment I don't have a clear idea to handle this use case. May be I can come up with a good solution later. Any suggestion is welcome.
        Hide
        Arthur Ryman added a comment -

        Dilshan, If programmers need to use both the read-only and the read-write interfaces together, then it would be awkward. I assume programmers will only use one or the other. Leaving "Editable" in the names is OK.

        Show
        Arthur Ryman added a comment - Dilshan, If programmers need to use both the read-only and the read-write interfaces together, then it would be awkward. I assume programmers will only use one or the other. Leaving "Editable" in the names is OK.
        Hide
        Dilshan Edirisuriya added a comment -

        Thanks Arthur for your valuable comments. I will follow that.

        Show
        Dilshan Edirisuriya added a comment - Thanks Arthur for your valuable comments. I will follow that.
        Hide
        Sagara Gunathunga added a comment -

        "Arthur Ryman added a comment - 07/May/10 03:30 PM
        Dilshan, If programmers need to use both the read-only and the read-write interfaces together, then it would be awkward. I assume programmers will only use one or the other. Leaving "Editable" in the names is OK. "

        Arthur ,

        Above suggestion is much more clear with your assumption ,but practically this is not always possible. As an example if I take the use case mentioned in your 2nd point modifying existing WSDL file ; first WSDLReader returns object of Description type and then in order to modify the content user should cast into editable.Description, here we can see both read-only and read-write APIs together. In such scenarios user needs to use both APIs together.

        Also it is not possible to pre-determine the exact place where the user move in to one API to a another , as an example to add new child component to a Binding component of a existing WSDL file user has following two ( or more) options.

        1.) First read the file, cast Description into editable.Description and retrieve child components to reach to the particular editable.Binding component and add new child component.

        2.)First read the file and use Description component to reach to the particular Binding and once he want to add new child component cast Binding into edtable.Binding.

        I have two suggestion for this

        1.) Simply use "Ed" or "E" like prefix instead "Editable" to short the new interface names.

        2.) Use Arthur's suggestion with a convention /policy.

        We can introduce a policy something like if a user plan for a modification in future he should move into the read-write API at the top level by casting Description into editable.Description this will reduce mixing components from both APIs together. Also it is possible to encourage user to follow this policy by introducing a method like makeEditable() on Description interface ( public editable.Description makeEditable()

        {...}

        ). WDYT ?

        " Arthur Ryman added a comment - 07/May/10 03:30 PM
        2. The file serialization strategy relies and naming conventions to generate the file names. This means you can't handle the important use case of editing an existing set of WSDL 2.0 files. Suppose you start with a set of WSDL 2.0 files and want to modify them. You should serialize them back into the same files. This works unless the user creates new top-level components. In this case the user should be able to specify the name of the file. So I think the interface for creating a new top-level component should let to specify the name the file, or maybe an output stream. "

        I'm little confusing with this , Component level API does not contains any knowledge about physical constructs of a WSDL doc , there is no Imports or Includes. Once the user read a WSDL file and serialize back to the file using WSDLWriter it is necessary to preserve the physical constructs but when he serialize using Component level API is it necessary to preserve same physical structure ?

        IMO when he serialize using Component level API he can select one of the defined strategy and this behavior is same for both newly created docs and existing docs .

        Show
        Sagara Gunathunga added a comment - "Arthur Ryman added a comment - 07/May/10 03:30 PM Dilshan, If programmers need to use both the read-only and the read-write interfaces together, then it would be awkward. I assume programmers will only use one or the other. Leaving "Editable" in the names is OK. " Arthur , Above suggestion is much more clear with your assumption ,but practically this is not always possible. As an example if I take the use case mentioned in your 2nd point modifying existing WSDL file ; first WSDLReader returns object of Description type and then in order to modify the content user should cast into editable.Description, here we can see both read-only and read-write APIs together. In such scenarios user needs to use both APIs together. Also it is not possible to pre-determine the exact place where the user move in to one API to a another , as an example to add new child component to a Binding component of a existing WSDL file user has following two ( or more) options. 1.) First read the file, cast Description into editable.Description and retrieve child components to reach to the particular editable.Binding component and add new child component. 2.)First read the file and use Description component to reach to the particular Binding and once he want to add new child component cast Binding into edtable.Binding. I have two suggestion for this 1.) Simply use "Ed" or "E" like prefix instead "Editable" to short the new interface names. 2.) Use Arthur's suggestion with a convention /policy. We can introduce a policy something like if a user plan for a modification in future he should move into the read-write API at the top level by casting Description into editable.Description this will reduce mixing components from both APIs together. Also it is possible to encourage user to follow this policy by introducing a method like makeEditable() on Description interface ( public editable.Description makeEditable() {...} ). WDYT ? " Arthur Ryman added a comment - 07/May/10 03:30 PM 2. The file serialization strategy relies and naming conventions to generate the file names. This means you can't handle the important use case of editing an existing set of WSDL 2.0 files. Suppose you start with a set of WSDL 2.0 files and want to modify them. You should serialize them back into the same files. This works unless the user creates new top-level components. In this case the user should be able to specify the name of the file. So I think the interface for creating a new top-level component should let to specify the name the file, or maybe an output stream. " I'm little confusing with this , Component level API does not contains any knowledge about physical constructs of a WSDL doc , there is no Imports or Includes. Once the user read a WSDL file and serialize back to the file using WSDLWriter it is necessary to preserve the physical constructs but when he serialize using Component level API is it necessary to preserve same physical structure ? IMO when he serialize using Component level API he can select one of the defined strategy and this behavior is same for both newly created docs and existing docs .
        Hide
        Arthur Ryman added a comment -

        Sagara,

        I think we need to go back and state what use cases we are trying to satisfy. The potential uses cases are:

        1. Support java2wsdl via the Component API.
        2. Support editing an existing set of WSDL documents via Component API

        What is the scope of this enhancement?

        Show
        Arthur Ryman added a comment - Sagara, I think we need to go back and state what use cases we are trying to satisfy. The potential uses cases are: 1. Support java2wsdl via the Component API. 2. Support editing an existing set of WSDL documents via Component API What is the scope of this enhancement?
        Hide
        Sagara Gunathunga added a comment -


        I think we need to support both use cases create new WSDL via the Component API and modifying existing WSDL via the Component API.

        Show
        Sagara Gunathunga added a comment - I think we need to support both use cases create new WSDL via the Component API and modifying existing WSDL via the Component API.
        Hide
        Lawrence Mandel added a comment -

        I'll echo the comments that this is a good write up that may simply need a few tweaks.

        1. I agree that using the same interface names for the editable interface will likely be problematic.

        2. >2.)Create a new method called, 'Add(Component subComponent)' to add the existing sub component to
        >the component. This method will be needed for the Serializatio
        >3.)Create new methods, 'attach(Component subComponent)' and 'detach(Component subComponent)',

        Do the attach and add methods perform similar function? I'm not clear on the difference according to the description.

        3. For serialization, how about a strategy that separates the abstract descriptions from the concrete implementation details. In this scenario schemas will be written to their own files (I consider this a best practice), interfaces will be written to one WSDL file that is then included in a WSDL file containing the bindings and services.

        Show
        Lawrence Mandel added a comment - I'll echo the comments that this is a good write up that may simply need a few tweaks. 1. I agree that using the same interface names for the editable interface will likely be problematic. 2. >2.)Create a new method called, 'Add(Component subComponent)' to add the existing sub component to >the component. This method will be needed for the Serializatio >3.)Create new methods, 'attach(Component subComponent)' and 'detach(Component subComponent)', Do the attach and add methods perform similar function? I'm not clear on the difference according to the description. 3. For serialization, how about a strategy that separates the abstract descriptions from the concrete implementation details. In this scenario schemas will be written to their own files (I consider this a best practice), interfaces will be written to one WSDL file that is then included in a WSDL file containing the bindings and services.
        Hide
        Dilshan Edirisuriya added a comment -

        Thanks Lawrence for your comments. Please find my comments for the above points.

        1) I think this needs to be finalized based on your agreement.

        2) Add method encapsulates calls component creation and also it will add the parent to this created component. This is similar to element level API. Attach method simply set existing component to a parent and deattach method removes a component from a parent.

        3) Seems to be a good strategy. I will try to implement it.

        Show
        Dilshan Edirisuriya added a comment - Thanks Lawrence for your comments. Please find my comments for the above points. 1) I think this needs to be finalized based on your agreement. 2) Add method encapsulates calls component creation and also it will add the parent to this created component. This is similar to element level API. Attach method simply set existing component to a parent and deattach method removes a component from a parent. 3) Seems to be a good strategy. I will try to implement it.
        Hide
        Lawrence Mandel added a comment -

        Thanks for the follow-up details. One further question/comment:

        2. Is this Add method the factory method you referenced in your document or is there another mechanism to create components? I think that there should be a single approach to create components. If this is through a standard factory then components should be created and attached eliminating the need for the Add method.

        Show
        Lawrence Mandel added a comment - Thanks for the follow-up details. One further question/comment: 2. Is this Add method the factory method you referenced in your document or is there another mechanism to create components? I think that there should be a single approach to create components. If this is through a standard factory then components should be created and attached eliminating the need for the Add method.
        Hide
        Dilshan Edirisuriya added a comment -

        Thanks Lawrence

        Yes the add method is the factory method for components.

        Show
        Dilshan Edirisuriya added a comment - Thanks Lawrence Yes the add method is the factory method for components.
        Hide
        Dilshan Edirisuriya added a comment -

        I have completed the interface of the new editable package. Please find the initial patch.

        Show
        Dilshan Edirisuriya added a comment - I have completed the interface of the new editable package. Please find the initial patch.
        Hide
        Sagara Gunathunga added a comment -

        Applied above patch to the Woden-20 branch.

        Show
        Sagara Gunathunga added a comment - Applied above patch to the Woden-20 branch.
        Hide
        Sagara Gunathunga added a comment -

        There were few issue with patches but manged to apply them and merge to the trunk.

        Show
        Sagara Gunathunga added a comment - There were few issue with patches but manged to apply them and merge to the trunk.
        Hide
        Hudson added a comment -

        Integrated in woden-trunk #538 (See https://builds.apache.org/job/woden-trunk/538/)
        Merged woden-20 changes from woden-20 branch.

        Show
        Hudson added a comment - Integrated in woden-trunk #538 (See https://builds.apache.org/job/woden-trunk/538/ ) Merged woden-20 changes from woden-20 branch.

          People

          • Assignee:
            Dilshan Edirisuriya
            Reporter:
            Jeremy Hughes
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:

              Development