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 keith chapman <ke...@gmail.com> on 2007/10/26 04:01:29 UTC
[Axis2] Proposal to chage the method signature of set/get documentation
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/
Re: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by keith chapman <ke...@gmail.com>.
On 10/26/07, Eran Chinthaka <ch...@opensource.lk> wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> +1 from me.
>
> If some one calls the earlier methods, you can serialize the OMNode and
> return, which i think is the easier to do.
Sure.
Thanks,
Keith.
Chinthaka
>
> 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/
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.6 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
>
> iD8DBQFHIWucjON2uBzUhh8RAtmCAKCabVIEiPB/qtLSnzhw2PvW5Jj+GwCaA17r
> xWy2A3una8h4LSgppYDjGYM=
> =2Dyf
> -----END PGP SIGNATURE-----
>
> ---------------------------------------------------------------------
> 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/
Re: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by Eran Chinthaka <ch...@opensource.lk>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
+1 from me.
If some one calls the earlier methods, you can serialize the OMNode and
return, which i think is the easier to do.
Chinthaka
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/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFHIWucjON2uBzUhh8RAtmCAKCabVIEiPB/qtLSnzhw2PvW5Jj+GwCaA17r
xWy2A3una8h4LSgppYDjGYM=
=2Dyf
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
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 keith chapman <ke...@gmail.com>.
BTW I forgot to mention that this site is powered by axis2.
Thanks,
Keith.
On 10/31/07, keith chapman <ke...@gmail.com> wrote:
>
> Hi Tom,
>
> Yes its not very common to have xml is tour documentation but there are
> occations where such information can be helpful. Here is a sample wsdl which
> has documentation as XML.
>
> http://mashups.wso2.org/services/nationalgeographic?wsdl2&annotation=trueIf you look at the source of it you will see how ugly the documentation
> looks.
>
> Thanks,
> Keith.
>
> On 10/27/07, Tom Jordahl <tj...@adobe.com> 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* <gl...@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
> > 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/
>
--
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>.
Hi Tom,
Yes its not very common to have xml is tour documentation but there are
occations where such information can be helpful. Here is a sample wsdl which
has documentation as XML.
http://mashups.wso2.org/services/nationalgeographic?wsdl2&annotation=true If
you look at the source of it you will see how ugly the documentation looks.
Thanks,
Keith.
On 10/27/07, Tom Jordahl <tj...@adobe.com> 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* <gl...@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
> 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 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/
Re: [Axis2] Proposal to chage the method signature of set/get documentation
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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>.
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 <gl...@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
For additional commands, e-mail: axis-dev-help@ws.apache.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>.
+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 <gl...@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
> For additional commands, e-mail: axis-dev-help@ws.apache.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 Glen Daniels <gl...@thoughtcraft.com>.
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
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 Sanjiva Weerawarana <sa...@opensource.lk>.
+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/
--
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