Hi guys, from the design point of view I'd strongly prefer having annotations over a Map. My reasons for that are the following:
1. Code cleanness and readability 2. Having separate Message subclasses defining their parameters it helps and guides towards defining a strict specification API (i.e.: a messages of type DummyMessage need to have 3 parameters: paramA, paramB and paramC while a UselessMessage has only paramA and paramC) 3. Annotations, as stated by Simone, let you define some more logic (required parameters, default values, etc...) 4. Debugging maps it's annoying I undersand your points Pid, it's only about two different approaches, I think your one with Map is guided by the "keep things simple" rule. I like discussions about design which let us talk, know and learn from one another. Cheers, Tommaso 2010/6/15 Pid <[email protected]> > On 15/06/2010 21:14, Simone Tripodi wrote: > > Nice to see we've gone deeply in the loop :) > > Map is IMHO too generic, even if could help reducing the complexity > > because of the parameters names, it doesn't allow adding metadata > > annotations, so we would move the maintenance from the POJO to the > > algorithm, and forced to hard-code logic discriminating parameters. > > Immagine the snippet below (in meta language): > > > > if ("oauth_signature".equals(parameter)) { > > // do something > > } else if ("oauth_version".equals(parameter)) { > > // do something > > } else ... > > I don't see the need for that anywhere? > > > maybe everybody agrees that this is not so nice to have in our code :P > > Me either. > > > Generally speaking, I'd continue prefer maintain POJOs instead the > > algorithm, since POJOs are just types declaration and don't contain > > any logic. > > > More thoughts? > > I agree. I just don't see the need to annotate fields, which you have > to list, then sort alphabetically (for correct concatenation), before > reflectively extracting their values. > > Maybe I misunderstood; you were only referring to the known OAuth > parameters rather than the possible additional parameters that a > Consumer might need, that have to be supplied to the Provider during auth? > > > p > > > Simo > > > > http://people.apache.org/~simonetripodi/ > > > > > > > > On Tue, Jun 15, 2010 at 9:46 PM, Pid <[email protected]> wrote: > >> On 15/06/2010 20:07, Simone Tripodi wrote: > >>> Hi Pid, > >>> that's curious and funny at the same time, that's exactly what I've > >>> always avoided to do :) And don't worry, even if with totally > >>> different vision, we're here to work together for the same purpose, > >>> that's why we partecipate in a community, otherwise everybody could > >>> work alone, no? :P > >>> > >>> In the case of the Message, the reason why I thought so is that > >>> annotations contain not only the name parameter name, but also some > >>> logic hints that avoid us hard-coding logic in the client algorithm, > >>> like exclude parameters during the signature, the optional fields and > >>> so on. > >>> It helps to maintains the code more flexible - if new parameters have > >>> to be added, just extend the POJO and add new annotation, logic has > >>> not to be changed - and consequently more maintainable. > >> > >> I understand. I think that perhaps a Map might be more simple though - > >> you wouldn't need to recompile to handle new parameters? > >> > >> > >> p > >> > >>> http://people.apache.org/~simonetripodi/ > >>> > >>> > >>> > >>> On Tue, Jun 15, 2010 at 7:54 PM, Pid <[email protected]> wrote: > >>>> On 15/06/2010 16:14, Simone Tripodi wrote: > >>>>> Hi Simo, > >>>>> absolutely right, let's find a better way to describe how I started > >>>>> designing the signature APIs... > >>>>> > >>>>> First of all: use cases show us that there are symmetric algorithms > >>>>> (PLAINTEXT, HMAC_SHA) and asymmetric algorithms (RSA_SHA1), so the > >>>>> design should be able to be adaptable for both cases. I thought that > a > >>>>> symmetric algorithm is a special case of an asymmetric algorithm, so > >>>>> let's consider having a SigningKey and a VerifyingKey interfaces, in > >>>>> the case of a symmetric algorithm, the key implementation have to > >>>>> implement both interfaces. > >>>>> > >>>>> So, let's define the SignatureMethodAlgorithm - I hope the name is > >>>>> semful!!! That's the interface definition > >>>>> > >>>>> public interface SignatureMethodAlgorithm<S extends SigningKey, V > >>>>> extends VerifyingKey> > >>>>> > >>>>> where defined the the method to calculate the signature (throws > >>>>> SignatureException if any error occurs): > >>>>> > >>>>> String calculate(S signingKey, > >>>>> String secretCredential, > >>>>> Service service, > >>>>> RequestMessage message, > >>>>> Parameter... parameters) throws SignatureException; > >>>>> > >>>>> and the one to verify the signature: > >>>>> > >>>>> boolean verify(String signature, > >>>>> V verifyingKey, > >>>>> String secretCredential, > >>>>> Service service, > >>>>> RequestMessage message, > >>>>> Parameter... parameters) throws SignatureException; > >>>>> > >>>>> An abstract implementation, AbstractSignatureMethodAlgorithm, > contains > >>>>> common signature calculation stuff, like the base string creation. > >>>>> Any SignatureMethodAlgorithm implementation is annotated by a > >>>>> @SignatureMethod annotation to mark the oauth algorithm identifier, > >>>>> ie: > >>>>> > >>>>> @SignatureMethod("HMAC-SHA1") > >>>>> public final class HmacSha1MethodAlgorithm extends > >>>>> AbstractMethodAlgorithm<HmacSha1Key, HmacSha1Key> { > >>>>> ... > >>>>> } > >>>>> > >>>>> Let's now make clear what hell Service, RequestMessage and Parameter > are :) > >>>>> > >>>>> > >>>>> Service is the pair (URL, HttpMethod) that describes the service has > >>>>> to be invoked. HttpMethod is an enumeration of all admitted http > >>>>> method: > >>>>> HEAD, > >>>>> POST, > >>>>> PUT, > >>>>> GET, > >>>>> DELETE, > >>>>> OPTIONS, > >>>>> TRACE, > >>>>> CONNECT > >>>>> > >>>>> > >>>>> RequestMessage is a POJO that contains the OAuth parameters like > >>>>> version, nonce, timestamp, ... it is extended by the > >>>>> TokenRequestMessage that differs from the previous one because > >>>>> contains the token field. > >>>>> Every RequestMessage field is annotated by @OAuthParameter > annotation, > >>>>> to mark if the field: > >>>>> - is optional (false by default) > >>>>> - has to be included in the parameter list to calculate the signature > >>>>> (true by default) > >>>>> - moreover contains the oauth parameter name > >>>>> > >>>>> a sample can be found on the signature field: > >>>>> > >>>>> @OAuthParameter( > >>>>> name = "oauth_signature", > >>>>> includeInSignature = false > >>>>> ) > >>>>> private String signature; > >>>>> > >>>>> That's all in therms of design, there are few little tricks on the > >>>>> implementation side (java introspection rocks) but IMHO is small and > >>>>> intuitive. > >>>>> > >>>>> What do you think about it? Thoughts? Any feedback is more than > welcome!!!! > >>>> > >>>> I hope you'll forgive me for saying so, but I think it's quite > >>>> complicated. Annotations are nice, but seem like overkill for this > >>>> use-case. > >>>> > >>>> If the POJO contains all of the necessary items as named fields, why > not > >>>> just concatenate and encode them in the correct order? > >>>> > >>>> > >>>> p > >>>> > >>>> > >>>> (Sorry Simo!) > >>>> > >>>> > >>>> > >>>> > >>>> > >>>> > >>>>> All the best, have a nice reading :P > >>>>> Simo > >>>>> > >>>>> http://people.apache.org/~simonetripodi/ > >>>>> > >>>>> > >>>>> > >>>>> On Tue, Jun 15, 2010 at 4:17 PM, Simone Gianni <[email protected]> > wrote: > >>>>>> Hi Simo, > >>>>>> obviously current SVN *is* the starting point. > >>>>>> > >>>>>> Let's see how to continue on that line, if there are other > proposals, if > >>>>>> some of our other existing code bases approach in a different way, > or if > >>>>>> someone foresees some other kind of problems in integrating the > current API > >>>>>> with their app. > >>>>>> > >>>>>> Simone > >>>>>> > >>>>>> 2010/6/15 Simone Tripodi <[email protected]> > >>>>>> > >>>>>>> Hi Simo, > >>>>>>> currently in the current svn Amber repo there is the signature > (with > >>>>>>> implementation) and part of consumer APIs I wrote time ago for the > >>>>>>> Lab. > >>>>>>> They are still valid IMHO and part of my proposal, parts of code > could > >>>>>>> be extracted from there. > >>>>>>> > >>>>>>> Feel free to ask questions if some parts are not clear. > >>>>>>> All the best, > >>>>>>> Simo > >>>>>>> > >>>>>>> http://people.apache.org/~simonetripodi/< > http://people.apache.org/%7Esimonetripodi/> > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> On Tue, Jun 15, 2010 at 2:21 PM, Simone Gianni <[email protected]> > wrote: > >>>>>>>> Hi all, > >>>>>>>> so, one part of our roadmap are APIs. > >>>>>>>> > >>>>>>>> Each of us has his own idea of how an API should be, in general, > and many > >>>>>>> of > >>>>>>>> us already have an idea (or even code) on how an OAuth API should > be :) > >>>>>>>> > >>>>>>>> There is no "absolute way" to determine if an API is better or > worse than > >>>>>>>> another. It mostly depends on use cases. > >>>>>>>> > >>>>>>>> Amber will (as many other systems) interact with : > >>>>>>>> - external applications/frameworks, using Amber to integrate oauth > >>>>>>>> - internal extensions, providing for example different token > storages or > >>>>>>>> interation different backends > >>>>>>>> - modules of Amber itself > >>>>>>>> > >>>>>>>> I think it would be better to focus on the first API now : which > use > >>>>>>> cases > >>>>>>>> do we plan? How do you imagine the code of a web framework using > Amber > >>>>>>> look > >>>>>>>> like? > >>>>>>>> > >>>>>>>> If there are very different cases there is space for more than one > API, > >>>>>>> for > >>>>>>>> example a low level one and high level Façade. Since our goal is > to unify > >>>>>>>> different (often existing) pieces and ease the path of adoption on > >>>>>>> projects > >>>>>>>> that were planning to integrate OAuth, we'll need a bit of > flexibility. > >>>>>>>> > >>>>>>>> Cast your code sample ideas :) People in projects that already use > their > >>>>>>> own > >>>>>>>> implementation of OAuth can easily post real code. > >>>>>>>> > >>>>>>>> Simone > >>>>>>>> > >>>>>>> > >>>>>> > >>>> > >>>> > >>>> > >> > >> > >> > > >
