You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by Glen Daniels <gl...@thoughtcraft.com> on 2004/12/04 23:29:15 UTC

[Axis2] OM issues

Some comments about OM:

* Regardless of what we do with respect to "full infoset support", I 
think that it's important to factor the SOAP-specific stuff now so that 
we have the ability to cleanly allow OM to evolve into something people 
can use to do XML+datbinding+XOP even without SOAP.  I'd suggest very 
strongly that we a) rename OMEnvelope/OMHeader/OMBody/OMFault to 
SOAPEnvelope/SOAPHeader/SOAPBody/SOAPFault, and b) put them in another 
package, perhaps org.apache.axis.om.soap, or org.apache.axis.soap.

* Despite SAAJ doing it this way, I really don't like having a separate 
object for SOAPHeader and SOAPBody, especially since you don't really do 
anything with them except use them as containers.  To me, it's much more 
natural to have the SOAPEnvelope class allow you to add/remove/view 
headers (the world calls them "headers" and not "header blocks", so I'd 
prefer the API to as well) and bodies without using the extra layer of 
objects.  Example:

SOAPEnvelope env = new SOAPEnvelope(VERSION11);
SOAPHeader security = SecurityExtension.makeSecurityHeader();
env.addHeader(security);
env.getHeaderByQName(qname);
...etc...

* I don't understand the examine/extract APIs for header blocks.  Why do 
we need extract?  Can't the user just remove them themselves?

* I think that a given SOAPEnvelope should have a "context" of some kind 
associated with it, which includes at least the currently active roles. 
  Then when you iterate over the headers, the default behavior is to 
iterate over just the ones targeted at those roles.

SOAPContext context = new SOAPContext();
context.addRole(SECURITY_ROLE);
envelope.setContext(context);
Iterator i = envelope.examineHeaders();
// this iterator now only covers headers targeted to
// NEXT and SECURITY_ROLE...

The context gets created and associated with incoming envelopes by the 
engine, which knows the roles via configuration of the engine and the 
service.  If there is no context associated with a given SOAPEnvelope 
(as when we're creating one from scratch), examineHeaders() would just 
return everything just like examineAllHeaders().

* I don't understand the various fault-related operations in OMBody. 
Why isn't a fault just a particular kind of element?

* Fault codes are QNames, not strings.  And in SOAP 1.2, we have 
subcodes as well.

* We should in general be using the SOAP 1.2 terminology for the API. 
So for instance the header APIs for actor/role (currently on 
OMHeaderBlock, which I want to call SOAPHeader) should be 
getRole()/setRole() - if we want getActor()/setActor() as synonyms 
that's OK too but the SOAP 1.2 versions should be there.  Same for 
faultString/reason - should have getReason()/setReason() on OMFault 
(which I want to be SOAPFault).

* Related to the above, we should have relay and node accessors on the 
SOAPHeader/OMHeaderBlock class.

* There are no APIs for getting pull events from OMElements yet?

* Namespace APIs seem like they need some work.  First off, an element 
appears to only enable a single namespace (that of the element QName 
itself) right now - if I add multiple namespace mappings to a given 
element I would expect to see them serialized.  Second, it's nice for 
the programmer if they can do things in terms of QNames, and have the OM 
handle the namespace mapping stuff for them.  This goes along with the 
fact that I don't want OM to be harder to use than the current Axis1.2 
MessageElement APIs.  I want to be able to do:

QName qn = new QName("http://foo", "element");
OMElementImpl el = new OMElementImpl(qn);

...and have the system be able to serialize that as:

<ns1:element xmlns:ns1="http://foo"/>

* Incidentally, typing "Impl" all the time feels a little strange when 
building up OM structures.  So I'd like to consider one of two 
possibilities - first, don't bother making the OM classes interfaces. 
Are we really expecting lots of different implementations, or are we 
trying to simply build a lightweight API like JDOM (which just uses 
classes and is VERY easy)?  Second, if we stick with interfaces can we 
shift to using "IOMElement" for the interface and "OMElement" for the 
implementation class?

Thoughts appreciated.

Thanks,
--Glen

Re: [Axis2] OM issues

Posted by Glen Daniels <gl...@thoughtcraft.com>.
Hi Sanjiva:

Sanjiva Weerawarana wrote:
>>* Regardless of what we do with respect to "full infoset support", I 
>>think that it's important to factor the SOAP-specific stuff now so that 
>>we have the ability to cleanly allow OM to evolve into something people 
>>can use to do XML+datbinding+XOP even without SOAP.  I'd suggest very 
>>strongly that we a) rename OMEnvelope/OMHeader/OMBody/OMFault to 
>>SOAPEnvelope/SOAPHeader/SOAPBody/SOAPFault, and b) put them in another 
>>package, perhaps org.apache.axis.om.soap, or org.apache.axis.soap.
> 
> 
> I was against this earlier, but Alek has brought up a point that
> has made me change my position on it (I think .. need to think
> some more). Alek's point was that if one is including an entire XML
> doc via MTOM, then it would be awkward to tell the user "use our 
> API to read the XML directly on SOAP, but otherwise use a standard
> XML API." I have to agree that would indeed be awkward.
> 
> To make that work properly OM has to be complete and separate from SOAP.

While I'm definitely in the same camp as Alek here, I think what I'm 
asking for is a slightly simpler thing.  Although I would certainly be 
for making OM work outside the context of SOAP, I'm not even suggesting 
we go all the way to doing that right now - just that the SOAP specific 
classes should be named in what I think is the right way, which also 
happens to aid factoring it for more genericity.

>>SOAPEnvelope env = new SOAPEnvelope(VERSION11);
>>SOAPHeader security = SecurityExtension.makeSecurityHeader();
>>env.addHeader(security);
>>env.getHeaderByQName(qname);
>>...etc...
> 
> Hmmmm. I kinda like having SOAPBody and SOAPHeader because then users
> can add namespace declarations to them for example. Also, I'd like
> to tie-in JXPath (or something similar) to provide XPath nav over
> the OM at some point .. retaining the actual XML structure will
> make that much much easier.
> 
> Now, that said, I have no objection to providing what you showed
> as a convenience API. That will allow the user to work as if
> SOAPHeader doesn't exist .. unless they want to care. For example
> the WS-Addressing handler will want to care as that will allow it
> to avoid having the same namespace declared repeatedly for each
> occurence of a wsa: element.

+1, that sounds fine to me.

> Header block vs. Header .. my bad; I thought that the world indeed
> called them header blocks because that's what SOAP 1.2 calls 'em.

Have you heard the world doing this?  In the WSDL group, in the 
addressing group, etc, I keep hearing things like "add a header that 
will...", "process the <To> header...", etc.  That seems a pretty 
natural usage to me.

>>The context gets created and associated with incoming envelopes by the 
>>engine, which knows the roles via configuration of the engine and the 
>>service.  If there is no context associated with a given SOAPEnvelope 
>>(as when we're creating one from scratch), examineHeaders() would just 
>>return everything just like examineAllHeaders().
> 
> So the lifecycle of the context is 1-1 with that of the message?
> Hence it would be 1-1 with that of the MessageContext as well. 
> 
> I'm concerned this is overengineering it. I can see a use-case for
> looking for specific roles but are there other use-cases? Note that
> we already have MessageContext which is 1-1 with the envelope; I
> don't want to create any more objects on a per-message basis than
> needed.

The use case actually isn't looking for specific roles one-by-one.  The 
use case is the SOAP processing model - where a given node, when 
processing a SOAP message, should collect ALL the headers targeted at 
"it".  That means a) everything targeted at "next", b) everything 
targeted at "ultimateReceiver" if we're the ultimate receiver (the usual 
case), and c) everything targeted at any other custom role that this 
node is playing.  These headers, as a group, are the ones that we 
normally care about.

I don't think having this kind of thing is overengineering at all.  To 
answer your lifecycle questions, I don't think there needs to be a 1-1 
relationship - the set of actors that a given engine / service is 
playing is generally fixed and I see no reason not to take advantage of 
that.

> Also, what's the usage status of role? I know that I haven't used
> them in any of the specs I've been involved with .. since role has
> something to do with intermediaries and since the SOAP intermediary
> stuff hasn't caught on as expected, I'm more towards -1 towards 
> adding this level of power right now. 

I think we have to have this or something very much like it in order to 
be SOAP compliant, and to support future use of this stuff.  We've 
experimented with it, and I know BEA has done some work with 
intermediaries too - plus this stuff (unlike the RPC encoding) is in the 
core spec, and not optional.  It's not very heavyweight; take a look at 
Axis 1.2, which does this sort of thing already.

>>* Incidentally, typing "Impl" all the time feels a little strange when 
>>building up OM structures.  So I'd like to consider one of two 
>>possibilities - first, don't bother making the OM classes interfaces. 
>>Are we really expecting lots of different implementations, or are we 
>>trying to simply build a lightweight API like JDOM (which just uses 
>>classes and is VERY easy)?  Second, if we stick with interfaces can we 
>>shift to using "IOMElement" for the interface and "OMElement" for the 
>>implementation class?
> 
> As Srinath noted the idea is to enable multiple implementations.
> However, the user will *not* have to type "Impl" .. they should be
> creating from the factory (which is discovered via a JAXP like 
> mechanism).

Stylistic choice, I guess - I don't so much like factories for this.  I 
really really love the simplicity of JDOM, and would like it if we could 
be almost that easy to use.  Nice APIs make playing at "the XML level" 
much more pleasant.

--Glen

Re: [Axis2] OM issues

Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
Glen, excellent comments!

> * Regardless of what we do with respect to "full infoset support", I 
> think that it's important to factor the SOAP-specific stuff now so that 
> we have the ability to cleanly allow OM to evolve into something people 
> can use to do XML+datbinding+XOP even without SOAP.  I'd suggest very 
> strongly that we a) rename OMEnvelope/OMHeader/OMBody/OMFault to 
> SOAPEnvelope/SOAPHeader/SOAPBody/SOAPFault, and b) put them in another 
> package, perhaps org.apache.axis.om.soap, or org.apache.axis.soap.

I was against this earlier, but Alek has brought up a point that
has made me change my position on it (I think .. need to think
some more). Alek's point was that if one is including an entire XML
doc via MTOM, then it would be awkward to tell the user "use our 
API to read the XML directly on SOAP, but otherwise use a standard
XML API." I have to agree that would indeed be awkward.

To make that work properly OM has to be complete and separate from SOAP.

> * Despite SAAJ doing it this way, I really don't like having a separate 
> object for SOAPHeader and SOAPBody, especially since you don't really do 
> anything with them except use them as containers.  To me, it's much more 
> natural to have the SOAPEnvelope class allow you to add/remove/view 
> headers (the world calls them "headers" and not "header blocks", so I'd 
> prefer the API to as well) and bodies without using the extra layer of 
> objects.  Example:
> 
> SOAPEnvelope env = new SOAPEnvelope(VERSION11);
> SOAPHeader security = SecurityExtension.makeSecurityHeader();
> env.addHeader(security);
> env.getHeaderByQName(qname);
> ...etc...

Hmmmm. I kinda like having SOAPBody and SOAPHeader because then users
can add namespace declarations to them for example. Also, I'd like
to tie-in JXPath (or something similar) to provide XPath nav over
the OM at some point .. retaining the actual XML structure will
make that much much easier.

Now, that said, I have no objection to providing what you showed
as a convenience API. That will allow the user to work as if
SOAPHeader doesn't exist .. unless they want to care. For example
the WS-Addressing handler will want to care as that will allow it
to avoid having the same namespace declared repeatedly for each
occurence of a wsa: element.

Header block vs. Header .. my bad; I thought that the world indeed
called them header blocks because that's what SOAP 1.2 calls 'em.
 
> * I don't understand the examine/extract APIs for header blocks.  Why do 
> we need extract?  Can't the user just remove them themselves?

No opinion.

> * I think that a given SOAPEnvelope should have a "context" of some kind 
> associated with it, which includes at least the currently active roles. 
>   Then when you iterate over the headers, the default behavior is to 
> iterate over just the ones targeted at those roles.
> 
> SOAPContext context = new SOAPContext();
> context.addRole(SECURITY_ROLE);
> envelope.setContext(context);
> Iterator i = envelope.examineHeaders();
> // this iterator now only covers headers targeted to
> // NEXT and SECURITY_ROLE...
> 
> The context gets created and associated with incoming envelopes by the 
> engine, which knows the roles via configuration of the engine and the 
> service.  If there is no context associated with a given SOAPEnvelope 
> (as when we're creating one from scratch), examineHeaders() would just 
> return everything just like examineAllHeaders().

So the lifecycle of the context is 1-1 with that of the message?
Hence it would be 1-1 with that of the MessageContext as well. 

I'm concerned this is overengineering it. I can see a use-case for
looking for specific roles but are there other use-cases? Note that
we already have MessageContext which is 1-1 with the envelope; I
don't want to create any more objects on a per-message basis than
needed.

Also, what's the usage status of role? I know that I haven't used
them in any of the specs I've been involved with .. since role has
something to do with intermediaries and since the SOAP intermediary
stuff hasn't caught on as expected, I'm more towards -1 towards 
adding this level of power right now. 

> * I don't understand the various fault-related operations in OMBody. 
> Why isn't a fault just a particular kind of element?

+1 for making fault be a special element.

> * Fault codes are QNames, not strings.  And in SOAP 1.2, we have 
> subcodes as well.

+1.
 
> * We should in general be using the SOAP 1.2 terminology for the API. 
> So for instance the header APIs for actor/role (currently on 
> OMHeaderBlock, which I want to call SOAPHeader) should be 
> getRole()/setRole() - if we want getActor()/setActor() as synonyms 
> that's OK too but the SOAP 1.2 versions should be there.  Same for 
> faultString/reason - should have getReason()/setReason() on OMFault 
> (which I want to be SOAPFault).

+1.
 
> * Related to the above, we should have relay and node accessors on the 
> SOAPHeader/OMHeaderBlock class.

+1.
 
> * There are no APIs for getting pull events from OMElements yet?

(See other email.)

> * Namespace APIs seem like they need some work.  First off, an element 
> appears to only enable a single namespace (that of the element QName 
> itself) right now - if I add multiple namespace mappings to a given 
> element I would expect to see them serialized. 

+1.

> Second, it's nice for 
> the programmer if they can do things in terms of QNames, and have the OM 
> handle the namespace mapping stuff for them.  This goes along with the 
> fact that I don't want OM to be harder to use than the current Axis1.2 
> MessageElement APIs.  I want to be able to do:
> 
> QName qn = new QName("http://foo", "element");
> OMElementImpl el = new OMElementImpl(qn);
> 
> ...and have the system be able to serialize that as:
> 
> <ns1:element xmlns:ns1="http://foo"/>

+1.
 
> * Incidentally, typing "Impl" all the time feels a little strange when 
> building up OM structures.  So I'd like to consider one of two 
> possibilities - first, don't bother making the OM classes interfaces. 
> Are we really expecting lots of different implementations, or are we 
> trying to simply build a lightweight API like JDOM (which just uses 
> classes and is VERY easy)?  Second, if we stick with interfaces can we 
> shift to using "IOMElement" for the interface and "OMElement" for the 
> implementation class?

As Srinath noted the idea is to enable multiple implementations.
However, the user will *not* have to type "Impl" .. they should be
creating from the factory (which is discovered via a JAXP like 
mechanism).

Sanjiva.

Re: [Axis2] OM issues

Posted by Srinath Perera <he...@gmail.com>.
On Mon, 6 Dec 2004 07:13:37 +0600, Sanjiva Weerawarana
<sa...@opensource.lk> wrote:
> "Glen Daniels" <gl...@thoughtcraft.com> writes:
> >
> > Oh - I thought we had agreed in Sri Lanka that we wanted OMNode to be a
> > pull event source (without the need for a wrapper), and that's what I
> > was looking for.  A wrapper approach can work too.
> 
> +1; otherwise I don't see how the original pull source can be
> "passed thru" to the application .. a key requirement to make this
> perform as "natively" as possible.

I think the reson for have a wrapper e.g. 
XMLPullParser xpp = new OMXMLPullParser(OMNode); is to avoid making
the OM interface have too much  methods. e.g.  having next();
getText(); ... XML Pull methods are kind of not belong to OMNode and
user might mess up the Pull and xml infoset methods.
> a key requirement to make this
> perform as "natively" as possible.
I think the wrapper get the builder from the OMNode and works
natively! if the OM is half build and cache off the wrapper will shif
to the pull stream.  (I think that is how it work .. we should ask
Ajith!)

Re: [Axis2] OM issues

Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
"Glen Daniels" <gl...@thoughtcraft.com> writes:
> 
> Oh - I thought we had agreed in Sri Lanka that we wanted OMNode to be a 
> pull event source (without the need for a wrapper), and that's what I 
> was looking for.  A wrapper approach can work too.

+1; otherwise I don't see how the original pull source can be 
"passed thru" to the application .. a key requirement to make this
perform as "natively" as possible.

Sanjiva.

Re: [Axis2] OM issues

Posted by Glen Daniels <gl...@thoughtcraft.com>.
Hi Srinath!

>>* I think that a given SOAPEnvelope should have a "context" of some kind
>>associated with it, which includes at least the currently active roles.
>>  Then when you iterate over the headers, the default behavior is to
>>iterate over just the ones targeted at those roles.
>>
>>SOAPContext context = new SOAPContext();
>>context.addRole(SECURITY_ROLE);
>>envelope.setContext(context);
>>Iterator i = envelope.examineHeaders();
>>// this iterator now only covers headers targeted to
>>// NEXT and SECURITY_ROLE...
>>
>>The context gets created and associated with incoming envelopes by the
>>engine, which knows the roles via configuration of the engine and the
>>service.  If there is no context associated with a given SOAPEnvelope
>>(as when we're creating one from scratch), examineHeaders() would just
>>return everything just like examineAllHeaders().
> 
> +1 to give the ability to search the Headers via the role, what do you
> think about using
> envelope.examineHeaders(String role); instead of Context

I think it could be a useful API, but it is much less important than a 
context-based approach.  In general the Axis node is going to be playing 
one or more ("next" always, ultimate destination most of the time, then 
others on a configuration-specific basis) roles, and you don't want to 
force the pattern of searching for headers based on individual roles one 
at a time.  I don't think I would put examineHeaders(String role) into 
the API for now at all, personally.

>>* There are no APIs for getting pull events from OMElements >yet?
> 
> I think it is there .. there is something that wrap the OM element and
> act as a pull parser to generate events for the OM element and child
> element (I do not remeber the class name .. Ajith can answer this I
> belive)

Oh - I thought we had agreed in Sri Lanka that we wanted OMNode to be a 
pull event source (without the need for a wrapper), and that's what I 
was looking for.  A wrapper approach can work too.

--Glen

Re: [Axis2] OM issues

Posted by Srinath Perera <he...@gmail.com>.
Hi Glen; 

> * Despite SAAJ doing it this way, I really don't like having a separate
> object for SOAPHeader and SOAPBody, especially since you don't really do
> anything with them except use them as containers.  To me, it's much more
> natural to have the SOAPEnvelope class allow you to add/remove/view
> headers (the world calls them "headers" and not "header blocks", so I'd
> prefer the API to as well) and bodies without using the extra layer of
> objects.  Example:
> 
> SOAPEnvelope env = new SOAPEnvelope(VERSION11);
> SOAPHeader security = SecurityExtension.makeSecurityHeader();
> env.addHeader(security);
> env.getHeaderByQName(qname);
> ...etc...
+1 , I feel the same .. SecurityExtension.makeSecurityHeader(); is cool :)
 
> * I think that a given SOAPEnvelope should have a "context" of some kind
> associated with it, which includes at least the currently active roles.
>   Then when you iterate over the headers, the default behavior is to
> iterate over just the ones targeted at those roles.
> 
> SOAPContext context = new SOAPContext();
> context.addRole(SECURITY_ROLE);
> envelope.setContext(context);
> Iterator i = envelope.examineHeaders();
> // this iterator now only covers headers targeted to
> // NEXT and SECURITY_ROLE...
> 
> The context gets created and associated with incoming envelopes by the
> engine, which knows the roles via configuration of the engine and the
> service.  If there is no context associated with a given SOAPEnvelope
> (as when we're creating one from scratch), examineHeaders() would just
> return everything just like examineAllHeaders().
+1 to give the ability to search the Headers via the role, what do you
think about using
envelope.examineHeaders(String role); instead of Context
 
 
> * There are no APIs for getting pull events from OMElements >yet?
I think it is there .. there is something that wrap the OM element and
act as a pull parser to generate events for the OM element and child
element (I do not remeber the class name .. Ajith can answer this I
belive)
 
> * Namespace APIs seem like they need some work.  First off, an element
> appears to only enable a single namespace (that of the element QName
> itself) right now - if I add multiple namespace mappings to a given
> element I would expect to see them serialized.  Second, it's nice for
> the programmer if they can do things in terms of QNames, and have the OM
> handle the namespace mapping stuff for them.  This goes along with the
> fact that I don't want OM to be harder to use than the current Axis1.2
> MessageElement APIs.  I want to be able to do:
> 
> QName qn = new QName("http://foo", "element");
> OMElementImpl el = new OMElementImpl(qn);
> 
> ...and have the system be able to serialize that as:
> 
> <ns1:element xmlns:ns1="http://foo"/>

there may be possibilities to improve the Namespaces! 


> * Incidentally, typing "Impl" all the time feels a little strange when
> building up OM structures.  So I'd like to consider one of two
> possibilities - first, don't bother making the OM classes interfaces.
> Are we really expecting lots of different implementations, or are we
> trying to simply build a lightweight API like JDOM (which just uses
> classes and is VERY easy)?  Second, if we stick with interfaces can we
> shift to using "IOMElement" for the interface and "OMElement" for the
> implementation class?

we got two Impl's of OM! I think we should leave the interfaces there
.. due to reason I do not feel good about having I at the front!   but
am 0 on it. (if others think "I" is ok please go ahead)
 
Thanks
Srinath

[Axis2] Milestone Release & To Do's

Posted by Farhaan Mohideen <fa...@opensource.lk>.
Hi All;

As promised I have created the following wiki's for the Milestone Release of
01/M1.

Project Plan
http://wiki.apache.org/ws/FrontPage/Axis2/ProjectPlan

01/M1 Milestone Release Plan
http://wiki.apache.org/ws/FrontPage/Axis2/Release01M1

TO DO's for 01/M1
http://wiki.apache.org/ws/FrontPage/Axis2/ToDo01M1

Please update the TO DO as appropriate. I have not attempted to write down
what is outstanding as there are several mails being posted on the subject.



Regards
Farhaan




RE: [Axis2] OM issues

Posted by Eran Chinthaka <ch...@opensource.lk>.
Excellent comments Glen. 

I read the preceding mail of Sanjiva. But since, I want to comment on Geln's
comments, I use this email.
 
>>Some comments about OM:
>>
>>* Regardless of what we do with respect to "full infoset support", I
>>think that it's important to factor the SOAP-specific stuff now so that
>>we have the ability to cleanly allow OM to evolve into something people
>>can use to do XML+datbinding+XOP even without SOAP.  I'd suggest very
>>strongly that we a) rename OMEnvelope/OMHeader/OMBody/OMFault to
>>SOAPEnvelope/SOAPHeader/SOAPBody/SOAPFault, and b) put them in another
>>package, perhaps org.apache.axis.om.soap, or org.apache.axis.soap.
>>
[Chinthaka] 
[Chinthaka] (refer Sanjiva's reply)

>>* Despite SAAJ doing it this way, I really don't like having a separate
>>object for SOAPHeader and SOAPBody, especially since you don't really do
>>anything with them except use them as containers.  To me, it's much more
>>natural to have the SOAPEnvelope class allow you to add/remove/view
>>headers (the world calls them "headers" and not "header blocks", so I'd
>>prefer the API to as well) and bodies without using the extra layer of
>>objects.  Example:
>>
>>SOAPEnvelope env = new SOAPEnvelope(VERSION11);
>>SOAPHeader security = SecurityExtension.makeSecurityHeader();
>>env.addHeader(security);
>>env.getHeaderByQName(qname);
>>...etc...

[Chinthaka] I agree with you that SOAPHeader is just a container.
OK the rationale behind this approach was like this.

1. we tried to map the SOAP message elements directly to the api as well. So
we have Envelope in the XML and OMEnvelope in the API. SO as the Header.
Then comes HeaderBlocks. 
2. Header is giving out some functionality for the use to get some specific
header only. For example he can ask for getHeadersWithMustUnderstand(). I
think if we are removing, these methods have to be moved to OMEnvelope,
which is OK. 

>>
>>* I don't understand the examine/extract APIs for header blocks.  Why do
>>we need extract?  Can't the user just remove them themselves?
[Chinthaka] This is user convenience.

User can just *read* headers using examine methods. Or he can *read and
detach* while reading using extract. I put this method specifically keeping
security in mind. Where user may sometime need to read and detach some
nodes. Rather than he specifically doing that, the method, internally calls
the detach method.

>>
>>* I think that a given SOAPEnvelope should have a "context" of some kind
>>associated with it, which includes at least the currently active roles.
>>  Then when you iterate over the headers, the default behavior is to
>>iterate over just the ones targeted at those roles.
>>
>>SOAPContext context = new SOAPContext();
>>context.addRole(SECURITY_ROLE);
>>envelope.setContext(context);
>>Iterator i = envelope.examineHeaders();
>>// this iterator now only covers headers targeted to
>>// NEXT and SECURITY_ROLE...
>>
>>The context gets created and associated with incoming envelopes by the
>>engine, which knows the roles via configuration of the engine and the
>>service.  If there is no context associated with a given SOAPEnvelope
>>(as when we're creating one from scratch), examineHeaders() would just
>>return everything just like examineAllHeaders().


[Chinthaka] for this I agree with Sanjiva's comments.

>>
>>* I don't understand the various fault-related operations in OMBody.
>>Why isn't a fault just a particular kind of element?
[Chinthaka] +1
>>
>>* Fault codes are QNames, not strings.  And in SOAP 1.2, we have
>>subcodes as well.


[Chinthaka] ok
>>
>>* We should in general be using the SOAP 1.2 terminology for the API.
>>So for instance the header APIs for actor/role (currently on
>>OMHeaderBlock, which I want to call SOAPHeader) should be
>>getRole()/setRole() - if we want getActor()/setActor() as synonyms
>>that's OK too but the SOAP 1.2 versions should be there.  Same for
>>faultString/reason - should have getReason()/setReason() on OMFault
>>(which I want to be SOAPFault).

[Chinthaka] ok, I just got names from SAAJ API :(

>>
>>* Related to the above, we should have relay and node accessors on the
>>SOAPHeader/OMHeaderBlock class.
>>
>>* There are no APIs for getting pull events from OMElements yet?


[Chinthaka] Its there using wrappers. We can pass any OMElement to a
StreamingWrapper. For example OMStaxWrapper and can get StAX events from
that.

>>
>>* Namespace APIs seem like they need some work.  First off, an element
>>appears to only enable a single namespace (that of the element QName
>>itself) right now - if I add multiple namespace mappings to a given
>>element I would expect to see them serialized.  Second, it's nice for
>>the programmer if they can do things in terms of QNames, and have the OM
>>handle the namespace mapping stuff for them.  This goes along with the
>>fact that I don't want OM to be harder to use than the current Axis1.2
>>MessageElement APIs.  I want to be able to do:
>>
>>QName qn = new QName("http://foo", "element");
>>OMElementImpl el = new OMElementImpl(qn);
>>
>>...and have the system be able to serialize that as:
>>
>><ns1:element xmlns:ns1="http://foo"/>


[Chinthaka] This is already in the api. For an OMElement u can add any
number of namespaces. 
public OMNamespace createNamespace(String uri, String prefix);

and it will be serialized properly. There is a SimpleOMSerializer, if u want
to check this.

>>
>>* Incidentally, typing "Impl" all the time feels a little strange when
>>building up OM structures.  So I'd like to consider one of two
>>possibilities - first, don't bother making the OM classes interfaces.
>>Are we really expecting lots of different implementations, or are we
>>trying to simply build a lightweight API like JDOM (which just uses
>>classes and is VERY easy)?  Second, if we stick with interfaces can we
>>shift to using "IOMElement" for the interface and "OMElement" for the
>>implementation class?

[Chinthaka] I think u don't have to type "impl" over and over again. U
always use a factory, and there exists a factor for each and every
implementation.
Yes, there may not much of impls of OM. But we'd better keep the
flexibility, to improve OM. Remember we are greedy to have a better OM with
HIGH performance and LOW memory foot print.

Thankx and regards,

Eran Chinthaka
>>
>>Thoughts appreciated.
>>
>>Thanks,
>>--Glen