Re: HEAD not well supported?

[Chuck Hinson]

On 10/11/07, Jerome Louvel <[EMAIL PROTECTED]> wrote:
>
> Hi Sean,
>
> > I think *Representation is problematic: headRepresentation()?
> > I understand your
> > concerns with get(Variant), getVariant(). A colleague of mine
> > pointed out that
> > conceptually, merely using post(), get(), etc., is like
> > encroaching on a global
> > name space. He suggested (and I'm comfortable with),
> > doPost(), doGet(), doHead(),
> > doDelete(), doPut(), and doOptions(). The 'do' has the effect
> > of taking
> > the names out of the global name space...conceptually.
>
> I agree, but what do you think about the fact that we already have the
> handleGet, handlePost, handleHead or handleOptions right in the Resource
> class?
>
> Do you think that handleHead() should call a doHead() method? What would be
> the added value?
>
> In case of handleGet() we provide a default implementation based on the
> getVariants() and getRepresentation(Variant) methods in order to provide a
> default support for content negotiation. Same for handleHead() which in 99%
> of the case is just a GET with no entity sent back on the wire.
>
> The handleOptions() also has a default implementation which is based on the
> "alloww*" methods available that return true.
>
> If you don't want to use content negotiation, you could directly override
> the handleGet(), handleHead() methods. Doesn't it cover your needs?
>

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 cant find it, they're confused.

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.   As the
documentation stands right now (1.0), it's not even clear that
handleGet() will ultimately call getRepresentation().  And handlePut,
handlePost and handleDelete appear to do nothing more than call
put,post or delete respectively - even though the code shows that
there's a lot more going on.

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.

I've puposely avoided head and options because they're less
well-known, but the do*() and process*() patterns seem to cover them
just fine.

And if you don't want handleHead() being a one-liner with a call to
doHead(), make it clear in the docs that handleHead() actually calls
doGet().  Besides, I think the number of people who will be looking
for a head() or doHead() method will be significantly smaller than the
number of people looking for get() or doGet(). (And just how many
cases are there where you'd want to override the default behavior of
head anyway?)

--Chuck

[docs] Documentation wiki launch

[Jerome Louvel]

Hi all,

I would like to thank Marc Portier (from Outerthought) and Rob Heittman
(from Solertium) for swiftly launching this new project! 

I hope that they will continue to lead this documentation effort with the
same enthusiasm. For that, they need our help and contributions! The first
step is to register to become an author:
http://wiki.restlet.org/about/g1/4-restlet.html

I've updated the acknowledgments page to mention Daisy CMS, Outerthought
(creators of Daisy) and Solertium (hosting the wiki). Please have a look at
their web sites: 
http://www.restlet.org/about/acknowledgments

Best regards,
Jerome  

> -Message d'origine-
> De : Marc Portier [mailto:[EMAIL PROTECTED] De la part 
> de Marc Portier
> Envoyé : jeudi 11 octobre 2007 15:45
> À : discuss@restlet.tigris.org
> Objet : Re: [docs] Poll for participation and input.
> 
> Hi all,
> 
> I'm glad to let you know we've landed the documentation wiki service 
> hosting and made it available [1]
> 
> The draft TOC (for 1.1 docs) currently under discussion has 
> been put up 
> [2] there, people who become author [3] can leave their changes [4] 
> directly there. (by choosing Actions > Edit from the menu)
> 
> regards,
> -marc=
> 
> [1] http://wiki.restlet.org/
> [2] http://wiki.restlet.org/docs_1.1/2-restlet.html
> [3] http://wiki.restlet.org/about/g1/4-restlet.html
> [4] 
> http://wiki.restlet.org/docs_1.1/2-restlet/version/3/diff?othe
> rVersion=4

Sanity Check on Variants

[Jurgen Herrmann]

A quick sanity check:  If, from another environment I have an HttpUrlConnection
and execute its setRequestProperty("Accepts", "image/png"), I should expect my
variant.getMediaType() to match on IMAGE_PNG, right?  Or is there more to this. 
 

My Resource derived class adds variant support for TEXT_XML and IMAGE_PNG. 
Requests for XML force a post from the other environment that calls this same
resource but with the "image/png".  However the variant of the image call
appears as null. 

Any feedback on what I might be doing wrong?

Thanks
Jurgen

RE: JSON represenation based on json-lib from http://json-lib.sourceforge.net/

[Jerome Louvel]

Hi Evgeny,

I've updated the related RFE 

"Improve support for JSON"
http://restlet.tigris.org/issues/show_bug.cgi?id=131

I'm a bit reluctant to upgrade due to the fact that it requires two
additional dependencies (jakarta commons-beanutils 1.7.0 and ezmorph 1.0.3)
compared to the current list of Restlet dependencies... People already
complain about the current size of the distribution.

I hope to have a more modular distribution in the future (core package and
optional downloads), but probably not for 1.1.

Beside that it seems like a very cool enhancement, with support for
streaming. I've updated the RFE to plan for it in Restlet 1.2.

Best regards,
Jerome  

> -Message d'origine-
> De : news [mailto:[EMAIL PROTECTED] De la part de Evgeny Shepelyuk
> Envoyé : mercredi 10 octobre 2007 11:07
> À : discuss@restlet.tigris.org
> Objet : JSON represenation based on json-lib from 
> http://json-lib.sourceforge.net/
> 
>   Hello!
> Could it be possible to remake JSON represenation to start 
> using that  
> library.
> IMHO that library seems more mature and feature-rich than current :))
> 
> And also make some changes to JsonRepresentation by providing 
> constructor  
> that allows creation directly from POJO.
> 
> -- 
> Best Regards
> Evgeny K. Shepelyuk

RE: HEAD not well supported?

[Jerome Louvel]

Hi Sean,

> I think *Representation is problematic: headRepresentation()? 
> I understand your
> concerns with get(Variant), getVariant(). A colleague of mine 
> pointed out that
> conceptually, merely using post(), get(), etc., is like 
> encroaching on a global
> name space. He suggested (and I'm comfortable with), 
> doPost(), doGet(), doHead(),
> doDelete(), doPut(), and doOptions(). The 'do' has the effect 
> of taking 
> the names out of the global name space...conceptually.

I agree, but what do you think about the fact that we already have the
handleGet, handlePost, handleHead or handleOptions right in the Resource
class?

Do you think that handleHead() should call a doHead() method? What would be
the added value?

In case of handleGet() we provide a default implementation based on the
getVariants() and getRepresentation(Variant) methods in order to provide a
default support for content negotiation. Same for handleHead() which in 99%
of the case is just a GET with no entity sent back on the wire.

The handleOptions() also has a default implementation which is based on the
"alloww*" methods available that return true.

If you don't want to use content negotiation, you could directly override
the handleGet(), handleHead() methods. Doesn't it cover your needs?

Best regards,
Jerome  

RE: DecodeRepresentation.getSize returns -1

[Jerome Louvel]

Hi Jim,

This value is returned when there is no (direct) way to know in advance the
size of the compressed representation. It is the Variant.UNKNOWN_SIZE
constant.

Do you want the size of the uncompressed representation or the one of the
compressed representation? Are you looking at a Request coming from a HTTP
server connector?

Best regards,
Jerome  

> -Message d'origine-
> De : Jim Alateras [mailto:[EMAIL PROTECTED] 
> Envoyé : mercredi 10 octobre 2007 08:05
> À : discuss@restlet.tigris.org
> Objet : DecodeRepresentation.getSize returns -1
> 
> Hi,
> 
> When I attempt to get the encoded size of a representation (i.e. from 
> DecodeRepresentation) I get a value of -1. How can I retrieve 
> the size 
> of the representation, before it is decoded?
> 
> cheers
> 

Re: HEAD not well supported?

[Sean Landis]

Jerome Louvel  noelios.com> writes:

...

> It could also clarify things by renaming "post(Rep.)" to
> "postRepresentation(Rep.)" to be more consistent with
> "getRepresentation(Variant)" namine and to reduce the confusion with
> lower-level Uniform handle* methods.
> 
> What do you think? What is your ideal design for the Resource class?

I think *Representation is problematic: headRepresentation()? I understand your
concerns with get(Variant), getVariant(). A colleague of mine pointed out that
conceptually, merely using post(), get(), etc., is like encroaching on a global
name space. He suggested (and I'm comfortable with), doPost(), doGet(), 
doHead(),
doDelete(), doPut(), and doOptions(). The 'do' has the effect of taking 
the names out of the global name space...conceptually.

Sean

RE: Issue using StatusService

[Jerome Louvel]

Hi Davide,

>   I've an Application that sets it's StatusService. Here the 
> code (imports omitted):
 
[...]
 
> The status service is then connected to the Application via 
> setStatusService() instance method.
> my intent is to return the complete exception as html page. 
> I'm expecting getStatus() 
> to be called before getRerpresentation() but actually is never called.
> It's a bug?

When an exception or error is thrown, is it ultimately caught by the
Application's StatusFilter:

public void doHandle(Request request, Response response) {
try {
super.doHandle(request, response);
} catch (Throwable t) {
response.setStatus(getStatus(t, request, response));
}
}

The ApplicationStatusFilter, subclass of StatusFilter has this
implementation which calls your StatusService instance:

public Status getStatus(Throwable throwable, Request request,
Response response) {
Status result = getApplication().getStatusService().getStatus(
throwable, request, response);
if (result == null)
result = super.getStatus(throwable, request, response);
return result;
}

Your getRepresentation(Status,Req,Resp) method is called later, but only if
your status is an error status. See this StatusFilter code:

public void afterHandle(Request request, Response response) {
// If no status is set, then the "success ok" status is assumed.
if (response.getStatus() == null) {
response.setStatus(Status.SUCCESS_OK);
}

// Do we need to get a representation for the current status?
if (response.getStatus().isError()
&& ((response.getEntity() == null) || overwrite)) {
response.setEntity(getRepresentation(response.getStatus(),
request,
response));
}
}

This implementation looks fine to me (I've just tested it). I hope it helped
clarifying the expected behavior on your side. Let me know if it still
doesn't work.

Best regards,
Jerome  

RE: Index files don't work with Directory and clap://

[Jerome Louvel]

Thanks for testing. This needs to be fixed. I've entered a report:
http://restlet.tigris.org/issues/show_bug.cgi?id=370

Best regards,
Jerome  

> -Message d'origine-
> De : Rob Heittman [mailto:[EMAIL PROTECTED] 
> Envoyé : mardi 9 octobre 2007 23:36
> À : discuss@restlet.tigris.org
> Objet : Re: Index files don't work with Directory and clap://
> 
> 
> Nope, this doesn't work:
> 
> Directory d = new Directory(getContext(),
> "clap://thread/client-bin");
> d.setNegotiateContent(false);
> d.setIndexName("index.html");
> guard1.setNext(d);
> 
> Though this does:
> 
> Directory d = new Directory(getContext(),
> "file://home/imaginary/build/dir/client-bin");
> d.setNegotiateContent(false);
> d.setIndexName("index.html");
> guard1.setNext(d);
> 
> - Rob
> 
> - Original Message -
> From: "Jerome Louvel" <[EMAIL PROTECTED]>
> To: discuss@restlet.tigris.org
> Sent: Tuesday, October 9, 2007 3:41:05 PM (GMT-0500) America/New_York
> Subject: RE: Index files don't work with Directory and clap://
> 
> 
> Rob,
> 
> > Yes.  I think simply being able to specify "index.html" 
> > instead of "index"
> > and turn off content negotiation is what I want here.  So, if I set
> > negotiateContent to false and indexName to "index.html," that should
> > do the trick already, or do I need to do some surgery first?
> 
> My guess is that should work directly. Otherwise we'll make 
> it work this way
> :)
> 
> Best regards,
> Jerome  
> 
> 

RE: Thread-safety in Guard

[Jerome Louvel]

Hi Tim,

> What's the best way for me (or anyone else) to report other 
> concurrency and documentation issues that I encounter? In 
> this discussion group? This thread? Or somewhere else? 

For issues similar to the one we discussed, the best place is in the issue,
via the comments system. I've just broaden the scope of this issue:

"Fix thread safety issues"
http://restlet.tigris.org/issues/show_bug.cgi?id=368

If you have time to contribute patches, that would be more than welcome. 
 
> Here's my understanding of the basic concurrency requirements 
> of the Restlet framework: Restlets of all flavors must be 
> @ThreadSafe because they will in general be accessed 
> concurrently by many threads. Requests and Responses are 
> @NotThreadSafe; their handling is confined to a single 
> thread. Representations might or might not be thread-safe, 
> depending on whether they will be re-used in subsequent 
> request handling. Does that sound right? 

It is mostly right. For Representations, I don't think they should be shared
by multiple threads. The instances are generally short-lived, bounded to the
Request/Response life cycle.
 
> I posted some basic rules for writing @ThreadSafe classes 
>  e-classes.html>  on my blog. I hope they're helpful.

Cool, I've added the link to the threading documentation RFE:
http://www.outerthought.com/

Best regards,
Jerome  

Re: [docs] Poll for participation and input.

[Marc Portier]

Hi all,

I'm glad to let you know we've landed the documentation wiki service 
hosting and made it available [1]


The draft TOC (for 1.1 docs) currently under discussion has been put up 
[2] there, people who become author [3] can leave their changes [4] 
directly there. (by choosing Actions > Edit from the menu)


regards,
-marc=

[1] http://wiki.restlet.org/
[2] http://wiki.restlet.org/docs_1.1/2-restlet.html
[3] http://wiki.restlet.org/about/g1/4-restlet.html
[4] http://wiki.restlet.org/docs_1.1/2-restlet/version/3/diff?otherVersion=4


Jerome Louvel wrote:

Hi all,

I agree that the reference manual shouldn't be a repeating of the Javadocs
but go beyond and around them:
 - explain design choices
 - describe usage contexts
 - show sample code to copy and paste

IMO, it is not intended to be read in one shot like a book but more feature
by feature depending on the user needs (beside the first introductory
chapters).

Also, I think we should reintegrate some pages from the current web site,
see for example: http://www.restlet.org/documentation/1.0/
 - Tutorial  -> keep outside
 - Connectors-> merge with reference manual
 - Integrations  -> merge with reference manual
 - Javadocs *-> keep outside
 - Examples  -> merge with reference manual
 - Developer FAQ -> not sure...
 - Benchmark -> keep outside
 - Glossary  -> merge with reference manual

As for the 1.1 Javadoc, we'll put them up on the web site when we release
1.1 M1 sometimes soon.

Best regards,
Jerome  


-Message d'origine-
De : Marc Portier [mailto:[EMAIL PROTECTED] De la part 
de Marc Portier

Envoyé : mardi 9 octobre 2007 11:49
À : discuss@restlet.tigris.org
Objet : Re: [docs] Poll for participation and input.

Marc Portier wrote:

[...]

As mentioned earlier we can introduce a "javadoc:" linking 
convention in 
Daisy that should provide a way to avoid the 'repeating 
ourselves' by 

inserting direct pointers to the apidocs.


Thinking about providing that javadoc: linking feature...

Jerome,

I noticed the 1.1 javadoc is not up yet:
http://www.restlet.org/documentation/1.1/api/

I suppose you typically wait for the release to be ready before 
publishing those?


However I think we need to be able to let the docs in progress (about 
the version in progress) link to regular re-published apidocs.


wdyt?

regards,
-marc=

Re: Restlet site code

[Kyrre Kristiansen]

Oops! That should have been thanks, Thierry!

--- Kyrre Kristiansen <[EMAIL PROTECTED]>
wrote:

> yep, that's the one. I just couldn't locate it from
> the site. Thanks a lot, Jerome!
> 
> --- Thierry Boileau <[EMAIL PROTECTED]> wrote:
> 
> > yes I think so.
> > 
> > Is this what you are talking about : "
> >
>
http://www.restlet.org/documentation/1.0/examples/self";
> > ?
> > 
> > best regards,
> > Thierry Boileau
> > 
> > On 10/11/07, Kyrre Kristiansen
> > <[EMAIL PROTECTED]> wrote:
> > >
> > > Is this an answer to a different post?
> > >
> > > --- Patson <[EMAIL PROTECTED]> wrote:
> > >
> > > > Yes, tried on both IE and netscape...both had
> > the
> > > > same issue.
> > > >
> > > > The problem is the localhost server should not
> > send
> > > > the 401 response again after
> > > > its authenticated at the first GET
> > > >
> > > >
> > > >
> > > >
> > >
> > >
> > >
> >
>

> > > Kyrre Kristiansen
> > >
> > >
> > >  
> >
>
___
> > > Want ideas for reducing your carbon footprint?
> > Visit Yahoo! For Good
> > >
> >
>
http://uk.promotions.yahoo.com/forgood/environment.html
> > >
> > 
> 
> 
>

> Kyrre Kristiansen
> 
> 
>  
>
___
> Yahoo! Answers - Got a question? Someone out there
> knows the answer. Try it
> now.
> http://uk.answers.yahoo.com/ 
> 



Kyrre Kristiansen


  ___
Yahoo! Answers - Got a question? Someone out there knows the answer. Try it
now.
http://uk.answers.yahoo.com/ 

Re: Restlet site code

[Kyrre Kristiansen]

yep, that's the one. I just couldn't locate it from
the site. Thanks a lot, Jerome!

--- Thierry Boileau <[EMAIL PROTECTED]> wrote:

> yes I think so.
> 
> Is this what you are talking about : "
>
http://www.restlet.org/documentation/1.0/examples/self";
> ?
> 
> best regards,
> Thierry Boileau
> 
> On 10/11/07, Kyrre Kristiansen
> <[EMAIL PROTECTED]> wrote:
> >
> > Is this an answer to a different post?
> >
> > --- Patson <[EMAIL PROTECTED]> wrote:
> >
> > > Yes, tried on both IE and netscape...both had
> the
> > > same issue.
> > >
> > > The problem is the localhost server should not
> send
> > > the 401 response again after
> > > its authenticated at the first GET
> > >
> > >
> > >
> > >
> >
> >
> >
>

> > Kyrre Kristiansen
> >
> >
> >  
>
___
> > Want ideas for reducing your carbon footprint?
> Visit Yahoo! For Good
> >
>
http://uk.promotions.yahoo.com/forgood/environment.html
> >
> 



Kyrre Kristiansen


  ___
Yahoo! Answers - Got a question? Someone out there knows the answer. Try it
now.
http://uk.answers.yahoo.com/ 

Re: Issue when using Guard for POST and GET requests

[Patson]

Tried on both IE and netscape...both failed 

Re: Restlet site code

[Thierry Boileau]

yes I think so.

Is this what you are talking about : "
http://www.restlet.org/documentation/1.0/examples/self"; ?

best regards,
Thierry Boileau

On 10/11/07, Kyrre Kristiansen <[EMAIL PROTECTED]> wrote:
>
> Is this an answer to a different post?
>
> --- Patson <[EMAIL PROTECTED]> wrote:
>
> > Yes, tried on both IE and netscape...both had the
> > same issue.
> >
> > The problem is the localhost server should not send
> > the 401 response again after
> > its authenticated at the first GET
> >
> >
> >
> >
>
>
> 
> Kyrre Kristiansen
>
>
>   ___
> Want ideas for reducing your carbon footprint? Visit Yahoo! For Good
> http://uk.promotions.yahoo.com/forgood/environment.html
>

Re: Restlet site code

[Kyrre Kristiansen]

Is this an answer to a different post?

--- Patson <[EMAIL PROTECTED]> wrote:

> Yes, tried on both IE and netscape...both had the
> same issue.
> 
> The problem is the localhost server should not send
> the 401 response again after
> its authenticated at the first GET
> 
> 
> 
> 



Kyrre Kristiansen


  ___ 
Want ideas for reducing your carbon footprint? Visit Yahoo! For Good  
http://uk.promotions.yahoo.com/forgood/environment.html

Re: HEAD not well supported?

[Jerome Louvel]

Hi all,

Thanks for sharing your experience. This is very valuable feed-back
and I want to address these issues to this core class in release 1.1
if possible/necessary.

To try to clarify, I was initially hesitant to call
getRepresentation(Variant) just get(Variant) due to potential
confusion with the Javabeans naming, especially because we also need a
way to get the variants available. Having both a get(Variant) and a
getVariants() method seemed confusing to me.

So, I dediced to keep the uniform methods in Resource via the
handle*() methods (see Resource.handleHead(), handleOptions(), etc.)
and to provide good default implementations.

So, handleGet() does a getVariants() then a getRepresentation(Variant)
on the best matching variant. handleHead() delegates to handleGet(),
handlePost() calls post(Representation), etc.

The current approach I'm following for 1.1 is to try to move those
Resource.handle() methods to the Finder class and only keep the higher
level methods in Resource (getRepresentation, getVariants, post, put,
delete, etc.).

It could also clarify things by renaming "post(Rep.)" to
"postRepresentation(Rep.)" to be more consistent with
"getRepresentation(Variant)" namine and to reduce the confusion with
lower-level Uniform handle* methods.

What do you think? What is your ideal design for the Resource class?

Best,
Jerome


2007/10/11, Chuck Hinson <[EMAIL PROTECTED]>:
> On 10/10/07, Sean Landis <[EMAIL PROTECTED]> wrote:
> [...]
> > We have about a dozen people writing web services using Restlet. Although
> > head is confusing, I'd say we experience more confusion over the fact
> > that GET is a 'special case'. That is, there's no get(), but instead you
> > must use getRepresentation(). So far, every single developer here has 
> > stumbled
> > on this and required explanation. I'm afraid I can't give a rationale, I
> > just tell them that's the way it is.
> >
> > Sean
> >
>
> +1
>
> I've had the same experience with my group, and like Sean, I am at a
> loss as to how to explain why it has to be this way.
>
> At this point, i don't have a suggestion for how to resolve this, but
> I do think it violates the principle of least surprise (in a sort of
> roundabout way), and probably should have some effort devoted to
> determining whether this approach is worth the cognitive overhead it
> imposes.
>
> --Chuck
>