1616package feign .sax ;
1717
1818import feign .Response ;
19- import feign .codec .Decoder ;
2019import feign .codec .DecodeException ;
20+ import feign .codec .Decoder ;
2121import org .xml .sax .ContentHandler ;
2222import org .xml .sax .InputSource ;
2323import org .xml .sax .SAXException ;
2727import javax .inject .Provider ;
2828import java .io .IOException ;
2929import java .io .Reader ;
30+ import java .lang .reflect .Constructor ;
3031import java .lang .reflect .Type ;
3132import java .util .LinkedHashMap ;
3233import java .util .Map ;
3738import static feign .Util .resolveLastTypeParameter ;
3839
3940/**
40- * Decodes responses using SAX. Configure using the {@link SAXDecoder.Builder
41- * builder}.
41+ * Decodes responses using SAX, which is supported both in normal JVM environments, as well Android.
42+ * <br>
43+ * <h4>Basic example with with Feign.Builder</h4>
44+ * <br>
45+ * <pre>
46+ * api = Feign.builder()
47+ * .decoder(SAXDecoder.builder()
48+ * .registerContentHandler(ContentHandlerForFoo.class)
49+ * .registerContentHandler(ContentHandlerForBar.class)
50+ * .build())
51+ * .target(MyApi.class, "http://api");
52+ * </pre>
4253 * <p/>
43- *
54+ * <h4>Advanced example with Dagger</h4>
55+ * <br>
4456 * <pre>
4557 * @Provides
4658 * Decoder saxDecoder(Provider<ContentHandlerForFoo> foo, //
4759 * Provider<ContentHandlerForBar> bar) {
4860 * return SAXDecoder.builder() //
49- * .addContentHandler( foo) //
50- * .addContentHandler( bar) //
61+ * .registerContentHandler(Foo.class, foo) //
62+ * .registerContentHandler(Bar.class, bar) //
5163 * .build();
5264 * }
5365 * </pre>
@@ -63,10 +75,48 @@ public static class Builder {
6375 private final Map <Type , Provider <? extends ContentHandlerWithResult <?>>> handlerProviders =
6476 new LinkedHashMap <Type , Provider <? extends ContentHandlerWithResult <?>>>();
6577
66- public Builder addContentHandler (Provider <? extends ContentHandlerWithResult <?>> handler ) {
67- Type type = resolveLastTypeParameter (checkNotNull (handler , "handler" ).getClass (), Provider .class );
68- type = resolveLastTypeParameter (type , ContentHandlerWithResult .class );
69- this .handlerProviders .put (type , handler );
78+ /**
79+ * Will call {@link Constructor#newInstance(Object...)} on {@code handlerClass} for each content stream.
80+ * <p/>
81+ * <h3>Note</h3>
82+ * <br/>
83+ * While this is costly vs {@code new}, it may not affect real performance due to the high cost of reading streams.
84+ *
85+ * @throws IllegalArgumentException if there's no no-arg constructor on {@code handlerClass}.
86+ */
87+ public <T extends ContentHandlerWithResult <?>> Builder registerContentHandler (Class <T > handlerClass ) {
88+ Type type = resolveLastTypeParameter (checkNotNull (handlerClass , "handlerClass" ), ContentHandlerWithResult .class );
89+ return registerContentHandler (type , new NewInstanceProvider (handlerClass ));
90+ }
91+
92+ private static class NewInstanceProvider <T extends ContentHandlerWithResult <?>> implements Provider <T > {
93+ private final Constructor <T > ctor ;
94+
95+ private NewInstanceProvider (Class <T > clazz ) {
96+ try {
97+ this .ctor = clazz .getDeclaredConstructor ();
98+ // allow private or package protected ctors
99+ ctor .setAccessible (true );
100+ } catch (NoSuchMethodException e ) {
101+ throw new IllegalArgumentException ("ensure " + clazz + " has a no-args constructor" , e );
102+ }
103+ }
104+
105+ @ Override public T get () {
106+ try {
107+ return ctor .newInstance ();
108+ } catch (Exception e ) {
109+ throw new IllegalArgumentException ("exception attempting to instantiate " + ctor , e );
110+ }
111+ }
112+ }
113+
114+ /**
115+ * Will call {@link Provider#get()} on {@code handler} for each content stream.
116+ * The {@code handler} is expected to have a generic parameter of {@code type}.
117+ */
118+ public Builder registerContentHandler (Type type , Provider <? extends ContentHandlerWithResult <?>> handler ) {
119+ this .handlerProviders .put (checkNotNull (type , "type" ), checkNotNull (handler , "handler" ));
70120 return this ;
71121 }
72122
@@ -75,11 +125,12 @@ public SAXDecoder build() {
75125 }
76126 }
77127
78- /* Implementations are not intended to be shared across requests. */
128+ /**
129+ * Implementations are not intended to be shared across requests.
130+ */
79131 public interface ContentHandlerWithResult <T > extends ContentHandler {
80- /*
81- * expected to be set following a call to {@link
82- * XMLReader#parse(InputSource)}
132+ /**
133+ * expected to be set following a call to {@link XMLReader#parse(InputSource)}
83134 */
84135 T result ();
85136 }
0 commit comments