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 Sanjiva Weerawarana <sa...@opensource.lk> on 2007/11/01 01:36:31 UTC
Re: [Axis2] Proposal to chage the method signature of set/get documentation
+1 that we'd be making the keep-the-simple-case-simple rule by losing the
String method.
Keith, what's the harm in having two methods? That is, do both.
Sanjiva.
Tom Jordahl wrote:
> Removing String as an argument type seems like a bad idea to me for two
> reasons:
>
>
>
> 1. Breaking API compatibility, if it is public, is not nice.
>
>
>
> 2. If I want to put a string there (which I think you are saying goes in
> the <documentation> elements of the WSDL) you are making me create
> another object. Sure it’s “easy”, but it doesn’t make me like the API
> much. I think putting a string in this element is the 90+% use case,
> right? Who is putting XML in here? Is there a public WSDL that you can
> point to that does this?
>
>
>
> --
> Tom Jordahl
>
> ------------------------------------------------------------------------
>
> *From:* keith chapman [mailto:keithgchapman@gmail.com]
> *Sent:* Friday, October 26, 2007 8:16 AM
> *To:* axis-dev@ws.apache.org
> *Subject:* Re: [Axis2] Proposal to chage the method signature of set/get
> documentation
>
>
>
> +1 for changing getDocumentation to return OMNode (no deprecation, same
> will have to go for setDocumentation). Although this is an API method
> its mostly used from within for generating the WSDL.
>
> Thanks,
> Keith.
>
> On 10/26/07, *Glen Daniels* <glen@thoughtcraft.com
> <ma...@thoughtcraft.com>> wrote:
>
> Well, +1 except for the fact that you can't overload getDocumentation()
> and just change the return type - so there's no way to deprecate that
> one without adding another method like getDocumentationOM(). We could
> either do that and avoid breaking existing stuff, or just change
> getDocumentation() and accept the incompatible change.
>
> --Glen
>
> Sanjiva Weerawarana wrote:
>> +1.
>>
>> keith chapman wrote:
>> > Hi Devs,
>> >
>> > Currently the method signature for det/get documentation in
>> > AxisDescriptio is as follows.
>> >
>> > public String getDocumentation();
>> > public void setDocumentation(String documentation);
>> >
>> > As you can see it treats the documentation as a string. There are
>> > occasions where the documentation can be XML though. If the
>> > documentation is XML what we do currently is wrap it in CDATA tags.
>> > This works, but its not the best sollution.
>> >
>> > I propose deprecating the above methods and introducing the following
>> > methods which that documentation as an OMNode.
>> >
>> > public OMNode getDocumentation();
>> > public void setDocumentation(OMNode documentation);
>> >
>> > This will enable us to set the documentation as an OMText or OMElement.
>> >
>> > If needed we can retain the old methods without deprecating them (Just
>> > leave them as a convenience method), where they will call into the new
>> > method.
>> >
>> > The above proposal is targeted at improving the wsdl served by Axis2.
>> > With what we have currently documentation which is XML is wrapped in
>> > CDATA tags in the WSDL.
>> >
>> > Thanks,
>> > Keith.
>> >
>> > --
>> > Keith Chapman
>> > WSO2 Inc.
>> > Oxygen for Web Services Developers.
>> > http://wso2.org/
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> <ma...@ws.apache.org>
> For additional commands, e-mail: axis-dev-help@ws.apache.org
> <ma...@ws.apache.org>
>
>
>
>
> --
> Keith Chapman
> WSO2 Inc.
> Oxygen for Web Services Developers.
> http://wso2.org/
>
--
Sanjiva Weerawarana, Ph.D.
Founder & Director; Lanka Software Foundation; http://www.opensource.lk/
Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
Member; Apache Software Foundation; http://www.apache.org/
Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org
RE: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by Tom Jordahl <tj...@adobe.com>.
Sorry for the late follow up. Out last week.
+1 for proposal below.
+0 for getDocumentationAsString()
--
Tom Jordahl
________________________________
From: keith chapman [mailto:keithgchapman@gmail.com]
Sent: Wednesday, November 07, 2007 12:34 AM
To: axis-dev@ws.apache.org
Subject: Re: [Axis2] Proposal to chage the method signature of set/get
documentation
So shall we settle for
public OMNode getDocumentation();
public void setDocumentation(OMNode documentation);
public void setDocumentation(String documentation);
and do we need public String getDocumentationAsString();?
Thanks,
Keith.
On 11/1/07, keith chapman <ke...@gmail.com> wrote:
We can have the setter method for both but not the getter.
So we can have
public void setDocumentation(String documentation);
but we cant have
public String getDocumentation(); cause we would already have public
OMNode getDocumentation();
Thanks,
Keith.
On 11/1/07, Sanjiva Weerawarana < sanjiva@opensource.lk
<ma...@opensource.lk> > wrote:
+1 that we'd be making the keep-the-simple-case-simple rule by losing
the
String method.
Keith, what's the harm in having two methods? That is, do both.
Sanjiva.
Tom Jordahl wrote:
> Removing String as an argument type seems like a bad idea to me for
two
> reasons:
>
>
>
> 1. Breaking API compatibility, if it is public, is not nice.
>
>
>
> 2. If I want to put a string there (which I think you are saying goes
in
> the <documentation> elements of the WSDL) you are making me create
> another object. Sure it's "easy", but it doesn't make me like the API
> much. I think putting a string in this element is the 90+% use case,
> right? Who is putting XML in here? Is there a public WSDL that you
can
> point to that does this?
>
>
>
> --
> Tom Jordahl
>
>
------------------------------------------------------------------------
>
> *From:* keith chapman [mailto: keithgchapman@gmail.com]
> *Sent:* Friday, October 26, 2007 8:16 AM
> *To:* axis-dev@ws.apache.org
> *Subject:* Re: [Axis2] Proposal to chage the method signature of
set/get
> documentation
>
>
>
> +1 for changing getDocumentation to return OMNode (no deprecation,
same
> will have to go for setDocumentation). Although this is an API method
> its mostly used from within for generating the WSDL.
>
> Thanks,
> Keith.
>
> On 10/26/07, *Glen Daniels* <glen@thoughtcraft.com
> <mailto:glen@thoughtcraft.com >> wrote:
>
> Well, +1 except for the fact that you can't overload
getDocumentation()
> and just change the return type - so there's no way to deprecate that
> one without adding another method like getDocumentationOM(). We could
> either do that and avoid breaking existing stuff, or just change
> getDocumentation() and accept the incompatible change.
>
> --Glen
>
> Sanjiva Weerawarana wrote:
>> +1.
>>
>> keith chapman wrote:
>> > Hi Devs,
>> >
>> > Currently the method signature for det/get documentation in
>> > AxisDescriptio is as follows.
>> >
>> > public String getDocumentation();
>> > public void setDocumentation(String documentation);
>> >
>> > As you can see it treats the documentation as a string. There are
>> > occasions where the documentation can be XML though. If the
>> > documentation is XML what we do currently is wrap it in CDATA tags.
>> > This works, but its not the best sollution.
>> >
>> > I propose deprecating the above methods and introducing the
following
>> > methods which that documentation as an OMNode.
>> >
>> > public OMNode getDocumentation();
>> > public void setDocumentation(OMNode documentation);
>> >
>> > This will enable us to set the documentation as an OMText or
OMElement.
>> >
>> > If needed we can retain the old methods without deprecating them
(Just
>> > leave them as a convenience method), where they will call into the
new
>> > method.
>> >
>> > The above proposal is targeted at improving the wsdl served by
Axis2.
>> > With what we have currently documentation which is XML is wrapped
in
>> > CDATA tags in the WSDL.
>> >
>> > Thanks,
>> > Keith.
>> >
>> > --
>> > Keith Chapman
>> > WSO2 Inc.
>> > Oxygen for Web Services Developers.
>> > http://wso2.org/
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> <mailto: axis-dev-unsubscribe@ws.apache.org
<ma...@ws.apache.org> >
> For additional commands, e-mail: axis-dev-help@ws.apache.org
> <mailto: axis-dev-help@ws.apache.org
<ma...@ws.apache.org> >
>
>
>
>
> --
> Keith Chapman
> WSO2 Inc.
> Oxygen for Web Services Developers.
> http://wso2.org/
>
--
Sanjiva Weerawarana, Ph.D.
Founder & Director; Lanka Software Foundation; http://www.opensource.lk/
Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
Member; Apache Software Foundation; http://www.apache.org/
Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org
--
Keith Chapman
WSO2 Inc.
Oxygen for Web Services Developers.
http://wso2.org/
--
Keith Chapman
WSO2 Inc.
Oxygen for Web Services Developers.
http://wso2.org/
Re: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by keith chapman <ke...@gmail.com>.
So shall we settle for
public OMNode getDocumentation();
public void setDocumentation(OMNode documentation);
public void setDocumentation(String documentation);
and do we need public String getDocumentationAsString();?
Thanks,
Keith.
On 11/1/07, keith chapman <ke...@gmail.com> wrote:
>
> We can have the setter method for both but not the getter.
>
> So we can have
>
> public void setDocumentation(String documentation);
> but we cant have
> public String getDocumentation(); cause we would already have public
> OMNode getDocumentation();
>
> Thanks,
> Keith.
>
> On 11/1/07, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
> >
> > +1 that we'd be making the keep-the-simple-case-simple rule by losing
> > the
> > String method.
> >
> > Keith, what's the harm in having two methods? That is, do both.
> >
> > Sanjiva.
> >
> > Tom Jordahl wrote:
> > > Removing String as an argument type seems like a bad idea to me for
> > two
> > > reasons:
> > >
> > >
> > >
> > > 1. Breaking API compatibility, if it is public, is not nice.
> > >
> > >
> > >
> > > 2. If I want to put a string there (which I think you are saying goes
> > in
> > > the <documentation> elements of the WSDL) you are making me create
> > > another object. Sure it's "easy", but it doesn't make me like the API
> > > much. I think putting a string in this element is the 90+% use case,
> > > right? Who is putting XML in here? Is there a public WSDL that you
> > can
> > > point to that does this?
> > >
> > >
> > >
> > > --
> > > Tom Jordahl
> > >
> > >
> > ------------------------------------------------------------------------
> > >
> > > *From:* keith chapman [mailto: keithgchapman@gmail.com]
> > > *Sent:* Friday, October 26, 2007 8:16 AM
> > > *To:* axis-dev@ws.apache.org
> > > *Subject:* Re: [Axis2] Proposal to chage the method signature of
> > set/get
> > > documentation
> > >
> > >
> > >
> > > +1 for changing getDocumentation to return OMNode (no deprecation,
> > same
> > > will have to go for setDocumentation). Although this is an API method
> > > its mostly used from within for generating the WSDL.
> > >
> > > Thanks,
> > > Keith.
> > >
> > > On 10/26/07, *Glen Daniels* <glen@thoughtcraft.com
> > > <mailto:glen@thoughtcraft.com >> wrote:
> > >
> > > Well, +1 except for the fact that you can't overload
> > getDocumentation()
> > > and just change the return type - so there's no way to deprecate that
> > > one without adding another method like getDocumentationOM(). We could
> >
> > > either do that and avoid breaking existing stuff, or just change
> > > getDocumentation() and accept the incompatible change.
> > >
> > > --Glen
> > >
> > > Sanjiva Weerawarana wrote:
> > >> +1.
> > >>
> > >> keith chapman wrote:
> > >> > Hi Devs,
> > >> >
> > >> > Currently the method signature for det/get documentation in
> > >> > AxisDescriptio is as follows.
> > >> >
> > >> > public String getDocumentation();
> > >> > public void setDocumentation(String documentation);
> > >> >
> > >> > As you can see it treats the documentation as a string. There are
> > >> > occasions where the documentation can be XML though. If the
> > >> > documentation is XML what we do currently is wrap it in CDATA tags.
> > >> > This works, but its not the best sollution.
> > >> >
> > >> > I propose deprecating the above methods and introducing the
> > following
> > >> > methods which that documentation as an OMNode.
> > >> >
> > >> > public OMNode getDocumentation();
> > >> > public void setDocumentation(OMNode documentation);
> > >> >
> > >> > This will enable us to set the documentation as an OMText or
> > OMElement.
> > >> >
> > >> > If needed we can retain the old methods without deprecating them
> > (Just
> > >> > leave them as a convenience method), where they will call into the
> > new
> > >> > method.
> > >> >
> > >> > The above proposal is targeted at improving the wsdl served by
> > Axis2.
> > >> > With what we have currently documentation which is XML is wrapped
> > in
> > >> > CDATA tags in the WSDL.
> > >> >
> > >> > Thanks,
> > >> > Keith.
> > >> >
> > >> > --
> > >> > Keith Chapman
> > >> > WSO2 Inc.
> > >> > Oxygen for Web Services Developers.
> > >> > http://wso2.org/
> > >>
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> > > <mailto:axis-dev-unsubscribe@ws.apache.org >
> > > For additional commands, e-mail: axis-dev-help@ws.apache.org
> > > <mailto:axis-dev-help@ws.apache.org >
> > >
> > >
> > >
> > >
> > > --
> > > Keith Chapman
> > > WSO2 Inc.
> > > Oxygen for Web Services Developers.
> > > http://wso2.org/
> > >
> >
> > --
> > Sanjiva Weerawarana, Ph.D.
> > Founder & Director; Lanka Software Foundation; http://www.opensource.lk/
> > Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
> > Member; Apache Software Foundation; http://www.apache.org/
> > Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> > For additional commands, e-mail: axis-dev-help@ws.apache.org
> >
> >
>
>
> --
> Keith Chapman
> WSO2 Inc.
> Oxygen for Web Services Developers.
> http://wso2.org/
>
--
Keith Chapman
WSO2 Inc.
Oxygen for Web Services Developers.
http://wso2.org/
Re: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by keith chapman <ke...@gmail.com>.
We can have the setter method for both but not the getter.
So we can have
public void setDocumentation(String documentation);
but we cant have
public String getDocumentation(); cause we would already have public OMNode
getDocumentation();
Thanks,
Keith.
On 11/1/07, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
>
> +1 that we'd be making the keep-the-simple-case-simple rule by losing the
> String method.
>
> Keith, what's the harm in having two methods? That is, do both.
>
> Sanjiva.
>
> Tom Jordahl wrote:
> > Removing String as an argument type seems like a bad idea to me for two
> > reasons:
> >
> >
> >
> > 1. Breaking API compatibility, if it is public, is not nice.
> >
> >
> >
> > 2. If I want to put a string there (which I think you are saying goes in
> > the <documentation> elements of the WSDL) you are making me create
> > another object. Sure it's "easy", but it doesn't make me like the API
> > much. I think putting a string in this element is the 90+% use case,
> > right? Who is putting XML in here? Is there a public WSDL that you can
> > point to that does this?
> >
> >
> >
> > --
> > Tom Jordahl
> >
> > ------------------------------------------------------------------------
> >
> > *From:* keith chapman [mailto:keithgchapman@gmail.com]
> > *Sent:* Friday, October 26, 2007 8:16 AM
> > *To:* axis-dev@ws.apache.org
> > *Subject:* Re: [Axis2] Proposal to chage the method signature of set/get
> > documentation
> >
> >
> >
> > +1 for changing getDocumentation to return OMNode (no deprecation, same
> > will have to go for setDocumentation). Although this is an API method
> > its mostly used from within for generating the WSDL.
> >
> > Thanks,
> > Keith.
> >
> > On 10/26/07, *Glen Daniels* <glen@thoughtcraft.com
> > <ma...@thoughtcraft.com>> wrote:
> >
> > Well, +1 except for the fact that you can't overload getDocumentation()
> > and just change the return type - so there's no way to deprecate that
> > one without adding another method like getDocumentationOM(). We could
> > either do that and avoid breaking existing stuff, or just change
> > getDocumentation() and accept the incompatible change.
> >
> > --Glen
> >
> > Sanjiva Weerawarana wrote:
> >> +1.
> >>
> >> keith chapman wrote:
> >> > Hi Devs,
> >> >
> >> > Currently the method signature for det/get documentation in
> >> > AxisDescriptio is as follows.
> >> >
> >> > public String getDocumentation();
> >> > public void setDocumentation(String documentation);
> >> >
> >> > As you can see it treats the documentation as a string. There are
> >> > occasions where the documentation can be XML though. If the
> >> > documentation is XML what we do currently is wrap it in CDATA tags.
> >> > This works, but its not the best sollution.
> >> >
> >> > I propose deprecating the above methods and introducing the following
> >> > methods which that documentation as an OMNode.
> >> >
> >> > public OMNode getDocumentation();
> >> > public void setDocumentation(OMNode documentation);
> >> >
> >> > This will enable us to set the documentation as an OMText or
> OMElement.
> >> >
> >> > If needed we can retain the old methods without deprecating them
> (Just
> >> > leave them as a convenience method), where they will call into the
> new
> >> > method.
> >> >
> >> > The above proposal is targeted at improving the wsdl served by Axis2.
> >> > With what we have currently documentation which is XML is wrapped in
> >> > CDATA tags in the WSDL.
> >> >
> >> > Thanks,
> >> > Keith.
> >> >
> >> > --
> >> > Keith Chapman
> >> > WSO2 Inc.
> >> > Oxygen for Web Services Developers.
> >> > http://wso2.org/
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> > <ma...@ws.apache.org>
> > For additional commands, e-mail: axis-dev-help@ws.apache.org
> > <ma...@ws.apache.org>
> >
> >
> >
> >
> > --
> > Keith Chapman
> > WSO2 Inc.
> > Oxygen for Web Services Developers.
> > http://wso2.org/
> >
>
> --
> Sanjiva Weerawarana, Ph.D.
> Founder & Director; Lanka Software Foundation; http://www.opensource.lk/
> Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
> Member; Apache Software Foundation; http://www.apache.org/
> Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-dev-help@ws.apache.org
>
>
--
Keith Chapman
WSO2 Inc.
Oxygen for Web Services Developers.
http://wso2.org/