March 2021
Welcome to the release of CAP. Find the most noteworthy news and changes in the following sections.Important Changes
CDS Compiler v2
CDS compiler version 2 (cv2) brings numerous improvements, which allow us to greatly streamline model processing and memory consumption going forward. All projects are recommended to upgrade as soon as possible, as the former version will only receive critical fixes after v2 is released. Find a guide on how to upgrade at CDS > Compiler v2.
Consolidated Node.js APIs
In the course of finishing compiler v2 we also consolidated a few Node.js APIs for model processing. Those changes mostly affect private, undocumented APIs, so you should not encounter any adoption efforts if you sticked to the public APIs, Nevertheless find some things mentioned in the following Node.js section.
Capire Docs & Samples
New and Overhauled docs for cds.compile
and cds.reflect
APIs
In the course of finishing compiler v2, we also consolidated the APIs for parsing, compiling, and reflecting models. In response to feedback received, we also returned these docs back to the Node.js API reference docs. Find the updated docs at Node.js > cds.compile and > cds.reflect.
New and Overhauled docs for cds.ql
APIs
We filled in many gaps in the Node.js cds.ql
reference docs. This also includes docs for the newly introduced tagged template string support. Find the updated docs at Node.js > cds.ql.
Guide re Publishing to OpenAPI
Moved the formerly hidden information on CAP support for OpenAPI to a top-level guide at Advanced > OpenAPI.
Guided Tour in cap/samples for Java
Take a guided tour in VS Code through our CAP Java samples and learn which CAP features are showcased by the different parts of the repository. Just install the CodeTour extension for VS Code.
Command Line / Toolkit
Live Reload with cds watch
In addition to restarting the server, cds watch
now automatically reloads your browser page after a change in a CAP project. You can stay focused in the editor while the effect of your change is visible immediately.
Adding SAP HANA Support with cds add hana
To prepare your project for SAP HANA, it is no longer necessary to modify your package.json. Instead, use cds add hana
to enhance your project configuration. See section Enhance Project Configuration for SAP HANA Cloud for more details.
Adding Cloud Foundry Native Deployment Support with cds add cf-manifest
As an alternative to MTA-based deployment, you can now easily create the manifest files with cds add cf-manifest
. This replaces the CDS build base approach, but is currently limited to single tenant applications. See section Deploy Using Manifest Files for more details.
Linting CDS Models with cds lint
beta
You can now use CDS Linter in your CAP project. See section Setup & Usage for more details how to enable and use it.
CDS Editors & Tools
The following features are available for all editors based on our language server implementation for CDS in SAP Business Application Studio, Visual Studio Code, and Eclipse. The plugins are available for download for Visual Studio Code at Visual Studio Marketplace and for Eclipse at SAP Development Tools.
Support for CDS Compiler v2
The latest version of the editor supports both, CDS compiler v1 and v2.
As before, the editor picks up the compiler installed in the workspace if available, else from a globally installed @sap/cds-dk
if available, else the embedded compiler, which now is CDS compiler v2.
Support for Semantic Highlighting
Semantic highlighting adds additional coloring/styling on top of the existing syntax highlighting. It visualizes semantic information like the type of identifiers, for example, (namespace/context/service, entity/view/aspect, type, element, annotation) or modifiers, for example, if types are definitions, built-in, delivered with @sap/cds/common.cds
, or abstract.
Standard syntax highlighting:
Additional semantic highlighting (see following example configuration):
Semantic highlighting is disabled by default. It requires extra calculation. For large models, there might be a noticeable delay between typing and updated highlighting.
Enablement
Enable semantic highlighting for CDS source files:
- Open Settings.
- Restrict selection to
semantic
. - Ensure that
Editor > Semantic Highlighting: Enabled
is set totrue
orconfiguredByTheme
. - Enable specific CDS semantic highlighting by setting
Cds > Semantic Highlighting: Enabled
totrue
.
Configuration
Configure colors and font styles based on the additional information from semantic highlighting.
- Open Settings.
- Navigate to
Editor: Semantic Token Color Customizations
. - Follow the link
Edit in settings.json
.
TIP
If you have Editor > Semantic Highlighting: Enabled
set to configuredByTheme
, add the theme name as an extra node between editor.semanticTokenColorCustomizations
and rules
(use code completion support)
The underlying language server protocol defines a set of predefined constants for token types and modifiers. As there are no specific constants for entity-relation languages, use the following mapping:
Token types:
namespace/context/service
→"namespace"
entity/view/aspect
→"class"
element
→"property"
type
→"type"
annotation
→"typeParameter"
Modifiers:
- built-in types →
"*.static"
- types from
@sap/cds/common.cds
→"*.defaultLibrary"
- aspects/abstract entities →
"*.abstract"
- definitions →
"*.definition"
TIP
Some themes in the Marketplace already contain specific configuration for semantic highlighting information.
CDS Language & Compiler
Compiler v2 — A Major Step Forward
CDS compiler version 2 (cv2) brings numerous improvements, many of which behind the scenes, which allow us to greatly streamline model processing and memory consumption going forward.
We recommend upgrading as soon as possible, as the former version will only receive critical fixes after v2 is released.
Minimized Breaking Changes — Even though this is a major version update – actually the first in life for @sap/cds-compiler – we tried to minimize breaking changes to a minimum. Most changes should not affect you at all, as long as you sticked to public and documented APIs (which you always should!).
Nevertheless, we prepared a dedicated guide for you to ease upgrading at:
CDS > Upgrade to Compiler v2.
Fixed Temporal Data
Former releases had a major glitch, which made it literaly impossible to send as-of-now queries or time-travel queries; for example:
GET .../Books(ID=201) HTTP/1.1
... would be rejected by OData libs, asking you to specify the full compound key.
Reason for that was, we erroneously included validFrom
in the OData <PrimaryKey>
. But frequently you would not know the value of that. We've fixed that now by omitting validFrom
from the OData primary key, as documented in a corrected version of the Temporal Data guide.
Consequences:
- As-of-now and time-travel queries work now as they were thought to. In the unlikely case, you did own workarounds, adding
validFrom
to single-object requests as above, you'd need to remove that. - Time-series queries with
sap-valid-from/sap-valid-to
also continue to work, even though result sets may now have entries with duplicate keys, that is, sameID
with differentvalidFrom
→ OData specification disallows that, but most OData libs fortunately don't care.
In case you encounter issues, for example, using an OData library, that rejects duplicate keys, reach out to us. We do have a solution also for that, which we would share then.
Compiler Messages Explained
We added a guide to explain selected cds
compiler messages, with information how to fix them to CDS > Compiler Messages.
Scoped Definitions
You can now define an object Foo.Bar
even if there is a definition for Foo
that is not a context or a service. You can, for example, define entities Orders
and Orders.Items
.
Learn more in the CDS Definition Language Reference.
The compiler internally makes use of this, for example, for localized entities: the text entity for entity Foo
is now called Foo.texts
. See section Fix refs to Foo_texts for more details.
Simplified Syntax for Annotated OData Annotations
Almost all annotation assignments can now be written without delimited identifiers: the use of .
, @
, and #
is fine for annotation names, property names of structures, and in references used as annotation values. For example, you can now write:
@Common.Text: {
@UI.TextArrangement: #TextOnly,
...
}
Sorting SQL Statements
The compiler now sorts SQL statements in the order in which they have to be executed for deploying the model to a database.
Node.js Runtime
Major Version Update to v5
As a consequence of the major version upgrade of @sap/cds-compiler^2
, also the Node.js runtime package @sap/cds
received a major version update to v5 → npm update your project to receive that.
No Breaking Changes
- There are no breaking changes to public APIs.
Noteworthy Changes
You should take notice of the following changes, which may affect your project:
- Dropped support for Node.js v10 --› v12 is minimum required now; recommended: v14 (LTS).
@sap/cds^5
requires@sap/cds-compiler^2
.cds.features.snapi = false
has been removed nowreq.timestamp
now returnsDate
objects, before it was aDate.now()
integer.
Although a public API, this change should be transparent for custom code.
Changes to Implementation
Following are changes to undocumented internal implementations, hence shouldn't affect CAP-based projects. Nevertheless, they're listed here for your reference:
- Removed methods
cds.compile.to.hdbtabledata
and.to.hdbmigration
. - Removed support for deprecated
@sap/xssec^2
--› usexssec^3
instead.
Tagged Template Strings for CDL
, CQL
, and CXL
We enhanced cds.parse
with new functions CDL
, CQL
, and CXL
accepting tagged template string literals. These are made available by the cds
facade as global functions, so you can easily use them as follows:
Tagged Template Strings with cds.ql
We also extended this support of tagged template strings to cds.ql
, as well as the Querying API functions of cds.Service
, with great effects on readability of code:
Performance Optimizations
@sap/cds
version 5 comes with several performance optimizations, many happened on a detailed implementation level. A few stand out however, and should be understood and taken into account by you:
Outbound payload validation switched off by default — In former releases the OData library always validated outgoing data; we switched that off now by default, as it comes with a high overhead and minimal value. You can re-enable it with
cds.env.odata.skipValidation = false
, for example for debugging reasons during development.Locale-specific sorting is skipped if there is no order by clause if there's no
String
column in it. Background: on SAP HANA this requires using the SAP HANA-specificwith parameters
clause, which has certain performance issues today.Streamlined authorization checks — Authorization for draft-enabled entities via
@restrict
was streamlined in accordance to the Authorization cookbook. First, grants of@restrict
are now restricted to CRUD (former redundant support for NEW and EDIT got removed). Second, redundant checks for bound actions are skipped, as they are anyways covered by the "locked by user" check.
Tailored Search with @cds.search
Node.js runtime now supports entity-level annotation @cds.search
to control deep generic search capability: Just annotate those elements, which shall be searched, and which not. All elements typed String
are searchable by default. Reduce these to increase performance.
Learn more in Cookbook > Generic Providers > Search Capabilities.
Note 1: In previous versions, we also included all
UUID
-typed elements by default, which we don't do anymore, due to performance reasons.
Note 2: Deep search still remains unsupported at the moment. Hence, path expressions in
@cds.search
are currently ignored.
Note 3: The element-level annotation
@Search.defaultSearchElement
is deprecated and will be removed in future versions. In the meantime,@cds.search
supersedes those, that is, if both are defined,@cds.search
wins.
Scalable Multitenant Messaging Using Webhooks beta
The Node.js runtime now ships with full out-of-the-box support for outbound and inbound messaging in multitenant SaaS scenarios. To ensure scalability we avoid open connections.
On the inbound side, we use webhooks to achieve that. Instead of transferring incoming messages through a permanent AMQP connection, they are delivered through HTTP using webhooks.
Learn more in Node.js > Messaging reference docs.
Java SDK
Important Changes ❗️
Virtual Elements
The behaviour of virtual elements has been changed to align it with how virtual elements are treated by the CDS Compiler v2. Although virtual elements are present in the domain model, they are no longer reflected in the generated database view. They still can be used in queries but with some limitations. They are:
- ignored on the select list, order by and group by
- not returned by select *
- ignored in input data of insert, update, and upsert
- rejected when used in filters, where or having
Support for H2 Database
With CDS Compiler v2, SQL statements are sorted properly so that a generated schema.sql
file can be deployed without post-processing. This allows to smoothly use H2 for local development and Continuous Integration. In order to generate SQL for H2, the sql dialect in .cdsrc.json has to be set to "plain":
"sql": {
"dialect": "plain"
}
Compiler v2 Support
The new @sap/cds-dk@^4
including @sap/cds-compiler@^2
is supported by the CAP Java SDK. This release also maintains compatibility with @sap/cds-dk@^3
including @sap/cds-compiler@^1
.
See section Upgrade to Compiler v2 for more details on the new compiler version and how it might affect your CAP Java project.
To use the new major version, you can update the @sap/cds-dk
version in your pom.xml
file, by setting the version
property of the cds:install-cdsdk
Maven goal.
Learn more about the cds:install-cdsdk
Maven goal.
Indicating Errors
The method throwIfError()
has been added to the Messages interface. It simplifies throwing a ServiceException and aborting the request after collecting multiple error messages.
Learn more about throwIfError()
and Messages.
Updated Java Samples
We have revamped our CAP Java Sample application. Some highlights include:
- Updated SAP Fiori UIs and improved Vue.js UI
- Added ability to add reviews to books
- Showcased instance-based authorizations
You can now also take a guided tour in VS Code through our CAP Java sample application and learn which CAP features are showcased by the different parts of the repository. Just install the CodeTour extension for VS Code.
Support for Simple Projections in Remote Services beta
You can now use CQN queries targeting your own projections on entities from external services with Remote Services. Currently only simple projections are supported, which reduce the list of selected items without renaming them:
entity SimpleBooks as projection on Books { ID, title, descr };
entity SimpleAuthors as projection on Authors excluding { placeOfBirth, placeOfDeath };
Learn more about Remote Services.
Services Accepting CQN Queries
The interfaces ApplicationService
, PersistenceService
, and RemoteService
now all implement the common interface CqnService
, which will gradually replace the former CdsService
interface. Consider adapting your code to use CqnService
over CdsService
, as it captures the intent better and avoids name clashes with CdsService
from the Model Reflection API.
Learn more about these three service types and their differences.
Compositions of Aspects
Using compositions of aspects is now fully supported in CAP Java. Also accessor and model interfaces are generated accordingly. For example:
entity Orders {
key ID: Integer; //...
Items : Composition of many OrderItems;
}
aspect OrderItems {
key pos : Integer;
product : Association to Products;
quantity : Integer;
}
❗ Warning
Upgrading from CDS Compiler v1 to v2 will cause accessor and model interfaces for compositions of aspects to change. It is therefore recommended to firstly upgrade to CDS Compiler v2 before starting to use compositions of aspects.
Databases beta
Support for Schema Evolution on SAP HANA Cloud has been added as beta feature for non-productive usage and trial.