Skip to content

[DE-322] v7 documentation #471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 10, 2022
Merged

[DE-322] v7 documentation #471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
386dfa4
http client
rashtao Nov 10, 2022
9100c07
ArangoDB.execute
rashtao Nov 10, 2022
132223b
ConfigPropertiesProvider
rashtao Nov 10, 2022
7ae4a44
docs upd
rashtao Nov 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 25 additions & 17 deletions driver/ChangeLog.md → ChangeLog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -31,40 +34,45 @@ 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
- `ArangoDatabase.executeTraversal()`
- `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]

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
123 changes: 74 additions & 49 deletions docs/v7_detailed_changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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<ObjectMapper>)`,
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<ObjectMapper>)`, 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<T>, Class<U>): Response<U>` 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.