docs(Http): add docs about breaking changes with EventEmitter/Observable
BREAKING CHANGE: The Http module previously would return RxJS Observables from method calls of the Http class. In order to support Dart, the module was refactored to return the EventEmitter abstraction instead, which does not contain the same combinators or subscription semantics as an RxJS Observable. However, the EventEmitter provides a toRx() method which will return an RxJS Subject, providing the same subscription and combinator conveniences as were available prior to this refactor. This is temporary, until issue #2794 is resolved, when Observables will again be returned directly from Http class methods.
This commit is contained in:
parent
27e710019c
commit
34eaf65a79
|
@ -36,8 +36,17 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
|
|||
*
|
||||
* `Http` is available as an injectable class, with methods to perform http requests. Calling
|
||||
* `request` returns an {@link EventEmitter} which will emit a single {@link Response} when a
|
||||
*response is
|
||||
* received.
|
||||
* response is received.
|
||||
*
|
||||
*
|
||||
* ## Breaking Change
|
||||
*
|
||||
* Previously, methods of `Http` would return an RxJS Observable directly. For now,
|
||||
* the `toRx()` method of {@link EventEmitter} needs to be called in order to get the RxJS
|
||||
* Subject. `EventEmitter` does not provide combinators like `map`, and has different semantics for
|
||||
* subscribing/observing. This is temporary; the result of all `Http` method calls will be either an
|
||||
* Observable
|
||||
* or Dart Stream when [issue #2794](https://github.com/angular/angular/issues/2794) is resolved.
|
||||
*
|
||||
* #Example
|
||||
*
|
||||
|
@ -47,7 +56,9 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
|
|||
* @View({templateUrl: 'people.html'})
|
||||
* class PeopleComponent {
|
||||
* constructor(http: Http) {
|
||||
* http('people.json')
|
||||
* http.get('people.json')
|
||||
* //Get the RxJS Subject
|
||||
* .toRx()
|
||||
* // Call map on the response observable to get the parsed people object
|
||||
* .map(res => res.json())
|
||||
* // Subscribe to the observable to get the parsed people object and attach it to the
|
||||
|
@ -57,6 +68,16 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
|
|||
* }
|
||||
* ```
|
||||
*
|
||||
* To use the {@link EventEmitter} returned by `Http`, simply pass a generator (See "interface
|
||||
*Generator" in the Async Generator spec: https://github.com/jhusain/asyncgenerator) to the
|
||||
*`observer` method of the returned emitter, with optional methods of `next`, `throw`, and `return`.
|
||||
*
|
||||
* #Example
|
||||
*
|
||||
* ```
|
||||
* http.get('people.json').observer({next: (value) => this.people = people});
|
||||
* ```
|
||||
*
|
||||
* The default construct used to perform requests, `XMLHttpRequest`, is abstracted as a "Backend" (
|
||||
* {@link XHRBackend} in this case), which could be mocked with dependency injection by replacing
|
||||
* the {@link XHRBackend} binding, as in the following example:
|
||||
|
@ -75,7 +96,7 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
|
|||
* [MockBackend, BaseRequestOptions])
|
||||
* ]);
|
||||
* var http = injector.get(Http);
|
||||
* http.get('request-from-mock-backend.json').subscribe((res:Response) => doSomething(res));
|
||||
* http.get('request-from-mock-backend.json').toRx().subscribe((res:Response) => doSomething(res));
|
||||
* ```
|
||||
*
|
||||
**/
|
||||
|
|
Loading…
Reference in New Issue