Forums | Admin Discussion Forums: open-discussion Start New Thread Nested Flat Threaded Ultimate Show 25 Show 50 Show 75 Show 100   By: Trevor Schroeder RE: A roadmap of sorts [ reply ]   2006-09-09 14:15 It seems that in that wonderful flickry way, new cruft has been creeping into the API that wasn't there before. The reflection API offers a way to track newly available options and compare with keyword args on a method. Additionally, each node visited when processing a response should be marked. Any unprocessed nodes should signal an error. By: Trevor Schroeder RE: A roadmap of sorts [ reply ]   2006-02-08 07:52 The name thing isn't really a huge concern. rflickr is such a code-ism that it could probably stay that way. I'm not terribly invested in that. There are a few people using it in production and so far the incompatibilities that have been introduced have been pretty minor. Basically, apart from bug compatibility, I don't think there's really a lot of chance for making incompatible changes moving forward. What exists right now is so minimal that any changes will only extend that. I certainly don't have any interest in obscuring the raw Flickr API if that's what people want to use. Mainly it's an explicit statement that if something is buggy or implemented in a substantially braindead way, it will change. Code that exists as of this writing I expect to continue to work. As for testing, I agree it should be possible without disturbing the API. As I said, the API is pretty minimal and the logic that needs testing resides pretty much entirely within the methods that implement our reflection of the Flickr API. It will, however, require a fair chunk of restructuring under the hood, I think. As for the tests themselves, my hope is to use mock objects and all that sort of crap to decouple rflickr from most, if not all, external dependencies. Certainly relying on Flickr for unit test execution is both slow and prone to failure as it's still not uncommon to see Flickr outages, especially the API. By: Nathan Pahucki RE: A roadmap of sorts [ reply ]   2006-02-07 17:37 What is your motivation for wanting to change the name? To me, rflickr is more Ruby style than the 'bumpy-case' RFlicker, which seems to smack more of something done in Java. On #1, how many users does rflickr already have? How many production systems use it? While I generally agree with your sentiments, If the number of users is fairly modest, I'd give backward compatibility less weight when it stands in the way of making significant improvement to the API structure or implementation. What would be paramount here is documenting the changes and a migration path for anyone who has code already dependent on the parts changed. On #4, more doc would be great, I found myself referring to the source code quite a bit for things that are not in the Flicker API documents, such as return or parameter types. While unit testing at this point will be more difficult than had it been done to begin with, I feel that it can still be done without disturbing the API too much. Also, I think that a set of automated online functional tests should be pretty easy to generate with out disturbing the API at all. For example, you could have a dummy account setup on Flickr, which a test fixture uses to test that the APIs actually do what they are supposed to do. I'd be happy to explore implementing this sort of thing. By: Trevor Schroeder A roadmap of sorts [ reply ]   2006-02-07 05:26 So I've been doing quite a bit of thinking about where I want to take rflickr. Should I call it RFlickr, Rflickr, stick with rflickr? Crucial questions of capitalization aside, I've come up with a couple of major organizing principles that nicely define direction and scope. When I can check those off, I'll be happy with the result and I'm not sure where else to take it beyond that. That's a good thing. 1. MAXIMIZE BACKWARD COMPATIBILITY Complete backward compatilibity is not a goal. My aim is not to be bug-compatible. If something is truly broken and there's no good way to fix it without potentially breaking existing code, the fix should still be made. A good example of this is the recent reworking of token handling. I did my best to make it work with the most likely existing code, but at the end of the day, it may very well break things. Still, it was the right decision given that the initial implementation was faulty. Likewise, when Flickr changes the API, such as their recent move from representing object IDs as a mix of 32-bit integers, 64-bit integers, and strings to simply declaring everything a string, there's not much I can do about that. Still, to the maximum extent possible, future releases will remain compatible with code written today. 2. ABSTRACTION It's a great first draft to implement the official Flickr API verbatim. It makes it easy to consult Flickr documentation and map that directly into Ruby code without knowing first how rflickr exposes that functionality. It also means that anything you can do with the API can be done with rflickr. That said, that shouldn't be the only interface to Flickr. We should be exploiting the logical relationship between objects to make the API itself invisible to those who wish to ignore it. Why should I have to know flickr.transform.rotate(photo,90) when what I want to do can be concisely and intuitively expressed as photo.rotate(90)? This sort of encapsulation is obvious and has been a goal from the start. We're just not there yet. 3. TRANSPARENCY Along encapsulation lines but more ambitious, objects that require multiple API calls to construct full state should do so transparently. I shouldn't need to know that if I want full state on a photoset, I need to first call photoset.fetch or that there are multiple ways to get information on a person, some of them completely orthogonal. There needs to be a difference between nil, I haven't yet fetched this attribute, and nil, this attribute has no value. My plan is to change instance initialization so that each instance attribute will be tagged with a name, a getter method, and an optional setter method. Attribute values will internally be initialized to a UNFETCHED value. Parsing an XML result and setting those values will necessarily clear their UNFETCHED state. Attempts to access an UNFETCHED attribute will trigger the necessary callback to build state on that attribute. Clearly this will necessitate changes to the parsing code to modify how it accesses the underlying instance variables but it shouldn't be too heinous. An example from Flickr::Person might be flickr_attr :bandwidth_used, :get_upload_status flickr_attr :bandwidth_max, :get_upload_status where get_upload_status would be a private method wrapping flickr.people.getUploadStatus. Flickr::Photo might contain a description like flickr_attr :taken, :get_info, :set_dates flickr_attr :lastupdate, :get_info, :set_dates Again, get_info would be a method that calls flickr.photos.getInfo but the :set_dates is more interesting. The implication is that when we call photo.taken=some_time, @taken takes on the value of some_time and we would call set_dates which is presumably a wrapper around flickr.photos.setDates. Note that this is an example that's not backwards compatible with existing code. We'd need to provide compatibility with the current photo.dates[:posted]-type calls. There should also be a generic mechanism to suspend commit operations. So I might do something like photo.disconnect photo.title = "My Greatest Photo Ever" photo.description = "Blah blah blah blah. What more do you need?" photo.taken = Time.now photo.uploaded = Time.now photo.reconnect The class would have a list of which setter methods need to be called to propagate those changes to Flickr and send them along. The above example would save 50% of the calls if the instance were connected the entire time (a call to setDates and a call to setMeta versus two of each). A more ambitious plan might be to do this automatically. A thread in the main Flickr instance could track instance changes in its persistence cache and when a particular instance has been untouched for a certain amount of time, flush its changes back to Flickr. This needs a little more thought and would require some tie-in with garbage collection which can be very lazy. 4. UNIT TESTING AND DOCUMENTATION It's shameful that I've gotten this far without tests. I've never been a TDD person, but I recognize the merits and wanted to build rflickr with tests from the ground up. My mistake was to focus first on feature implementation instead of tests. Now I need to figure out how to squeeze it into a testing framework and I suspect it implies a great deal of refactoring and rearchitecting. That's too bad. Documentation is pretty much non-existant. It's good that I can refer users to Flickr's online docs, but that's a pretty sorry state. The fact that both of these things come at the end of my roadmap is probably a telling sign. So there you have it, my current 100% vision for rflickr. What do you think?