Thanks everyone for your inputs.
We should avoid making changes to the APIs which have only one name. So they'll
continue to have the annotation:
@APICommand(name="apiName1")
For APIs with multiple names, we should support String[] as suggested by John.
Preferred and deprecated would be required in case of multiple API names.
Preferred and deprecated params should also support String[].
@APICommand(name={'Foo', 'Bar', 'FooBar'}, preferred='Foo',
deprecated={'Bar','FooBar'})
> -----Original Message-----
> From: Chiradeep Vittal [mailto:chiradeep.vit...@citrix.com]
> Sent: Tuesday, 9 April 2013 12:05 PM
> To: dev@cloudstack.apache.org
> Subject: Re: [Discuss] API name alias
>
> 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.
>
> On 4/8/13 9:52 PM, "Rohit Yadav" <bhais...@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.vit...@citrix.com> wrote:
> >
> >>
> >>
> >> On 4/8/13 11:18 AM, "Rohit Yadav" <bhais...@apache.org> wrote:
> >>
> >> >On Mon, Apr 8, 2013 at 7:10 PM, John Burwell <jburw...@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"})@APICommand(name={"apiName1", "apiName2",
> >> >> "apiName3"})@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 <bhais...@apache.org> wrote:
> >> >>
> >> >> > On Mon, Apr 8, 2013 at 6:33 PM, Kishan Kavala
> >> >><kishan.kav...@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')
> >>
> >>
