usage.md

Behaviour

This crate contains the functionality to parse SAP OData metadata at runtime.

When the parser feature is enabled, the parser::gen_src function is invoked by your application's build script and will generate two Rust modules: one for teh OData service document, and one for the service metadata.

For example, if you wish to consume the demo OData service GWSAMPLE_BASIC, then after parsing this service's metadata document, the following two modules will be generated:

• gwsample_basic.rs
• gwsample_basic_metadata.rs

Overview

Usage

1. In your browser, request the metadata for the OData service you wish to consume.

   It is assumed you already have a userid and password for this OData server and that you have the correct authorisation to invoke the required OData service.

2. Copy the entire XML document and store is as .xml in a file in the ./odata directory.

   Using the demo service GWSAMPLE_BASIC available from SAP's Dev Center server, display the service metadata then save it in file ./odata/gwsample_basic.xml.

3. In Cargo.toml add a [build-dependencies] for parse-sap-odata with the parser feature enabled:

   [build-dependencies]
   parse-sap-odata = { version = "1.2", features = ["parser"]}

   This feature is only required at build time.

   Your app will also require at least these [dependencies]:

   [dependencies]
   chrono = { version = "0.4", features = ["serde"] }
   parse-sap-odata = "1.2"
   parse-sap-atom-feed = "0.2"
   rust_decimal = { version = "1.30", features = ["serde-with-str"]}
   serde = { version = "1.0", features = ["derive"] }
   uuid = { version = "1.4", features = ["serde"] }

   • A dependency on parse-sap-odata (without the parser feature) allows you to consume the OData service metadata at runtime.
   • A dependency on parse-sap-atom-feed allows you to consume entity set data from the OData service.

4. In your app's build script (build.rs), invoke the generator for your desired OData service:

   use parse_sap_odata::parser::gen_src;
   
   fn main() {
       gen_src(
           "gwsample_basic", // metadata_file_name.  The ".xml" extension is added automatically
           "GWSAMPLE_BASIC"  // Value of the Namespace attribute of the <Schema> tag
       );
   }

   More information about Rust build scripts is available on the Rust documentation site.

5. When cargo detects a build.rs file in your project/crate, then this file is compiled and run before your application is compiled.

   Any output generated by build.rs will be written to a build directory whose name is stored in the environment variable OUT_DIR. This includes not only the generated Rust modules, but also any error messages that might be produced during the code generation steps.

   The default directory into which all build.rs output is written is target/[debug|release]/build/<your_package_name>/out, but you do not need to remember this specifically as the value can be obtained by calling the Rust macro env!("OUT_DIR").

   See Cargo Configuration for more details.

   All generated structs implement at least the following traits #[derive(Clone, Debug, Default)]

6. In the source code of your application, use the include!() macro to pull in the generated source code, then bring the generated module into scope with a use command:

   // Include the generated code
   include!(concat!(env!("OUT_DIR"), "/gwsample_basic.rs"));
   
   use gwsample_basic::*;
   
   // Use the BusinessPartner struct for example
   fn main() {
       let bp: BusinessPartner = Default::default();
       println!("{:#?}", bp);
   }