Service Generator Tool¶
Command-Line Tool¶
The service generator command-line tool (csdl-to-war
) is delivered as a Windows batch file (csdl-to-war.bat
) and as a Mac/Linux shell script
(csdl-to-war.sh
) in the resources\server-odata-sdk\bin
folder within the
Visual Studio Code extension for mobile back-end tools (vsc-extension-mbt
).
-
Windows:
%USERPROFILE%\.vscode\extensions\sapse.vsc-extension-mbt-
X.Y.Z\resources\server-odata-sdk\bin\csdl-to-war.bat
-
Mac/Linux:
$HOME/.vscode/extensions/sapse.vsc-extension-mbt-
X.Y.Z/resources/server-odata-sdk/bin/csdl-to-war.sh
-
SAP Business Application Studio (in a
Terminal
window): locate withfind /tmp/vscode-unpacked -name csdl-to-war.sh -print
The command-line tool accepts an OData CSDL XML file as input (for OData version 2.0 or 4.0) and generates a Java EE web application project that can build a deployable WAR file (web application archive) for the implementation of an OData service.
Command-Line Tool Usage¶
The minimum required command-line tool parameters are an OData Common Schema Definition Language (CSDL) XML input file name and a target project folder name. The target project folder will be created if it does not already exist.
Mac/Linux shell example:
csdl-to-war.sh ~/test/example.csdl.xml ~/projects/myapp
Windows Command Prompt example:
csdl-to-war.bat c:\test\example.csdl.xml c:\projects\myapp
The above example command generates a Maven project for an OData service. The files generated in the project folder and subfolders include Java source files, associated XML files, and other files required for WAR file deployment.
The command also runs the mvn package
command, which compiles the Java sources and builds an
initial deployable WAR file.
To determine the generated WAR file name in the project's target
folder,
check the command output for a line like this:
Building war: c:\projects\myapp\target\odata-service-1.0.0.war
Caution
The initial generated WAR file will not have security enabled. Refer to the
-login
option
and Securing the Generated Service
for information on enabling security before deployment.
Command-Line Tool Options¶
Minimally, apart from the metadata file and project folder arguments,
one of -bind
, -h2db
,
-imdb
or -nodb
should be specified
to indicate where OData entity sets are stored. If none of those options
is specified, then -bind DefaultDB
is assumed.
Option: -application <name>
¶
Specifies the application name. The default is derived from the Java package name.
See also: Automatic Database Table Creation.
Option: -bind [<db-type>:]<db-name>
¶
Specifies a binding of JDBC DataSource
reference jdbc/DefaultDB
(in the generated Java code) to a
named database service instance.
Example:
-bind hana:testdb
The type of database (if indicated) must be one of: ase
(SAP ASE), derby
(Apache Derby), h2
(H2 database), hana
(SAP HANA), mssql
(Azure SQL or Microsoft SQL Server), oracle
(Oracle Database), pgsql
(PostgreSQL) or sqlany
(SAP SQL
Anywhere). Otherwise it defaults to hana
.
-
The named database service instance should already exist in the target runtime environment.
-
Apache Derby and H2 database are supported for local testing only. Note that the
-h2db
option can be used instead to obtain an Embedded H2 Database for testing. Using the-bind
option requires a non-embedded server database. -
For SAP Business Technology Platform Cloud Foundry environment (using the
-sap:cf
option), the supported database types arehana
,mssql
(Azure SQL) andpgsql
(PostgreSQL).-
HDI container based HANA databases are not supported, as they don't allow the tooling to change the database schema. In Cloud Foundry environment (including trial) a binding with Schema plan is therefore required.
The
-bind
option value should be formatted as"hana:*hana-service-instance-name*"
.Example:
In your space, create a service instance of type "SAP HANA Schemas & HDI Containers", plan schema.
cf create-service hana schema mbt-demo-hana
The
-bind
parameter in this example should be"hana:mbt-demo-hana"
. -
For Azure SQL (if available from hyperscaler), it may be necessary to define the connectivity/credentials information using a Cloud Foundry
User-Provided Service
definition in SAP Business Technology Platform Cockpit. In such cases, the-bind
option value should be formatted as"mssql:user-provided:*user-provided-service-name*"
and theCredentials
in the User-Provided Service Instance definition should be defined using property naming conventions of Apache Commons DBCP.Example:
{ "driverClassName": "com.microsoft.sqlserver.jdbc.SQLServerDriver", "url": "jdbc:sqlserver://<db-host>:<db-port>;databaseName=<db-name>", "username": "<db-username>", "password": "<db-password>" }
The db-host should look like "xxx.database.windows.net". To create an Azure SQL Database, please refer to: Quickstart: Create a single database in Azure SQL Database.
-
For PostgreSQL (if available from hyperscaler), it may be necessary to define the connectivity/credentials information using a Cloud Foundry
User-Provided Service
definition in SAP Business Technology Platform Cockpit.In such cases, the
-bind
option value should be formatted as"pgsql:user-provided:*user-provided-service-name*"
and theCredentials
in the User-Provided Service Instance definition should be defined using property naming conventions of Apache Commons DBCP.Example:
{ "driverClassName": "org.postgresql.Driver", "url": "jdbc:postgresql://<db-host>:<db-port>/<db-name>", "username": "<db-username>", "password": "<db-password>" }
The db-host should look like "xxx.rds.amazonaws.com". To create an AWS PostgreSQL DB, please refer to: Create and Connect to a PostgreSQL Database with Amazon RDS.
-
-
For SAP Business Technology Platform Neo environment (using the
-sap:neo
option), the supported database types arease
andhana
. The data source binding must be arranged after deployment by using the SAP Business Technology Platform Cockpit orneo
command-line tool. -
For local testing or on-premise production deployment, the supported database types are:
ase
,db2
,hana
,mssql
,pgsql
,oracle
,sqlany
. The relevant web application server documentation for configuration and binding of JDBC resources should be reviewed (see TomEE and Virgo). This usually requires installation of an appropriate JDBC driver into the application server'slib
folder.-
Additional privileges may need to be granted to the database user of
mssql
,db2
,oracle
.-
For
mssql
USE MASTER
GO
GRANT VIEW SERVER STATE TO <db-username>
-
For
db2
GRANT EXECUTE ON FUNCTION SYSPROC.MON_GET_TRANSACTION_LOG TO <db-username>
GRANT EXECUTE ON FUNCTION SYSPROC.MON_GET_UNIT_OF_WORK TO <db-username>
-
For
oracle
grant select on gv_$transaction to <db-username>;
grant select on gv_$locked_object to <db-username>;
grant select on gv_$session to <db-username>;
-
-
Option: -catalina:home <folder>
¶
Specify the home folder where the local Tomcat/TomEE application server software has been previously installed.
When using a Tomcat/TomEE server that has CATALINA_BASE
differing from CATALINA_HOME
,
specify the CATALINA_HOME
value.
Note
When using a Tomcat/TomEE server that has CATALINA_BASE
matching CATALINA_HOME
,
this option does not need to be specified.
When using the preinstalled Tomcat in SAP Business Application Studio,
this option defaults to /extbin
.
Option: -cf:debug
¶
Enable debugging of a Cloud-Foundry-deployed service via ssh
tunneling.
Once the service is deployed and running, use the Run > Start Debugging menu option in Visual Studio Code (or Debug > Start Debugging menu option in SAP Business Application Studio) to attach the Java debugger to the running service.
Note
The performance of Cloud Foundry debugging from a desktop computer system can be poor, due to network latency. Consider using SAP Business Application Studio which has better performance for debugging Cloud Foundry-deployed services.
Option: -cf:logs
¶
Capture Cloud Foundry runtime logs from the running OData service to the logs
project subfolder.
Option: -cf:push
¶
Push (deploy) the generated WAR file to Cloud Foundry, and start the service.
Option: -clean <subfolder>
¶
Delete the previous contents of the specified target project subfolder before generation.
Warning
If the -clean
option is used with the subfolder name src
, any prior customizations will be lost.
Option: -console:log
¶
Enables logging to the application server's console, bypassing the usual SLF4J configuration of the target application server.
Particularly for testing, this will simplify logging configuration and enable more readable log messages.
If the -console:log
option is not used, then you need to consult the documentation for your target application server in regard to the configuration of SLF4J logging. For SAP Business Technology Platform deployments, see Monitoring Generated Services.
Option: -cors:allow <host>
¶
Enables Spring CORS request for specific origin URL
Note
The -cors:allow <host>
option can only be used together with -spring:boot
option
Option: -csrf:token
¶
Enables CSRF token for generated OData Service
Option: -eclipse
¶
Generate files using the folder layout for an Eclipse Dynamic Web Project. Without this option, a Maven folder layout will be used.
See Integration with Eclipse IDE for more details.
Option: -h2db
¶
Specifies that an Embedded H2 database should be used for entity set storage. An embedded database is only suitable for testing, and only in a single-node application server deployment.
This option can be used for end-to-end validation of the generated OData service with a real SQL database, while deferring the final target database configuration.
If this option is used with the -eclipse
option, the generated Eclipse project will not automatically
include the H2 database JAR file, so please download it and add it to the project yourself.
If this option is used without the -eclipse
option, the generated Maven project (when built) will
fetch the H2 database JAR file from the Maven Central Repository.
Note
The contents of the embedded H2 database will survive restart of a local web application server.
Caution
The contents of the embedded H2 database will not survive redeployment in a Cloud Foundry environment.
Option: -http
¶
Configures the generated service to accept HTTP (unencrypted) requests even if the
-login
option is specified.
This may simplify local testing by enabling authentication/authorization testing without having to configure transport-level security in a local server.
Note
It is not recommended to use this option when generating a service for production deployment.
Option: -https
¶
Configures the generated service to require HTTPS (encrypted) requests even if the
-login
is not specified.
This may simplify local testing by enabling confidentiality testing without having to configure authentication or authorization in a local server.
Note
It is not recommended to use this option when generating a service for production deployment.
Option: -imdb
¶
Specifies that an embedded in-memory (non-SQL) database should be used for entity set storage. An embedded in-memory database is only suitable for testing, and only in a single-node application server deployment.
This option can be used for end-to-end validation of the generated OData service with a non-SQL database, while deferring the final target database selection/configuration.
Note
The -imdb
option cannot be used with a cache database service.
Caution
The contents of the embedded in-memory database will not survive restart of the web application server.
Option: -local:debug
¶
Debug the local application server after WAR file deployment.
Once the service is deployed and running, use the Run > Start Debugging menu option in Visual Studio Code (or Debug > Start Debugging menu option in SAP Business Application Studio) to attach the Java debugger to the running service.
Option: -local:deploy <file>
¶
Specify a WAR file name (e.g. test.war
) for local deployment.
For Apache Tomcat/TomEE, you can use the name ROOT.war
to deploy the service with an empty
context path.
Option: -local:run
¶
Run the local application server after WAR file deployment.
Option: -local:server <folder>
¶
Specify the base folder where the local application server software has been previously installed. See also TomEE and Virgo.
When using a Tomcat/TomEE server that has CATALINA_BASE
differing from CATALINA_HOME
,
specify the CATALINA_BASE
value, e.g. /home/user/.tomcat/default
for the preinstalled Apache Tomcat in SAP Business Application Studio.
Option: -login <method>
¶
Specifies the authentication method to be used for authenticating users and administrators of the OData service. The valid authentication methods are determined by the target application server. Please refer to the relevant application server documentation.
Example for the SAP Business Technology Platform Cloud Foundry Environment:
-login XSUAA
Example for the SAP Business Technology Platform Neo Environment, or local Apache TomEE or Eclipse Virgo:
-login BASIC
See Securing the Generated Service for more information.
Caution
If the -login
option is not specified, the service will be generated without authentication/authorization checks.
Option: -log:debug
¶
Enables DEBUG-level log messages when used together with the -console:log
option.
Option: -log:debug:<subsystem>
¶
Enables DEBUG-level log messages for a server subsystem when used together with the -console:log
option.
See also: Logging Subsystem Names.
Option: -log:trace
¶
Enables TRACE-level log messages when used together with the -console:log
option.
Option: -log:trace:<subsystem>
¶
Enables TRACE-level log messages for a server subsystem when used together with the -console:log
option.
See also: Logging Subsystem Names.
Option: -nodb
¶
Specifies that no database should be used for entity set storage.
In this case, all OData operations must be implemented using customization of handler classes.
Option: -overwrite
¶
Overwrite any previously-generated files, discarding their previous contents.
By default, if the csdl-to-war
tool is used to regenerate an existing project, it will skip regeneration of any files
that may be customized by the developer, so as not to lose any customizations.
Warning
If the -overwrite
option is used, any customized files will be overwritten and any prior customizations will be lost.
Option: -package <name>
¶
Specifies the base Java package name for the generated Java source files. If not specified, it is derived from the OData CSDL Schema Namespace (converted to lowercase).
Example:
-package com.example.myapp
Option: -sap:bas
¶
Specifies that the service generation is being invoked from SAP Business Application Studio.
This facilitates optimal interaction with the Terminal
.
Option: -sap:cf
¶
Specifies that the generated WAR file is intended for deployment in SAP Business Technology Platform - Cloud Foundry Environment.
Option: -sap:neo
¶
Specifies that the generated WAR file is intended for deployment in SAP Business Technology Platform - Neo Environment.
Option: -spring:boot
¶
Specifies that the generated project files should use Spring Boot conventions, rather than standard Java EE conventions.
Option: -test:mode
¶
Enables test mode, which results in automatic generation of test data in the resources/test-data
folder and automatic population of the database tables with this test data.
Note
Test data is only loaded into the SQL database the first time the server is started after deployment.
If the -test:mode
option is subsequently added to the command-line and the service is regenerated
and restarted, the test data will not be present. Increase the -version
number and regenerate/redeploy to obtain a database with test data.
Option: -version <number>
¶
Specifies the application version number. The default is 0.1.0
.
It is recommended to use Semantic Versioning, e.g. three numbers in the format MAJOR.MINOR.PATCH.
See also: Automatic Database Table Creation.
Option: -vs:code
¶
Specifies that the service generation is being invoked from Visual Studio Code.
This facilitates optimal interaction with the Terminal
.
Option: -workspace <folder>
¶
Specifies an IDE workspace folder, if it is different from the project folder. For example, the workspace folder for SAP Business Application Studio or Visual Studio Code.
Logging Subsystem Names¶
When logging is enabled using the -console:log
option, then -log:debug:<subsystem>
or
-log:trace:<subsystem>
can be selectively enabled for each subsystem. Available subsystem names are:
-
odata:cache
- to log cache refresh activity. -
odata:online
- to log outgoing OData requests. -
odata:server
- to log incoming OData requests. -
odata:sql
- to log SQL database interactions.
Additionally when using cache databases, logging of interactions with particular back-end subsystems can be selectively enabled using the following subsystem names:
-
odata:http:<destination-name>
- to log HTTP communication with a REST back-end for a particular named destination. -
odata:jco:<destination-name>
- to log JCo communication with an SAP back-end for a particular named destination. -
odata:jdbc:<data-source-name>
- to log JDBC communication with a SQL back-end for a particular named data source.
Using subsystem name odata:http
, odata:jco
or odata:jdbc
without a suffix will enable the logging
for all back-end systems of the respective type.
Log settings configured as above are propagated to the running OData service via the file
src/main/resources/system.properties
, with the properties XS_LOG_*
.
For a local (on-premise) server such as Apache TomEE (or Tomcat) which explodes the deployed
WAR file into a folder within the webapps
folder, the system.properties
file can be
manually edited to make logging configuration changes (followed by server restart) without
re-running the csdl-to-war
tool. This might be helpful for quick enablement of logging
in a production or test system where the OData service is already deployed.
Instead of editing the system.properties
file in the exploded WAR file folder, system-level environment variables XS_LOG_*
can also be set to true
(followed by server restart).