This seems reasonable - encapsulating the creation of a child element
within it's parent and have the parent add it at the same time. I think
I'd prefer to stick with the method name 'createXXX' with an appropriate
return type and javadoc explaining that it creates then adds. The name
'createAndAddXXX' seems clunky and 'addXXX' or 'appendXXX' suggest a method
that requires an argument (the thing to add), whereas IMHO 'createXXX'
suits the no-arg style.
But...#1
Although DescriptionElement only has 'addXXX' methods for its direct
children, it has factory-type 'createXXX' methods for all WSDL elements,
not just for the child elements of <description>
(it's adpated from WSDL4J's Definition). Description gets passed around
the Reader, down the parseXXX call path so it can be used as an element
factory. To keep the API consistent, I assume Jeremy's proposal for
DescriptionElement applies across the whole Element model, so that every
parent becomes a factory for creating (and adding) its own child elements.
If so, this involves quite a bit of change in the Reader and the Element
API including:
- Remove all 'addXXX' methods
- Distribute the 'createXXX' methods from DecriptionElement to the
appropriate Elements.
- change the 'createXXX' behaviour to create-and-add
- change the signature of the Reader.parseXXX methods so that they don't
pass the DescriptionElement around (at least not as a factory, but we need
to check if it contains other stuff that the parseXXX methods use).
- fix any test cases broken by these changes (probably the biggest task)
I'm not suggesting this change is bad, just pointing out there's a lot of
work.
And...#2
This change imposes on the Element API what in UML terms is 'composition'
where a class only exists in the context of another class (i.e. it must
have exactly 1 parent or owner). What we have at the moment in the Element
API is 'aggregation' (i.e. an element can be created then later added to
one or more parent elements).
We need to be clear on whether or not there are use cases that require an
element to be created and then added to different parents. I don't think I
understand all the use cases well enough to be certain about enforcing
composition, but I'm keen to hear from Woden users on this (e.g. the Axis2
developers).
For example, as a user of the Woden API creating WSDL via the Element API,
I might want to have an interface containing faults common across the
application that I want to use in multiple service descriptions that share
these common faults. At the infoset level there are multiple <description>
elements each containing the same looking <inteface> element. Even though a
better practise might be to put this interface in its own description and
use import or include for reuse, there's nothing to stop me duplicating the
same <interface> across multiple <description>s. The easiest programming
model here is where I create the InterfaceElement once then add it to the
DescriptionElements that need to use it. It's more work if I have to
re-create what is logically the same InterfaceElement from every
DescriptionElement that needs that interface.
I'm just playing devil's advocate here - maybe this isn't a good example,
but there may be better examples in the WSDL2Java space.
There might be another example with InterfaceMessageReferenceElements. I
could have some common input or output message that I want to use for
multiple operations. In this case I would prefer to create my
InterfaceMessageReferenceElement once, then add it to the
InterfaceOperationElements that need that message format. Under the
proposed change, I would re-create a similar
InterfaceMessageReferenceElement from each InterfaceOperationElement that
used that message format.
Maybe we can enforce composition without introducing more user effort
through cloning. Wherever we define 'createXxx' we could add the method
'cloneXxx(Xxx)' to perform a deep copy and add it to the parent element.
regards,
John Kaputin
Arthur Ryman
<[EMAIL PROTECTED]
> To
[email protected]
09/06/2006 21:02 cc
[EMAIL PROTECTED],
[email protected]
Please respond to Subject
[EMAIL PROTECTED] Re: DescriptionElement create and
he.org add methods
Jeremy,
+1
It doesn't make sense to have unparented child elements.
How about appendXXX() as the method name?
Arthur Ryman,
IBM Software Group, Rational Division
blog: http://ryman.eclipsedevelopersjournal.com/
phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: [EMAIL PROTECTED]
"Jeremy Hughes"
<[EMAIL PROTECTED]>
Sent by: [EMAIL PROTECTED] To
[email protected]
cc
06/09/2006 12:02 PM
Subject
DescriptionElement create
Please respond to and add methods
[email protected]
The DescriptionElement interface has two roles - it acts as a
container for the data in the <description> element and it acts as a
factory for objects representing child elements of <description>.
In the factory role it has createXxxx and addXxxx methods. It is
possible to call createXxxx on one instance of DescriptionElement and
call the associated addXxxx method on a difference instance of
DescriptionElement. I don't think this is necessary so I would like to
contract this into a 'createAndAdd' method - ok I need a better name.
Why bother? Well I want to avoid this scenario:
DescriptionElement desc = new DescriptionImpl();
desc.setTargetNamespace(namespace1);
// Create an interface element, name it and add to the description
element
InterfaceElement interfac = desc.createInterfaceElement();
interfac.setName(name1);
desc.addInterfaceElement(interfac);
// Create another interface element, name it and add to the
description element
InterfaceElement interfac2 = desc.createInterfaceElement();
interfac2.setName(name2);
// Make interfac extend interfac2
// ***
interfac.addExtendedInterfaceName(interfac2.getName());
Because interfac2 hasn't been added to a DescriptionElement at the
point at which interfac2.getName() is called the targetNamespace of
interfac2 is undefined see [1]. It is therefore not possible to supply
interfac with an interface to extend - because the tns of interfac2 is
undefined.
If at *** this line of code is added:
desc.addInterfaceElement(interfac2);
then both interfac and interfac2 will be members of the
DescriptionElement and they will both have a tns defined.
To avoid unnecessary pitfalls for the Woden client programmer I
propose merging the addXxxx and createXxxx methods. After all why
would you create an Xxxx from one DescriptionElement and add it to
another instance!?
[1] http://issues.apache.org/jira/browse/WODEN-25
Cheers,
Jeremy
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
