[axis2] proposal for client API refactoring

[Sanjiva Weerawarana <sa...@opensource.lk>]

Eran and I spent quite a few hours in the last few days going thru the
client API and have a proposal for how to refactor it. Without
explaining the current state in detail, I'll write up the proposed new
state and then list the work items so you can see what we're proposing
to change. 

The main motivation for the changes are to eliminate duplication across
different levels of the API and overall to hide complexity and disclose
it only as needed. 

All code is o.a.axis2.client unless otherwise indicated. The basic
structure is as follows:

- Options
    This class is the generic options class containing all the options
to configure any MEP client. This JavaBean will have bean properties for
the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a
HashMap backed property bag for putting arbitrary properties. Basically
the idea is to make the Options class the one class that users use to
configure any MEP client. Each MEPClient subclass will specify
additional properties that must be in the Options instance in order to
configure those downstream Client classes. 

- MEPClient
    This is the abstract base class for all MEP clients. Remove all the
get/set methods for addressing properties etc. and replace it with one
method: get/setOptions which takes an Options instance.

- InOutMEPClient
    As above but inherit stuff from MEPClient instead.

- InOnlyMEPClient
    As above for cleanup. After that, rename as RobustInOnlyMEPClient as
that's the MEP this is really implementing.

- Add new InOnlyMEPClient to implement true fire-n-forget behavior on
the client using a new thread. 

- Remove MessageSender and move the convenience method to send just a
SOAPEnvelope or an OMElement to the parent RobustInOnlyMEPClient class.
Add similar conveniences for the new InOnlyMEPClient class. Change the
send() methods to not take an operation name at all but rather defalt to
something.

- Move Call.invoke with the simple forms of invoke() using a SOAPElement
or an OMElement to the parent InOutMEPClient class. That makes Call
redundant for the most part .. I'm fine in leaving for user convenience.

Once we change this stuff, the code usage will look like this:

import o.a.axis2.client.*;

...
Options o = new Options();
o.setX(..);
o.setY(..);
...
Call c = new Call ();
c.setOptions (o);
c.invoke ...

So this avoids problems like having message information headers in
multiple places etc.. Some other supporting mods are needed too but
those are straightforward. 

We discussed doing the same approach for the Stub class but I haven't
written that up yet.

Sanjiva.

Re: [axis2] proposal for client API refactoring

[Sanjiva Weerawarana <sa...@opensource.lk>]

On Tue, 2005-11-29 at 00:49 +0600, Sanjiva Weerawarana wrote:
..
> - Options
>     This class is the generic options class containing all the options
> to configure any MEP client. This JavaBean will have bean properties for
> the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a

BTW I forgot to say .. I think Glen suggested this a while back :) so
credit goes to him for the good idea! (I'm assuming he still thinks its
a good idea ;-))

Sanjiva.

Re: [axis2] proposal for client API refactoring

[Paul Fremantle <pz...@gmail.com>]

Eran

Nice argument!

Unfortunately I don't agree with [1]. "Dynamic" flexible invocation is a
part of most Web Services stacks - both Axis1 and even JAX-RPC. The fact
that Axis2 doesn't have a single client class that can call a service
whatever MEP seems rather limiting. You state [1] as if it were an obvious
conclusion. But it doesn't strike me as axiomatic.

Paul

On 11/30/05, Eran Chinthaka <ch...@opensource.lk> wrote:
>
> Hi Paul,
>
>
>
> Paul Fremantle wrote:
>
> On 11/29/05, Eran Chinthaka <ch...@opensource.lk> <ch...@opensource.lk> wrote:
>
>  I think the preferred way is to write a Client extending from MEPClient.
> But I don't think it should come in to Axis2.
>
> -- EC
>
>     I think you have misunderstood my statement.
>
> <Axis2 Hat on>
> [1]When we write Clients extending from MEPClient, at least for the time
> being, we limit to support for basic MEPs.
>
> what we have always been telling to the users was that, if you want to
> have some custom MEPs or if you want to have a combination, you can easily
> write your own one. One has "enough" support and flexibility within Axis2 to
> do that.
>
> Let me take your question again. You wanted to write a client, which
> doesn't know it is invoking an INonly service or a IN-OUT service.  So this
> statement contradicts with my statement [1]. There are lot of combinations
> you can get wiring some IN pipes and OUT pipes. And at the same time if the
> client tries to support different combinations of MEPs at the same time, the
> situation becomes more complicated.
>
>
>  Why don't you think it should come from Axis2? From Synapse POV, I would
> like the only APIs I use from Axis2 to be the published APIs of Axis2. At
> the moment I am using all sorts of cool stuff from inside Axis2. Which means
> when you change it, Synapse will complain. If Synapse sticks to APIs only
> and not internals, then this won't be a problem.
>
>  No I don't think this is a valid argument. When you write your own
> MEPClient extension, this does not anyway breaks the statement "If Synapse
> sticks to APIs only and not internals, then this won't be a problem."
> You are not going in to internals by writing a custom client.
>
> FYI, I wanted to extend the functionality of IN-OUT mep once, for a test,
> and I didn't introduce a new MEPClient for that for Axis2. I wrote my custom
> MEPClient within the test package and used that :-) .
>
> </Axis2 Hat on>
>
> <Synapse Hat on>
> I don't see any problem why we can not write our own extension from
> MEPClient within Synapse. And I don't think that will anyway harm our rules
> or concepts. Rather that will make the job easier.
> </Synapse Hat on>
>
>
> Paul, may be I'm missing something, or I have got this unneccessarily
> complicated (if yes, 1000 appologies :-) ). I think its better to only
> support basic MEPs within Axis2, and not customs MEPs, nor combinations of
> basic MEPs.
>
> -- Chinthaka
>
> Another way of looking at this - Synapse is a user of Axis2. If a user
> really needs this (and in this case is willing to help write it) why
> wouldn't you want to support that user?
>
> I don't think this is such an unusual use case that it wouldn't be useful
> for other users.
>
> Paul
>
>

Re: [axis2] proposal for client API refactoring

[Eran Chinthaka <ch...@opensource.lk>]

Hi Paul,



Paul Fremantle wrote:

>On 11/29/05, Eran Chinthaka <ch...@opensource.lk> wrote:
>  
>
>>I think the preferred way is to write a Client extending from MEPClient.
>>But I don't think it should come in to Axis2.
>>
>>-- EC
>>    
>>
>
>  
>
I think you have misunderstood my statement.

<Axis2 Hat on>
[1]When we write Clients extending from MEPClient, at least for the time
being, we limit to support for basic MEPs.

what we have always been telling to the users was that, if you want to
have some custom MEPs or if you want to have a combination, you can
easily write your own one. One has "enough" support and flexibility
within Axis2 to do that.

Let me take your question again. You wanted to write a client, which
doesn't know it is invoking an INonly service or a IN-OUT service.  So
this statement contradicts with my statement [1]. There are lot of
combinations you can get wiring some IN pipes and OUT pipes. And at the
same time if the client tries to support different combinations of MEPs
at the same time, the situation becomes more complicated.


>
>Why don't you think it should come from Axis2? From Synapse POV, I would
>like the only APIs I use from Axis2 to be the published APIs of Axis2. At
>the moment I am using all sorts of cool stuff from inside Axis2. Which means
>when you change it, Synapse will complain. If Synapse sticks to APIs only
>and not internals, then this won't be a problem.
>  
>
No I don't think this is a valid argument. When you write your own
MEPClient extension, this does not anyway breaks the statement "If
Synapse sticks to APIs only and not internals, then this won't be a
problem."
You are not going in to internals by writing a custom client.

FYI, I wanted to extend the functionality of IN-OUT mep once, for a
test, and I didn't introduce a new MEPClient for that for Axis2. I wrote
my custom MEPClient within the test package and used that :-) .

</Axis2 Hat on>

<Synapse Hat on>
I don't see any problem why we can not write our own extension from
MEPClient within Synapse. And I don't think that will anyway harm our
rules or concepts. Rather that will make the job easier.
</Synapse Hat on>


Paul, may be I'm missing something, or I have got this unneccessarily
complicated (if yes, 1000 appologies :-) ). I think its better to only
support basic MEPs within Axis2, and not customs MEPs, nor combinations
of basic MEPs.

-- Chinthaka

>Another way of looking at this - Synapse is a user of Axis2. If a user
>really needs this (and in this case is willing to help write it) why
>wouldn't you want to support that user?
>
>I don't think this is such an unusual use case that it wouldn't be useful
>for other users.
>
>Paul
>
>  
>

Re: [axis2] proposal for client API refactoring

[Paul Fremantle <pz...@gmail.com>]

On 11/29/05, Eran Chinthaka <ch...@opensource.lk> wrote:
>
>
> I think the preferred way is to write a Client extending from MEPClient.
> But I don't think it should come in to Axis2.
>
> -- EC



Why don't you think it should come from Axis2? From Synapse POV, I would
like the only APIs I use from Axis2 to be the published APIs of Axis2. At
the moment I am using all sorts of cool stuff from inside Axis2. Which means
when you change it, Synapse will complain. If Synapse sticks to APIs only
and not internals, then this won't be a problem.

Another way of looking at this - Synapse is a user of Axis2. If a user
really needs this (and in this case is willing to help write it) why
wouldn't you want to support that user?

I don't think this is such an unusual use case that it wouldn't be useful
for other users.

Paul

Re: [axis2] proposal for client API refactoring

[Eran Chinthaka <ch...@opensource.lk>]

hmm, can we handle this scenario in Axis2, in general.

I think the preferred way is to write a Client extending from MEPClient.
But I don't think it should come in to Axis2.

-- EC

Paul Fremantle wrote:

>+1 I think this is good.
>
>BTW Synapse also has a need for a "flexible sync/async MEP client". The use
>case is where we have a message and we don't know if it is in-only, robust
>in-only or in-out/fault.
>
>Paul
>
>On 11/28/05, Davanum Srinivas <da...@gmail.com> wrote:
>  
>
>>+1 from me.
>>
>>-- dims
>>
>>On 11/28/05, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
>>    
>>
>>>Eran and I spent quite a few hours in the last few days going thru the
>>>client API and have a proposal for how to refactor it. Without
>>>explaining the current state in detail, I'll write up the proposed new
>>>state and then list the work items so you can see what we're proposing
>>>to change.
>>>
>>>The main motivation for the changes are to eliminate duplication across
>>>different levels of the API and overall to hide complexity and disclose
>>>it only as needed.
>>>
>>>All code is o.a.axis2.client unless otherwise indicated. The basic
>>>structure is as follows:
>>>
>>>- Options
>>>    This class is the generic options class containing all the options
>>>to configure any MEP client. This JavaBean will have bean properties for
>>>the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a
>>>HashMap backed property bag for putting arbitrary properties. Basically
>>>the idea is to make the Options class the one class that users use to
>>>configure any MEP client. Each MEPClient subclass will specify
>>>additional properties that must be in the Options instance in order to
>>>configure those downstream Client classes.
>>>
>>>- MEPClient
>>>    This is the abstract base class for all MEP clients. Remove all the
>>>get/set methods for addressing properties etc. and replace it with one
>>>method: get/setOptions which takes an Options instance.
>>>
>>>- InOutMEPClient
>>>    As above but inherit stuff from MEPClient instead.
>>>
>>>- InOnlyMEPClient
>>>    As above for cleanup. After that, rename as RobustInOnlyMEPClient as
>>>that's the MEP this is really implementing.
>>>
>>>- Add new InOnlyMEPClient to implement true fire-n-forget behavior on
>>>the client using a new thread.
>>>
>>>- Remove MessageSender and move the convenience method to send just a
>>>SOAPEnvelope or an OMElement to the parent RobustInOnlyMEPClient class.
>>>Add similar conveniences for the new InOnlyMEPClient class. Change the
>>>send() methods to not take an operation name at all but rather defalt to
>>>something.
>>>
>>>- Move Call.invoke with the simple forms of invoke() using a SOAPElement
>>>or an OMElement to the parent InOutMEPClient class. That makes Call
>>>redundant for the most part .. I'm fine in leaving for user convenience.
>>>
>>>Once we change this stuff, the code usage will look like this:
>>>
>>>import o.a.axis2.client.*;
>>>
>>>...
>>>Options o = new Options();
>>>o.setX(..);
>>>o.setY(..);
>>>...
>>>Call c = new Call ();
>>>c.setOptions (o);
>>>c.invoke ...
>>>
>>>So this avoids problems like having message information headers in
>>>multiple places etc.. Some other supporting mods are needed too but
>>>those are straightforward.
>>>
>>>We discussed doing the same approach for the Stub class but I haven't
>>>written that up yet.
>>>
>>>Sanjiva.
>>>
>>>
>>>      
>>>
>>--
>>Davanum Srinivas : http://wso2.com/blogs/
>>
>>    
>>
>
>  
>

Re: [axis2] proposal for client API refactoring

[Paul Fremantle <pz...@gmail.com>]

+1 I think this is good.

BTW Synapse also has a need for a "flexible sync/async MEP client". The use
case is where we have a message and we don't know if it is in-only, robust
in-only or in-out/fault.

Paul

On 11/28/05, Davanum Srinivas <da...@gmail.com> wrote:
>
> +1 from me.
>
> -- dims
>
> On 11/28/05, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
> > Eran and I spent quite a few hours in the last few days going thru the
> > client API and have a proposal for how to refactor it. Without
> > explaining the current state in detail, I'll write up the proposed new
> > state and then list the work items so you can see what we're proposing
> > to change.
> >
> > The main motivation for the changes are to eliminate duplication across
> > different levels of the API and overall to hide complexity and disclose
> > it only as needed.
> >
> > All code is o.a.axis2.client unless otherwise indicated. The basic
> > structure is as follows:
> >
> > - Options
> >     This class is the generic options class containing all the options
> > to configure any MEP client. This JavaBean will have bean properties for
> > the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a
> > HashMap backed property bag for putting arbitrary properties. Basically
> > the idea is to make the Options class the one class that users use to
> > configure any MEP client. Each MEPClient subclass will specify
> > additional properties that must be in the Options instance in order to
> > configure those downstream Client classes.
> >
> > - MEPClient
> >     This is the abstract base class for all MEP clients. Remove all the
> > get/set methods for addressing properties etc. and replace it with one
> > method: get/setOptions which takes an Options instance.
> >
> > - InOutMEPClient
> >     As above but inherit stuff from MEPClient instead.
> >
> > - InOnlyMEPClient
> >     As above for cleanup. After that, rename as RobustInOnlyMEPClient as
> > that's the MEP this is really implementing.
> >
> > - Add new InOnlyMEPClient to implement true fire-n-forget behavior on
> > the client using a new thread.
> >
> > - Remove MessageSender and move the convenience method to send just a
> > SOAPEnvelope or an OMElement to the parent RobustInOnlyMEPClient class.
> > Add similar conveniences for the new InOnlyMEPClient class. Change the
> > send() methods to not take an operation name at all but rather defalt to
> > something.
> >
> > - Move Call.invoke with the simple forms of invoke() using a SOAPElement
> > or an OMElement to the parent InOutMEPClient class. That makes Call
> > redundant for the most part .. I'm fine in leaving for user convenience.
> >
> > Once we change this stuff, the code usage will look like this:
> >
> > import o.a.axis2.client.*;
> >
> > ...
> > Options o = new Options();
> > o.setX(..);
> > o.setY(..);
> > ...
> > Call c = new Call ();
> > c.setOptions (o);
> > c.invoke ...
> >
> > So this avoids problems like having message information headers in
> > multiple places etc.. Some other supporting mods are needed too but
> > those are straightforward.
> >
> > We discussed doing the same approach for the Stub class but I haven't
> > written that up yet.
> >
> > Sanjiva.
> >
> >
>
>
> --
> Davanum Srinivas : http://wso2.com/blogs/
>

Re: [axis2] proposal for client API refactoring

[Davanum Srinivas <da...@gmail.com>]

+1 from me.

-- dims

On 11/28/05, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
> Eran and I spent quite a few hours in the last few days going thru the
> client API and have a proposal for how to refactor it. Without
> explaining the current state in detail, I'll write up the proposed new
> state and then list the work items so you can see what we're proposing
> to change.
>
> The main motivation for the changes are to eliminate duplication across
> different levels of the API and overall to hide complexity and disclose
> it only as needed.
>
> All code is o.a.axis2.client unless otherwise indicated. The basic
> structure is as follows:
>
> - Options
>     This class is the generic options class containing all the options
> to configure any MEP client. This JavaBean will have bean properties for
> the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a
> HashMap backed property bag for putting arbitrary properties. Basically
> the idea is to make the Options class the one class that users use to
> configure any MEP client. Each MEPClient subclass will specify
> additional properties that must be in the Options instance in order to
> configure those downstream Client classes.
>
> - MEPClient
>     This is the abstract base class for all MEP clients. Remove all the
> get/set methods for addressing properties etc. and replace it with one
> method: get/setOptions which takes an Options instance.
>
> - InOutMEPClient
>     As above but inherit stuff from MEPClient instead.
>
> - InOnlyMEPClient
>     As above for cleanup. After that, rename as RobustInOnlyMEPClient as
> that's the MEP this is really implementing.
>
> - Add new InOnlyMEPClient to implement true fire-n-forget behavior on
> the client using a new thread.
>
> - Remove MessageSender and move the convenience method to send just a
> SOAPEnvelope or an OMElement to the parent RobustInOnlyMEPClient class.
> Add similar conveniences for the new InOnlyMEPClient class. Change the
> send() methods to not take an operation name at all but rather defalt to
> something.
>
> - Move Call.invoke with the simple forms of invoke() using a SOAPElement
> or an OMElement to the parent InOutMEPClient class. That makes Call
> redundant for the most part .. I'm fine in leaving for user convenience.
>
> Once we change this stuff, the code usage will look like this:
>
> import o.a.axis2.client.*;
>
> ...
> Options o = new Options();
> o.setX(..);
> o.setY(..);
> ...
> Call c = new Call ();
> c.setOptions (o);
> c.invoke ...
>
> So this avoids problems like having message information headers in
> multiple places etc.. Some other supporting mods are needed too but
> those are straightforward.
>
> We discussed doing the same approach for the Stub class but I haven't
> written that up yet.
>
> Sanjiva.
>
>


--
Davanum Srinivas : http://wso2.com/blogs/

Re: [axis2] proposal for client API refactoring

[Srinath Perera <he...@gmail.com>]

+1 for options

May be we need to change the message signature of *MEPClient
invoke*(..) methods to pass the SOAPEnvelope instead of MessageContext
and do the property transfer via Options.

Exposing the MessageContext results in very loosly defined bundries of
what should be set or not. Unless user knows finer detail it is bit
tricky to create a MessageContext himself.
Thanks

Srinath

On 11/28/05, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
> Eran and I spent quite a few hours in the last few days going thru the
> client API and have a proposal for how to refactor it. Without
> explaining the current state in detail, I'll write up the proposed new
> state and then list the work items so you can see what we're proposing
> to change.
>
> The main motivation for the changes are to eliminate duplication across
> different levels of the API and overall to hide complexity and disclose
> it only as needed.
>
> All code is o.a.axis2.client unless otherwise indicated. The basic
> structure is as follows:
>
> - Options
>     This class is the generic options class containing all the options
> to configure any MEP client. This JavaBean will have bean properties for
> the usual addressing stuff (To/From/ReplyTo/FaultTo/etc.) as well as a
> HashMap backed property bag for putting arbitrary properties. Basically
> the idea is to make the Options class the one class that users use to
> configure any MEP client. Each MEPClient subclass will specify
> additional properties that must be in the Options instance in order to
> configure those downstream Client classes.
>
> - MEPClient
>     This is the abstract base class for all MEP clients. Remove all the
> get/set methods for addressing properties etc. and replace it with one
> method: get/setOptions which takes an Options instance.
>
> - InOutMEPClient
>     As above but inherit stuff from MEPClient instead.
>
> - InOnlyMEPClient
>     As above for cleanup. After that, rename as RobustInOnlyMEPClient as
> that's the MEP this is really implementing.
>
> - Add new InOnlyMEPClient to implement true fire-n-forget behavior on
> the client using a new thread.
>
> - Remove MessageSender and move the convenience method to send just a
> SOAPEnvelope or an OMElement to the parent RobustInOnlyMEPClient class.
> Add similar conveniences for the new InOnlyMEPClient class. Change the
> send() methods to not take an operation name at all but rather defalt to
> something.
>
> - Move Call.invoke with the simple forms of invoke() using a SOAPElement
> or an OMElement to the parent InOutMEPClient class. That makes Call
> redundant for the most part .. I'm fine in leaving for user convenience.
>
> Once we change this stuff, the code usage will look like this:
>
> import o.a.axis2.client.*;
>
> ...
> Options o = new Options();
> o.setX(..);
> o.setY(..);
> ...
> Call c = new Call ();
> c.setOptions (o);
> c.invoke ...
>
> So this avoids problems like having message information headers in
> multiple places etc.. Some other supporting mods are needed too but
> those are straightforward.
>
> We discussed doing the same approach for the Stub class but I haven't
> written that up yet.
>
> Sanjiva.
>
>