diff --git a/README.md b/README.md index a46efe6ff..c8c653412 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,18 @@ Long Term - The future ☁️ --- +# Usage + +The feign library is available from [Maven Central](https://central.sonatype.com/search?q=g:io.github.openfeign%20%20a:feign-core). + +```xml + + io.github.openfeign + feign-core + ??feign.version?? + +``` + ### Basics Usage typically looks like this, an adaptation of the [canonical Retrofit sample](https://github.com/square/retrofit/blob/master/samples/src/main/java/com/example/retrofit/SimpleService.java). @@ -359,7 +371,9 @@ Feign includes example [GitHub](./example-github) and [Wikipedia](./example-wiki ### Integrations Feign intends to work well with other Open Source tools. Modules are welcome to integrate with your favorite projects! -### Gson +### Encoder/Decoder + +#### Gson [Gson](./gson) includes an encoder and decoder you can use with a JSON API. Add `GsonEncoder` and/or `GsonDecoder` to your `Feign.Builder` like so: @@ -376,7 +390,7 @@ public class Example { } ``` -### Jackson +#### Jackson [Jackson](./jackson) includes an encoder and decoder you can use with a JSON API. Add `JacksonEncoder` and/or `JacksonDecoder` to your `Feign.Builder` like so: @@ -395,7 +409,7 @@ public class Example { For the lighter weight Jackson Jr, use `JacksonJrEncoder` and `JacksonJrDecoder` from the [Jackson Jr Module](./jackson-jr). -### Sax +#### Sax [SaxDecoder](./sax) allows you to decode XML in a way that is compatible with normal JVM and also Android environments. Here's an example of how to configure Sax response parsing: @@ -411,7 +425,7 @@ public class Example { } ``` -### JAXB +#### JAXB [JAXB](./jaxb) includes an encoder and decoder you can use with an XML API. Add `JAXBEncoder` and/or `JAXBDecoder` to your `Feign.Builder` like so: @@ -427,7 +441,31 @@ public class Example { } ``` -### JAX-RS +#### SOAP +[SOAP](./soap) includes an encoder and decoder you can use with an XML API. + + +This module adds support for encoding and decoding SOAP Body objects via JAXB and SOAPMessage. It also provides SOAPFault decoding capabilities by wrapping them into the original `javax.xml.ws.soap.SOAPFaultException`, so that you'll only need to catch `SOAPFaultException` in order to handle SOAPFault. + +Add `SOAPEncoder` and/or `SOAPDecoder` to your `Feign.Builder` like so: + +```java +public class Example { + public static void main(String[] args) { + Api api = Feign.builder() + .encoder(new SOAPEncoder(jaxbFactory)) + .decoder(new SOAPDecoder(jaxbFactory)) + .errorDecoder(new SOAPErrorDecoder()) + .target(MyApi.class, "http://api"); + } +} +``` + +NB: you may also need to add `SOAPErrorDecoder` if SOAP Faults are returned in response with error http codes (4xx, 5xx, ...) + +### Contract + +#### JAX-RS [JAXRSContract](./jaxrs) overrides annotation processing to instead use standard ones supplied by the JAX-RS specification. This is currently targeted at the 1.1 spec. Here's the example above re-written to use JAX-RS: @@ -446,7 +484,9 @@ public class Example { } ``` -### OkHttp +### Client + +#### OkHttp [OkHttpClient](./okhttp) directs Feign's http requests to [OkHttp](http://square.github.io/okhttp/), which enables SPDY and better network control. To use OkHttp with Feign, add the OkHttp module to your classpath. Then, configure Feign to use the OkHttpClient: @@ -461,7 +501,7 @@ public class Example { } ``` -### Ribbon +#### Ribbon [RibbonClient](./ribbon) overrides URL resolution of Feign's client, adding smart routing and resiliency capabilities provided by [Ribbon](https://github.com/Netflix/ribbon). Integration requires you to pass your ribbon client name as the host part of the url, for example `myAppProd`. @@ -475,7 +515,7 @@ public class Example { } ``` -### Java 11 Http2 +#### Java 11 Http2 [Http2Client](./java11) directs Feign's http requests to Java11 [New HTTP/2 Client](https://openjdk.java.net/jeps/321) that implements HTTP/2. To use New HTTP/2 Client with Feign, use Java SDK 11. Then, configure Feign to use the Http2Client: @@ -486,7 +526,9 @@ GitHub github = Feign.builder() .target(GitHub.class, "https://api.github.com"); ``` -### Hystrix +### Breaker + +#### Hystrix [HystrixFeign](./hystrix) configures circuit breaker support provided by [Hystrix](https://github.com/Netflix/Hystrix). To use Hystrix with Feign, add the Hystrix module to your classpath. Then use the `HystrixFeign` builder: @@ -499,29 +541,9 @@ public class Example { } ``` -### SOAP -[SOAP](./soap) includes an encoder and decoder you can use with an XML API. - - -This module adds support for encoding and decoding SOAP Body objects via JAXB and SOAPMessage. It also provides SOAPFault decoding capabilities by wrapping them into the original `javax.xml.ws.soap.SOAPFaultException`, so that you'll only need to catch `SOAPFaultException` in order to handle SOAPFault. - -Add `SOAPEncoder` and/or `SOAPDecoder` to your `Feign.Builder` like so: - -```java -public class Example { - public static void main(String[] args) { - Api api = Feign.builder() - .encoder(new SOAPEncoder(jaxbFactory)) - .decoder(new SOAPDecoder(jaxbFactory)) - .errorDecoder(new SOAPErrorDecoder()) - .target(MyApi.class, "http://api"); - } -} -``` - -NB: you may also need to add `SOAPErrorDecoder` if SOAP Faults are returned in response with error http codes (4xx, 5xx, ...) +### Logger -### SLF4J +#### SLF4J [SLF4JModule](./slf4j) allows directing Feign's logging to [SLF4J](http://www.slf4j.org/), allowing you to easily use a logging backend of your choice (Logback, Log4J, etc.) To use SLF4J with Feign, add both the SLF4J module and an SLF4J binding of your choice to your classpath. Then, configure Feign to use the Slf4jLogger: