Hystrix.zip

# hystrix-javanica Java language has a great advantages over other languages such as reflection and annotations. All modern frameworks such as Spring, Hibernate, myBatis and etc. seek to use this advantages to the maximum. The idea of introduction annotations in Hystrix is obvious solution for improvement. Currently using Hystrix involves writing a lot of code that is a barrier to rapid development. You likely be spending a lot of time on writing a Hystrix commands. Idea of the Javanica project is make easier using of Hystrix by the introduction of support annotations. First of all in order to use hystrix-javanica you need to add hystrix-javanica dependency in your project. Example for Maven: ```xml <dependency> <groupId>com.netflix.hystrix</groupId> <artifactId>hystrix-javanica</artifactId> <version>x.y.z</version> </dependency> ``` To implement AOP functionality in the project was used AspectJ library. If in your project already used AspectJ then you need to add hystrix aspect in aop.xml as below: ```xml <aspects> ... <aspect name="com.netflix.hystrix.contrib.javanica.aop.aspectj.HystrixCommandAspect"/> ... </aspects> ``` More about AspectJ configuration read [here] (http://www.eclipse.org/aspectj/doc/next/devguide/ltw-configuration.html) If you use Spring AOP in your project then you need to add specific configuration using Spring AOP namespace in order to make Spring capable to manage aspects which were written using AspectJ and declare `HystrixCommandAspect` as Spring bean like below: ```xml <aop:aspectj-autoproxy/> <bean id="hystrixAspect" class="com.netflix.hystrix.contrib.javanica.aop.aspectj.HystrixCommandAspect"></bean> ``` Or if you are using Spring code configuration: ```java @Configuration public class HystrixConfiguration { @Bean public HystrixCommandAspect hystrixAspect() { return new HystrixCommandAspect(); } } ``` It doesn't matter which approach you use to create proxies in Spring, javanica works fine with JDK and CGLIB proxies. If you use another framework for aop which supports AspectJ and uses other libs (Javassist for instance) to create proxies then let us know what lib you use to create proxies and we'll try to add support for this library in near future. More about Spring AOP + AspectJ read [here] (http://docs.spring.io/spring/docs/current/spring-framework-reference/html/aop.html) ## Aspect weaving Javanica supports two weaving modes: implementation and runtime. Load time weaving hasn't been tested but it should work. If you tried LTW mode and got any problems then raise javanica issue or create pull request with fix. - CTW. To use CTW mode you need to use specific jar version: **hystrix-javanica-ctw-X.Y.Z** . This jar is assembled with aspects compiled with using [AJC](https://eclipse.org/aspectj/doc/next/devguide/ajc-ref.html) compiler. If you will try to use regular hystrix-javanica-X.Y.Z with CTW then you get ``` NoSuchMethodError aspectOf() ``` at runtime from building with iajc. Also, you need to start your app with using java property: ```-DWeavingMode=compile```. **NOTE**: Javanica depends on aspectj library and uses internal features of aspectj and these features aren't provided as a part of open API thus it can change from version to version. Javanica tested with latest aspectj version 1.8.7. If you updated aspectj version and noticed any issues then please don't hestitate to create new issue or contribute. - RTW works, you can use regular hystrix-javanica-X.Y.Z - LTM hasn't been tested but it should work fine. # How to use ## Hystrix command ### Synchronous Execution To run method as Hystrix command synchronously you need to annotate method with `@HystrixCommand` annotation, for example ```java public class UserService { ... @HystrixCommand public User getUserById(String id) { return userResource.getUserById(id); } } ... ``` In example above the `getUserById` method will be processed [synchronously](https://github.com/Netflix/Hystrix/wiki/How-To-Use#wiki-Synchronous-Execution) within new Hystrix command. By default the name of **command key** is command method name: `getUserById`, default **group key** name is class name of annotated method: `UserService`. You can change it using necessary `@HystrixCommand` properties: ```java @HystrixCommand(groupKey="UserGroup", commandKey = "GetUserByIdCommand") public User getUserById(String id) { return userResource.getUserById(id); } ``` To set threadPoolKey use ```@HystrixCommand#threadPoolKey()``` ### Asynchronous Execution To process Hystrix command asynchronously you should return an instance of `AsyncResult` in your command method as in the example below: ```java @HystrixCommand public Future<User> getUserByIdAsync(final String id) { return new AsyncResult<User>() { @Override public User invoke() { return userResource.getUserById(id); } }; } ``` The return type of command method should be Future that indicates that a command should be executed [asynchronously] (https://github.com/Netflix/Hystrix/wiki/How-To-Use#wiki-Asynchronous-Execution). ## Reactive Execution To perform "Reactive Execution" you should return an instance of `Observable` in your command method as in the example below: ```java @HystrixCommand public Observable<User> getUserById(final String id) { return Observable.create(new Observable.OnSubscribe<User>() { @Override public void call(Subscriber<? super User> observer) { try { if (!observer.isUnsubscribed()) { observer.onNext(new User(id, name + id)); observer.onCompleted(); } } catch (Exception e) { observer.onError(e); } } }); } ``` In addition to `Observable` Javanica supports the following RX types: `Single` and `Completable`. Hystrix core supports only one RX type which is `Observable`, `HystrixObservableCommand` requires to return `Observable` therefore javanica transforms `Single` or `Completable` to `Observable` using `toObservable()` method for appropriate type and before returning the result to caller it translates `Observable` to either `Single` or `Completable` using `toSingle()` or `toCompletable()` correspondingly. HystrixObservable interface provides two methods: ```observe()``` - eagerly starts execution of the command the same as ``` HystrixCommand#queue()``` and ```HystrixCommand#execute()```; ```toObservable()``` - lazily starts execution of the command only once the Observable is subscribed to. To control this behaviour and swith between two modes ```@HystrixCommand``` provides specific parameter called ```observableExecutionMode```. ```@HystrixCommand(observableExecutionMode = EAGER)``` indicates that ```observe()``` method should be used to execute observable command ```@HystrixCommand(observableExecutionMode = LAZY)``` indicates that ```toObservable()``` should be used to execute observable command **NOTE: EAGER mode is used by default** ## Fallback Graceful degradation can be achieved by declaring name of fallback method in `@HystrixCommand` like below: ```java @HystrixCommand(fallbackMethod = "defaultUser") public User getUserById(String id) { return userResource.getUserById(id); } private User defaultUser(String id) { return new User("def", "def"); } ``` **_Its important to remember that Hystrix command and fallback should be placed in the same class and have same method signature (optional parameter for failed execution exception)_**. Fallback method can have any access modifier. Method `defaultUser` will be used to process fallback logic in a case of any errors. If you need to run fallback method `defaultUser` as separate H