mirror of https://gitee.com/bigwinds/arangodb
81 lines
5.1 KiB
Plaintext
81 lines
5.1 KiB
Plaintext
!CHAPTER Legacy compatibility mode for 2.8 services
|
|
|
|
ArangoDB 3 continues to support Foxx services written for ArangoDB 2.8 by running them in a special legacy compatibility mode that provides access to some of the modules and APIs no longer provided in 3.0 and beyond.
|
|
|
|
**Note:** Legacy compatibility mode is strictly intended as a temporary stop gap solution for supporting existing services while [upgrading to ArangoDB 3.0](Migrating2x.md) and should not be considered a permanent feature of ArangoDB or Foxx.
|
|
|
|
In order to mark an existing service as a legacy service, just make sure the following attribute is defined in the service manifest:
|
|
|
|
```json
|
|
"engines": {
|
|
"arangodb": "^2.8.0"
|
|
}
|
|
```
|
|
|
|
This [semantic version range](http://semver.org) denotes that the service is known to work with ArangoDB 2.8.0 and supports all newer versions of ArangoDB up to but not including 3.0.0 (nor any development version of 3.0.0 and greater).
|
|
|
|
Any similar version range the does not include 3.0.0 or greater will have the same effect (e.g. `^2.5.0` will also trigger the legacy compatibility mode, as will `1.2.3`, but `>=2.8.0` will not as it indicates compatibility with *all* versions greater or equal 2.8.0, not just those within the 2.x version range).
|
|
|
|
!SECTION Features supported in legacy compatibility mode
|
|
|
|
Legacy compatibility mode supports the old manifest format, specifically:
|
|
|
|
* `main` is ignored
|
|
* `controllers` will be mounted as in 2.8
|
|
* `exports` will be executed as in 2.8
|
|
|
|
Additionally the `isSystem` attribute will be ignored if present but does not result in a warning in legacy compatibility mode.
|
|
|
|
The Foxx console is available as the `console` pseudo-global variable (shadowing the global console object).
|
|
|
|
The service context is available as the `applicationContext` pseudo-global variable in the `controllers`, `exports`, `scripts` and `tests` as in 2.8. The following additional properties are available on the service context in legacy compatibility mode:
|
|
|
|
* `path()` is an alias for 3.x `fileName()` (using `path.join` to build file paths)
|
|
* `fileName()` behaves as in 2.x (using `fs.safeJoin` to build file paths)
|
|
* `foxxFileName()` is an alias for 2.x `fileName`
|
|
* `version` exposes the service manifest's `version` attribute
|
|
* `name` exposes the service manifest's `name` attribute
|
|
* `options` exposes the service's raw options
|
|
|
|
The following methods are removed on the service context in legacy compatibility mode:
|
|
|
|
* `use()` -- use `@arangodb/foxx/controller` instead
|
|
* `apiDocumentation()` -- use `controller.apiDocumentation()` instead
|
|
* `registerType()` -- not supported in legacy compatibility mode
|
|
|
|
The following modules that have been removed or replaced in 3.0.0 are available in legacy compatibility mode:
|
|
|
|
* `@arangodb/foxx/authentication`
|
|
* `@arangodb/foxx/console`
|
|
* `@arangodb/foxx/controller`
|
|
* `@arangodb/foxx/model`
|
|
* `@arangodb/foxx/query`
|
|
* `@arangodb/foxx/repository`
|
|
* `@arangodb/foxx/schema`
|
|
* `@arangodb/foxx/sessions`
|
|
* `@arangodb/foxx/template_middleware`
|
|
|
|
The `@arangodb/foxx` module also provides the same exports as in 2.8, namely:
|
|
|
|
* `Controller` from `@arangodb/foxx/controller`
|
|
* `createQuery` from `@arangodb/foxx/query`
|
|
* `Model` from `@arangodb/foxx/model`
|
|
* `Repository` from `@arangodb/foxx/repository`
|
|
* `toJSONSchema` from `@arangodb/foxx/schema`
|
|
* `getExports` and `requireApp` from `@arangodb/foxx/manager`
|
|
* `queues` from `@arangodb/foxx/queues`
|
|
|
|
!SECTION Incompatibilities with 2.8 and earlier
|
|
|
|
As built-in support for CoffeeScript was removed in 3.0 any service using CoffeeScript source files directly will not work in legacy compatibility mode. If you want to use an alternative language like CoffeeScript, make sure to pre-compile the raw source files to JavaScript and use the compiled JavaScript files in the service.
|
|
|
|
The `@arangodb/request` module when used with the `json` option previously overwrote the string in the `body` property of the response object of the response with the parsed JSON body. In 2.8 this was changed so the parsed JSON body is added as the `json` property of the response object in addition to overwriting the `body` property. In 3.0 and later (including legacy compatibility mode) the `body` property is no longer overwritten and must use the `json` property instead. Note that this only affects code using the `json` option when making the request.
|
|
|
|
The "magical comments" that could be used to supply documentation for controllers in ArangoDB 2.x are no longer supported and need to be replaced with calls to the controller's `description` and `summary` methods.
|
|
|
|
The utility module `lodash` is now available and should be used instead of `underscore`, but both modules will continue to be provided.
|
|
|
|
Additionally, any feature not supported in 2.8 will also not work in legacy compatibility mode. When migrating from an older version of ArangoDB it is a good idea to migrate to ArangoDB 2.8 first for an easier upgrade path.
|
|
|
|
**Note:** The `org/arangodb` module is aliased to the new name `@arangodb` in ArangoDB 3.0.0 and the `@arangodb` module was aliased to the old name `org/arangodb` in ArangoDB 2.8.0. Either one will work in 2.8 and 3.0 but outside of legacy services you should use `@arangodb` going forward.
|