From 5bf0eb4fea2ac4a25aeac648ae394ddb8d0e6f49 Mon Sep 17 00:00:00 2001 From: Omar_A Date: Thu, 27 Dec 2018 11:17:11 +0100 Subject: [PATCH] Doc - Sync-external-repo-2018-12-25 (#7854) --- .../Books/Drivers/JS/Reference/Aql.md | 151 +++++++++++ .../Books/Drivers/JS/Reference/Cursor.md | 2 +- .../Drivers/JS/Reference/Database/Queries.md | 130 +++++++++- .../Drivers/JS/Reference/Database/README.md | 14 +- .../Books/Drivers/JS/Reference/README.md | 1 + .../Books/Drivers/JS/Reference/Route.md | 144 ++++++----- .../Books/Drivers/Java/Reference/Setup.md | 24 +- Documentation/Books/Drivers/SUMMARY.md | 1 + .../SpringData/GettingStarted/README.md | 236 +++++++++--------- .../Books/Drivers/SpringData/README.md | 26 +- .../Drivers/SpringData/Reference/README.md | 48 ++-- 11 files changed, 536 insertions(+), 241 deletions(-) create mode 100644 Documentation/Books/Drivers/JS/Reference/Aql.md diff --git a/Documentation/Books/Drivers/JS/Reference/Aql.md b/Documentation/Books/Drivers/JS/Reference/Aql.md new file mode 100644 index 0000000000..313c8c4ee0 --- /dev/null +++ b/Documentation/Books/Drivers/JS/Reference/Aql.md @@ -0,0 +1,151 @@ + +# AQL Helpers + +These helpers are available via the `aql` export from the arangojs module: + +```js +import arangojs, { aql } from "arangojs"; + +// or CommonJS: + +const arangojs = require("arangojs"); +const aql = arangojs.aql; +``` + +## aql + +`aql: AqlQuery` + +The `aql` function is a JavaScript template string handler (or template tag). +It can be used to write complex AQL queries as multi-line strings without +having to worry about bindVars and the distinction between collections +and regular parameters. + +To use it just prefix a JavaScript template string (the ones with backticks +instead of quotes) with its import name (e.g. `aql`) and pass in variables +like you would with a regular template string. The string will automatically +be converted into an object with `query` and `bindVars` attributes which you +can pass directly to `db.query` to execute. If you pass in a collection it +will be automatically recognized as a collection reference +and handled accordingly. + +The `aql` template tag can also be used inside other `aql` template strings, +allowing arbitrary nesting. Bind parameters of nested queries will be merged +automatically. + +**Examples** + +```js +const filterValue = 23; +const mydata = db.collection("mydata"); +const result = await db.query(aql` + FOR d IN ${mydata} + FILTER d.num > ${filterValue} + RETURN d +`); + +// nested queries + +const color = "green"; +const filterByColor = aql`FILTER d.color == ${color}'`; +const result2 = await db.query(aql` + FOR d IN ${mydata} + ${filterByColor} + RETURN d +`); +``` + +## aql.literal + +`aql.literal(value): AqlLiteral` + +The `aql.literal` helper can be used to mark strings to be inlined into an AQL +query when using the `aql` template tag, rather than being treated as a bind +parameter. + +{% hint 'danger' %} +Any value passed to `aql.literal` will be treated as part of the AQL query. +To avoid becoming vulnerable to AQL injection attacks you should always prefer +nested `aql` queries if possible. +{% endhint %} + +**Arguments** + +- **value**: `string` + + An arbitrary string that will be treated as a literal AQL fragment when used + in an `aql` template. + +**Examples** + +```js +const filterGreen = aql.literal('FILTER d.color == "green"'); +const result = await db.query(aql` + FOR d IN ${mydata} + ${filterGreen} + RETURN d +`); +``` + +## aql.join + +`aql.join(values)` + +The `aql.join` helper takes an array of queries generated using the `aql` tag +and combines them into a single query. The optional second argument will be +used as literal string to combine the queries. + +**Arguments** + +- **values**: `Array` + + An array of arbitrary values, typically AQL query objects or AQL literals. + +- **sep**: `string` (Default: `" "`) + + String that will be used in between the values. + +**Examples** + +```js +// Basic usage +const parts = [aql`FILTER`, aql`x`, aql`%`, aql`2`]; +const joined = aql.join(parts); // aql`FILTER x % 2` + +// Merge without the extra space +const parts = [aql`FIL`, aql`TER`]; +const joined = aql.join(parts, ""); // aql`FILTER`; + +// Real world example: translate keys into document lookups +const users = db.collection("users"); +const keys = ["abc123", "def456"]; +const docs = keys.map(key => aql`DOCUMENT(${users}, ${key})`); +const aqlArray = aql`[${aql.join(docs, ", ")}]`; +const result = await db.query(aql` + FOR d IN ${aqlArray} + RETURN d +`); +// Query: +// FOR d IN [DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)] +// RETURN d +// Bind parameters: +// @value0: "users" +// value1: "abc123" +// value2: "def456" + +// Alternative without `aql.join` +const users = db.collection("users"); +const keys = ["abc123", "def456"]; +const result = await db.query(aql` + FOR key IN ${keys} + LET d = DOCUMENT(${users}, key) + RETURN d +`); +// Query: +// FOR key IN @value0 +// LET d = DOCUMENT(@@value1, key) +// RETURN d +// Bind parameters: +// value0: ["abc123", "def456"] +// @value1: "users" +``` diff --git a/Documentation/Books/Drivers/JS/Reference/Cursor.md b/Documentation/Books/Drivers/JS/Reference/Cursor.md index 1c619a2519..4b22f5f896 100644 --- a/Documentation/Books/Drivers/JS/Reference/Cursor.md +++ b/Documentation/Books/Drivers/JS/Reference/Cursor.md @@ -32,7 +32,7 @@ remaining result list. **Examples** ```js -const cursor = await db._query('FOR x IN 1..5 RETURN x'); +const cursor = await db.query('FOR x IN 1..5 RETURN x'); const result = await cursor.all() // result is an array containing the entire query result assert.deepEqual(result, [1, 2, 3, 4, 5]); diff --git a/Documentation/Books/Drivers/JS/Reference/Database/Queries.md b/Documentation/Books/Drivers/JS/Reference/Database/Queries.md index fcb81830ac..72aac33663 100644 --- a/Documentation/Books/Drivers/JS/Reference/Database/Queries.md +++ b/Documentation/Books/Drivers/JS/Reference/Database/Queries.md @@ -1,8 +1,10 @@ # Queries -This function implements the -[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html). +These functions implements the +[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html) +as well as the +[HTTP API for managing queries](../../../..//HTTP/AqlQuery/index.html). For collection-specific queries see [Simple Queries](../Collection/SimpleQueries.md). @@ -15,10 +17,13 @@ Performs a database query using the given _query_ and _bindVars_, then returns a **Arguments** -- **query**: `string` +- **query**: `string | AqlQuery | AqlLiteral` - An AQL query string or a [query builder](https://npmjs.org/package/aqb) - instance. + An AQL query as a string or + [AQL query object](../Aql.md#aql) or + [AQL literal](../Aql.md#aqlliteral). + If the query is an AQL query object, the second argument is treated as the + _opts_ argument instead of _bindVars_. - **bindVars**: `Object` (optional) @@ -48,6 +53,12 @@ Dirty reads are only available when targeting ArangoDB 3.4 or later, see [Compatibility](../../GettingStarted/README.md#compatibility). {% endhint %} +Additionally _opts.timeout_ can be set to a non-negative number to force the +request to be cancelled after that amount of milliseconds. Note that this will +simply close the connection and not result in the actual query being cancelled +in ArangoDB, the query will still be executed to completion and continue to +consume resources in the database or cluster. + If _query_ is an object with _query_ and _bindVars_ properties, those will be used as the values of the respective arguments instead. @@ -68,10 +79,9 @@ const cursor = await db.query(aql` // -- or -- // Old-school JS with explicit bindVars: -db.query( - "FOR u IN _users FILTER u.authData.active == @active RETURN u.user", - { active: true } -).then(function(cursor) { +db.query("FOR u IN _users FILTER u.authData.active == @active RETURN u.user", { + active: true +}).then(function(cursor) { // cursor is a cursor for the query result }); ``` @@ -135,3 +145,105 @@ const query = aql` `; // FILTER user.email == @value0 ``` + +## database.explain + +`async database.explain(query, [bindVars,] [opts]): ExplainResult` + +Explains a database query using the given _query_ and _bindVars_ and +returns one or more plans. + +**Arguments** + +- **query**: `string | AqlQuery | AqlLiteral` + + An AQL query as a string or + [AQL query object](../Aql.md#aql) or + [AQL literal](../Aql.md#aqlliteral). + If the query is an AQL query object, the second argument is treated as the + _opts_ argument instead of _bindVars_. + +- **bindVars**: `Object` (optional) + + An object defining the variables to bind the query to. + +- **opts**: `Object` (optional) + + - **optimizer**: `Object` (optional) + + An object with a single property **rules**, a string array of optimizer + rules to be used for the query. + + - **maxNumberOfPlans**: `number` (optional) + + Maximum number of plans that the optimizer is allowed to generate. + Setting this to a low value limits the amount of work the optimizer does. + + - **allPlans**: `boolean` (Default: `false`) + + If set to true, all possible execution plans will be returned + as the _plans_ property. Otherwise only the optimal execution plan will + be returned as the _plan_ property. + +## database.parse + +`async database.parse(query): ParseResult` + +Parses the given query and returns the result. + +**Arguments** + +- **query**: `string | AqlQuery | AqlLiteral` + + An AQL query as a string or + [AQL query object](../Aql.md#aql) or + [AQL literal](../Aql.md#aqlliteral). + If the query is an AQL query object, its bindVars (if any) will be ignored. + +## database.queryTracking + +`async database.queryTracking(): QueryTrackingProperties` + +Fetches the query tracking properties. + +## database.setQueryTracking + +`async database.setQueryTracking(props): void` + +Modifies the query tracking properties. + +**Arguments** + +- **props**: `Partial` + + Query tracking properties with new values to set. + +## database.listRunningQueries + +`async database.listRunningQueries(): Array` + +Fetches a list of information for all currently running queries. + +## database.listSlowQueries + +`async database.listSlowQueries(): Array` + +Fetches a list of information for all recent slow queries. + +## database.clearSlowQueries + +`async database.clearSlowQueries(): void` + +Clears the list of recent slow queries. + +## database.killQuery + +`async database.killQuery(queryId): void` + +Kills a running query with the given ID. + +**Arguments** + +- **queryId**: `string` + + The ID of a currently running query. diff --git a/Documentation/Books/Drivers/JS/Reference/Database/README.md b/Documentation/Books/Drivers/JS/Reference/Database/README.md index a731c37862..a15c090d65 100644 --- a/Documentation/Books/Drivers/JS/Reference/Database/README.md +++ b/Documentation/Books/Drivers/JS/Reference/Database/README.md @@ -49,11 +49,23 @@ If _config_ is a string, it will be interpreted as _config.url_. your certificates to the _agentOptions_, e.g.: ```js + ... agentOptions: { ca: [ fs.readFileSync(".ssl/sub.class1.server.ca.pem"), fs.readFileSync(".ssl/ca.pem") - ]; + ] + } + ``` + + Although this is **strongly discouraged**, it's also possible to disable + HTTPS certificate validation entirely, but note this has + **extremely dangerous** security implications: + + ```js + ... + agentOptions: { + rejectUnauthorized: false } ``` diff --git a/Documentation/Books/Drivers/JS/Reference/README.md b/Documentation/Books/Drivers/JS/Reference/README.md index 2638e3d68a..f64a904865 100644 --- a/Documentation/Books/Drivers/JS/Reference/README.md +++ b/Documentation/Books/Drivers/JS/Reference/README.md @@ -19,6 +19,7 @@ - [Indexes](Collection/Indexes.md) - [Simple Queries](Collection/SimpleQueries.md) - [Bulk Import](Collection/BulkImport.md) +- [AQL Helpers](Aql.md) - [View Manipulation](ViewManipulation.md) - [Cursor](Cursor.md) - [Graph](Graph/README.md) diff --git a/Documentation/Books/Drivers/JS/Reference/Route.md b/Documentation/Books/Drivers/JS/Reference/Route.md index 5e7436940c..d05f5802d0 100644 --- a/Documentation/Books/Drivers/JS/Reference/Route.md +++ b/Documentation/Books/Drivers/JS/Reference/Route.md @@ -13,11 +13,11 @@ route) that can be used to perform arbitrary HTTP requests. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The relative URL of the route. -* **headers**: `Object` (optional) +- **headers**: `Object` (optional) Default headers that should be sent with each request to the route. @@ -40,12 +40,12 @@ Performs a GET request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -54,20 +54,20 @@ Performs a GET request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); +const route = db.route("my-foxx-service"); const response = await route.get(); // response.body is the response body of calling // GET _db/_system/my-foxx-service // -- or -- -const response = await route.get('users'); +const response = await route.get("users"); // response.body is the response body of calling // GET _db/_system/my-foxx-service/users // -- or -- -const response = await route.get('users', {group: 'admin'}); +const response = await route.get("users", { group: "admin" }); // response.body is the response body of calling // GET _db/_system/my-foxx-service/users?group=admin ``` @@ -80,16 +80,16 @@ Performs a POST request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **body**: `string` (optional) +- **body**: `string` (optional) The response body. If _body_ is an object, it will be encoded as JSON. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -98,22 +98,22 @@ Performs a POST request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); -const response = await route.post() +const route = db.route("my-foxx-service"); +const response = await route.post(); // response.body is the response body of calling // POST _db/_system/my-foxx-service // -- or -- -const response = await route.post('users') +const response = await route.post("users"); // response.body is the response body of calling // POST _db/_system/my-foxx-service/users // -- or -- -const response = await route.post('users', { - username: 'admin', - password: 'hunter2' +const response = await route.post("users", { + username: "admin", + password: "hunter2" }); // response.body is the response body of calling // POST _db/_system/my-foxx-service/users @@ -121,10 +121,14 @@ const response = await route.post('users', { // -- or -- -const response = await route.post('users', { - username: 'admin', - password: 'hunter2' -}, {admin: true}); +const response = await route.post( + "users", + { + username: "admin", + password: "hunter2" + }, + { admin: true } +); // response.body is the response body of calling // POST _db/_system/my-foxx-service/users?admin=true // with JSON request body {"username": "admin", "password": "hunter2"} @@ -138,16 +142,16 @@ Performs a PUT request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **body**: `string` (optional) +- **body**: `string` (optional) The response body. If _body_ is an object, it will be encoded as JSON. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -156,22 +160,22 @@ Performs a PUT request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); +const route = db.route("my-foxx-service"); const response = await route.put(); // response.body is the response body of calling // PUT _db/_system/my-foxx-service // -- or -- -const response = await route.put('users/admin'); +const response = await route.put("users/admin"); // response.body is the response body of calling // PUT _db/_system/my-foxx-service/users // -- or -- -const response = await route.put('users/admin', { - username: 'admin', - password: 'hunter2' +const response = await route.put("users/admin", { + username: "admin", + password: "hunter2" }); // response.body is the response body of calling // PUT _db/_system/my-foxx-service/users/admin @@ -179,10 +183,14 @@ const response = await route.put('users/admin', { // -- or -- -const response = await route.put('users/admin', { - username: 'admin', - password: 'hunter2' -}, {admin: true}); +const response = await route.put( + "users/admin", + { + username: "admin", + password: "hunter2" + }, + { admin: true } +); // response.body is the response body of calling // PUT _db/_system/my-foxx-service/users/admin?admin=true // with JSON request body {"username": "admin", "password": "hunter2"} @@ -196,16 +204,16 @@ Performs a PATCH request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **body**: `string` (optional) +- **body**: `string` (optional) The response body. If _body_ is an object, it will be encoded as JSON. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -214,21 +222,21 @@ Performs a PATCH request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); +const route = db.route("my-foxx-service"); const response = await route.patch(); // response.body is the response body of calling // PATCH _db/_system/my-foxx-service // -- or -- -const response = await route.patch('users/admin'); +const response = await route.patch("users/admin"); // response.body is the response body of calling // PATCH _db/_system/my-foxx-service/users // -- or -- -const response = await route.patch('users/admin', { - password: 'hunter2' +const response = await route.patch("users/admin", { + password: "hunter2" }); // response.body is the response body of calling // PATCH _db/_system/my-foxx-service/users/admin @@ -236,9 +244,13 @@ const response = await route.patch('users/admin', { // -- or -- -const response = await route.patch('users/admin', { - password: 'hunter2' -}, {admin: true}); +const response = await route.patch( + "users/admin", + { + password: "hunter2" + }, + { admin: true } +); // response.body is the response body of calling // PATCH _db/_system/my-foxx-service/users/admin?admin=true // with JSON request body {"password": "hunter2"} @@ -252,12 +264,12 @@ Performs a DELETE request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -266,20 +278,20 @@ Performs a DELETE request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); -const response = await route.delete() +const route = db.route("my-foxx-service"); +const response = await route.delete(); // response.body is the response body of calling // DELETE _db/_system/my-foxx-service // -- or -- -const response = await route.delete('users/admin') +const response = await route.delete("users/admin"); // response.body is the response body of calling // DELETE _db/_system/my-foxx-service/users/admin // -- or -- -const response = await route.delete('users/admin', {permanent: true}) +const response = await route.delete("users/admin", { permanent: true }); // response.body is the response body of calling // DELETE _db/_system/my-foxx-service/users/admin?permanent=true ``` @@ -292,12 +304,12 @@ Performs a HEAD request to the given URL and returns the server response. **Arguments** -* **path**: `string` (optional) +- **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. -* **qs**: `string` (optional) +- **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. @@ -306,7 +318,7 @@ Performs a HEAD request to the given URL and returns the server response. ```js const db = new Database(); -const route = db.route('my-foxx-service'); +const route = db.route("my-foxx-service"); const response = await route.head(); // response is the response object for // HEAD _db/_system/my-foxx-service @@ -320,47 +332,53 @@ Performs an arbitrary request to the given URL and returns the server response. **Arguments** -* **opts**: `Object` (optional) +- **opts**: `Object` (optional) An object with any of the following properties: - * **path**: `string` (optional) + - **path**: `string` (optional) The route-relative URL for the request. If omitted, the request will be made to the base URL of the route. - * **absolutePath**: `boolean` (Default: `false`) + - **absolutePath**: `boolean` (Default: `false`) Whether the _path_ is relative to the connection's base URL instead of the route. - * **body**: `string` (optional) + - **body**: `string` (optional) The response body. If _body_ is an object, it will be encoded as JSON. - * **qs**: `string` (optional) + - **qs**: `string` (optional) The query string for the request. If _qs_ is an object, it will be translated to a query string. - * **headers**: `Object` (optional) + - **headers**: `Object` (optional) An object containing additional HTTP headers to be sent with the request. - * **method**: `string` (Default: `"GET"`) + - **method**: `string` (Default: `"GET"`) HTTP method of this request. + - **timeout**: `number` (optional) + + A non-negative amount of milliseconds after which the request will be + aborted. Note that ArangoDB may continue processing the request even + after it has timed out. + **Examples** ```js const db = new Database(); -const route = db.route('my-foxx-service'); +const route = db.route("my-foxx-service"); const response = await route.request({ - path: 'hello-world', - method: 'POST', - body: {hello: 'world'}, - qs: {admin: true} + path: "hello-world", + method: "POST", + body: { hello: "world" }, + qs: { admin: true } }); // response.body is the response body of calling // POST _db/_system/my-foxx-service/hello-world?admin=true diff --git a/Documentation/Books/Drivers/Java/Reference/Setup.md b/Documentation/Books/Drivers/Java/Reference/Setup.md index 05ebc6c71a..b1eebc79a4 100644 --- a/Documentation/Books/Drivers/Java/Reference/Setup.md +++ b/Documentation/Books/Drivers/Java/Reference/Setup.md @@ -11,16 +11,16 @@ ArangoDB arangoDB = new ArangoDB.Builder().build(); The driver is configured with some default values: -property-key | description | default value --------------------------|-----------------------------------------|---------------- -arangodb.hosts | ArangoDB hosts | 127.0.0.1:8529 -arangodb.timeout | connect & request timeout (millisecond) | 0 -arangodb.user | Basic Authentication User | -arangodb.password | Basic Authentication Password | -arangodb.useSsl | use SSL connection | false -arangodb.chunksize | VelocyStream Chunk content-size (bytes) | 30000 -arangodb.connections.max | max number of connections | 1 VST, 20 HTTP -arangodb.protocol | used network protocol | VST +| property-key | description | default value | +| ------------------------ | --------------------------------------- | -------------- | +| arangodb.hosts | ArangoDB hosts | 127.0.0.1:8529 | +| arangodb.timeout | connect & request timeout (millisecond) | 0 | +| arangodb.user | Basic Authentication User | +| arangodb.password | Basic Authentication Password | +| arangodb.useSsl | use SSL connection | false | +| arangodb.chunksize | VelocyStream Chunk content-size (bytes) | 30000 | +| arangodb.connections.max | max number of connections | 1 VST, 20 HTTP | +| arangodb.protocol | used network protocol | VST | To customize the configuration the parameters can be changed in the code... @@ -178,8 +178,8 @@ ArangoDB arangoDB = new ArangoDB.Builder() ## Connection time to live -Since version 4.4 the driver supports setting a TTL for connections managed -by the internal connection pool. +Since version 4.4 the driver supports setting a TTL (time to life) in milliseconds +for connections managed by the internal connection pool. ```Java ArangoDB arango = new ArangoDB.Builder() diff --git a/Documentation/Books/Drivers/SUMMARY.md b/Documentation/Books/Drivers/SUMMARY.md index 0853b64736..61b4e2a786 100644 --- a/Documentation/Books/Drivers/SUMMARY.md +++ b/Documentation/Books/Drivers/SUMMARY.md @@ -57,6 +57,7 @@ * [Indexes](JS/Reference/Collection/Indexes.md) * [Simple Queries](JS/Reference/Collection/SimpleQueries.md) * [Bulk Import](JS/Reference/Collection/BulkImport.md) + * [AQL Helpers](JS/Reference/Aql.md) * [View Manipulation](JS/Reference/ViewManipulation.md) * [Cursor](JS/Reference/Cursor.md) * [Graph](JS/Reference/Graph/README.md) diff --git a/Documentation/Books/Drivers/SpringData/GettingStarted/README.md b/Documentation/Books/Drivers/SpringData/GettingStarted/README.md index 7bbc79dd05..5e9ae5101e 100644 --- a/Documentation/Books/Drivers/SpringData/GettingStarted/README.md +++ b/Documentation/Books/Drivers/SpringData/GettingStarted/README.md @@ -1,119 +1,119 @@ -# Spring Data ArangoDB - Getting Started - -## Supported versions - -| Spring Data ArangoDB | Spring Data | ArangoDB | -| -------------------- | ----------- | ----------- | -| 1.3.x | 1.13.x | 3.0\*, 3.1+ | -| 2.3.x | 2.0.x | 3.0\*, 3.1+ | -| 3.0.x | 2.0.x | 3.0\*, 3.1+ | - -Spring Data ArangoDB requires ArangoDB 3.0 or higher - which you can download [here](https://www.arangodb.com/download/) - and Java 8 or higher. - -**Note**: ArangoDB 3.0 does not support the default transport protocol -[VelocyStream](https://github.com/arangodb/velocystream). A manual switch to -HTTP is required. See chapter [configuration](#configuration). Also ArangoDB 3.0 -does not support geospatial queries. - -## Maven - -To use Spring Data ArangoDB in your project, your build automation tool needs to be configured to include and use the Spring Data ArangoDB dependency. Example with Maven: - -```xml - - com.arangodb - arangodb-spring-data - 3.1.0 - -``` - -There is a [demonstration app](https://github.com/arangodb/spring-data-demo), which contains common use cases and examples of how to use Spring Data ArangoDB's functionality. - -## Configuration - -You can use Java to configure your Spring Data environment as show below. Setting up the underlying driver (`ArangoDB.Builder`) with default configuration automatically loads a properties file `arangodb.properties`, if it exists in the classpath. - -```java -@Configuration -@EnableArangoRepositories(basePackages = { "com.company.mypackage" }) -public class MyConfiguration extends AbstractArangoConfiguration { - - @Override - public ArangoDB.Builder arango() { - return new ArangoDB.Builder(); - } - - @Override - public String database() { - // Name of the database to be used - return "example-database"; - } - -} -``` - -The driver is configured with some default values: - -| property-key | description | default value | -| ----------------- | ----------------------------------- | ------------- | -| arangodb.host | ArangoDB host | 127.0.0.1 | -| arangodb.port | ArangoDB port | 8529 | -| arangodb.timeout | socket connect timeout(millisecond) | 0 | -| arangodb.user | Basic Authentication User | -| arangodb.password | Basic Authentication Password | -| arangodb.useSsl | use SSL connection | false | - -To customize the configuration, the parameters can be changed in the Java code. - -```java -@Override -public ArangoDB.Builder arango() { - ArangoDB.Builder arango = new ArangoDB.Builder() - .host("127.0.0.1") - .port(8529) - .user("root"); - return arango; -} -``` - -In addition you can use the _arangodb.properties_ or a custom properties file to supply credentials to the driver. - -_Properties file_ - -``` -arangodb.hosts=127.0.0.1:8529 -arangodb.user=root -arangodb.password= -``` - -_Custom properties file_ - -```java -@Override -public ArangoDB.Builder arango() { - InputStream in = MyClass.class.getResourceAsStream("my.properties"); - ArangoDB.Builder arango = new ArangoDB.Builder() - .loadProperties(in); - return arango; -} -``` - -**Note**: When using ArangoDB 3.0 it is required to set the transport protocol to HTTP and fetch the dependency `org.apache.httpcomponents:httpclient`. - -```java -@Override -public ArangoDB.Builder arango() { - ArangoDB.Builder arango = new ArangoDB.Builder() - .useProtocol(Protocol.HTTP_JSON); - return arango; -} -``` - -```xml - - org.apache.httpcomponents - httpclient - 4.5.1 - -``` +# Spring Data ArangoDB - Getting Started + +## Supported versions + +| Spring Data ArangoDB | Spring Data | ArangoDB | +| -------------------- | ----------- | ----------- | +| 1.3.x | 1.13.x | 3.0\*, 3.1+ | +| 2.3.x | 2.0.x | 3.0\*, 3.1+ | +| 3.0.x | 2.0.x | 3.0\*, 3.1+ | + +Spring Data ArangoDB requires ArangoDB 3.0 or higher - which you can download [here](https://www.arangodb.com/download/) - and Java 8 or higher. + +**Note**: ArangoDB 3.0 does not support the default transport protocol +[VelocyStream](https://github.com/arangodb/velocystream). A manual switch to +HTTP is required. See chapter [configuration](#configuration). Also ArangoDB 3.0 +does not support geospatial queries. + +## Maven + +To use Spring Data ArangoDB in your project, your build automation tool needs to be configured to include and use the Spring Data ArangoDB dependency. Example with Maven: + +```xml + + com.arangodb + arangodb-spring-data + 3.1.0 + +``` + +There is a [demonstration app](https://github.com/arangodb/spring-data-demo), which contains common use cases and examples of how to use Spring Data ArangoDB's functionality. + +## Configuration + +You can use Java to configure your Spring Data environment as show below. Setting up the underlying driver (`ArangoDB.Builder`) with default configuration automatically loads a properties file `arangodb.properties`, if it exists in the classpath. + +```java +@Configuration +@EnableArangoRepositories(basePackages = { "com.company.mypackage" }) +public class MyConfiguration extends AbstractArangoConfiguration { + + @Override + public ArangoDB.Builder arango() { + return new ArangoDB.Builder(); + } + + @Override + public String database() { + // Name of the database to be used + return "example-database"; + } + +} +``` + +The driver is configured with some default values: + +| property-key | description | default value | +| ----------------- | ----------------------------------- | ------------- | +| arangodb.host | ArangoDB host | 127.0.0.1 | +| arangodb.port | ArangoDB port | 8529 | +| arangodb.timeout | socket connect timeout(millisecond) | 0 | +| arangodb.user | Basic Authentication User | +| arangodb.password | Basic Authentication Password | +| arangodb.useSsl | use SSL connection | false | + +To customize the configuration, the parameters can be changed in the Java code. + +```java +@Override +public ArangoDB.Builder arango() { + ArangoDB.Builder arango = new ArangoDB.Builder() + .host("127.0.0.1") + .port(8529) + .user("root"); + return arango; +} +``` + +In addition you can use the _arangodb.properties_ or a custom properties file to supply credentials to the driver. + +_Properties file_ + +``` +arangodb.hosts=127.0.0.1:8529 +arangodb.user=root +arangodb.password= +``` + +_Custom properties file_ + +```java +@Override +public ArangoDB.Builder arango() { + InputStream in = MyClass.class.getResourceAsStream("my.properties"); + ArangoDB.Builder arango = new ArangoDB.Builder() + .loadProperties(in); + return arango; +} +``` + +**Note**: When using ArangoDB 3.0 it is required to set the transport protocol to HTTP and fetch the dependency `org.apache.httpcomponents:httpclient`. + +```java +@Override +public ArangoDB.Builder arango() { + ArangoDB.Builder arango = new ArangoDB.Builder() + .useProtocol(Protocol.HTTP_JSON); + return arango; +} +``` + +```xml + + org.apache.httpcomponents + httpclient + 4.5.1 + +``` diff --git a/Documentation/Books/Drivers/SpringData/README.md b/Documentation/Books/Drivers/SpringData/README.md index 8c02250919..4ac5dacfa6 100644 --- a/Documentation/Books/Drivers/SpringData/README.md +++ b/Documentation/Books/Drivers/SpringData/README.md @@ -1,14 +1,14 @@ -# Spring Data ArangoDB - -- [Getting Started](GettingStarted/README.md) -- [Reference](Reference/README.md) -- [Migration](Migration/README.md) - -## Learn more - -- [ArangoDB](https://www.arangodb.com/) -- [Demo](https://github.com/arangodb/spring-data-demo) -- [JavaDoc 1.0.0](http://arangodb.github.io/spring-data/javadoc-1_0/index.html) -- [JavaDoc 2.0.0](http://arangodb.github.io/spring-data/javadoc-2_0/index.html) -- [Changelog](https://github.com/arangodb/spring-data/blob/master/ChangeLog.md#changelog) +# Spring Data ArangoDB + +- [Getting Started](GettingStarted/README.md) +- [Reference](Reference/README.md) +- [Migration](Migration/README.md) + +## Learn more + +- [ArangoDB](https://www.arangodb.com/) +- [Demo](https://github.com/arangodb/spring-data-demo) +- [JavaDoc 1.0.0](http://arangodb.github.io/spring-data/javadoc-1_0/index.html) +- [JavaDoc 2.0.0](http://arangodb.github.io/spring-data/javadoc-2_0/index.html) +- [Changelog](https://github.com/arangodb/spring-data/blob/master/ChangeLog.md#changelog) diff --git a/Documentation/Books/Drivers/SpringData/Reference/README.md b/Documentation/Books/Drivers/SpringData/Reference/README.md index 03306fb5bf..d612c3ef07 100644 --- a/Documentation/Books/Drivers/SpringData/Reference/README.md +++ b/Documentation/Books/Drivers/SpringData/Reference/README.md @@ -1,25 +1,25 @@ -# Spring Data ArangoDB - Reference - -- [Template](Template/README.md) - - [Queries](Template/Queries.md) - - [Document Manipulation](Template/DocumentManipulation.md) - - [Multiple Document Manipulation](Template/MultiDocumentManipulation.md) - - [Collection Manipulation](Template/CollectionManipulation.md) -- [Repositories](Repositories/README.md) - - [Queries](Repositories/Queries/README.md) - - [Derived queries](Repositories/Queries/DerivedQueries.md) - - [Query methods](Repositories/Queries/QueryMethods.md) - - [Named queries](Repositories/Queries/NamedQueries.md) - - [Document Manipulation](Repositories/DocumentManipulation.md) - - [Multiple Document Manipulation](Repositories/MultiDocumentManipulation.md) - - [Query by example](Repositories/QueryByExample.md) -- [Mapping](Mapping/README.md) - - [Document](Mapping/Document.md) - - [Edge](Mapping/Edge.md) - - [Reference](Mapping/Reference.md) - - [Relations](Mapping/Relations.md) - - [Indexes](Mapping/Indexes.md) - - [Converter](Mapping/Converter.md) - - [Events](Mapping/Events.md) - - [Auditing](Mapping/Auditing.md) +# Spring Data ArangoDB - Reference + +- [Template](Template/README.md) + - [Queries](Template/Queries.md) + - [Document Manipulation](Template/DocumentManipulation.md) + - [Multiple Document Manipulation](Template/MultiDocumentManipulation.md) + - [Collection Manipulation](Template/CollectionManipulation.md) +- [Repositories](Repositories/README.md) + - [Queries](Repositories/Queries/README.md) + - [Derived queries](Repositories/Queries/DerivedQueries.md) + - [Query methods](Repositories/Queries/QueryMethods.md) + - [Named queries](Repositories/Queries/NamedQueries.md) + - [Document Manipulation](Repositories/DocumentManipulation.md) + - [Multiple Document Manipulation](Repositories/MultiDocumentManipulation.md) + - [Query by example](Repositories/QueryByExample.md) +- [Mapping](Mapping/README.md) + - [Document](Mapping/Document.md) + - [Edge](Mapping/Edge.md) + - [Reference](Mapping/Reference.md) + - [Relations](Mapping/Relations.md) + - [Indexes](Mapping/Indexes.md) + - [Converter](Mapping/Converter.md) + - [Events](Mapping/Events.md) + - [Auditing](Mapping/Auditing.md)