Skip to content
This repository was archived by the owner on Dec 13, 2023. It is now read-only.

[DE-681] Spring Data: v4 updates #1469

Closed
wants to merge 2 commits into from
Closed

[DE-681] Spring Data: v4 updates #1469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
78f8ebe
Spring Data: v4 updates
rashtao Sep 6, 2023
b4dd13c
Add new page to navigation definition
Simran-B Sep 7, 2023
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
2 changes: 2 additions & 0 deletions _data/drivers.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@
href: spring-data-migration-migrating-1-x-3-0.html
- text: Migrating 2.x to 3.0
href: spring-data-migration-migrating-2-x-3-0.html
- text: Migrating 3.x to 4.0
href: spring-data-migration-migrating-3-x-4-0.html
- text: ArangoDB Datasource for Apache Spark
href: spark-connector-new.html
- text: ArangoDB Spark Connector
Expand Down
10 changes: 10 additions & 0 deletions drivers/spring-data-migration-migrating-3-x-4-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
layout: default
---
# Migrating Spring Data ArangoDB 3.x to 4.0

## Java Driver
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe some more concrete points here: https://gist.github.com/aburmeis/97759b8057219b97ed5165b402e32d70


Spring Data ArangoDB 4.x uses ArangoDB Java Driver version 7, which introduced several
breaking [changes](java-changes-v7.html).

1 change: 1 addition & 0 deletions drivers/spring-data-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ layout: default

- [Migrating 1.x to 3.0](spring-data-migration-migrating-1-x-3-0.html)
- [Migrating 2.x to 3.0](spring-data-migration-migrating-2-x-3-0.html)
- [Migrating 3.x to 4.0](spring-data-migration-migrating-3-x-4-0.html)
16 changes: 8 additions & 8 deletions drivers/spring-data-reference-mapping-converter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,23 +24,23 @@ public class MyConfiguration implements ArangoConfiguration {

## Implementing a Spring Converter

A `Converter` is used for reading if the source type is of type `VPackSlice` or `DBDocumentEntity`.
A `Converter` is used for reading if the source type is of type `JsonNode` or `DBDocumentEntity`.

A `Converter` is used for writing if the target type is of type `VPackSlice`, `DBDocumentEntity`, `BigInteger`, `BigDecimal`, `java.sql.Date`, `java.sql.Timestamp`, `Instant`, `LocalDate`, `LocalDateTime`, `OffsetDateTime`, `ZonedDateTime`, `Boolean`, `Short`, `Integer`, `Byte`, `Float`, `Double`, `Character`, `String`, `Date`, `Class`, `Enum`, `boolean[]`, `long[]`, `short[]`, `int[]`, `byte[]`, `float[]`, `double[]` or `char[]`.
A `Converter` is used for writing if the target type is of type `JsonNode`, `DBDocumentEntity`, `BigInteger`, `BigDecimal`, `java.sql.Date`, `java.sql.Timestamp`, `Instant`, `LocalDate`, `LocalDateTime`, `OffsetDateTime`, `ZonedDateTime`, `Boolean`, `Short`, `Integer`, `Byte`, `Float`, `Double`, `Character`, `String`, `Date`, `Class`, `Enum`, `boolean[]`, `long[]`, `short[]`, `int[]`, `byte[]`, `float[]`, `double[]` or `char[]`.

**Examples**

```java
public class MyConverter implements Converter<MyObject, VPackSlice> {
public class MyConverter implements Converter<MyObject, JsonNode> {

@Override
public VPackSlice convert(final MyObject source) {
VPackBuilder builder = new VPackBuilder();
public JsonNode convert(final MyObject source) {
ObjectNode on = JsonNodeFactory.instance.objectNode();
// map fields of MyObject to builder
return builder.slice();
// on.put("key", "value");
// ...
return on;
}

}
```

For performance reasons `VPackSlice` should always be used within a converter. If your object is too complex, you can also use `DBDocumentEntity` to simplify the mapping.
4 changes: 2 additions & 2 deletions drivers/spring-data-reference-mapping-indexes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Possible `@<IndexType>Indexed` annotations are:

- `@PersistentIndexed`
- `@GeoIndexed`
- `@FulltextIndexed`
- `@FulltextIndexed` (deprecated)
- `@TtlIndexed`

The following example creates a persistent index on the field `name` and a separate persistent index on the field `age`:
Expand Down Expand Up @@ -52,7 +52,7 @@ Possible `@<IndexType>Index` annotations are:

- `@PersistentIndex`
- `@GeoIndex`
- `@FulltextIndex`
- `@FulltextIndex` (deprecated)
- `@TtlIndex`

The following example creates a single persistent index on the fields `name` and `age`, note that if a field is renamed in the database with @Field, the new field name must be used in the index declaration:
Expand Down
94 changes: 36 additions & 58 deletions drivers/spring-data-reference-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ title: Spring Data ArangoDB - Mapping
---
# Mapping

In this section we will describe the features and conventions for mapping Java objects to documents and how to override those conventions with annotation based mapping metadata.
In this section we will describe the features and conventions for mapping Java objects to documents and how to override
those conventions with annotation based mapping metadata.

## Conventions

Expand All @@ -20,37 +21,13 @@ In this section we will describe the features and conventions for mapping Java o
- a non-parameterized constructor or
- a parameterized constructor annotated with `@PersistenceConstructor`

## Type conventions

ArangoDB uses [VelocyPack](https://github.com/arangodb/velocypack){:target="_blank"} as it's internal storage format which supports a large number of data types. In addition Spring Data ArangoDB offers - with the underlying Java driver - built-in converters to add additional types to the mapping.

| Java type | VelocyPack type |
| ------------------------ | ----------------------------- |
| java.lang.String | string |
| java.lang.Boolean | bool |
| java.lang.Integer | signed int 4 bytes, smallint |
| java.lang.Long | signed int 8 bytes, smallint |
| java.lang.Short | signed int 2 bytes, smallint |
| java.lang.Double | double |
| java.lang.Float | double |
| java.math.BigInteger | string |
| java.math.BigDecimal | string |
| java.lang.Number | double |
| java.lang.Character | string |
| java.util.UUID | string |
| java.lang.byte[] | string (Base64) |
| java.util.Date | string (date-format ISO 8601) |
| java.sql.Date | string (date-format ISO 8601) |
| java.sql.Timestamp | string (date-format ISO 8601) |
| java.time.Instant | string (date-format ISO 8601) |
| java.time.LocalDate | string (date-format ISO 8601) |
| java.time.LocalDateTime | string (date-format ISO 8601) |
| java.time.OffsetDateTime | string (date-format ISO 8601) |
| java.time.ZonedDateTime | string (date-format ISO 8601) |

## Type mapping

As collections in ArangoDB can contain documents of various types, a mechanism to retrieve the correct Java class is required. The type information of properties declared in a class may not be enough to restore the original class (due to inheritance). If the declared complex type and the actual type do not match, information about the actual type is stored together with the document. This is necessary to restore the correct type when reading from the DB. Consider the following example:
As collections in ArangoDB can contain documents of various types, a mechanism to retrieve the correct Java class is
required. The type information of properties declared in a class may not be enough to restore the original class (due to
inheritance). If the declared complex type and the actual type do not match, information about the actual type is stored
together with the document. This is necessary to restore the correct type when reading from the DB. Consider the
following example:

```java
public class Person {
Expand Down Expand Up @@ -138,37 +115,38 @@ To deactivate the type mapping process, you can return `null` from the `typeKey(

### Annotation overview

| annotation | level | description |
|-------------------------| ------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------|
| @Document | class | marks this class as a candidate for mapping |
| @Edge | class | marks this class as a candidate for mapping |
| @Id | field | stores the field as the system field \_key |
| @Rev | field | stores the field as the system field \_rev |
| @Field("alt-name") | field | stores the field with an alternative name |
| @Ref | field | stores the \_id of the referenced document and not the nested document |
| @From | field | stores the \_id of the referenced document as the system field \_from |
| @To | field | stores the \_id of the referenced document as the system field \_to |
| @Relations | field | vertices which are connected over edges |
| @Transient | field, method, annotation | marks a field to be transient for the mapping framework, thus the property will not be persisted and not further inspected by the mapping framework |
| annotation | level | description |
|-----------------------| ------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------|
| @Document | class | marks this class as a candidate for mapping |
| @Edge | class | marks this class as a candidate for mapping |
| @Id | field | stores the field as the system field \_key |
| @ArangoId | field | stores the field as the system field \_id |
| @Rev | field | stores the field as the system field \_rev |
| @Field("alt-name") | field | stores the field with an alternative name |
| @Ref | field | stores the \_id of the referenced document and not the nested document |
| @From | field | stores the \_id of the referenced document as the system field \_from |
| @To | field | stores the \_id of the referenced document as the system field \_to |
| @Relations | field | vertices which are connected over edges |
| @Transient | field, method, annotation | marks a field to be transient for the mapping framework, thus the property will not be persisted and not further inspected by the mapping framework |
| @PersistenceConstructor | constructor | marks a given constructor - even a package protected one - to use when instantiating the object from the database |
| @TypeAlias("alias") | class | set a type alias for the class when persisted to the DB |
| @PersistentIndex | class | describes a persistent index |
| @PersistentIndexed | field | describes how to index the field |
| @GeoIndex | class | describes a geo index |
| @GeoIndexed | field | describes how to index the field |
| @FulltextIndex | class | describes a fulltext index |
| @FulltextIndexed | field | describes how to index the field |
| @TtlIndex | class | describes a TTL index |
| @TtlIndexed | field | describes how to index the field |
| @CreatedBy | field | Declares a field as the one representing the principal that created the entity containing the field. |
| @CreatedDate | field | Declares a field as the one representing the date the entity containing the field was created. |
| @LastModifiedBy | field | Declares a field as the one representing the principal that recently modified the entity containing the field. |
| @LastModifiedDate | field | Declares a field as the one representing the date the entity containing the field was recently modified. |
| @TypeAlias("alias") | class | set a type alias for the class when persisted to the DB |
| @PersistentIndex | class | describes a persistent index |
| @PersistentIndexed | field | describes how to index the field |
| @GeoIndex | class | describes a geo index |
| @GeoIndexed | field | describes how to index the field |
| @FulltextIndex | class | describes a fulltext index |
| @FulltextIndexed | field | describes how to index the field |
| @TtlIndex | class | describes a TTL index |
| @TtlIndexed | field | describes how to index the field |
| @CreatedBy | field | Declares a field as the one representing the principal that created the entity containing the field. |
| @CreatedDate | field | Declares a field as the one representing the date the entity containing the field was created. |
| @LastModifiedBy | field | Declares a field as the one representing the principal that recently modified the entity containing the field. |
| @LastModifiedDate | field | Declares a field as the one representing the date the entity containing the field was recently modified. |


## Invoking conversion manually

In order to invoke entity serialization and deserialization to and from `VPackSlice` manually, you can inject an
In order to invoke entity serialization and deserialization to and from Jackson `JsonNode` manually, you can inject an
instance of `ArangoConverter` and respectively call the methods `write` and `read` on it, e.g.:

```java
Expand All @@ -178,10 +156,10 @@ instance of `ArangoConverter` and respectively call the methods `write` and `rea
ArangoConverter arangoConverter;

// ...
VPackSlice vPackSlice = converter.write(entity);
JsonNode jn = converter.write(entity);

// ...
MyEntity entity = converter.read(MyEntity.class, vPackSlice);
MyEntity entity = converter.read(MyEntity.class, jn);
```

This is useful for cases where you need to use the underlying Java driver directly (accessible from
Expand Down
4 changes: 2 additions & 2 deletions drivers/spring-data-reference-repositories-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Spring Data ArangoDB supports three kinds of queries:

## Return types

The method return type for single results can be a primitive type, a domain class, `Map<String, Object>`, `BaseDocument`, `BaseEdgeDocument`, `Optional<Type>`, `GeoResult<Type>`.
The method return type for single results can be a primitive type, a domain class, `JsonNode`, `ObjectNode`, `Map<String, Object>`, `BaseDocument`, `BaseEdgeDocument`, `Optional<Type>`, `GeoResult<Type>`.

The method return type for multiple results can additionally be `ArangoCursor<Type>`, `Iterable<Type>`, `Collection<Type>`, `List<Type>`, `Set<Type>`, `Page<Type>`, `Slice<Type>`, `GeoPage<Type>`, `GeoResults<Type>` where Type can be everything a single result can be.
The method return type for multiple results can be `JsonNode`, `ArrayNode`, `ArangoCursor<Type>`, `Iterable<Type>`, `Collection<Type>`, `List<Type>`, `Set<Type>`, `Page<Type>`, `Slice<Type>`, `GeoPage<Type>`, `GeoResults<Type>` where Type can be everything a single result can be.

## AQL query options

Expand Down
Loading