dev@jsr311.java.net

Re: Alternate API proposition

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Wed, 25 Apr 2007 13:51:36 -0400

On Apr 25, 2007, at 1:29 PM, Jerome Louvel wrote:
>
> Thanks for pointing out this error :) I've attached an updated ZIP,
> with the
> @Variable annotation used as a private field.
>
> I'll answer to the rest later.
>
I think it would also be helpful to the group if you could explain
the motivations and advantages of your proposition compared to the
sketch2 APIs.

E.g. you introduce the @ApplicationClass and @HostRef annotations but
its not clear what their true purposes are beyond obtaining the host
name from the URI which as Paul demonstrates below is already pretty
straightforward to do without additional annotations.

Thanks,
Marc.

>
>> -----Message d'origine-----
>> De : Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
>> Envoyé : mercredi 25 avril 2007 19:11
>> À : dev_at_jsr311.dev.java.net
>> Objet : Re: Alternate API proposition
>>
>> Jerome Louvel wrote:
>>> Hi all,
>>>
>>> As promised, I've worked on a sample application (based on
>> BlinkSale API)
>>> that illustrates some of the ideas I have in mind for this JSR API.
>>>
>>> The Javadocs and source code should be self explaining, but
>> I can detail
>>> more if needed.
>>>
>>
>> Quick question: is the use of @ResourceRef with the Account
>> and Invoice
>> classes a mistake? namely is it part of an old design, or is it
>> something you intended?
>>
>> The reason i ask is if it is indeed intended then i think it
>> a mistake
>> :-) but i don't want to send unnecessarily detailed emails
>> saying why i
>> think this the case if this is part of an old design.
>>
>>
>>> The idea is to provide a sketch that can illustrates my
>> point of view and
>>> triggers some discussions. It doesn't pretend to be a
>> complete solution, but
>>> it does seem to provide the main pieces to implement an API such as
>>> BlinkSale. Note that I haven't fully covered the BlinkSale
>> resources yet,
>>> but the design pattern should be obvious.
>>>
>>
>> In the interests of comparing i have included POJOs for
>> clients/client
>> (at the end of the email) that follow the same pattern as the
>> previous
>> one for invoice/invoices (which are also included). I also included a
>> base resource to obtain the account ID.
>>
>>
>> AFAICT the main differences in terms of resource POJOs are:
>>
>> 1) the degree of separation between resource and representation
>> POJOs;
>>
>> 2) static vs. dynamic for recursive matching based on URI templates;
>>
>> 3) the inheritance rules for HTTP methods of resource POJOs;
>>
>> 4) the explicit/implicit declaration of HTTP methods of
>> resource POJOs;
>>
>> In further separate emails (most likely not today!) i will
>> try and pick
>> out some of the differences in more detail.
>>
>> Paul.
>>
>>
>> @ConsumeMime("application/vnd.blinksale+xml'")
>> @ProduceMime("application/vnd.blinksale+xml'")
>> public abstract class BaseResource {
>> protected String accountId;
>>
>> private @HttpContext UriInfo info;
>>
>> public BaseResource() {
>> this.accountId = getAccountId(info.getUri().getHost());
>> }
>>
>> private String getAccountId(String host) {
>> return host.substring(0, host.indexOf("."));
>> }
>> }
>>
>> @UriTemplate("/clients")
>> @SubResources({ClientResource.class})
>> class ClientsResource extends BaseResource {
>>
>> @HttpMethod
>> public Collection<Client> getClients() { ... }
>>
>> @HttpMethod
>> public Response post(Client client) { ... }
>>
>> }
>>
>> @UriTemplate("{client_Id}")
>> public class ClientResource extends BaseResource {
>>
>> int clientId;
>>
>> public ClientResource(@UriParam("client_Id") int clientId) {
>> this.clientId = clientId;
>> if (clientId > 0)
>> throw new NotFoundException("Client ID not found");
>> }
>>
>> @HttpMethod
>> public Client getClient() { ... }
>>
>> @HttpMethod
>> public void delete() { ... }
>>
>> @HttpMethod
>> public void put(Client client) { ... }
>>
>>
>> @UriTemplate("people")
>> public PeopleResource getPeopleResource () {
>> return new PeopleResource(accountId, clientId);
>> }
>> }
>>
>> @UriTemplate("/invoices")
>> @SubResources({InvoiceResource.class})
>> class InvoicesResource extends BaseResource {
>>
>> Date start, end;
>> String status, tags;
>>
>> public InvoicesResource(
>> @QueryParam("start") Date start,
>> @QueryParam("end") Date end,
>> @QueryParam("status") String status,
>> @QueryParam("tags") String tags)
>> ...
>> }
>>
>> @HttpMethod
>> Collection<Invoice> getInvoices() { ... }
>>
>> @ProduceMime("application/atom+xml")
>> @HttpMethod
>> Feed getInvoicesAsFeed() { ... }
>>
>> @ProduceMime("text/calendar")
>> @HttpMethod
>> Calendar getInvoicesAsCalendar() { ... }
>>
>> @HttpMethod
>> Response postInvoice(Invoice i) { ... }
>> }
>>
>>
>> @UriTemplate("{invoice_Id}")
>> class InvoiceResource extends BaseResource {
>>
>> int id;
>>
>> public InvoiceResource(
>> @UriParam("invoice_Id}" int id) {
>> if (id not recognized)
>> throw NotFoundException(...);
>>
>> this.id = id;
>> }
>>
>> @HttpMethod
>> Invoice getInvoice() { ... }
>>
>> @ProduceMime("application/atom+xml")
>> @HttpMethod
>> Entry getInvoiceAsEntry() { ... }
>>
>> @HttpMethod
>> void putInvoice(Invoice i) { ... }
>>
>> @HttpMethod
>> void deleteInvoice() { ... }
>>
>> @UriTemplate("deliveries")
>> DeliveriesResource getDeliveriesResource () {
>> return new DeliveriesResource(accountId, i);
>> }
>>
>> @UriTemplate("payments")
>> PaymentsResource getPaymentsResource () {
>> return new PaymentsResource(accountId, i);
>> }
>> }
>>
>>
>> --
>> | ? + ? = To question
>> ----------------\
>> Paul Sandoz
>> x38109
>> +33-4-76188109
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
>> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net
>>
>> <noelios-jsr311.zip>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.