Finer-grained control over service methods (Pecl Request #11944)

Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
asking for finer-grained control over the methods which are
surfaced
on a service interface.  We currently just use class
visibility (i.e.
all public methods) to control this.

There's a small amount of discussion in the request, but I
thought it
would be good to raise it here to get greater visibility and
gather
more options/opinions.

Graham.


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

On 31 Aug, 08:42, Graham Charters <gchart...googlemail.com> wrote:
> Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> asking for finer-grained control over the methods which
are surfaced
> on a service interface.  We currently just use class
visibility (i.e.
> all public methods) to control this.
>
> There's a small amount of discussion in the request,
but I thought it
> would be good to raise it here to get greater
visibility and gather
> more options/opinions.
>
> Graham.

Following up on the comments made in the feature request...

It is true that in the Java SCA implementation the Service
information is associated with interfaces so a class will
implementat
one, or more, interfaces and this tells the runtime which
methods of
the class should be treated as service methods.

This is not currently how the PHP SCA implementation works.
All
annotations are placed on the class itself. This leads to a
level of
simplicity in service construction but we pay for this in
lack of
flexibility, for example, in excluding some methods from the
service
interface. At least given the set of annotations we have at
the
moment.

Having said this I'm not convinced that the use of
unannotated (is
that a word?) methods as part of the service interface makes
a lot of
sense give the way that the implementation works at the
moment. If you
look at what is actually generated in the WSDL in the case
of the
method "function foo($bar)" in the feature request
it doesn't seem to
be that useful. I.e. it defines null input and output types.
I assume
this is because there are no annotations for SCA to use for
typing the
interface. Fine for PHP but not so great for a service
interface.

So there are two issues here

1/ What should SCA do if it finds a method without
annotations, i.e.
no type information
2/ How can methods be omitted from the service interface,
i.e. we just
don't want to expose the method

As first suggested we could omit methods that don't have
comments at
all.. However this is problematic for issue 2 as annotations
may have
been included for producing the documentation that the
annotations
were originally designed for. However I think we should
consider
omitting methods without annotations due to issue 1 so this
could be a
short term solution 2.

Following the conversation on for issue 2. Maybe, as an
alternative to
scaExcludeMethod we could defined some new annotation
for the header
block that works as an alternative to defining an interface
(we should
look whether interfaces could be made to work), e.g.

/**
 * Scaffold implementation for a remote StockQuote Web
service.
 *
 * service
 * serviceinterface GetQuote getQuote
 * binding.soap
 *
 */

 If these don't appear then the default would be to operate
as now
with all of the (annotated) methods being parsed. The
intention here
being to replace/augment this with annotations on interfaces
if/'when
they work.

Regards

Simon



--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Hi Simon, thanks for the rapid comments.  Here's my thoughts
on the
two issues you identified:

> 1/ What should SCA do if it finds a method without
annotations, i.e.
> no type information

This probably depends on the type of service.  Service types
which
don't have a service description (e.g. local, REST and
Atom), don't
require this information to be specified.  Service types
which do have
service descriptions (soap, json-rpc, xml-rpc), do (to
varying
degrees).

I think if the binding type requires documentation then we
should warn
and not generate (rather than generating something which is
of no
use).  If the binding type doesn't require documentation
then it's
included.

> 2/ How can methods be omitted from the service
interface, i.e. we just
> don't want to expose the method
>


I don't think the absence of comments should be used as a
control
mechanism for the reason you and Matt have already
highlighted (might
want to document something but still not have it on the
service
interface).

I quite like the idea of using interfaces to add this level
of
control.  It would also be consistent with SCA (SCA Java
does this and
also supports the same class implementation approach we use
(i.e.
where there is no interface)).  How about something like:

/**
 * Scaffold implementation for a remote StockQuote Web
service.
 *
 * service StockQuoteInterface
 * binding.soap
 *
 */
StockQuoteImpl implements StockQuoteInterface,
ANOtherInterface {
  ...
}

This would be taken to mean that only those methods defined
on
StockQuoteInterface are part of the soap service.  Those in
ANOtherInterface or just in StockQuoteImpl would be
excluded.  I'd
prefer to pursue this approach rather than creating a new
annotations
which may go away in the near future.

Does this make sense and seem sensible?



On 31 Aug, 09:30, simonsl...googlemail.com wrote:
> On 31 Aug, 08:42, Graham Charters <gchart...googlemail.com> wrote:
>
> > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > asking for finer-grained control over the methods
which are surfaced
> > on a service interface.  We currently just use
class visibility (i.e.
> > all public methods) to control this.
>
> > There's a small amount of discussion in the
request, but I thought it
> > would be good to raise it here to get greater
visibility and gather
> > more options/opinions.
>
> > Graham.
>
> Following up on the comments made in the feature
request...
>
> It is true that in the Java SCA implementation the Service
> information is associated with interfaces so a class
will implementat
> one, or more, interfaces and this tells the runtime
which methods of
> the class should be treated as service methods.
>
> This is not currently how the PHP SCA implementation
works. All
> annotations are placed on the class itself. This leads
to a level of
> simplicity in service construction but we pay for this
in lack of
> flexibility, for example, in excluding some methods
from the service
> interface. At least given the set of annotations we
have at the
> moment.
>
> Having said this I'm not convinced that the use of
unannotated (is
> that a word?) methods as part of the service interface
makes a lot of
> sense give the way that the implementation works at the
moment. If you
> look at what is actually generated in the WSDL in the
case of the
> method "function foo($bar)" in the feature
request it doesn't seem to
> be that useful. I.e. it defines null input and output
types. I assume
> this is because there are no annotations for SCA to use
for typing the
> interface. Fine for PHP but not so great for a service
interface.
>
> So there are two issues here
>
> 1/ What should SCA do if it finds a method without
annotations, i.e.
> no type information
> 2/ How can methods be omitted from the service
interface, i.e. we just
> don't want to expose the method
>
> As first suggested we could omit methods that don't
have comments at
> all.. However this is problematic for issue 2 as
annotations may have
> been included for producing the documentation that the
annotations
> were originally designed for. However I think we should
consider
> omitting methods without annotations due to issue 1 so
this could be a
> short term solution 2.
>
> Following the conversation on for issue 2. Maybe, as an
alternative to
> scaExcludeMethod we could defined some new annotation
for the header
> block that works as an alternative to defining an
interface (we should
> look whether interfaces could be made to work), e.g.
>
> /**
>  * Scaffold implementation for a remote StockQuote Web
service.
>  *
>  * service
>  * serviceinterface GetQuote getQuote
>  * binding.soap
>  *
>  */
>
>  If these don't appear then the default would be to
operate as now
> with all of the (annotated) methods being parsed. The
intention here
> being to replace/augment this with annotations on
interfaces if/'when
> they work.
>
> Regards
>
> Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Hi Graham

Some more comments in line...

On 31 Aug, 11:26, Graham Charters <gchart...googlemail.com> wrote:
> Hi Simon, thanks for the rapid comments.  Here's my
thoughts on the
> two issues you identified:
>
> > 1/ What should SCA do if it finds a method without
annotations, i.e.
> > no type information
>
> This probably depends on the type of service.  Service
types which
> don't have a service description (e.g. local, REST and
Atom), don't
> require this information to be specified.  Service
types which do have
> service descriptions (soap, json-rpc, xml-rpc), do (to
varying
> degrees).
>
> I think if the binding type requires documentation then
we should warn
> and not generate (rather than generating something
which is of no
> use).  If the binding type doesn't require
documentation then it's
> included.
>
> > 2/ How can methods be omitted from the service
interface, i.e. we just
> > don't want to expose the method
>
> I don't think the absence of comments should be used as
a control
> mechanism for the reason you and Matt have already
highlighted (might
> want to document something but still not have it on the
service
> interface).
>
> I quite like the idea of using interfaces to add this
level of
> control.  It would also be consistent with SCA (SCA
Java does this and
> also supports the same class implementation approach we
use (i.e.
> where there is no interface)).  How about something
like:
>
> /**
>  * Scaffold implementation for a remote StockQuote Web
service.
>  *
>  * service StockQuoteInterface
>  * binding.soap
>  *
>  */
> StockQuoteImpl implements StockQuoteInterface,
ANOtherInterface {
>   ...
>
> }

So I like service StokeQuoteInterface

If you are suggesting that we can parse the
StockQuoteInterface to
pull out the method names which should be provided as
service
interfaces (without the need for further annotation on the
interface
itself) then this could work. My approach was a contraction
of this by
just providing the method names after the interface name in
the
annotation but your approach is more forward thinking.

Presumably the default would be to provide all methods if no
interface
is described.


>
> This would be taken to mean that only those methods
defined on
> StockQuoteInterface are part of the soap service. 
Those in
> ANOtherInterface or just in StockQuoteImpl would be
excluded.  I'd
> prefer to pursue this approach rather than creating a
new annotations
> which may go away in the near future.
>
> Does this make sense and seem sensible?
>
> On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > asking for finer-grained control over the
methods which are surfaced
> > > on a service interface.  We currently just
use class visibility (i.e.
> > > all public methods) to control this.
>
> > > There's a small amount of discussion in the
request, but I thought it
> > > would be good to raise it here to get greater
visibility and gather
> > > more options/opinions.
>
> > > Graham.
>
> > Following up on the comments made in the feature
request...
>
> > It is true that in the Java SCA implementation the
Service
> > information is associated with interfaces so a
class will implementat
> > one, or more, interfaces and this tells the
runtime which methods of
> > the class should be treated as service methods.
>
> > This is not currently how the PHP SCA
implementation works. All
> > annotations are placed on the class itself. This
leads to a level of
> > simplicity in service construction but we pay for
this in lack of
> > flexibility, for example, in excluding some
methods from the service
> > interface. At least given the set of annotations
we have at the
> > moment.
>
> > Having said this I'm not convinced that the use of
unannotated (is
> > that a word?) methods as part of the service
interface makes a lot of
> > sense give the way that the implementation works
at the moment. If you
> > look at what is actually generated in the WSDL in
the case of the
> > method "function foo($bar)" in the
feature request it doesn't seem to
> > be that useful. I.e. it defines null input and
output types. I assume
> > this is because there are no annotations for SCA
to use for typing the
> > interface. Fine for PHP but not so great for a
service interface.
>
> > So there are two issues here
>
> > 1/ What should SCA do if it finds a method without
annotations, i.e.
> > no type information
> > 2/ How can methods be omitted from the service
interface, i.e. we just
> > don't want to expose the method
>
> > As first suggested we could omit methods that
don't have comments at
> > all.. However this is problematic for issue 2 as
annotations may have
> > been included for producing the documentation that
the annotations
> > were originally designed for. However I think we
should consider
> > omitting methods without annotations due to issue
1 so this could be a
> > short term solution 2.
>
> > Following the conversation on for issue 2. Maybe,
as an alternative to
> > scaExcludeMethod we could defined some new annotation
for the header
> > block that works as an alternative to defining an
interface (we should
> > look whether interfaces could be made to work),
e.g.
>
> > /**
> >  * Scaffold implementation for a remote StockQuote
Web service.
> >  *
> >  * service
> >  * serviceinterface GetQuote getQuote
> >  * binding.soap
> >  *
> >  */
>
> >  If these don't appear then the default would be
to operate as now
> > with all of the (annotated) methods being parsed.
The intention here
> > being to replace/augment this with annotations on
interfaces if/'when
> > they work.
>
> > Regards
>
> > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Comments inlined below...

On 31 Aug, 11:35, simonsl...googlemail.com wrote:
> Hi Graham
>
> Some more comments in line...
>
> On 31 Aug, 11:26, Graham Charters <gchart...googlemail.com> wrote:
>
>
>
> > Hi Simon, thanks for the rapid comments.  Here's
my thoughts on the
> > two issues you identified:
>
> > > 1/ What should SCA do if it finds a method
without annotations, i.e.
> > > no type information
>
> > This probably depends on the type of service. 
Service types which
> > don't have a service description (e.g. local, REST
and Atom), don't
> > require this information to be specified.  Service
types which do have
> > service descriptions (soap, json-rpc, xml-rpc), do
(to varying
> > degrees).
>
> > I think if the binding type requires documentation
then we should warn
> > and not generate (rather than generating something
which is of no
> > use).  If the binding type doesn't require
documentation then it's
> > included.
>
> > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > don't want to expose the method
>
> > I don't think the absence of comments should be
used as a control
> > mechanism for the reason you and Matt have already
highlighted (might
> > want to document something but still not have it
on the service
> > interface).
>
> > I quite like the idea of using interfaces to add
this level of
> > control.  It would also be consistent with SCA
(SCA Java does this and
> > also supports the same class implementation
approach we use (i.e.
> > where there is no interface)).  How about
something like:
>
> > /**
> >  * Scaffold implementation for a remote StockQuote
Web service.
> >  *
> >  * service StockQuoteInterface
> >  * binding.soap
> >  *
> >  */
> > StockQuoteImpl implements StockQuoteInterface,
ANOtherInterface {
> >   ...
>
> > }
>
> So I like service StokeQuoteInterface
>
> If you are suggesting that we can parse the
StockQuoteInterface to
> pull out the method names which should be provided as
service
> interfaces (without the need for further annotation on
the interface
> itself) then this could work. My approach was a
contraction of this by
> just providing the method names after the interface
name in the
> annotation but your approach is more forward thinking.
>

We should be able to update this in
SCA_AnnotationReader.php.  I
believe all the information is available through Reflection.
 You can
call getInterfaces() on the ReflectionClass, which returns
an array of
ReflectionClass objects, one for each interface.  I don't
think we
would require further annotations in the interface, but we
will need
to decided whether to use annotations/documentation in an
interface if
it is provided.

> Presumably the default would be to provide all methods
if no interface
> is described.
>

Yes, so this would be backwards compatible.

>
>
> > This would be taken to mean that only those
methods defined on
> > StockQuoteInterface are part of the soap service. 
Those in
> > ANOtherInterface or just in StockQuoteImpl would
be excluded.  I'd
> > prefer to pursue this approach rather than
creating a new annotations
> > which may go away in the near future.
>
> > Does this make sense and seem sensible?
>
> > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > asking for finer-grained control over
the methods which are surfaced
> > > > on a service interface.  We currently
just use class visibility (i.e.
> > > > all public methods) to control this.
>
> > > > There's a small amount of discussion in
the request, but I thought it
> > > > would be good to raise it here to get
greater visibility and gather
> > > > more options/opinions.
>
> > > > Graham.
>
> > > Following up on the comments made in the
feature request...
>
> > > It is true that in the Java SCA
implementation the Service
> > > information is associated with interfaces so
a class will implementat
> > > one, or more, interfaces and this tells the
runtime which methods of
> > > the class should be treated as service
methods.
>
> > > This is not currently how the PHP SCA
implementation works. All
> > > annotations are placed on the class itself.
This leads to a level of
> > > simplicity in service construction but we pay
for this in lack of
> > > flexibility, for example, in excluding some
methods from the service
> > > interface. At least given the set of
annotations we have at the
> > > moment.
>
> > > Having said this I'm not convinced that the
use of unannotated (is
> > > that a word?) methods as part of the service
interface makes a lot of
> > > sense give the way that the implementation
works at the moment. If you
> > > look at what is actually generated in the
WSDL in the case of the
> > > method "function foo($bar)" in the
feature request it doesn't seem to
> > > be that useful. I.e. it defines null input
and output types. I assume
> > > this is because there are no annotations for
SCA to use for typing the
> > > interface. Fine for PHP but not so great for
a service interface.
>
> > > So there are two issues here
>
> > > 1/ What should SCA do if it finds a method
without annotations, i.e.
> > > no type information
> > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > don't want to expose the method
>
> > > As first suggested we could omit methods that
don't have comments at
> > > all.. However this is problematic for issue 2
as annotations may have
> > > been included for producing the documentation
that the annotations
> > > were originally designed for. However I think
we should consider
> > > omitting methods without annotations due to
issue 1 so this could be a
> > > short term solution 2.
>
> > > Following the conversation on for issue 2.
Maybe, as an alternative to
> > > scaExcludeMethod we could defined some new
annotation for the header
> > > block that works as an alternative to
defining an interface (we should
> > > look whether interfaces could be made to
work), e.g.
>
> > > /**
> > >  * Scaffold implementation for a remote
StockQuote Web service.
> > >  *
> > >  * service
> > >  * serviceinterface GetQuote getQuote
> > >  * binding.soap
> > >  *
> > >  */
>
> > >  If these don't appear then the default would
be to operate as now
> > > with all of the (annotated) methods being
parsed. The intention here
> > > being to replace/augment this with
annotations on interfaces if/'when
> > > they work.
>
> > > Regards
>
> > > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

On 31 Aug, 12:20, Graham Charters <gchart...googlemail.com> wrote:
> Comments inlined below...
>
> On 31 Aug, 11:35, simonsl...googlemail.com wrote:
>
>
>
> > Hi Graham
>
> > Some more comments in line...
>
> > On 31 Aug, 11:26, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > Hi Simon, thanks for the rapid comments. 
Here's my thoughts on the
> > > two issues you identified:
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
>
> > > This probably depends on the type of service.
 Service types which
> > > don't have a service description (e.g. local,
REST and Atom), don't
> > > require this information to be specified. 
Service types which do have
> > > service descriptions (soap, json-rpc,
xml-rpc), do (to varying
> > > degrees).
>
> > > I think if the binding type requires
documentation then we should warn
> > > and not generate (rather than generating
something which is of no
> > > use).  If the binding type doesn't require
documentation then it's
> > > included.
>
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > I don't think the absence of comments should
be used as a control
> > > mechanism for the reason you and Matt have
already highlighted (might
> > > want to document something but still not have
it on the service
> > > interface).
>
> > > I quite like the idea of using interfaces to
add this level of
> > > control.  It would also be consistent with
SCA (SCA Java does this and
> > > also supports the same class implementation
approach we use (i.e.
> > > where there is no interface)).  How about
something like:
>
> > > /**
> > >  * Scaffold implementation for a remote
StockQuote Web service.
> > >  *
> > >  * service StockQuoteInterface
> > >  * binding.soap
> > >  *
> > >  */
> > > StockQuoteImpl implements
StockQuoteInterface, ANOtherInterface {
> > >   ...
>
> > > }
>
> > So I like service StokeQuoteInterface
>
> > If you are suggesting that we can parse the
StockQuoteInterface to
> > pull out the method names which should be provided
as service
> > interfaces (without the need for further
annotation on the interface
> > itself) then this could work. My approach was a
contraction of this by
> > just providing the method names after the
interface name in the
> > annotation but your approach is more forward
thinking.
>
> We should be able to update this in
SCA_AnnotationReader.php.  I
> believe all the information is available through
Reflection.  You can
> call getInterfaces() on the ReflectionClass, which
returns an array of
> ReflectionClass objects, one for each interface.  I
don't think we
> would require further annotations in the interface, but
we will need
> to decided whether to use annotations/documentation in
an interface if
> it is provided.
>
> > Presumably the default would be to provide all
methods if no interface
> > is described.
>
> Yes, so this would be backwards compatible.
>
>
>
> > > This would be taken to mean that only those
methods defined on
> > > StockQuoteInterface are part of the soap
service.  Those in
> > > ANOtherInterface or just in StockQuoteImpl
would be excluded.  I'd
> > > prefer to pursue this approach rather than
creating a new annotations
> > > which may go away in the near future.
>
> > > Does this make sense and seem sensible?
>
> > > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > > asking for finer-grained control
over the methods which are surfaced
> > > > > on a service interface.  We
currently just use class visibility (i.e.
> > > > > all public methods) to control
this.
>
> > > > > There's a small amount of
discussion in the request, but I thought it
> > > > > would be good to raise it here to
get greater visibility and gather
> > > > > more options/opinions.
>
> > > > > Graham.
>
> > > > Following up on the comments made in the
feature request...
>
> > > > It is true that in the Java SCA
implementation the Service
> > > > information is associated with
interfaces so a class will implementat
> > > > one, or more, interfaces and this tells
the runtime which methods of
> > > > the class should be treated as service
methods.
>
> > > > This is not currently how the PHP SCA
implementation works. All
> > > > annotations are placed on the class
itself. This leads to a level of
> > > > simplicity in service construction but
we pay for this in lack of
> > > > flexibility, for example, in excluding
some methods from the service
> > > > interface. At least given the set of
annotations we have at the
> > > > moment.
>
> > > > Having said this I'm not convinced that
the use of unannotated (is
> > > > that a word?) methods as part of the
service interface makes a lot of
> > > > sense give the way that the
implementation works at the moment. If you
> > > > look at what is actually generated in
the WSDL in the case of the
> > > > method "function foo($bar)" in
the feature request it doesn't seem to
> > > > be that useful. I.e. it defines null
input and output types. I assume
> > > > this is because there are no annotations
for SCA to use for typing the
> > > > interface. Fine for PHP but not so great
for a service interface.
>
> > > > So there are two issues here
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > > As first suggested we could omit methods
that don't have comments at
> > > > all.. However this is problematic for
issue 2 as annotations may have
> > > > been included for producing the
documentation that the annotations
> > > > were originally designed for. However I
think we should consider
> > > > omitting methods without annotations due
to issue 1 so this could be a
> > > > short term solution 2.
>
> > > > Following the conversation on for issue
2. Maybe, as an alternative to
> > > > scaExcludeMethod we could defined some new
annotation for the header
> > > > block that works as an alternative to
defining an interface (we should
> > > > look whether interfaces could be made to
work), e.g.
>
> > > > /**
> > > >  * Scaffold implementation for a remote
StockQuote Web service.
> > > >  *
> > > >  * service
> > > >  * serviceinterface GetQuote getQuote
> > > >  * binding.soap
> > > >  *
> > > >  */
>
> > > >  If these don't appear then the default
would be to operate as now
> > > > with all of the (annotated) methods
being parsed. The intention here
> > > > being to replace/augment this with
annotations on interfaces if/'when
> > > > they work.
>
> > > > Regards
>
> > > > Simon
I think we would uses annotations on an interface if we find
them
there and we can make the code work to do this. Don't
necessarily need
to make this work in the first instance though.

Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Setting service on the interface to allow exclusion of
methods in the
class also seems the best route to me.  The only thing I see
missing
is if the service is set on the interface, I suppose you
would want to
annotate all the methods on the interface instead of the
class?



Matt

On 31 Aug, 06:20, Graham Charters <gchart...googlemail.com> wrote:
> Comments inlined below...
>
> On 31 Aug, 11:35, simonsl...googlemail.com wrote:
>
>
>
> > Hi Graham
>
> > Some more comments in line...
>
> > On 31 Aug, 11:26, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > Hi Simon, thanks for the rapid comments. 
Here's my thoughts on the
> > > two issues you identified:
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
>
> > > This probably depends on the type of service.
 Service types which
> > > don't have a service description (e.g. local,
REST and Atom), don't
> > > require this information to be specified. 
Service types which do have
> > > service descriptions (soap, json-rpc,
xml-rpc), do (to varying
> > > degrees).
>
> > > I think if the binding type requires
documentation then we should warn
> > > and not generate (rather than generating
something which is of no
> > > use).  If the binding type doesn't require
documentation then it's
> > > included.
>
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > I don't think the absence of comments should
be used as a control
> > > mechanism for the reason you and Matt have
already highlighted (might
> > > want to document something but still not have
it on the service
> > > interface).
>
> > > I quite like the idea of using interfaces to
add this level of
> > > control.  It would also be consistent with
SCA (SCA Java does this and
> > > also supports the same class implementation
approach we use (i.e.
> > > where there is no interface)).  How about
something like:
>
> > > /**
> > >  * Scaffold implementation for a remote
StockQuote Web service.
> > >  *
> > >  * service StockQuoteInterface
> > >  * binding.soap
> > >  *
> > >  */
> > > StockQuoteImpl implements
StockQuoteInterface, ANOtherInterface {
> > >   ...
>
> > > }
>
> > So I like service StokeQuoteInterface
>
> > If you are suggesting that we can parse the
StockQuoteInterface to
> > pull out the method names which should be provided
as service
> > interfaces (without the need for further
annotation on the interface
> > itself) then this could work. My approach was a
contraction of this by
> > just providing the method names after the
interface name in the
> > annotation but your approach is more forward
thinking.
>
> We should be able to update this in
SCA_AnnotationReader.php.  I
> believe all the information is available through
Reflection.  You can
> call getInterfaces() on the ReflectionClass, which
returns an array of
> ReflectionClass objects, one for each interface.  I
don't think we
> would require further annotations in the interface, but
we will need
> to decided whether to use annotations/documentation in
an interface if
> it is provided.
>
> > Presumably the default would be to provide all
methods if no interface
> > is described.
>
> Yes, so this would be backwards compatible.
>
>
>
> > > This would be taken to mean that only those
methods defined on
> > > StockQuoteInterface are part of the soap
service.  Those in
> > > ANOtherInterface or just in StockQuoteImpl
would be excluded.  I'd
> > > prefer to pursue this approach rather than
creating a new annotations
> > > which may go away in the near future.
>
> > > Does this make sense and seem sensible?
>
> > > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > > asking for finer-grained control
over the methods which are surfaced
> > > > > on a service interface.  We
currently just use class visibility (i.e.
> > > > > all public methods) to control
this.
>
> > > > > There's a small amount of
discussion in the request, but I thought it
> > > > > would be good to raise it here to
get greater visibility and gather
> > > > > more options/opinions.
>
> > > > > Graham.
>
> > > > Following up on the comments made in the
feature request...
>
> > > > It is true that in the Java SCA
implementation the Service
> > > > information is associated with
interfaces so a class will implementat
> > > > one, or more, interfaces and this tells
the runtime which methods of
> > > > the class should be treated as service
methods.
>
> > > > This is not currently how the PHP SCA
implementation works. All
> > > > annotations are placed on the class
itself. This leads to a level of
> > > > simplicity in service construction but
we pay for this in lack of
> > > > flexibility, for example, in excluding
some methods from the service
> > > > interface. At least given the set of
annotations we have at the
> > > > moment.
>
> > > > Having said this I'm not convinced that
the use of unannotated (is
> > > > that a word?) methods as part of the
service interface makes a lot of
> > > > sense give the way that the
implementation works at the moment. If you
> > > > look at what is actually generated in
the WSDL in the case of the
> > > > method "function foo($bar)" in
the feature request it doesn't seem to
> > > > be that useful. I.e. it defines null
input and output types. I assume
> > > > this is because there are no annotations
for SCA to use for typing the
> > > > interface. Fine for PHP but not so great
for a service interface.
>
> > > > So there are two issues here
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > > As first suggested we could omit methods
that don't have comments at
> > > > all.. However this is problematic for
issue 2 as annotations may have
> > > > been included for producing the
documentation that the annotations
> > > > were originally designed for. However I
think we should consider
> > > > omitting methods without annotations due
to issue 1 so this could be a
> > > > short term solution 2.
>
> > > > Following the conversation on for issue
2. Maybe, as an alternative to
> > > > scaExcludeMethod we could defined some new
annotation for the header
> > > > block that works as an alternative to
defining an interface (we should
> > > > look whether interfaces could be made to
work), e.g.
>
> > > > /**
> > > >  * Scaffold implementation for a remote
StockQuote Web service.
> > > >  *
> > > >  * service
> > > >  * serviceinterface GetQuote getQuote
> > > >  * binding.soap
> > > >  *
> > > >  */
>
> > > >  If these don't appear then the default
would be to operate as now
> > > > with all of the (annotated) methods
being parsed. The intention here
> > > > being to replace/augment this with
annotations on interfaces if/'when
> > > > they work.
>
> > > > Regards
>
> > > > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Actually after a second glance, I see all annotations are
still set in
the class.  It probably wouldn't make any sense to have SCA
parse
annotations in the interface.


Matt

On 31 Aug, 06:20, Graham Charters <gchart...googlemail.com> wrote:
> Comments inlined below...
>
> On 31 Aug, 11:35, simonsl...googlemail.com wrote:
>
>
>
> > Hi Graham
>
> > Some more comments in line...
>
> > On 31 Aug, 11:26, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > Hi Simon, thanks for the rapid comments. 
Here's my thoughts on the
> > > two issues you identified:
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
>
> > > This probably depends on the type of service.
 Service types which
> > > don't have a service description (e.g. local,
REST and Atom), don't
> > > require this information to be specified. 
Service types which do have
> > > service descriptions (soap, json-rpc,
xml-rpc), do (to varying
> > > degrees).
>
> > > I think if the binding type requires
documentation then we should warn
> > > and not generate (rather than generating
something which is of no
> > > use).  If the binding type doesn't require
documentation then it's
> > > included.
>
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > I don't think the absence of comments should
be used as a control
> > > mechanism for the reason you and Matt have
already highlighted (might
> > > want to document something but still not have
it on the service
> > > interface).
>
> > > I quite like the idea of using interfaces to
add this level of
> > > control.  It would also be consistent with
SCA (SCA Java does this and
> > > also supports the same class implementation
approach we use (i.e.
> > > where there is no interface)).  How about
something like:
>
> > > /**
> > >  * Scaffold implementation for a remote
StockQuote Web service.
> > >  *
> > >  * service StockQuoteInterface
> > >  * binding.soap
> > >  *
> > >  */
> > > StockQuoteImpl implements
StockQuoteInterface, ANOtherInterface {
> > >   ...
>
> > > }
>
> > So I like service StokeQuoteInterface
>
> > If you are suggesting that we can parse the
StockQuoteInterface to
> > pull out the method names which should be provided
as service
> > interfaces (without the need for further
annotation on the interface
> > itself) then this could work. My approach was a
contraction of this by
> > just providing the method names after the
interface name in the
> > annotation but your approach is more forward
thinking.
>
> We should be able to update this in
SCA_AnnotationReader.php.  I
> believe all the information is available through
Reflection.  You can
> call getInterfaces() on the ReflectionClass, which
returns an array of
> ReflectionClass objects, one for each interface.  I
don't think we
> would require further annotations in the interface, but
we will need
> to decided whether to use annotations/documentation in
an interface if
> it is provided.
>
> > Presumably the default would be to provide all
methods if no interface
> > is described.
>
> Yes, so this would be backwards compatible.
>
>
>
> > > This would be taken to mean that only those
methods defined on
> > > StockQuoteInterface are part of the soap
service.  Those in
> > > ANOtherInterface or just in StockQuoteImpl
would be excluded.  I'd
> > > prefer to pursue this approach rather than
creating a new annotations
> > > which may go away in the near future.
>
> > > Does this make sense and seem sensible?
>
> > > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > > asking for finer-grained control
over the methods which are surfaced
> > > > > on a service interface.  We
currently just use class visibility (i.e.
> > > > > all public methods) to control
this.
>
> > > > > There's a small amount of
discussion in the request, but I thought it
> > > > > would be good to raise it here to
get greater visibility and gather
> > > > > more options/opinions.
>
> > > > > Graham.
>
> > > > Following up on the comments made in the
feature request...
>
> > > > It is true that in the Java SCA
implementation the Service
> > > > information is associated with
interfaces so a class will implementat
> > > > one, or more, interfaces and this tells
the runtime which methods of
> > > > the class should be treated as service
methods.
>
> > > > This is not currently how the PHP SCA
implementation works. All
> > > > annotations are placed on the class
itself. This leads to a level of
> > > > simplicity in service construction but
we pay for this in lack of
> > > > flexibility, for example, in excluding
some methods from the service
> > > > interface. At least given the set of
annotations we have at the
> > > > moment.
>
> > > > Having said this I'm not convinced that
the use of unannotated (is
> > > > that a word?) methods as part of the
service interface makes a lot of
> > > > sense give the way that the
implementation works at the moment. If you
> > > > look at what is actually generated in
the WSDL in the case of the
> > > > method "function foo($bar)" in
the feature request it doesn't seem to
> > > > be that useful. I.e. it defines null
input and output types. I assume
> > > > this is because there are no annotations
for SCA to use for typing the
> > > > interface. Fine for PHP but not so great
for a service interface.
>
> > > > So there are two issues here
>
> > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > no type information
> > > > 2/ How can methods be omitted from the
service interface, i.e. we just
> > > > don't want to expose the method
>
> > > > As first suggested we could omit methods
that don't have comments at
> > > > all.. However this is problematic for
issue 2 as annotations may have
> > > > been included for producing the
documentation that the annotations
> > > > were originally designed for. However I
think we should consider
> > > > omitting methods without annotations due
to issue 1 so this could be a
> > > > short term solution 2.
>
> > > > Following the conversation on for issue
2. Maybe, as an alternative to
> > > > scaExcludeMethod we could defined some new
annotation for the header
> > > > block that works as an alternative to
defining an interface (we should
> > > > look whether interfaces could be made to
work), e.g.
>
> > > > /**
> > > >  * Scaffold implementation for a remote
StockQuote Web service.
> > > >  *
> > > >  * service
> > > >  * serviceinterface GetQuote getQuote
> > > >  * binding.soap
> > > >  *
> > > >  */
>
> > > >  If these don't appear then the default
would be to operate as now
> > > > with all of the (annotated) methods
being parsed. The intention here
> > > > being to replace/augment this with
annotations on interfaces if/'when
> > > > they work.
>
> > > > Regards
>
> > > > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

It sounds like we may have consensus.  To summarise:

1.  We should add the ability to specify an optional
interface for the
service on the service annotation (e.g. service
MyServiceInterface).  This would only be used to limit the
methods
exposed by the service, so we would not look for any other
metadata in
the interface (we could support this later).
2.  We should not include methods in service descriptions
which have
not been appropriately documented (this is to avoid
generating duff
services descriptions, and is not meant to be used as a
means of
controlling the service interface).

Hopefully I'll be able to take a look at 1 sometime towards
the end of
this week, unless someone else is itching to do it :-D

Graham.


On 31 Aug, 15:03, Matthew Schultz <matt...gmail.com> wrote:
> Actually after a second glance, I see all annotations
are still set in
> the class.  It probably wouldn't make any sense to have
SCA parse
> annotations in the interface.
>
> Matt
>
> On 31 Aug, 06:20, Graham Charters <gchart...googlemail.com> wrote:> Comments inlined
below...
>
> > On 31 Aug, 11:35, simonsl...googlemail.com wrote:
>
> > > Hi Graham
>
> > > Some more comments in line...
>
> > > On 31 Aug, 11:26, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > Hi Simon, thanks for the rapid comments.
 Here's my thoughts on the
> > > > two issues you identified:
>
> > > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > > no type information
>
> > > > This probably depends on the type of
service.  Service types which
> > > > don't have a service description (e.g.
local, REST and Atom), don't
> > > > require this information to be
specified.  Service types which do have
> > > > service descriptions (soap, json-rpc,
xml-rpc), do (to varying
> > > > degrees).
>
> > > > I think if the binding type requires
documentation then we should warn
> > > > and not generate (rather than generating
something which is of no
> > > > use).  If the binding type doesn't
require documentation then it's
> > > > included.
>
> > > > > 2/ How can methods be omitted from
the service interface, i.e. we just
> > > > > don't want to expose the method
>
> > > > I don't think the absence of comments
should be used as a control
> > > > mechanism for the reason you and Matt
have already highlighted (might
> > > > want to document something but still not
have it on the service
> > > > interface).
>
> > > > I quite like the idea of using
interfaces to add this level of
> > > > control.  It would also be consistent
with SCA (SCA Java does this and
> > > > also supports the same class
implementation approach we use (i.e.
> > > > where there is no interface)).  How
about something like:
>
> > > > /**
> > > >  * Scaffold implementation for a remote
StockQuote Web service.
> > > >  *
> > > >  * service StockQuoteInterface
> > > >  * binding.soap
> > > >  *
> > > >  */
> > > > StockQuoteImpl implements
StockQuoteInterface, ANOtherInterface {
> > > >   ...
>
> > > > }
>
> > > So I like service
StokeQuoteInterface
>
> > > If you are suggesting that we can parse the
StockQuoteInterface to
> > > pull out the method names which should be
provided as service
> > > interfaces (without the need for further
annotation on the interface
> > > itself) then this could work. My approach was
a contraction of this by
> > > just providing the method names after the
interface name in the
> > > annotation but your approach is more forward
thinking.
>
> > We should be able to update this in
SCA_AnnotationReader.php.  I
> > believe all the information is available through
Reflection.  You can
> > call getInterfaces() on the ReflectionClass, which
returns an array of
> > ReflectionClass objects, one for each interface. 
I don't think we
> > would require further annotations in the
interface, but we will need
> > to decided whether to use
annotations/documentation in an interface if
> > it is provided.
>
> > > Presumably the default would be to provide
all methods if no interface
> > > is described.
>
> > Yes, so this would be backwards compatible.
>
> > > > This would be taken to mean that only
those methods defined on
> > > > StockQuoteInterface are part of the soap
service.  Those in
> > > > ANOtherInterface or just in
StockQuoteImpl would be excluded.  I'd
> > > > prefer to pursue this approach rather
than creating a new annotations
> > > > which may go away in the near future.
>
> > > > Does this make sense and seem sensible?
>
> > > > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > > > On 31 Aug, 08:42, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > > > asking for finer-grained
control over the methods which are surfaced
> > > > > > on a service interface.  We
currently just use class visibility (i.e.
> > > > > > all public methods) to control
this.
>
> > > > > > There's a small amount of
discussion in the request, but I thought it
> > > > > > would be good to raise it here
to get greater visibility and gather
> > > > > > more options/opinions.
>
> > > > > > Graham.
>
> > > > > Following up on the comments made
in the feature request...
>
> > > > > It is true that in the Java SCA
implementation the Service
> > > > > information is associated with
interfaces so a class will implementat
> > > > > one, or more, interfaces and this
tells the runtime which methods of
> > > > > the class should be treated as
service methods.
>
> > > > > This is not currently how the PHP
SCA implementation works. All
> > > > > annotations are placed on the class
itself. This leads to a level of
> > > > > simplicity in service construction
but we pay for this in lack of
> > > > > flexibility, for example, in
excluding some methods from the service
> > > > > interface. At least given the set
of annotations we have at the
> > > > > moment.
>
> > > > > Having said this I'm not convinced
that the use of unannotated (is
> > > > > that a word?) methods as part of
the service interface makes a lot of
> > > > > sense give the way that the
implementation works at the moment. If you
> > > > > look at what is actually generated
in the WSDL in the case of the
> > > > > method "function
foo($bar)" in the feature request it doesn't seem to
> > > > > be that useful. I.e. it defines
null input and output types. I assume
> > > > > this is because there are no
annotations for SCA to use for typing the
> > > > > interface. Fine for PHP but not so
great for a service interface.
>
> > > > > So there are two issues here
>
> > > > > 1/ What should SCA do if it finds a
method without annotations, i.e.
> > > > > no type information
> > > > > 2/ How can methods be omitted from
the service interface, i.e. we just
> > > > > don't want to expose the method
>
> > > > > As first suggested we could omit
methods that don't have comments at
> > > > > all.. However this is problematic
for issue 2 as annotations may have
> > > > > been included for producing the
documentation that the annotations
> > > > > were originally designed for.
However I think we should consider
> > > > > omitting methods without
annotations due to issue 1 so this could be a
> > > > > short term solution 2.
>
> > > > > Following the conversation on for
issue 2. Maybe, as an alternative to
> > > > > scaExcludeMethod we could
defined some new annotation for the header
> > > > > block that works as an alternative
to defining an interface (we should
> > > > > look whether interfaces could be
made to work), e.g.
>
> > > > > /**
> > > > >  * Scaffold implementation for a
remote StockQuote Web service.
> > > > >  *
> > > > >  * service
> > > > >  * serviceinterface GetQuote
getQuote
> > > > >  * binding.soap
> > > > >  *
> > > > >  */
>
> > > > >  If these don't appear then the
default would be to operate as now
> > > > > with all of the (annotated) methods
being parsed. The intention here
> > > > > being to replace/augment this with
annotations on interfaces if/'when
> > > > > they work.
>
> > > > > Regards
>
> > > > > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---

Just a quick status update...

I've done the code to optionally allow an interface to be
specified
and tested this independent of a protocol binding and all
works fine.
Unfortunately, when called from a remote invocation, the
classexists
tests for the service implementation fails. 
Get_declared_classes()
confirms that it does not have the definition and
get_declared_interfaces() confirms that it knows about the
interfaces.  Removing the interfaces makes everything work
as before,
so it appears to be a PHP nit.

I'm going to try to create a little test case to reproduce
this
outside SCA.  If anyone has heard of anything which might be
relevant,
please let me know.

Graham.

On 3 Sep, 13:18, Graham Charters <gchart...googlemail.com> wrote:
> It sounds like we may have consensus.  To summarise:
>
> 1.  We should add the ability to specify an optional
interface for the
> service on the service annotation (e.g. service
> MyServiceInterface).  This would only be used to limit
the methods
> exposed by the service, so we would not look for any
other metadata in
> the interface (we could support this later).
> 2.  We should not include methods in service
descriptions which have
> not been appropriately documented (this is to avoid
generating duff
> services descriptions, and is not meant to be used as a
means of
> controlling the service interface).
>
> Hopefully I'll be able to take a look at 1 sometime
towards the end of
> this week, unless someone else is itching to do it :-D
>
> Graham.
>
> On 31 Aug, 15:03, Matthew Schultz <matt...gmail.com> wrote:> Actually after a second
glance, I see all annotations are still set in
> > the class.  It probably wouldn't make any sense to
have SCA parse
> > annotations in the interface.
>
> > Matt
>
> > On 31 Aug, 06:20, Graham Charters
<gchart...googlemail.com> wrote:> Comments
inlined below...
>
> > > On 31 Aug, 11:35, simonsl...googlemail.com wrote:
>
> > > > Hi Graham
>
> > > > Some more comments in line...
>
> > > > On 31 Aug, 11:26, Graham Charters
<gchart...googlemail.com> wrote:
>
> > > > > Hi Simon, thanks for the rapid
comments.  Here's my thoughts on the
> > > > > two issues you identified:
>
> > > > > > 1/ What should SCA do if it
finds a method without annotations, i.e.
> > > > > > no type information
>
> > > > > This probably depends on the type
of service.  Service types which
> > > > > don't have a service description
(e.g. local, REST and Atom), don't
> > > > > require this information to be
specified.  Service types which do have
> > > > > service descriptions (soap,
json-rpc, xml-rpc), do (to varying
> > > > > degrees).
>
> > > > > I think if the binding type
requires documentation then we should warn
> > > > > and not generate (rather than
generating something which is of no
> > > > > use).  If the binding type doesn't
require documentation then it's
> > > > > included.
>
> > > > > > 2/ How can methods be omitted
from the service interface, i.e. we just
> > > > > > don't want to expose the
method
>
> > > > > I don't think the absence of
comments should be used as a control
> > > > > mechanism for the reason you and
Matt have already highlighted (might
> > > > > want to document something but
still not have it on the service
> > > > > interface).
>
> > > > > I quite like the idea of using
interfaces to add this level of
> > > > > control.  It would also be
consistent with SCA (SCA Java does this and
> > > > > also supports the same class
implementation approach we use (i.e.
> > > > > where there is no interface)).  How
about something like:
>
> > > > > /**
> > > > >  * Scaffold implementation for a
remote StockQuote Web service.
> > > > >  *
> > > > >  * service
StockQuoteInterface
> > > > >  * binding.soap
> > > > >  *
> > > > >  */
> > > > > StockQuoteImpl implements
StockQuoteInterface, ANOtherInterface {
> > > > >   ...
>
> > > > > }
>
> > > > So I like service
StokeQuoteInterface
>
> > > > If you are suggesting that we can parse
the StockQuoteInterface to
> > > > pull out the method names which should
be provided as service
> > > > interfaces (without the need for further
annotation on the interface
> > > > itself) then this could work. My
approach was a contraction of this by
> > > > just providing the method names after
the interface name in the
> > > > annotation but your approach is more
forward thinking.
>
> > > We should be able to update this in
SCA_AnnotationReader.php.  I
> > > believe all the information is available
through Reflection.  You can
> > > call getInterfaces() on the ReflectionClass,
which returns an array of
> > > ReflectionClass objects, one for each
interface.  I don't think we
> > > would require further annotations in the
interface, but we will need
> > > to decided whether to use
annotations/documentation in an interface if
> > > it is provided.
>
> > > > Presumably the default would be to
provide all methods if no interface
> > > > is described.
>
> > > Yes, so this would be backwards compatible.
>
> > > > > This would be taken to mean that
only those methods defined on
> > > > > StockQuoteInterface are part of the
soap service.  Those in
> > > > > ANOtherInterface or just in
StockQuoteImpl would be excluded.  I'd
> > > > > prefer to pursue this approach
rather than creating a new annotations
> > > > > which may go away in the near
future.
>
> > > > > Does this make sense and seem
sensible?
>
> > > > > On 31 Aug, 09:30, simonsl...googlemail.com wrote:
>
> > > > > > On 31 Aug, 08:42, Graham
Charters <gchart...googlemail.com> wrote:
>
> > > > > > > Pecl Request #11944 (http://pecl
.php.net/bugs/bug.php?id=11944) is
> > > > > > > asking for finer-grained
control over the methods which are surfaced
> > > > > > > on a service interface. 
We currently just use class visibility (i.e.
> > > > > > > all public methods) to
control this.
>
> > > > > > > There's a small amount of
discussion in the request, but I thought it
> > > > > > > would be good to raise it
here to get greater visibility and gather
> > > > > > > more options/opinions.
>
> > > > > > > Graham.
>
> > > > > > Following up on the comments
made in the feature request...
>
> > > > > > It is true that in the Java
SCA implementation the Service
> > > > > > information is associated with
interfaces so a class will implementat
> > > > > > one, or more, interfaces and
this tells the runtime which methods of
> > > > > > the class should be treated as
service methods.
>
> > > > > > This is not currently how the
PHP SCA implementation works. All
> > > > > > annotations are placed on the
class itself. This leads to a level of
> > > > > > simplicity in service
construction but we pay for this in lack of
> > > > > > flexibility, for example, in
excluding some methods from the service
> > > > > > interface. At least given the
set of annotations we have at the
> > > > > > moment.
>
> > > > > > Having said this I'm not
convinced that the use of unannotated (is
> > > > > > that a word?) methods as part
of the service interface makes a lot of
> > > > > > sense give the way that the
implementation works at the moment. If you
> > > > > > look at what is actually
generated in the WSDL in the case of the
> > > > > > method "function
foo($bar)" in the feature request it doesn't seem to
> > > > > > be that useful. I.e. it
defines null input and output types. I assume
> > > > > > this is because there are no
annotations for SCA to use for typing the
> > > > > > interface. Fine for PHP but
not so great for a service interface.
>
> > > > > > So there are two issues here
>
> > > > > > 1/ What should SCA do if it
finds a method without annotations, i.e.
> > > > > > no type information
> > > > > > 2/ How can methods be omitted
from the service interface, i.e. we just
> > > > > > don't want to expose the
method
>
> > > > > > As first suggested we could
omit methods that don't have comments at
> > > > > > all.. However this is
problematic for issue 2 as annotations may have
> > > > > > been included for producing
the documentation that the annotations
> > > > > > were originally designed for.
However I think we should consider
> > > > > > omitting methods without
annotations due to issue 1 so this could be a
> > > > > > short term solution 2.
>
> > > > > > Following the conversation on
for issue 2. Maybe, as an alternative to
> > > > > > scaExcludeMethod we could
defined some new annotation for the header
> > > > > > block that works as an
alternative to defining an interface (we should
> > > > > > look whether interfaces could
be made to work), e.g.
>
> > > > > > /**
> > > > > >  * Scaffold implementation for
a remote StockQuote Web service.
> > > > > >  *
> > > > > >  * service
> > > > > >  * serviceinterface GetQuote
getQuote
> > > > > >  * binding.soap
> > > > > >  *
> > > > > >  */
>
> > > > > >  If these don't appear then
the default would be to operate as now
> > > > > > with all of the (annotated)
methods being parsed. The intention here
> > > > > > being to replace/augment this
with annotations on interfaces if/'when
> > > > > > they work.
>
> > > > > > Regards
>
> > > > > > Simon


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "phpsoa" group.
To post to this group, send email to phpsoagooglegroups.com
To unsubscribe from this group, send email to
phpsoa-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.co.uk/group/phpsoa?hl=en
-~----------~----~----~----~------~----~------~--~---