com.squareup.retrofit2:converter-jaxb

Changed

• Upgrade to OkHttp 4.12 (from 3.14).

  This is the version of OkHttp that is written in Kotlin, and as a result Retrofit now has a transitive Kotlin dependency. However, this is also the supported version of OkHttp whereas the previous version was out of support for nearly 4 years.

Note: The 3.x versions of Retrofit maintain forward binary-compatibility with the 2.x versions.
This means libraries compiled against 2.x can still be used with the 3.x versions.

Changed

• Upgrade to OkHttp 4.12 (from 3.14).

  This is the version of OkHttp that is written in Kotlin, and as a result Retrofit now has a transitive Kotlin dependency. However, this is also the supported version of OkHttp whereas the previous version was out of support for nearly 4 years.

Note: The 3.x versions of Retrofit maintain forward binary-compatibility with the 2.x versions. This means libraries compiled against 2.x can still be used with the 3.x versions.

New

• First-party converters now support deferring serialization to happen when the request body is written (i.e., during HTTP execution) rather than when the HTTP request is created. In some cases this moves conversion from a calling thread to a background thread, such as in the case when using Call.enqueue directly.

  The following converters support this feature through a new withStreaming() factory method:

  • Gson
  • Jackson
  • Moshi
  • Protobuf
  • Wire

Fixed

• Primitive types used with @Tag now work by storing the value boxed with the boxed class as the key.

New

• First-party converters now support deferring serialization to happen when the request body is written (i.e., during HTTP execution) rather than when the HTTP request is created. In some cases this moves conversion from a calling thread to a background thread, such as in the case when using Call.enqueue directly.

  The following converters support this feature through a new withStreaming() factory method:

  • Gson
  • Jackson
  • Moshi
  • Protobuf
  • Wire

Fixed

• Primitive types used with @Tag now work by storing the value boxed with the boxed class as the key.

New

• The built-in OptionalConverterFactory is now public to allow installing it before other converters which consume all types (e.g., Moshi, Gson, Jackson, etc.).

Fixed

• Ensure that exceptions thrown from failure to parse method annotations can be observed by multiple threads/callers. Previously only the first caller would see the actual parsing exception and other callers would get a cryptic ClassCastException.

New

• The built-in OptionalConverterFactory is now public to allow installing it before other converters which consume all types (e.g., Moshi, Gson, Jackson, etc.).

Fixed

• Ensure that exceptions thrown from failure to parse method annotations can be observed by multiple threads/callers. Previously only the first caller would see the actual parsing exception and other callers would get a cryptic ClassCastException.

New

• Support using Unit as a response type. This can be used for non-body HTTP methods like HEAD or body-containing HTTP methods like GET where the body will be discarded without deserialization.

• kotlinx.serialization converter!

  This was imported from github.com/JakeWharton/retrofit2-kotlinx-serialization-converter/ and remains unchanged from its 1.0.0 release.

  The Maven coordinates are com.squareup.retrofit2:converter-kotlinx-serialization.

• JAXB 3 converter!

  The Maven coordinates are com.squareup.retrofit2:converter-jaxb3.

• @Header, @Headers, and @HeaderMap can now set non-ASCII values through the allowUnsafeNonAsciiValues annotation property. These are not technically compliant with the HTTP specification, but are often supported or required by services.

• Publish a BOM of all modules. The Maven coordinates are com.squareup.retrofit2:retrofit-bom.

• Invocation now exposes the service Class<?> and the instance on which the method was invoked. This disambiguates the source when service inheritence is used.

• A response type keeper annotation processor is now available for generating shrinker rules for all referenced types in your service interface. In some cases, it's impossible for static shrinker rules to keep the entirety of what Retrofit needs at runtime. This annotation processor generates those additional rules. For more info see its README.

Changed

• Add shrinker rules to retain the generic signatures of built-in types (Call, Response, etc.) which are used via reflection at runtime.
• Remove backpressure support from RxJava 2 and 3 adapters. Since we only deliver a single value and the Reactive Streams specification states that callers must request a non-zero subscription value, we never need to honor backpressure.
• Kotlin Retrofit.create function now has a non-null lower bound. Even if you specified a nullable type before this function would never return null.
• Suspend functions now capture and defer all Throwable subtypes (not just Exception subtypes) to avoid Java's UndeclaredThrowableException when thrown synchronously.
• Eagerly reject suspend fun functions that return Call<Body>. These are never correct, and should declare a return type of Body directly.
• Support for Java 14-specific and Java 16-specific reflection needed to invoke default methods on interfaces have been moved to separate versions of a class through a multi-release jar. This should have no observable impact other than the jar now contains classes which target Java 14 and Java 16 bytecode that might trip up some static analysis tools which are not aware of multi-release jars.
• Parameter names are now displayed in exception messages when available in the underlying Java bytecode.
• Jackson converter now supports binary formats by using byte streams rather than character streams in its implementation. Use the create(ObjectMapper, MediaType) overload to supply the value of the Content-Type header for your format.

Fixed

• Do not include synthetic methods when doing eager validation.
• Use per-method rather than per-class locking when parsing annotations. This eliminates contention when multiple calls are made in quick succession at the beginning of the process lifetime.

New

• Support using Unit as a response type. This can be used for non-body HTTP methods like HEAD or body-containing HTTP methods like GET where the body will be discarded without deserialization.

• kotlinx.serialization converter!

  This was imported from github.com/JakeWharton/retrofit2-kotlinx-serialization-converter/ and remains unchanged from its 1.0.0 release.

  The Maven coordinates are com.squareup.retrofit2:converter-kotlinx-serialization.

• JAXB 3 converter!

  The Maven coordinates are com.squareup.retrofit2:converter-jaxb3.

• @Header, @Headers, and @HeaderMap can now set non-ASCII values through the allowUnsafeNonAsciiValues annotation property. These are not technically compliant with the HTTP specification, but are often supported or required by services.

• Publish a BOM of all modules. The Maven coordinates are com.squareup.retrofit2:retrofit-bom.

• Invocation now exposes the service Class<?> and the instance on which the method was invoked. This disambiguates the source when service inheritence is used.

• A response type keeper annotation processor is now available for generating shrinker rules for all referenced types in your service interface. In some cases, it's impossible for static shrinker rules to keep the entirety of what Retrofit needs at runtime. This annotation processor generates those additional rules. For more info see its README.

Changed

• Add shrinker rules to retain the generic signatures of built-in types (Call, Response, etc.) which are used via reflection at runtime.
• Remove backpressure support from RxJava 2 and 3 adapters. Since we only deliver a single value and the Reactive Streams specification states that callers must request a non-zero subscription value, we never need to honor backpressure.
• Kotlin Retrofit.create function now has a non-null lower bound. Even if you specified a nullable type before this function would never return null.
• Suspend functions now capture and defer all Throwable subtypes (not just Exception subtypes) to avoid Java's UndeclaredThrowableException when thrown synchronously.
• Eagerly reject suspend fun functions that return Call<Body>. These are never correct, and should declare a return type of Body directly.
• Support for Java 14-specific and Java 16-specific reflection needed to invoke default methods on interfaces have been moved to separate versions of a class through a multi-release jar. This should have no observable impact other than the jar now contains classes which target Java 14 and Java 16 bytecode that might trip up some static analysis tools which are not aware of multi-release jars.
• Parameter names are now displayed in exception messages when available in the underlying Java bytecode.
• Jackson converter now supports binary formats by using byte streams rather than character streams in its implementation. Use the create(ObjectMapper, MediaType) overload to supply the value of the Content-Type header for your format.

Fixed

• Do not include synthetic methods when doing eager validation.
• Use per-method rather than per-class locking when parsing annotations. This eliminates contention when multiple calls are made in quick succession at the beginning of the process lifetime.

• New: RxJava 3 adapter!

  The Maven coordinates are com.squareup.retrofit2:adapter-rxjava3.

  Unlike the RxJava 1 and RxJava 2 adapters, the RxJava 3 adapter's create() method will produce asynchronous HTTP requests by default. For synchronous requests use createSynchronous() and for synchronous on a scheduler use createWithScheduler(..).

• Fix: Detect running on the Android platform by using system property rather than the presence of classes. This ensures that even when you're running on the JVM with Android classes present on the classpath you get JVM semantics.
• Fix: Update to OkHttp 3.14.9 which contains an associated Android platform detection fix.

• Fix: Do not access MethodHandles.Lookup on Android API 24 and 25. The class is only available on Android API 26 and higher.

• New: Add Call.timeout() which returns the okio.Timeout of the full call.
• Fix: Change Call.awaitResponse() to accept a nullable response type.
• Fix: Support default methods on Java 14+. We had been working around a bug in earlier versions of Java. That bug was fixed in Java 14, and the fix broke our workaround.

• Fix: Update to OkHttp 3.14.7 for compatibility with Android R (API 30).

• Fix: Support 'suspend' functions in services interfaces when using 'retrofit-mock' artifact.

This release changes the minimum requirements to Java 8+ or Android 5+. See this blog post for more information on the change.

• New: Upgrade to OkHttp 3.14.4. Please see its changelog for 3.x.
• Fix: Allow service interfaces to extend other interfaces.
• Fix: Ensure a non-null body is returned by Response.error.

• Fix: Support 'suspend' functions in services interfaces when using 'retrofit-mock' artifact.

• Fix: Change mechanism for avoiding UndeclaredThrowableException in rare cases from using yield an explicit dispatch which ensures that it will work even on dispatchers which do not support yielding.

• Fix: Avoid IOExceptions being wrapped in UndeclaredThrowableException in rare cases when using Response<..> as a return type for Kotlin 'suspend' functions.

• Fix: Avoid IOExceptions being wrapped in UndeclaredThrowableException in rare cases.
• Fix: Include no-content ResponseBody for responses created by Response.error.
• Fix: Update embedded R8/ProGuard rules to not warn about nested classes used for Kotlin extensions.

• New: Support suspend modifier on functions for Kotlin! This allows you to express the asynchrony of HTTP requests in an idiomatic fashion for the language.

  @GET("users/{id}")
  suspend fun user(@Path("id") id: Long): User
  

  Behind the scenes this behaves as if defined as fun user(...): Call<User> and then invoked with Call.enqueue. You can also return Response<User> for access to the response metadata.

  Currently this integration only supports non-null response body types. Follow issue 3075 for nullable type support.

• New: @Tag parameter annotation for setting tags on the underlying OkHttp Request object. These can be read in CallAdapters or OkHttp Interceptors for tracing, analytics, varying behavior, and more.

• New: @SkipCallbackExecutor method annotation will result in your Call invoking its Callback on the background thread on which the HTTP call was made.

• New: Support OkHttp's Headers type for @HeaderMap parameters.

• New: Add Retrofit.Builder.baseUrl(URL) overload.

• Fix: Add embedded R8/ProGuard rule which retains Retrofit interfaces (while still allowing obfuscation). This is needed because R8 running in 'full mode' (i.e., not in ProGuard-compatibility mode) will see that there are no subtypes of these interfaces and rewrite any code which references instances to null.

• Fix: Mark HttpException.response() as @Nullable as serializing the exception does not retain this instance.

• Fix: Fatal errors (such as stack overflows, out of memory, etc.) now propagate to the OkHttp Dispatcher thread on which they are running.

• Fix: Ensure JAX-B converter closes the response body when an exception is thrown during deserialization.

• Fix: Ignore static methods when performing eager validation of interface methods.

• Fix: Ensure that calling source() twice on the ResponseBody passed to a Converter always returns the same instance. Prior to the fix, intermediate buffering would cause response data to be lost.

• New: Built-in support for Kotlin's Unit type. This behaves the same as Java's Void where the body content is ignored and immediately discarded.
• New: Built-in support for Java 8's Optional and CompletableFuture types. Previously the 'converter-java8' and 'adapter-java8' dependencies were needed and explicitly adding Java8OptionalConverterFactory and/or Java8CallAdapterFactory to your Retrofit.Builder in order to use these types. Support is now built-in and those types and their artifacts are marked as deprecated.
• New: Invocation class provides a reference to the invoked method and argument list as a tag on the underlying OkHttp Call. This can be accessed from an OkHttp interceptor for things like logging, analytics, or metrics aggregation.
• New: Kotlin extension for Retrofit which allows you call create passing the interface type only as a generic parameter (e.g., retrofit.create<MyService>()).
• New: Added Response.success overload which allows specifying a custom 2xx status code.
• New: Added Calls.failure overload which allows passing any Throwable subtype.
• New: Minimal R8 rules now ship inside the jar requiring no client configuration in the common case.
• Fix: Do not propagate fatal errors to the callback. They are sent to the thread's uncaught exception handler.
• Fix: Do not enqueue/execute an otherwise useless call when the RxJava type is disposed by onSubscribe.
• Fix: Call RxJavaPlugins assembly hook when creating an RxJava 2 type.
• Fix: Ensure both the Guava and Java 8 Optional converters delegate properly. This ensures that converters registered prior to the optional converter can be used for deserializing the body type.
• Fix: Prevent @Path values from participating in path-traversal. This ensures untrusted input passed as a path value cannot cause you to make a request to an un-intended relative URL.
• Fix: Simple XML converter (which is deprecated) no longer wraps subtypes of RuntimeException or IOException when it fails.
• Fix: Prevent JAXB converter from loading remote entities and DTDs.
• Fix: Correctly detect default methods in interfaces on Android (API 24+). These still do not work, but now a correct exception will be thrown when detected.
• Fix: Report more accurate exceptions when a @QueryName or @QueryMap precedes a @Url parameter.
• Update OkHttp dependency to 3.12.

• New: Retrofit.Builder exposes mutable lists of the added converter and call adapter factories.
• New: Call adapter added for Scala's Future.
• New: Converter for JAXB replaces the now-deprecated converter for Simple XML Framework.
• New: Add Java 9 automatic module names for each artifact corresponding to their root package.
• Fix: Do not swallow Errors from callbacks (usually OutOfMemoryError).
• Fix: Moshi and Gson converters now assert that the full response was consumed. This prevents hiding bugs in faulty adapters which might not have consumed the full JSON input which would then cause failures on the next request over that connection.
• Fix: Do not conflate OkHttp Call cancelation with RxJava unsubscription/disposal. Prior to this change, canceling of a Call would prevent a cancelation exception from propagating down the Rx stream.