Skip to content

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 with find /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 are hana, mssql (Azure SQL) and pgsql (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 the Credentials 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 the Credentials 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 are ase and hana. The data source binding must be arranged after deployment by using the SAP Business Technology Platform Cockpit or neo 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's lib 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).


Last update: November 18, 2021