Copyright 2014 Netflix, Inc.
Licensed 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.
/**
 * Copyright 2014 Netflix, Inc.
 * 
 * Licensed 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.
 */
package com.netflix.hystrix;

import rx.Observable;
import rx.schedulers.Schedulers;

import com.netflix.hystrix.HystrixCommandProperties.ExecutionIsolationStrategy;
import com.netflix.hystrix.exception.HystrixBadRequestException;
import com.netflix.hystrix.exception.HystrixRuntimeException;

Common interface for executables that implement the Observable methods observe() and toObservable() so client code can treat them the same and combine in typed collections if desired. 
Type parameters:
<R> – /**
 * Common interface for executables that implement the Observable methods {@link #observe()} and {@link #toObservable()} so client code can treat them the same and combine in typed collections if desired.
 * 
 * @param <R>
 */
public interface HystrixObservable<R> extends HystrixInvokable<R> {

    
Used for asynchronous execution of command with a callback by subscribing to the Observable. 
 This eagerly starts execution of the command the same as HystrixCommand.queue() and HystrixCommand.execute(). 
 A lazy Observable can be obtained from toObservable(). 

Callback Scheduling


When using ExecutionIsolationStrategy.THREAD this defaults to using Schedulers.computation() for callbacks.
When using ExecutionIsolationStrategy.SEMAPHORE this defaults to using Schedulers.immediate() for callbacks.


See https://github.com/ReactiveX/RxJava/wiki for more information.
Throws:
HystrixRuntimeException – 
            if a fallback does not exist
            

            

            
via Observer#onError if a failure occurs
            
or immediately if the command can not be queued (such as short-circuited, thread-pool/semaphore rejected)
            
HystrixBadRequestException –  via Observer#onError if invalid arguments or state were used representing a user failure, not a system failure
IllegalStateException – 
            if invoked more than once
Returns:
Observable<R> that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason./**
     * Used for asynchronous execution of command with a callback by subscribing to the {@link Observable}.
     * <p>
     * This eagerly starts execution of the command the same as {@link HystrixCommand#queue()} and {@link HystrixCommand#execute()}.
     * <p>
     * A lazy {@link Observable} can be obtained from {@link #toObservable()}.
     * <p>
     * <b>Callback Scheduling</b>
     * <p>
     * <ul>
     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
     * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
     * </ul>
     * <p>
     * See https://github.com/ReactiveX/RxJava/wiki for more information.
     *
     * @return {@code Observable<R>} that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason.
     * @throws HystrixRuntimeException
     *             if a fallback does not exist
     *             <p>
     *             <ul>
     *             <li>via {@code Observer#onError} if a failure occurs</li>
     *             <li>or immediately if the command can not be queued (such as short-circuited, thread-pool/semaphore rejected)</li>
     *             </ul>
     * @throws HystrixBadRequestException
     *             via {@code Observer#onError} if invalid arguments or state were used representing a user failure, not a system failure
     * @throws IllegalStateException
     *             if invoked more than once
     */
    public Observable<R> observe();

    
Used for asynchronous execution of command with a callback by subscribing to the Observable. 
 This lazily starts execution of the command only once the Observable is subscribed to. 
 An eager Observable can be obtained from observe() 

Callback Scheduling


When using ExecutionIsolationStrategy.THREAD this defaults to using Schedulers.computation() for callbacks.
When using ExecutionIsolationStrategy.SEMAPHORE this defaults to using Schedulers.immediate() for callbacks.


See https://github.com/ReactiveX/RxJava/wiki for more information.
Throws:
HystrixRuntimeException – 
            if a fallback does not exist
            

            

            
via Observer#onError if a failure occurs
            
or immediately if the command can not be queued (such as short-circuited, thread-pool/semaphore rejected)
            
HystrixBadRequestException –  via Observer#onError if invalid arguments or state were used representing a user failure, not a system failure
IllegalStateException – 
            if invoked more than once
Returns:
Observable<R> that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason./**
     * Used for asynchronous execution of command with a callback by subscribing to the {@link Observable}.
     * <p>
     * This lazily starts execution of the command only once the {@link Observable} is subscribed to.
     * <p>
     * An eager {@link Observable} can be obtained from {@link #observe()}
     * <p>
     * <b>Callback Scheduling</b>
     * <p>
     * <ul>
     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
     * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
     * </ul>
     * <p>
     * See https://github.com/ReactiveX/RxJava/wiki for more information.
     *
     * @return {@code Observable<R>} that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason.
     * @throws HystrixRuntimeException
     *             if a fallback does not exist
     *             <p>
     *             <ul>
     *             <li>via {@code Observer#onError} if a failure occurs</li>
     *             <li>or immediately if the command can not be queued (such as short-circuited, thread-pool/semaphore rejected)</li>
     *             </ul>
     * @throws HystrixBadRequestException
     *             via {@code Observer#onError} if invalid arguments or state were used representing a user failure, not a system failure
     * @throws IllegalStateException
     *             if invoked more than once
     */
    public Observable<R> toObservable();
    
}