cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajesh Battala <rajesh.batt...@citrix.com>
Subject RE: [Discuss] API name alias
Date Tue, 09 Apr 2013 02:33:56 GMT


> -----Original Message-----
> From: Chiradeep Vittal [mailto:Chiradeep.Vittal@citrix.com]
> Sent: Tuesday, April 9, 2013 3:19 AM
> To: dev@cloudstack.apache.org
> Subject: Re: [Discuss] API name alias
> 
> 
> 
> 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')

The above convention looks good. In future release we can remove the deprecated api's.  preferred/deprecated
will be list type?

Thanks
Rajesh Battala

Mime
View raw message