<commit_before>angular-http-decoration-with-cancellation
=========================================

### Request Cancellation.
Some requests may trigger a CPU intensive task at the backend, this could be a behaviour a client understands and appreciates that it cannot be faster. Hence it makes sense to provide the client with an option to cancel the request before it is completed. This feature is also desirable when we want to take mitigating action on realising that a completion of the task would be pointless - consider that a client had started a long running task but decided to navigate away before it completed, one could subscribe to the `beforeunload` event in anticipation and cancel all pending and unfinished requests in its handler.

The cancellation method is guaranteed to ensure the client does not waste cycles for awaiting the return of a response due to a request. But your backend should implement a cancellation API for this to make a complete sense. How you implement cancellation at the backend is totally up to your design.

#### Client-side Cancellation with $http
The default implementation of the [$http service](https://docs.angularjs.org/api/ng/service/$http) already exposes a means to achieve client-side cancellation. In its usage, `$http(config);`, you are required to pass a configuration object. Adding a `timeout` property to the `config` object enables the possibility for a cancellation. You should ensure that the property value is either a number or a [promise](https://docs.angularjs.org/api/ng/service/$q).
If the `timeout` property value is a number, `t`, then the request will *timeout* after _t milliseconds_ and it will be cancelled then. Otherwise, given a _promise_ value, the request will be cancelled when the _promise_ is resolved.

#### Server-side Cancellation
Long running operations may be implemented as cancellable tasks (e.g. [FutureTask](https://docs.oracle.com/javase/7/docs/api/index.html?java/util/concurrent/FutureTask.html) in Java or [Task](http://msdn.microsoft.com/en-us/library/system.threading.tasks.task%28v=vs.110%29.aspx) in .NET). A task triggered by the client may be identified by a unique ID (which would serve as a cancellation token) generated by it and bound to the session on the server. Subsequent requests by the client may specify that an unfinished task mapped to a given token should be cancelled.
\- That was just a very shallow description. Of course one should consider the best practices on the target platform. You shouldn't go spawning threads outside the control of your web container. For instance, if you are working with Java, you should submit your tasks to the container's [ManagedExecutorService](https://docs.oracle.com/javaee/7/api/javax/enterprise/concurrent/ManagedExecutorService.html) to run.

### Enabling a Fluent and seamless Cancellation API in AngularJS' $http Service
There are several ways to do this I suppose. One way could be to simply wrap the $http service. But I wanted to reach my aim in such a way it would not require that I refactor our existing code base, also it should remain Angular. So I decided implementing a [decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator) was the way to go.

#### The $http [Decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator) Implementation
This is done in the [configuration block](https://docs.angularjs.org/guide/module#configuration-blocks) of your application, as demonstrated below:

```
<script src="https://gist.github.com/igwejk/0d03b23cb6238ad08456.js"></script>
```<commit_msg>getting gist snippet to work in readme<commit_after>angular-http-decoration-with-cancellation
=========================================

### Request Cancellation.
Some requests may trigger a CPU intensive task at the backend, this could be a behaviour a client understands and appreciates that it cannot be faster. Hence it makes sense to provide the client with an option to cancel the request before it is completed. This feature is also desirable when we want to take mitigating action on realising that a completion of the task would be pointless - consider that a client had started a long running task but decided to navigate away before it completed, one could subscribe to the `beforeunload` event in anticipation and cancel all pending and unfinished requests in its handler.

The cancellation method is guaranteed to ensure the client does not waste cycles for awaiting the return of a response due to a request. But your backend should implement a cancellation API for this to make a complete sense. How you implement cancellation at the backend is totally up to your design.

#### Client-side Cancellation with $http
The default implementation of the [$http service](https://docs.angularjs.org/api/ng/service/$http) already exposes a means to achieve client-side cancellation. In its usage, `$http(config);`, you are required to pass a configuration object. Adding a `timeout` property to the `config` object enables the possibility for a cancellation. You should ensure that the property value is either a number or a [promise](https://docs.angularjs.org/api/ng/service/$q).
If the `timeout` property value is a number, `t`, then the request will *timeout* after _t milliseconds_ and it will be cancelled then. Otherwise, given a _promise_ value, the request will be cancelled when the _promise_ is resolved.

#### Server-side Cancellation
Long running operations may be implemented as cancellable tasks (e.g. [FutureTask](https://docs.oracle.com/javase/7/docs/api/index.html?java/util/concurrent/FutureTask.html) in Java or [Task](http://msdn.microsoft.com/en-us/library/system.threading.tasks.task%28v=vs.110%29.aspx) in .NET). A task triggered by the client may be identified by a unique ID (which would serve as a cancellation token) generated by it and bound to the session on the server. Subsequent requests by the client may specify that an unfinished task mapped to a given token should be cancelled.
\- That was just a very shallow description. Of course one should consider the best practices on the target platform. You shouldn't go spawning threads outside the control of your web container. For instance, if you are working with Java, you should submit your tasks to the container's [ManagedExecutorService](https://docs.oracle.com/javaee/7/api/javax/enterprise/concurrent/ManagedExecutorService.html) to run.

### Enabling a Fluent and seamless Cancellation API in AngularJS' $http Service
There are several ways to do this I suppose. One way could be to simply wrap the $http service. But I wanted to reach my aim in such a way it would not require that I refactor our existing code base, also it should remain Angular. So I decided implementing a [decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator) was the way to go.

#### The $http [Decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator) Implementation
This is done in the [configuration block](https://docs.angularjs.org/guide/module#configuration-blocks) of your application, as demonstrated below:

<script src="https://gist.github.com/igwejk/0d03b23cb6238ad08456.js"></script>
{'fraction_non_alphanumeric': 0.08063394967329347, 'fraction_numerical': 0.006395106353399138, 'mean_word_length': 4.9503722084367245, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3330115', 'n_tokens_mistral': 1803, 'n_tokens_neox': 1712, 'n_words': 934}