Re: wsdd remarks

[James Snell <js...@lemoorenet.com>]

Steve, Jacek,

I copied the list on this so others can play also ;-)

Comments inline:


----- Original Message -----
From: "Jacek Kopecky" <ja...@idoox.com>
To: "Steve Graham" <sg...@us.ibm.com>
Cc: <js...@lemoorenet.com>
Sent: Friday, March 09, 2001 6:56 AM
Subject: Re: wsdd remarks


> I slept well last night so I'm capable of responding now. 8-)
> In a few hours I'll go away from the net for the weekend...
> See comments inside.
>
>                             Jacek Kopecky
>                                Idoox
>
>
>
> On Fri, 9 Mar 2001, Steve Graham wrote:
>
>  > Jacek:
>  > I have copied James on this, since he is active co-author of the WSDD
>  > stuff.
>  > If possible, I would like to move this conversation to Axis-Dev as soon
as
>  > possible.
>
> I guess we can actually just resend our conversation to axis-dev, if
> you agree I can do that soon. I would resend my initial remarks and
> this reply with some tiny editing. 8-)
>
>  > I attempt to address your thoughts/concerns below.
>  > Other changes that must come:
>  > - given the current "rethink" of the supplier stuff (handlers must be
>  > thread safe and state is in the MsgContext or elsewhere) the entire
>  > id/idref construct in WSDD may be punted
>
> I viewed id/idref on handlers as a way of sharing handler
> configuration, so that you don't have to configure a handler every
> time you use it. So <handler> without an ID would be anonymous to the
> repositories (if this is possible), first <handler> element with a
> particular ID would introduce this handler together with this
> particular config - meaning "create the handler and put it into the
> repository", IDREFs would mean "ask the repository for this handler".
>
>  > - the whole lifecycle thing (supplier ref) is likely to go
>
> I agree here.
>

Hey!  Did I miss something?  I think so.  Can somebody fill in the thought
process on this so I know what's changing? :-)


>  > >1) name should be NMTOKEN everywhere, not string, the root should
>  > >have targetNamespace so we know what namespace the definitions' names
>  > >fall into and we can use QNames easily. This helps with <import>s if
>  > >we add them.
>  > Can NMTOKEN contain the '*' character used to indicate global chain?
>
> I dislike the way global chains are configured as pivotless service
> with the name *, this does not follow the actual model of how the
> engine works and how the global handlers (I thinks they are handlers,
> even though of course they can in fact be chains, too) are stored.
>

Jacek, can you ellaborate a bit more on this?  Perhaps show a few XML/WSDD
snippets of what you'd like to see as opposed to what Steve and I have done?

>  > >2) <provider java:classname='...'/> should be
>  > ><provider><java:classname>...</></> or maybe
>  > ><java:provider ..../>
>  > I am comfortable with what James and I came up with for the
pluggability of
>  > provider here.
>  > I am not sure what the benefit is of the syntactical change you
suggested.
>  > Can you elaborate?
>
> If you use the first way, every single attribute(value) has to be
> namespace qualified, this is going to be inconvenient and it would
> negatively affect readability of WSDD. And I feel that namespaced
> attributes are for special use only, mostly for convenience
> reasons.
>

This is more of a preferential issue but I get your point.  This wouldn't be
a change to the WSDD core schema, just to the secondary provider-specific
schemas that define the extension elements.

> So this is actually mostly an issue of habit. Also, attributes of an
> element are not conceptually on the same level, they are not "side by
> side", that's why I would move the attributes into element
> children. Also you mix WSDD attribute serviceHandler with non-WSDD
> attributes, a thing you probably wouldn't do even among element
> children. (I know that WSDL does this.)
>
> The second way I suggested is visually more explicit about that all
> the things are for java, but now I think that
> <provider><java:.../><java:.../></provider> is better.
>
>  > >3) attribute type="classname" should become class="classname" or
>  > >handler="classname", or idref="qname" or ref="qname" in cases of
>  > >referencing reusable handlers
>  > Are you refering to the type attribute on Chain and Handler (and
>  > serviceConfig and transportConfig etc.)?
>  > The thinking here was the type attr would contain the "key" for a
handler
>  > in the handlerRegistry.
>  > For simple deployments, the key is the class of the handler.  For
>  > reusables, the key is an id within a handlerConfig.
>  > The idref/ref construct is likely going to go away because we are not
going
>  > to "share" multiple references to a single handler (per
supplier/stateful
>  > handler discussion above).  We may lose the ability to "inline" the
>  > declaration of a handler in the handler registry, but this is probably
not
>  > such a big loss.
>
> About id/ref see my comment above. As for deploying/referencing
> handlers, I thought the ID would be the registry key (why not
> reuse?). I don't like using the attribute "type" for multiple
> different things. If the <handler> element is used within a chain, it
> should use "ref" attribute to explicitly show that this is _not_
> definition, that it's just a reference to definition elsewhere. Then
> the "type" attribute could be renamed to "class" because that would be
> the only use of it.
>

Jacek: our original thoughts on this were:

    using "ref" means that we are referencing a existing instance of a
deployed handler.
    using "type" means that we are referencing a new instance of either a
deployed handler or a java class.

This is used consistently throughout the WSDD schema (type always refers to
a "new instance").  In other words, using the following syntax:

    <handler id="myHandler" type="org.apache.axis.handlers.MyHandler" />
    <handler id="myHandlerInstance" ref="myHandler" />

Every instance of "myHandlerInstance" would share a single instance of
"org.apache.axis.handlers.MyHandler". While:

    <handler id="myHandler" type="org.apache.axis.handlers.MyHandler" />
    <handler id="myHandlerInstance" type="myHandler" />

Would create a new instance of "org.apache.axis.handlers.MyHandler" for each
instance of "myHandlerInstance".

Referencing the java class is not the only use of the "type" attribute then.
It is also used to indicate programatically how handlers are instantiated.
Now, I realize from other comments that have been made that this model may
be changing so we may need to look at this again, but I don't think renaming
"type" to "class" is a good move in this case.

> The "type" attribute of elements other than flow/chain/handler should
> be renamed to "handler" or "handlerRef" because this is what it
> means. (AFAICS)
>

That's what the "ref" attribute is for.  "type" tells us to create a new
instance of the named handler.  "ref" tells us to reuse.

>  > >4) Can you explain more what the "style" attribute in
>  > ><serviceDeployment> is needed for? Some examples show
>  > >style="message" deployments with <operation>s in it...
>  > Similar to the notion in Apache SOAP deployment descriptor.
>  > Style indicates whether the service is RPC or Message
(document-centric).
>  > Style attribute is modeled as an enumeration of these two values.
>
> Yes, that I could see from the schema itself, but can you please
> describe the meaning of the style? What changes when I switch the
> state?
>
>  > >5) Why <operations>? Why not just use a set of simple <operation>s?
>  > I struggled with this one.  We I liked Apache SOAP DD's use of a
methods
>  > attribute, listing a whitespace separated list of methods.  This was
simple
>  > and expressive.  We needed an operation element to allow for things
like
>  > having a "public name" different from the name derived from the method
>  > signature.
>
> No example uses the <operations> element and even though I think it's
> kind of nice, I think that it's unnecessary because it's easier to
> grasp
>    <operation name="a"/>
>    <operation name="b"/>
>    <operation name="c" uriExtension="blah"/>
>  than
>    <operations names="a b"/>
>    <operation name="c" uriExtension="blah"/>
>  because having <operations> followed by <operation> is kind of
> suggesting that by the <operations> we listed the operations that we
> want to refine by using <operation>.
>

I would agree with Jacek on this.  My vote would be to drop the "operations"
element.

>  > >6) What does <operation> tell the deployment? What's uriExtension?
>  > Operation tells the deployment what subset of the public methods should
be
>  > exposed as web service operations.  So if a class has 5 public methods,
the
>  > operation would say which of the 5 (perhaps all) are exposed as web
service
>  > operations.
>
> How do you specify that an operation should have the public name
> different from the actual name? No example shows that.
>

Not sure about Steve, but I hadn't thought of this.  Perhaps if we throw an
"aliasFor" attribute that indicates the actual operation name or an "alias"
attribute that indicates what we want the public name to be.

>  > The URIExtension is essentially the <urlPattern> element within a
web.xml
>  > file in a web-app deployment for servlets.
>
> I don't know this detail of web.xml files, can you please stress what
> it would mean for Axis?
>

Ditto.  I missed the reference here also Steve.  Can you please elaborate?

>  > >7) <flow type ...?> should become <request...> or <response...>,
>  > >configuration params of targeted chain.
>  > Sorry, I don't understand your point here.
>
> I meant that <flow> element should be renamed to <requestHandler> and
> <responseHandler>, which the targeted chain that gets this
> configuration understands as its configuration parameters. What do you
> do when you have multiple <flow>s with the same type "request"? It is
> nice that you generalize request(Chain|Handler) and
> response(Chain|Handler) and flow(Chain|Handler) into <flow>, but since
> there are no more choices here, readability would be improved greatly
> by the renaming I suggested.
>

Hmm... again, this seems to be a preferential thing.  Let me take a while
longer to consider.

>  > >8) handler config should look like:
>  > > <handler class="..." xmlns:hns="urn:handlers-namespace-uri">
>  > I hadn't imagined that  each handler would have their own namespace.
>  > James: what do you think here?
>
> The most commonly used handlers packaged with Axis could use the WSDD
> namespace, but generally I think separating different languages (as in
> different sets of configuration elements) is exactly the point of XML
> namespaces. 8-)
>

This is interesting.  The entire WSDD could exist in it's own namespace.
All of the handlers could be namespace qualified.  Not sure about the
utility of this but it is an intriguing thought.  Give me some time to stew
on it.

>  > >  <param name="...">string</param>
>  > >  <hns:whatever ...>...</hns:whatever>
>  > > </handler>
>  > >then the handler would accept a NodeSet of his own elements (every
>  > >element from a different namespace) and normal Properties
>  > >(string->string)
>  > >or only <param>s with possibly underlying elements, not only text:
>  > > <handler ...>
>  > >  <param name="...">
>  > >   <hns:something>...</>
>  > >  </>
>  > > </>
>  > >This would allow the <request> and <response> from 7) to become
>  > > <wsdd:param name="request">
>  > >  <tcns:request xmlns:tcns="urn:targeted-chain-namespace">
>  > >   ...
>  > >  </>
>  > > </>
>  > Um, the request flow defines the handlers that appear in the request
chain
>  > of the targeted-chain-container.
>  > Request is not itself a param, but a structure.
>
> Request is a configuration parameter of this instance of the
> TargetedChainContainer. Or should be, because otherwise you'd end up
> with some handlers being configured in one way and some in a
> completely different way.
>

?? Jacek: can you please ellaborate.  If possible, please use a few WSDD
examples to demonstrate the problem.

>  > >9) what's the diff between ServiceConfiguration and ServiceDeployment
>  > >anyway? Is ServiceDeployment the pivot?!? That's such a weird name...
>  > ServiceConfiguration models the pair of:
>  > -  a serviceDeployment (pivot, yes, essentially what is an Apache SOAP
v2.x
>  > deployment descriptor)
>  > and
>  > - the handlers (eg chains) related to pre and post processing of the
>  > service.
>
> Then please rename ServiceDeployment into something else, like
> "pivot", with the stuff that's in there would be a configuration of
> the particular dispatcher class used in the pivot.
>

what do you think about "ServiceTarget" as opposed to "ServiceDeployment" ??

>  > >10) who wrote the English texts? "... is wrappered around ..." 8-)
>  > The wrapping is a vestige of using modern tools :-).
>  > In other words, I did not use an 80 character limit, as I had no plans
to
>  > render this onto punch cards :-)
>  > Seriously, I suppose we should look at changing the annotation text to
obey
>  > 80 char limit.
>
> I didn't mean the long lines, those can be handled easily, that text
> was a literal excerpt from one of the examples. I was just pointing
> out the English. I saw some of such bugs in multiple places. 8-)
>

All errors in grammar must be equally attributed to myself and Steve ;-)
.... (primarily to Steve though... he is from Canada you know... :-D...)

>  > >11) if the contents of an element depend on the value of an attribute,
>  > >the different contents should be from different namespaces
>  > This is in reference to what element in particular that brought this to
>  > mind?
>
> This remark was the result of my misinterpretation of my own notes. So
> we can just strike out 11), I'll state what I really wanted to say
> later.
>
>  > >12) can <chain ref> reference a <handler id> or is it only <chain id>?
>  > Strangely enough, it can reference a chain or a handler.
>
> So a <chain> is actually a synonym for <handler> with just a
> predefined default for the handling class? Can <handler> be used to
> set up a chain? If not, I'd have to ask: "Why not?"
>

Although all Chains are Handlers, not all Handlers are Chains.  I'd prefer
to keep these separate.

> Maybe the two elements could go into an XML Schema equivalence class.
>

Preferential.  This could go either way.

>  > >13) internal reusable? It cannot be referenced from elsewhere? How do
>  > >we prevent that assuming XML id resolving?
>  > The reference can happen from anywhere.  Essentially this allows a
>  > reusuable to be defined "inline" by a handler element which is child of
>  > chain.  This is an alternative mechanism to defining a handlerConfig
for
>  > the handler.  Because of the current thinking with suppliers/stateful
>  > handlers, the notion of "inline" definition of reusables and the
id/idref
>  > construct is likely to go away.
>
> Why should we not be able to inline the definitions? I think that
> id/ref can still be used for sharing configurations.
>
>  > >14, 15 prelude)  we can forbid the local handler configs and only
>  > >allow referencing handlers set up with <handler>...</>, but the local
>  > >config can prove useful
>  > I am not sure what your point here is.
>
> It was about inlining handler definitions, actually. I thought we
> could forbid inlining, but it could prove useful.
>
>  > >14) is transportConfiguration just a setup of the transport input and
>  > >output chains?
>  > Yes.
>  >
>  > >It either shouldn't be a targetedchain
>  > It won't be.  I doubt the chainGenerator will be built to generate a
>  > targettedChain for this.
>  > Or if it does, I doubt the pivot aspect will be used, but rather the
>  > request and response chain
>  > will be referenced by the engine when needed.
>  >
>  > >or the pivot is
>  > >the engine, but in any case the class itself should not be used, we
>  > >agreed it's the engine who calls the chains.
>  > Yes, the engine calls the request or response transport specific
chains.
>  >
>  > >So I imagine:
>  > > <deployments>
>  > >  <!-- ... definitions of handlers here -->
>  > >  <requestTransportHandler
>  > >   transportName="..." ref="id-of-a-handler"/>
>  > >  <responseTransportHandler transportName="...">
>  > >   <!-- ... a handler config here -->
>  > >  </responseTransportHandler>
>  > > </deployments>
>  > I am less comfortable with defining the requestTransportHandler and
>  > responseTransportHandler syntax.  The construct we have for
>  > transportConfiguration is parallel construct for defining
>  > serviceConfiguration.  At this point, I am comfortable with the
symettry.
>  > James, what do you think?
>
> I don't like symmetrizing things that are not symmetric. 8-) Services
> are not symmetric to transports/transport(request|response)chains.
>

I too prefer the way we have it.  The two may not be completely symmetrical
but by defining them as we have, the WSDD structure is simplified and in my
opinion, easier to grasp.

> And I strongly dislike using the same construct (the unrestricted
> <flow> syntax) in one place to set up a targetted chain, in other
> place to just set up (at most) two chains. What would you do with
> transportConfiguration containing <flow flowType="fault">?
>

We would invoke the appropriate fault flow in response to any fault fired
off at a lower level.  I'm not quite sure what you're getting at here
Jacek...

> And one more thing: transportConfiguration is not actually a
> configuration of a transport, is it? It should be named
> transportHandlersConfiguration, but then I think that
> <requestTransportHandler> and <responseTransportHandler> would be
> equal in element name length and more expressive.
>
>  > >15) global chains (serviceConfiguration name="*") is plainly WRONG
>  > >Asi in 14), I see it rather as
>  > > <deployments>
>  > >  <globalRequestHandler ref="id-of-a-handler"/>
>  > >  <globalResponseHandler>
>  > >   <!-- ... a handler config here -->
>  > >  </>
>  > > </>
>  > Why do you characterize the way global chains are modeled as "WRONG"?
>  > I am not comfortable with adding new element syntax for this one case.
>
> Well, I have to say I am not comfortable with describing something
> that is definitely not a service with the syntax used for
> services. Again what would you do with a fault flow in this
> configuration?
>
> I don't like the way many things are very sensitive even though you
> follow the schema. If you cannot define a fault for global chains, you
> shouldn't be allowed to, it there is a simple way of disallowing
> it.
>

You CAN define a fault for a Global chain.  Can you put together a few
examples that demonstrate "following the schema but still defining an
invalid deployment"?

>  > >16) typeMappingUse should be <typeMapping ref>, then typeMapping
>  > >wouldn't require id, it would require that if ref is present, nothing
>  > >else is. This is as the XML Schema folks do it.
>  > >And this would allow us to specify typeMapping in the place where
>  > >it's needed if it's only needed in one place.
>  > Interesting.  James, what do you think?  This looks like something WSDD
>  > should do.
>  >

I agree with this.  Drop "typeMappingUse" and add a "ref" attribute to
"typeMapping".

>  > >17) what is java:isStatic?
>  > Determines whether the web service operation invocation is a method
call to
>  > a Java Static method, or whether the operation is an invocation of an
>  > instance method.
>  >
>  > >18) we need to specify what exactly the target is here.
>  > I am not sure where "here" is.
>
> I meant the target that leads to selecting this particular service.
>
>  > > We might wanna
>  > >provide a sugar for some kind of URI relative to the server. We need
>  > >to be able to say that we wanna dispatch on SOAPAction or URI or
>  > >something else, this could be shown somewhere else than only in the
>  > >configuration of the transport, transport request chain and global
>  > >request chain.
>
>  > Thanks for taking the time to look over the WSDD.
>
> I really do have strong feelings about the clarity and simplicity of
> XML languages, especially when I have to work with them or when they
> are part of products I'm cooperating on. 8-)
>

Hey... just be glad we didn't model this after the XML Schema spec! B-D

Keep the feedback coming, we need to get this nailed down and get some code
written.

- James