
# Differences from Spring

`spring_web_dart` keeps Spring Web's names and meanings: the mapping annotations, `ResponseEntity`, `HttpHeaders`, `HttpStatus`, `ProblemDetail`, `PathPattern`. This page lists where Dart gives them another shape, and what is added.

## Why

Dart has no overloading, cannot mix an optional positional parameter with named ones, has extension types and null safety, and runs in the browser. Each difference below follows from one of these.

## Example

```dart
@GetMapping.of(path: '/books', produces: MediaType.applicationJson)
Future<List<Book>> search(@RequestParam('page') int page = 0);
```

```java
@GetMapping(value = "/books", produces = MediaType.APPLICATION_JSON_VALUE)
List<Book> search(@RequestParam(name = "page", defaultValue = "0") int page);
```

## Annotations

| Spring | Here | Why |
|---|---|---|
| `@GetMapping("/books", produces = ...)` | `@GetMapping.of(path: '/books', produces: ...)`; `@GetMapping()` and `@GetMapping('/books')` stay | No optional positional parameter next to named ones. |
| `produces` and `consumes` as arrays | one `String`, comma-separated | |
| `required`, `defaultValue` | the Dart parameter: nullable is optional, a default is the default, anything else is required | Null safety says it. |
| Mapping `headers` on a client (OpenFeign) | `'Name=value'` sent; conditions (`'Name'`, `'!Name'`, `'Name!=value'`) ignored; Feign's `'Name: value'` rejected at startup | |
| `@ExceptionHandler` matches subtypes | `types` matched by exact runtime type | No runtime subtype test between `Type`s. |

## Types

| Spring | Here |
|---|---|
| `HttpStatus` enum with `name()` | `int` constants (an extension type); `toString()` is the number; `100 Continue` is `HttpStatus.continue_`; deprecated aliases (`PAYLOAD_TOO_LARGE`, `UNPROCESSABLE_ENTITY`) left out. A response's `statusCode` is an `HttpStatusCode`, also an `int`. |
| `HttpHeaders.CONTENT_TYPE` | `HttpHeaders.contentTypeHeader` (the plain names are the typed accessors, as in `dart:io`). |
| `contentType` a `MediaType`, `lastModified` `-1` when absent, an empty `contentDisposition` | `contentType` a `String`, `accept` a `List<MediaType>`, `lastModified` and `date` `DateTime?`, `contentDisposition` `null` when absent. |
| `addAll(HttpHeaders)`, `putAll(HttpHeaders)` | `addHeaders(other)`, `putAll(other)`; `addAll(name, values)` adds values of one name; `size` counts names. `operator []` gives the first value, `getAll` all; `toMap()` joins values with `, `, `toSingleValueMap()` keeps the first. |
| `MediaType` objects and `..._VALUE` strings | constants are strings (usable in annotations); `MediaType.parse` gives an object. A `charset` Dart does not know is `null` instead of an error, and `bodyText` falls back to UTF-8. |
| `ResponseEntity.ok()` builder, `of(Optional)` | `ResponseEntity.ok(body)` is a constructor; the builder is `ResponseEntity.status(HttpStatus.ok)`; `of` takes a nullable body. `==` compares collections in the body by content. |
| `HttpMethod.valueOf("get")` creates a method | `HttpMethod.parse` is case-sensitive and throws on any other text. |

## Clients and server

| Spring | Here |
|---|---|
| A read timeout | `readTimeout` (the same) and `timeout`, a deadline for the whole exchange |
| No limit on a request's total work | `RequestDeadline`, carried in the `Zone` and honoured by the web and Feign starters |
| `WebSocketHandler` callbacks; `TextMessage`, `BinaryMessage`; blocking `sendMessage` | `messages` as a `Stream`; `sendMessage(String)` or bytes; non-blocking, with `flush()` on `dart:io`; `closeStatus` on the session |
| Tomcat's client follows handshake redirects | not followed, as in browsers |
| `AllowedOrigins` (in `CorsConfiguration`) with any origin length | an origin over 1024 characters is never allowed |
| `EventStream` absent; `Flux<ServerSentEvent<T>>` | `EventStream<T>` is a `Stream<T>` with `.events`, reconnection built in |

## Not supported yet

- A `RestClient`-style fluent client (Feign interfaces and `HttpTransport` cover the use).
- Compression extensions for WebSocket (permessage-deflate).

## See also

- [Overview](index.md)
- [Mapping annotations](mapping-annotations.md)
- [HTTP types](http-types.md)
