diff --git a/examples/raw-templates/Ballerina.toml b/examples/raw-templates/Ballerina.toml deleted file mode 100644 index f687b9038e..0000000000 --- a/examples/raw-templates/Ballerina.toml +++ /dev/null @@ -1,2 +0,0 @@ -[[platform.java17.dependency]] -path = "h2-2.1.210.jar" diff --git a/examples/raw-templates/raw_templates.bal b/examples/raw-templates/raw_templates.bal index 13dfc72336..8da0e2decc 100644 --- a/examples/raw-templates/raw_templates.bal +++ b/examples/raw-templates/raw_templates.bal @@ -1,31 +1,28 @@ import ballerina/io; -import ballerinax/java.jdbc; -import ballerina/sql; -jdbc:Client dbClient = check new (url = "jdbc:h2:file:./master/orderdb", - user = "test", password = "test"); +function col3() returns boolean { + return false; +} -public function main() returns error? { - // Uses a raw template to create the `Orders` table. - _ = check dbClient->execute(`CREATE TABLE IF NOT EXISTS Orders - (orderId INTEGER NOT NULL, customerId INTEGER, noOfItems INTEGER, - PRIMARY KEY (orderId))`); - // Uses a raw template to insert values to the `Orders` table. - _ = check dbClient->execute(`INSERT INTO Orders (orderId, customerId, noOfItems) - VALUES (1, 1, 20)`); - _ = check dbClient->execute(`INSERT INTO Orders (orderId, customerId, noOfItems) - VALUES (2, 1, 15)`); +type MyCSVRawTemplate object { + *object:RawTemplate; + public (string[] & readonly) strings; + public [int, int, boolean] insertions; +}; - stream strm = getOrders(1); - record {|record {} value;|}|sql:Error? v = strm.next(); - while (v is record {|record {} value;|}) { - record {} value = v.value; - io:println(value); - v = strm.next(); - } -} +public function main() { + int col1 = 5; + int col2 = 10; + + // Any value is allowed as an interpolation when defining a value of the `object:RawTemplate` type + // since it has `(any|error)[]` as the `insertions` type. + object:RawTemplate rawTemplate = `${col1}, fixed_string1, ${col2}, ${col3()}, fixed_string3`; + io:println(rawTemplate.strings); + io:println(rawTemplate.insertions); -function getOrders(int customerId) returns stream { - // In this raw template, the `customerId` variable is interpolated in the literal. - return dbClient->query(`SELECT * FROM orders WHERE customerId = ${customerId}`); + // With the custom `MyCSVRawTemplate ` raw template type, the compiler + // expects two integers followed by a boolean value as interpolations. + MyCSVRawTemplate myCSVRawTemplate = `fixed_string4, ${col1}, ${col2}, fixed_string_5, ${col3()}`; + io:println(myCSVRawTemplate.strings); + io:println(myCSVRawTemplate.insertions); } diff --git a/examples/raw-templates/raw_templates.md b/examples/raw-templates/raw_templates.md index 172dc6593f..f40101316f 100644 --- a/examples/raw-templates/raw_templates.md +++ b/examples/raw-templates/raw_templates.md @@ -1,22 +1,16 @@ # Raw templates -A raw template is a backtick template without a tag. Exposes result of phase 1 without further processing. Raw template is evaluated by evaluating each expression and creating an object containing. +Raw template expressions are backtick templates without a tag (such as `string` or `xml`). This is a sequence of characters interleaved with interpolations within a pair of backticks (in the form `${expression}`). The result of evaluating such a raw template is an `object:RawTemplate` object that has two fields `(readonly & string[]) strings` and `(any|error)[] insertions`. The `strings` array will have string literals in the backtick string broken at interpolations and the `insertions` array will have the resultant values of evaluating each interpolation. -- an `array` of the `strings` separated by insertions -- an `array` of the results of expression evaluation and an `array` of `strings` separating +If you want to control the type of the strings or the interpolations more precisely, you can define an object type that includes the `object:RawTemplate` type and override the relevant field(s) with narrower types. Then, the compiler will statically validate the values against the expected type(s). ->**Important use case:** SQL parameters. - ->**Note:** The relevant database driver JAR should be defined in the `Ballerina.toml` file as a dependency. This sample is based on an H2 database and the H2 database driver JAR need to be added to `Ballerina.toml` file. This sample is written using H2 2.1.210 and it is recommended to use H2 JAR with versions higher than 2.1.210. - -For a sample configuration and more information on the underlying module, see the [`jdbc` module](https://lib.ballerina.io/ballerinax/java.jdbc/latest/). +An important use case of custom raw templates is SQL parameterized queries. ::: code raw_templates.bal ::: -Add the relevant database driver JAR details to the `Ballerina.toml` file. - -::: code Ballerina.toml ::: - -Build and run the project using the `bal run` command. +::: out raw_templates.out ::: -::: out raw_templates.out ::: \ No newline at end of file +## Related links +- [Backtick templates](https://ballerina.io/learn/by-example/backtick-templates/) +- [Object type inclusion](https://ballerina.io/learn/by-example/object-type-inclusion/) +- [Database Access - Simple query](https://ballerina.io/learn/by-example/mysql-query-operation/) diff --git a/examples/raw-templates/raw_templates.out b/examples/raw-templates/raw_templates.out index f0b75ca539..6e88292894 100644 --- a/examples/raw-templates/raw_templates.out +++ b/examples/raw-templates/raw_templates.out @@ -1,3 +1,5 @@ $ bal run -{"ORDERID":1,"CUSTOMERID":1,"NOOFITEMS":20} -{"ORDERID":2,"CUSTOMERID":1,"NOOFITEMS":15} +["",", fixed_string1, ",", ",", fixed_string3"] +[5,10,false] +["fixed_string4, ",", ",", fixed_string_5, ",""] +[5,10,false]