On 10/11/07, Chuck Hinson <[EMAIL PROTECTED]> wrote: > > allowPut(), allowPost(), allowDelete(), allowGet() > > handlePut(), handlePost(), handleDelete(), handleGet() > > put(), post(), delete(), getRepresentation() - eh? what? > > The lack of symmetry there is jarring - it leads people to go looking > for the get() method and when they can't find it, they're confused.
It depends on how they approach the documentation. The javadoc class comment for Resource presents these in the reverse order; it isn't jarring if you first encounter getVariants, getRepresentation, put, post, and delete, *then* find out that there is a lower level of handle* methods (that you might not have to deal with at all, if you're lucky). It *is* slightly awkward that you have to use the lower level allow* methods to control whether your higher-level overrides will be used. Maybe the constructor could take an argument to handle some common cases with, say, an EnumSet? I think two things need to happen. First, the documentation for > handlePut(), handlePost(), handleDelete() and handleGet() needs a > whole lot more detail making it plain what exactly they do. More precisely, what they do by default (i.e., implement the higher-level API of getVariants, getRepresentation, post, put, delete) *and* what they should do if overridden, e.g., a warning that overriding handleGet without calling super.handleGet can cause any overridden getRepresentation and getVariants methods to be ignored (unless your handleGet calls getPreferredRepresentation, say). And second, yes, I think put(), post() and delete() and > getRepresentation() need to be renamed. While doPut(), doPost(), > doDelete() and doGet() are OK, I think I'd prefer processPut(), > processPost(), processDelete() and processGet() - but anything that > makes it clear that they are at the same level of processing is fine. There's a false parallel here that I don't think should be encouraged by providing parallel names. getRepresentation takes a Variant argument, handleGet does not; post takes a Representation argument, handlePost does not. If anything, I'd argue for names that were *less* parallel, e.g., add instead of post, and remove instead of delete. Resource is the place where the uniform interface hits the rich interface of your domain objects. It's entirely appropriate (and convenient!) to have an intermediate API (getVariant, getRepresentation, put, post, and delete) to help ease the transition between them. --tim
