///////////////////////////////////////////////////////////////
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
///////////////////////////////////////////////////////////////

[[library-rest-client, ReST Client Library]]
= ReST Client =

[devstatus]
--------------
source=libraries/rest-client/dev-status.xml
--------------

Rickard sent a very interesting <<library-rest-client-primer>> to the mailing list in October 2011, as the starting
point for the renovation of the ReST Client Library. You should read that to get the full background on the choices
made in this library.

include::../../build/docs/buildinfo/artifact.txt[]

== Usage ==
This library leverages the http://restlet.org[Restlet library], so keep its documentation nearby as well.

This library expects the client code to build up handlers on how to react to resources and errors.
It is a more declarative approach than a typical ReST client application, which often isn't HATEOAS at all, and
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven[Roy Fielding is upset that ReST now means something else] than it was originally intended.
We try to be true to Dr. Fielding's intentions.

=== Establish Client ===

The first thing that must be done is to create a ContextResourceClient.
Let's walk through the different steps typically needed.

[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=client-create1
-------------

Above we create the Client instance and a ContextResourceClientFactory, which takes a client via @Uses annotation. We
also set the accepted media type to JSON.

We then create the global handler, which will be set to all ContextResourceClient instances that this factory creates.

[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=client-create2
-------------

Above, we try to handle that autheorization is required by setting user credentials and then try again. The client
could do a pop-up box instead, have its own cached entries, contact a credentials server or many other things.

We also added another handler that does a _refresh()_ on any recoverable error.

Note that the ErrorHandler.AUTHENTICATION_REQUIRED and ErrorHandler.RECOVERABLE_ERROR are not enums or constants, but
Specifications and it is possible to implement your own.

We then simply proceed to create the _ContextResourceClient_, by giving the factory the bookmarkable reference of the
ReST API.

[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=client-create3
-------------

=== Using ContextClientResource ===

Once we have the ContextResourceClient, we can proceed with using it.
The general approach is to register handlers for potential results when invoking the method on the ReST resource.


=== Query without Value ===
[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=query-without-value
-------------

=== Query and Command ===
[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=query-and-command
-------------

=== Query List and Command ===
[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=query-list-and-command
-------------

=== Query List and Command Progressive ===
[snippet,java]
-------------
source=libraries/rest-client/src/test/java/org/apache/polygene/library/rest/client/ContextResourceClientFactoryTest.java
tag=query-list-and-command-progressive
-------------

include::primer.txt[]