diff --git a/driver/ChangeLog.md b/ChangeLog.md similarity index 96% rename from driver/ChangeLog.md rename to ChangeLog.md index 0b27cc0df..2bcbc63d2 100644 --- a/driver/ChangeLog.md +++ b/ChangeLog.md @@ -10,18 +10,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a ### Changed -- changed default communication protocol from VST to HTTP/1.1 -- changed default content-type encoding format from VPACK to JSON -- transitive dependency on `org.apache.httpcomponents:httpclient:4.5.x` is not optional anymore, but it can be excluded - if using VST only +- configuration properties from local files are not read automatically anymore +- `ArangoDB.execute()` accepts now target deserialization type +- `Request` and `Response` support now generic body type +- removed default host configuration to `127.0.0.1:8529` +- changed http client library to Vert.x WebClient +- changed default communication protocol from `VST` to `HTTP/2` +- changed default content-type encoding format from `VPACK` to `JSON` - VPACK support is now provided by the optional dependency `com.arangodb:jackson-dataformat-velocypack` as dataformat backend for Jackson - changed serialization module, which is now based on Jackson API - data objects passed as arguments to API methods are now treated as immutable and the related metadata fields are not updated anymore (updated metadata can be found anyway in the object returned by the API method) - changed some API signatures which were using unnecessary generics -- changed `com.arangodb.ArangoCursor#getStats()` to return untyped map -- modeled replication factor with a new interface (`com.arangodb.entity.ReplicationFactor`) with +- changed `ArangoCursor#getStats()` to return untyped map +- modeled replication factor with a new interface (`ReplicationFactor`) with implementations: `NumericReplicationFactor` and `SatelliteReplicationFactor` - all data definition classes are now `final` - `BaseDocument` and `BaseEdgeDocument` are now `final` @@ -31,12 +34,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a ### Removed -- removed user data custom serializer API based on `com.arangodb.util.ArangoSerialization` (in favor - of `com.arangodb.serde.ArangoSerde`) -- removed user data custom serializer implementation `com.arangodb.mapping.ArangoJack` (in favor - of `com.arangodb.serde.JacksonSerde`) -- removed support for interpreting raw strings as JSON (in favor of `com.arangodb.util.RawJson`) -- removed support of data type `com.arangodb.velocypack.VPackSlice` (in favor of Jackson types: `JsonNode`, `ArrayNode`, `ObjectNode`, ...) +- removed user data custom serializer API based on `ArangoSerialization` (in favor of `ArangoSerde`) +- removed user data custom serializer implementation `ArangoJack` (in favor of `JacksonSerde`) +- removed support for interpreting raw strings as JSON (in favor of `RawJson`) +- removed support of data type `VPackSlice` (in favor of Jackson types: `JsonNode`, `ArrayNode`, `ObjectNode`, ...) - removed client APIs already deprecated in Java Driver version `6.19.0` - removed deprecated server APIs: - `MMFiles` related APIs @@ -44,27 +45,34 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a - `ArangoDB.getLogs()` - `minReplicationFactor` in collections and graphs - `overwrite` flag in `DocumentCreateOptions` +- removed `ArangoCursorInitializer` ### Added +- added `ArangoDB.Builder.loadProperties(ConfigPropertiesProvider)` to register custom configuration providers +- added `FileConfigPropertiesProvider` to load properties from local files +- added support to `HTTP/2` communication protocol +- added transitive dependency on `io.vertx:vertx-web-client`, which can be excluded if using VST only - added transitive dependency on Jackson Core, Databind and Annotations -- added wrapper class for raw JSON content (`com.arangodb.util.RawJson`) -- added wrapper class for content already encoded as byte array (`com.arangodb.util.RawBytes`) +- added wrapper class for raw JSON content (`RawJson`) +- added wrapper class for content already encoded as byte array (`RawBytes`) - added support for Jackson types (`JsonNode`, `ArrayNode`, `ObjectNode`, ...) - added support for Jackson annotations in data types -- added new user data custom serializer API based on `com.arangodb.serde.ArangoSerde` -- added new user data custom serializer implementation based on Jackson (`com.arangodb.serde.JacksonSerde`) +- added new user data custom serializer API based on `ArangoSerde` +- added new user data custom serializer implementation based on Jackson (`JacksonSerde`) - added methods and parameters targets to meta binding annotations - added overloaded methods for CRUD operations allowing specifying the return type - added API to support CRUD operations from raw data (`RawBytes` and `RawJson`) containing multiple documents - added `BaseDocument#removeAttribute(String)` and `BaseEdgeDocument#removeAttribute(String)` +- added request id to `ArangoDBException` ### Fixed - removed `--allow-incomplete-classpath` from native image configuration (#397) - ability to control whether `null` values are included in the serialization (#389) -- added support to `com.arangodb.model.DocumentCreateOptions#keepNull` (#374) +- added support to `DocumentCreateOptions#keepNull` (#374) - allow specifying the return type on insertDocuments (#373) +- removed credentials logging (#410) ## [6.19.0] diff --git a/README.md b/README.md index d50d4ec1d..843d4e3e1 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ The official [ArangoDB](https://www.arangodb.com/) Java Driver. ## Learn more -- [ChangeLog](driver/ChangeLog.md) +- [ChangeLog](ChangeLog.md) - [Examples](driver/src/test/java/com/arangodb/example) - [Examples Async](driver/src/test/java/com/arangodb/async/example) - [Tutorial](https://www.arangodb.com/docs/stable/drivers/java-tutorial.html) diff --git a/docs/v7_detailed_changes.md b/docs/v7_detailed_changes.md index 65769cd83..f63fc6578 100644 --- a/docs/v7_detailed_changes.md +++ b/docs/v7_detailed_changes.md @@ -1,34 +1,48 @@ # Version 7.0: detailed changes +## HTTP client -## Default protocol +The HTTP client has been changed to Vert.x WebClient. `HTTP/2` is now supported. `HTTP/2` supports multiplexing and uses +`1` connection per host by default. -The default communication protocol is now `HTTP_JSON` (`HTTP/1.1` with `JSON` content type). +## Configuration changes +The default communication protocol is now `HTTP2_JSON` (`HTTP/2` with `JSON` content type). + +The default host configuration to `127.0.0.1:8529` has been removed. + +Configuration properties are not read automatically from properties files anymore. + +A new configuration option for loading properties has been +introduced: `ArangoDB.Builder.loadProperties(ConfigPropertiesProvider)`. Implementations could supply configuration +properties coming from different sources, eg. system properties, remote stores, frameworks facilities, etc. An +implementation for loading properties from local files is provided by `FileConfigPropertiesProvider`. ## Transitive dependencies -A transitive dependency on `org.apache.httpcomponents:httpclient:4.5.x` has been added and the dependency -on `com.arangodb:velocypack` has been removed. -The dependency on `org.apache.httpcomponents:httpclient` can be excluded when using `VST` communication protocol only. -When using `VST` or `HTTP_VPACK`, the optional dependency on `com.arangodb:jackson-dataformat-velocypack` must be -provided. -When using `HTTP_JSON` (default), no dependencies on `VPACK` libraries are required. +A transitive dependency on `io.vertx:vertx-web-client` has been added. In can be excluded when using `VST` protocol +only. + +The dependency on `com.arangodb:velocypack` has been removed. + +When using protocol `VST`, `HTTP_VPACK` or `HTTP2_VPACK`, the optional dependency +on `com.arangodb:jackson-dataformat-velocypack` must be provided. + +When using protocol `HTTP_JSON` or `HTTP2_JSON` (default), no dependencies on `VPACK` libraries are required. + Transitive dependencies on Jackson Core, Databind and Annotations have been added, using by default version `2.13`. The versions of such libraries can be overridden, the driver is compatible with Jackson versions: `2.10`, `2.11`, `2.12` , `2.13`. - ## User Data Types Before version `7.0` the driver always parsed raw strings as JSON, but unfortunately this does not allow distinguishing the case when the intent is to use the raw string as such, without parsing it. Since version `7.0`, strings are not -interpreted as JSON anymore. To represent user data as raw JSON, the wrapper class `com.arangodb.util.RawJson` has been -added. +interpreted as JSON anymore. To represent user data as raw JSON, the wrapper class `RawJson` has been added. -To represent user data already encoded as byte array, the wrapper class `com.arangodb.util.RawBytes` has been added. -The byte array can either represent a `JSON` string (UTF-8 encoded) or a `VPACK` value, but the encoding must be the -same used for the driver protocol configuration (`JSON` for `HTTP_JSON`, `VPACK` otherwise). +To represent user data already encoded as byte array, the wrapper class `RawBytes` has been added. +The byte array can either represent a `JSON` string (UTF-8 encoded) or a `VPACK` value, but the encoding must be the +same used for the driver protocol configuration (`JSON` for `HTTP_JSON` and `HTTP2_JSON`, `VPACK` otherwise). `BaseDocument` and `BaseEdgeDocument` are now `final`, they have a new method `removeAttribute(String)` and `getProperties()` returns now an unmodifiable map. @@ -38,75 +52,86 @@ metadata received in the response. Since version `7.0`, the input data objects p treated as immutable and the related metadata fields are not updated anymore. The updated metadata can still be found in the object returned by the API method. - ## Serialization The serialization module has been changed and is now based on the Jackson API. -Up to version 6, the (de)serialization was always performed to/from `VPACK`. In case the JSON representation was required, -the raw `VPACK` was then converted to `JSON`. Since version 7, the serialization module is a dataformat agnostic API, based -on the Jackson API. By default, it reads and writes `JSON` format. `VPACK` support is provided by the optional -dependency `com.arangodb:jackson-dataformat-velocypack`, which is a dataformat backend implementation for Jackson. - -The (de)serialization of user data can be customized by registering an implementation -of `com.arangodb.serde.ArangoSerde` via `com.arangodb.ArangoDB.Builder#serializer()`. -The default user data serializer is `com.arangodb.serde.JacksonSerde`, which is based on Jackson API and is available -for both `JSON` and `VPACK`. It (de)serializes user data using Jackson Databind and can handle Jackson Annotations. -It can be customized through `com.arangodb.serde.JacksonSerde#configure(Consumer)`, -i.e. registering Kotlin or Scala modules. Furthermore, meta binding annotations (`@Id`, `@Key`, `@Rev`, `@From`, `@To`) -are supported for mapping documents and edges metadata fields (`_id`, `_key`, `_rev`, `_from`, `_to`). - -`com.arangodb.serde.ArangoSerde` interface is not constrained to Jackson. It is instead an abstract API that can be -implemented using any custom serialization library, e.g. an example of `JSON-B` implementation can be found in +Up to version 6, the (de)serialization was always performed to/from `VPACK`. In case the JSON representation was +required, the raw `VPACK` was then converted to `JSON`. Since version 7, the serialization module is a dataformat +agnostic API, based on the Jackson API. By default, it reads and writes `JSON` format. `VPACK` support is provided by +the optional dependency `com.arangodb:jackson-dataformat-velocypack`, which is a dataformat backend implementation for +Jackson. + +The (de)serialization of user data can be customized by registering an implementation of `ArangoSerde` +via `ArangoDB.Builder#serializer()`. The default user data serializer is `JacksonSerde`, which is based on Jackson API +and is available for both `JSON` and `VPACK`. It (de)serializes user data using Jackson Databind and can handle Jackson +Annotations. It can be customized through `JacksonSerde#configure(Consumer)`, i.e. registering Kotlin or +Scala modules. Furthermore, meta binding annotations (`@Id`, `@Key`, `@Rev`, `@From`, `@To`) are supported for mapping +documents and edges metadata fields (`_id`, `_key`, `_rev`, `_from`, `_to`). + +`ArangoSerde` interface is not constrained to Jackson. It is instead an abstract API that can be implemented using any +custom serialization library, e.g. an example of `JSON-B` implementation can be found in the [tests](../src/test/java/com/arangodb/serde/JsonbSerdeImpl.java). Independently of the user data serializer, the following data types are (de)serialized with specific handlers (not customizable): + - `JsonNode` and its children (`ArrayNode`, `ObjectNode`, ...) - `RawJson` - `RawBytes` - `BaseDocument` - `BaseEdgeDocument` - ## Removed APIs The following client APIs have been removed: + - client APIs already deprecated in Java Driver version `6.19.0` - client API to interact with deprecated server APIs: - - `MMFiles` related APIs - - `ArangoDatabase.executeTraversal()` - - `ArangoDB.getLogs()` - - `minReplicationFactor` in collections and graphs - - `overwrite` flag in `DocumentCreateOptions` - -The deprecation notes in the related javadoc contain information about the reason of the deprecation and suggest -migration alternatives to use. + - `MMFiles` related APIs + - `ArangoDatabase.executeTraversal()` + - `ArangoDB.getLogs()` + - `minReplicationFactor` in collections and graphs + - `overwrite` flag in `DocumentCreateOptions` -To migrate your existing project to Java Driver version `7.0`, it is recommended updating to version `6.19` first and -make sure that your code does not use any deprecated API. This can be done by checking the presence of deprecation -warnings in the Java compiler output. +The user data custom serializer implementation `ArangoJack` has been removed in favor of `JacksonSerde`. -The user data custom serializer implementation `com.arangodb.mapping.ArangoJack` has been removed in favor of `com.arangodb.serde.JacksonSerde`. +Support for interpreting raw strings as JSON has been removed (in favor of `RawJson`). -Support for interpreting raw strings as JSON has been removed (in favor of `com.arangodb.util.RawJson`). - -Support of data type `com.arangodb.velocypack.VPackSlice` has been removed (in favor of Jackson types: `JsonNode`, `ArrayNode`, `ObjectNode`, ...). +Support of data type `VPackSlice` has been removed (in favor of Jackson types: `JsonNode`, `ArrayNode`, `ObjectNode`, +...). +Support for custom initialization of +cursors (`ArangoDB._setCursorInitializer(ArangoCursorInitializer cursorInitializer)`) has been removed. ## API methods changes -Before version `7.0` some CRUD API methods inferred the return type from the type of the data object passed as input. Now the return type can be explicitly set for each CRUD API method. +Before version `7.0` some CRUD API methods inferred the return type from the type of the data object passed as input. +Now the return type can be explicitly set for each CRUD API method. CRUD operations operating with multiple documents have now an overloaded variant which accepts raw data (`RawBytes` and `RawJson`) containing multiple documents. -`com.arangodb.ArangoCursor#getStats()` returns now an untyped map. +`ArangoCursor#getStats()` returns now an untyped map. + +`Request` and `Response` classes have been refactored to support generic body +type. `ArangoDB.execute(Request, Class): Response` accepts now the target deserialization type for the response +body. +`ArangoDBException` has been enhanced with the id of the request causing it. ## API entities All entities and options classes are now `final`. -The replication factor is now modeled with a new interface (`com.arangodb.entity.ReplicationFactor`) with +The replication factor is now modeled with a new interface (`ReplicationFactor`) with implementations: `NumericReplicationFactor` and `SatelliteReplicationFactor`. + +## Migration + +To migrate your existing project to Java Driver version `7.0`, it is recommended updating to version `6.19` first and +make sure that your code does not use any deprecated API. This can be done by checking the presence of deprecation +warnings in the Java compiler output. + +The deprecation notes in the related javadoc contain information about the reason of the deprecation and suggest +migration alternatives to use.