Skip to content
This repository has been archived by the owner on Feb 6, 2021. It is now read-only.

Commit

Permalink
Rearranges content
Browse files Browse the repository at this point in the history
  • Loading branch information
@devraj
devraj committed Apr 3, 2015
1 parent ef24b5d commit 133846d
Showing 1 changed file with 71 additions and 46 deletions.
117 changes: 71 additions & 46 deletions source/client.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,55 +244,13 @@ Our request manager can work this, this is done by using a shared instance of th
})
};
Then use the ``makeRequest`` method on the Request Manager instance to dispatch API calls, it requires the following parameters:

* ``request`` is a ``prestans.rest.json.Request`` object.
* ``callbackSuccessMethod`` which is a reference to a function the Request Manager calls if the API call succeeds, the method will be passed a response object. Ensure you use ``goog.bind`` to bind your function to your namespace.
* ``callbackFailureMethod`` optional reference to a function the Request Manager calls if the API call fails, this method will be passed a response object with failure information.
* ``opt_abortPreviousRequests``, asks the Request Manager to cancel all pending requests.

.. code-block:: javascript
# Assume you have a request object
pdemo.GLOBALS.API_CLIENT.makeRequest(
request,
goog.bind(this.successCallback_, this),
goog.bind(this.failureCallback_, this),
false
);
.. note:: Request objects tell the manager if they are willing to be aborted, this is configurable per request lodged with the manager.

The second method the Request Manager provides is ``abortAllPendingRequests``, this accepts no parameters and is responsible for aborting any currently queued connections. The failure callback is not fired when requests are aborted.

Xhr Communication Events
^^^^^^^^^^^^^^^^^^^^^^^^

The Request Manager raises the following events. These come in handy if your application requires global UI interactions e.g a Modal popup if network communication fails, or notification messages on success.

* ``prestans.rest.json.Client.EventType.RESPONSE``, raised when a round trip succeeds, this would be raised even if your API raised an error code, e.g Bad Request or Service Unavailable.
* ``prestans.rest.json.Client.EventType.FAILURE`` raised if a round trip fails.

Example of using ``goog.events.EventHandler`` to listen to the Failure event:

.. code-block:: javascript
goog.require('goog.events.EventHandler');
# and somewhere in one of your functions
this.eventHandler = new goog.events.EventHandler(this);
this.eventHandler_.listen(pdemo.GLOBALS.API_CLIENT, prestans.rest.json.Client.EventType.FAILURE, this.handleFailure_);
The ``event`` object passed to the end points is of type ``prestans.rest.json.Client.Event`` a subclass of ``goog.events.Event``. Call ``getResponse`` method on the event to get the ``Response`` object, this will give you access all the information about the request and it's outcome.
Composing a Request
-------------------

Requests ``prestans.rest.Request``

``prestans.rest.json.Request``
To place an Xhr request you compose a request by instantiating a ``prestans.rest.Request`` object, it accepts the following parameters as a JSON configuration:

* ``identifier`` unique string identifier for this request type
* ``identifier`` unique string identifier for this request type, these are used to cancel requests
* ``cancelable`` boolean value to determine if this request can be canceled
* ``httpMethod`` a ``prestans.net.HttpMethod`` constant
* ``parameters`` an array of key value pairs send as part of the URL
Expand All @@ -313,7 +271,54 @@ Requests ``prestans.rest.Request``
* ``prestans.net.HttpMethod.DELETE``
* ``prestans.net.HttpMethod.PATCH``

Example of a GET request:
Placing a Request
-----------------

Then use the ``makeRequest`` method on the Request Manager instance to dispatch API calls, it requires the following parameters:

* ``request`` is a ``prestans.rest.json.Request`` object.
* ``callbackSuccessMethod`` which is a reference to a function the Request Manager calls if the API call succeeds, the method will be passed a response object. Ensure you use ``goog.bind`` to bind your function to your namespace.
* ``callbackFailureMethod`` optional reference to a function the Request Manager calls if the API call fails, this method will be passed a response object with failure information.
* ``opt_abortPreviousRequests``, asks the Request Manager to cancel all pending requests.

.. code-block:: javascript
# Assume you have a request object
pdemo.GLOBALS.API_CLIENT.makeRequest(
request,
goog.bind(this.successCallback_, this),
goog.bind(this.failureCallback_, this),
false
);
.. note:: Request objects tell the manager if they are willing to be aborted, this is configurable per request lodged with the manager.

The second method the Request Manager provides is ``abortAllPendingRequests``, this accepts no parameters and is responsible for aborting any currently queued connections. The failure callback is not fired when requests are aborted.

Example of a GET request which optionally passes two parameters and expects the server to return a set of ``Album`` entities:

.. code-block:: javascript
var config_ = {
identifier: "AlbumSearchFetch",
httpMethod: prestans.net.HttpMethod.GET,
responseFilter: opt_filter,
responseModel: pdemo.data.model.Album,
isArray: true,
urlFormat: "/album",
parameters: [
{
key: "search_text",
value: searchText
},
{
key: "limit",
value: limit
}
]
};
Example of a GET request which fetches a particular entity:

.. code-block:: javascript
Expand All @@ -322,8 +327,9 @@ Example of a GET request:
httpMethod: prestans.net.HttpMethod.GET,
responseFilter: opt_filter,
responseModel: pdemo.data.model.Album,
isArray: false,
urlFormat: "/album/%i",
urlArgs: [id]
urlArgs: [albumId]
};
Expand All @@ -338,3 +344,22 @@ Reading a Response
* ``responseBody`` JSON Object (Optional)


Xhr Communication Events
------------------------

The Request Manager raises the following events. These come in handy if your application requires global UI interactions e.g a Modal popup if network communication fails, or notification messages on success.

* ``prestans.rest.json.Client.EventType.RESPONSE``, raised when a round trip succeeds, this would be raised even if your API raised an error code, e.g Bad Request or Service Unavailable.
* ``prestans.rest.json.Client.EventType.FAILURE`` raised if a round trip fails.

Example of using ``goog.events.EventHandler`` to listen to the Failure event:

.. code-block:: javascript
goog.require('goog.events.EventHandler');
# and somewhere in one of your functions
this.eventHandler = new goog.events.EventHandler(this);
this.eventHandler_.listen(pdemo.GLOBALS.API_CLIENT, prestans.rest.json.Client.EventType.FAILURE, this.handleFailure_);
The ``event`` object passed to the end points is of type ``prestans.rest.json.Client.Event`` a subclass of ``goog.events.Event``. Call ``getResponse`` method on the event to get the ``Response`` object, this will give you access all the information about the request and it's outcome.

0 comments on commit 133846d

Please sign in to comment.