On Tue, Apr 9, 2013 at 11:34 PM, Chiradeep Vittal <
chiradeep.vit...@citrix.com> wrote:
> In Kishan's case he is adding a better, accurate name for the API. The API
> was misnamed in the previous version (ACL = Access Control List, but ACL
> was referring to an individual item within the list). Similarly, there are
> other poorly worded APIs (createIpForwardingRule instead of
> createStaticNat comes to mind).
>
Okay I did not see that I thought putting them in the apiname array of name
fields would work. In such a case, we can just keep name = "current or
preferred or new api name" and another field "deprecated" can have the old
name. Whenever someone queries by that name, we can message them somehow to
avoid using the deprecated api name.
Cheers.
>
> On 4/9/13 2:19 AM, "Rohit Yadav" <bhais...@apache.org> wrote:
>
> >On Tue, Apr 9, 2013 at 12:04 PM, Chiradeep Vittal <
> >chiradeep.vit...@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" <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"})
> >> >> >>
> >> >> >> 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')
> >> >>
> >> >>
> >>
> >>
>
>
