cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rohit Yadav <bhais...@apache.org>
Subject Re: [Discuss] API name alias
Date Tue, 09 Apr 2013 09:19:16 GMT
On Tue, Apr 9, 2013 at 12:04 PM, Chiradeep Vittal <
Chiradeep.Vittal@citrix.com> wrote:

> Rohit, that's like saying we won't fix a leaky faucet today because we're
> moving in a couple of years anyway. It isn't a big deal to add this and it
> clarifies to the end user what is the correct alias to use.
>

Chiradeep, if there are multiple apinames for the same operation (cmd
class) where does the question of "correct alias to use" come?

Excuse my ignorance, I don't understand why we need "preferred" and
"deprecated" fields in that respect. IMO it won't solve any problem but add
confusion and ambiguity, unless there is some use you may explain?

As Kishan shares, he would use the array styled approach which John
suggested and I think it should work, why we want preferred and deprecated
Strings or String[].

Cheers.


> On 4/8/13 9:52 PM, "Rohit Yadav" <bhaisaab@apache.org> wrote:
>
> >If we are still on our previously discussed plan (search a wiki shared by
> >Min) on deprecating the whole query based API (Server), it's just
> >unnecessary work on present APIs. I think for now just changing the name
> >attribute type from String to String[] would just work, as John suggested.
> >
> >Adding other fields, may not hold much use for now. Except for few of them
> >the rest of 300 apis will have preferred == current apiname and deprecated
> >as blank string.
> >
> >I think we should just deprecated all cmd classes (query based) over a
> >long
> >period say 1 or 2 years, and/or find a way to rewrite/refactor them so as
> >to reuse them with our new rest based API server for future.
> >
> >Cheers.
> >
> >On Tue, Apr 9, 2013 at 3:18 AM, Chiradeep Vittal <
> >Chiradeep.Vittal@citrix.com> wrote:
> >
> >>
> >>
> >> On 4/8/13 11:18 AM, "Rohit Yadav" <bhaisaab@apache.org> wrote:
> >>
> >> >On Mon, Apr 8, 2013 at 7:10 PM, John Burwell <jburwell@basho.com>
> >>wrote:
> >> >
> >> >> Rohit,
> >> >>
> >> >> Why would we need to rewrite any Java code to switch to an array?
> >>As I
> >> >> mentioned, array annotation values are treated as varargs.
> >>Therefore,
> >> >> annotations with single values can be left alone.  Only cases where
> >> >> multiple values are required would require the addition of curly
> >>braces.
> >> >>  For example, for an APICommand with one name, the following would
> >> >>continue
> >> >> to work:
> >> >>
> >> >
> >> >Hey John, you're right but it's a matter of code styling, I prefer
> >> >writing;
> >> >
> >> >@APICommand(name = {'name1'}) even if it's only one name, this way any
> >> >subsequent api author would know that name is an array and they can
> >>have
> >> >aliases which is what Kishan wants.
> >> >
> >> >
> >> >>
> >> >>         @APICommand(name="apiName1")
> >> >>
> >> >> While for an APICommand with multiple names, the following form would
> >> >>now
> >> >> be supported:
> >> >>
> >> >>         @APICommand(name={"apiName1", "apiName2", "apiName3"})
> >> >>
> >> >> I am not familiar with the Marvin code, so I can not speak to the
> >>impact
> >> >> of this change to it.  However, the only changes to the Java code
> >> >>should be
> >> >> the API commands with multiple names and the classes that actually
> >> >>consume
> >> >> the value of this annotation.
> >> >>
> >> >
> >> >Yes, you're right we can skip the code styling I referred then it won't
> >> >consume much coding, we just need to fix these;
> >> >
> >> >- Fix APICommand annotation interface definition to accept name as an
> >> >array
> >> >- Fix method in ApiServer which creates apiname->cmdclass map to care
> >>for
> >> >aliases
> >> >- Fix ApiDiscovery to take care of the aliases (create different
> >>response
> >> >objs for the same cmd class)
> >> >- Fix apidocs XmlWriter class to take of the aliases and the api html
> >> >generator to process the same.
> >> >- Fix Marvin's codegenerator.py to take care of the aliases (which
> >>means
> >> >create apiname related modules which would contain cmd and response
> >> >boilterplate fields/class)
> >> >
> >> >Cheers.
> >> >
> >> >
> >> >>
> >> >> Thanks,
> >> >> -John
> >> >>
> >> >> On Apr 8, 2013, at 9:22 AM, Rohit Yadav <bhaisaab@apache.org>
wrote:
> >> >>
> >> >> > On Mon, Apr 8, 2013 at 6:33 PM, Kishan Kavala
> >> >><Kishan.Kavala@citrix.com
> >> >> >wrote:
> >> >> >
> >> >> >> APICommand annotation in API Cmd object has a name parameter.
> >> >>Currently
> >> >> >> name parameter takes only one value. I plan to enhance this
to
> >> >>support
> >> >> >> comma separated values. This will allow multiple API names
for the
> >> >>same
> >> >> API
> >> >> >> Cmd object.
> >> >> >>
> >> >> >> Current:
> >> >> >> @APICommand(name = "apiName1", ..
> >> >> >>
> >> >> >> Proposed:
> >> >> >> @APICommand(name = "apiName1, apiAlias2, apiAlias3", ..
> >> >> >>
> >> >> >
> >> >> > It's a hack, but doable. While not elegant as John suggests,
> >>parsing
> >> >> comma
> >> >> > separated value can lead to some issues.
> >> >> >
> >> >> > Changing the name field to array would require a lot of rewriting
> >>the
> >> >> > present apis annotation name fields, again doable by a small python
> >> >> program
> >> >> > (like the one I used in the last name field refactoring).
> >> >> >
> >> >> > This would really help remove duplicate cmd classes for apis such
> >>as
> >> >>copy
> >> >> > iso and volume which does the same job but requires two different
> >>cmd
> >> >> class
> >> >> > implementations.
> >> >> >
> >> >> > Whatever way you decide, pl. make sure to fix ApiDiscovery,
> >>ApiServer
> >> >> > cmdclass-apiname map generator method and apidocs generation
> >> >>accordingly.
> >> >> >
> >> >> > Cheers.
> >> >> >
> >> >> >
> >> >> >>
> >> >> >> Requirement:
> >> >> >> As part of CLOUDSTACK-763, I'll be introducing NetworkACLList
> >> >>(grouping
> >> >> of
> >> >> >> NetworkACLItems).  Current APIs use *NetworkACL (create
> >> >> >> NetworkACL/deleteNetworkACL etc..) for NetworkACLItem related
> >>APIs.
> >> >> These
> >> >> >> APIs have to be changed to *NetworkACL Item(create
> >> >> >> NetworkACLItem/deleteNetworkACLItem etc..) to get the terminology
> >> >> right. We
> >> >> >> also need to support old API names for backward compatibility.
> >>Hence
> >> >>the
> >> >> >> need for API name alias.
> >> >> >>
> >> >> >> Terminology:
> >> >> >> NetworkACLItem - Individual ACL Entry (was NetworlACL earlier).
> >> >> >> NetworkACL - Group of Network ACL Items. API will use the
term
> >> >> >> NetworkACLList to differentiate from the existing NetworkACL
APIs.
> >> >> >>
> >>
> >> How about an additional attribute 'preferred' or 'deprecated' ?
> >>
> >> @APICommand(name={'Foo', 'Bar'}, preferred='Foo', deprecated='Bar')
> >>
> >>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message