Merge pull request #6 from prakanth97/issue_6073

Support options for XML conversions and Refactor apis
ballerina-platform · Mar 26, 2024 · 165ff1f · 165ff1f
2 parents 7ed4f4b + c936da5
commit 165ff1f
Show file tree

Hide file tree

Showing 54 changed files with 1,916 additions and 583 deletions.
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ This library is the refined successor of the `ballerina/xmldata` module, incorpo
 
 ### Converting an XML value to a Record value
 
-To convert an XML value to a Record value, you can utilize the `fromXmlWithType` function provided by the library. The example below showcases the transformation of an XML value into a Record value.
+To convert an XML value to a Record value, you can utilize the `parseAsType` function provided by the library. The example below showcases the transformation of an XML value into a Record value.
 
 ```ballerina
 import ballerina/data.xmldata;
@@ -27,7 +27,7 @@ public function main() returns error? {
         <author>string</author>
     </book>`;
 
-    Book book = check xmldata:fromXmlWithType(data);
+    Book book = check xmldata:parseAsType(data);
     io:println(book);
 }
 
@@ -40,15 +40,15 @@ type Book record {
 
 ### Converting an external XML document to a Record value
 
-For transforming XML content from an external source into a Record value, the `fromXmlStringWithType` function can be used. This external source can be in the form of a string or a byte array/byte stream that houses the XML data. This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an XML value from an external source into a Record value.
+For transforming XML content from an external source into a Record value, the `parseString`, `parseBytes`, `parseStream` functions can be used. This external source can be in the form of a string or a byte array/byte-block-stream that houses the XML data. This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an XML value from an external source into a Record value.
 
 ```ballerina
 import ballerina/data.xmldata;
 import ballerina/io;
 
 public function main() returns error? {
     string xmlContent = check io:fileReadString("path/to/file.xml");
-    Book book = check xmldata:fromXmlStringWithType(xmlContent);
+    Book book = check xmldata:parseString(xmlContent);
     io:println(book);
 }
 
@@ -320,18 +320,22 @@ The translation into a Ballerina record would be:
 import ballerina/data.xmldata;
 
 @xmldata:Namespace {
+    prefix: "bk",
     uri: "http://example.com/book"
 }
 type Book record {|
     @xmldata:Namespace {
+        prefix: "bk",
         uri: "http://example.com/book"
     }
     int id;
     @xmldata:Namespace {
+        prefix: "bk",
         uri: "http://example.com/book"
     }
     string title;
     @xmldata:Namespace {
+        prefix: "bk",
         uri: "http://example.com/book"
     }
     string author;
@@ -445,7 +449,7 @@ The process of projecting XML data into a record supports various use cases, inc
 
 ## Issues and projects
 
-Issues and Projects tabs are disabled for this repository as this is part of the Ballerina standard library. To report bugs, request new features, start new discussions, view project boards, etc. please visit Ballerina standard library [parent repository](https://github.com/ballerina-platform/ballerina-standard-library).
+Issues and Projects tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc. please visit Ballerina library [parent repository](https://github.com/ballerina-platform/ballerina-library).
 
 This repository only contains the source code for the package.
 
@@ -494,6 +498,5 @@ All contributors are encouraged to read the [Ballerina code of conduct](https://
 
 ## Useful links
 
-[//]: # (* For more information go to the [`xmldata` library]&#40;https://lib.ballerina.io/ballerina/data.xmldata/latest&#41;.)
 * Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
-* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
+* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
diff --git a/ballerina/Ballerina.toml b/ballerina/Ballerina.toml
@@ -6,11 +6,11 @@ authors = ["Ballerina"]
 keywords = ["xml"]
 repository = "https://github.com/ballerina-platform/module-ballerina-data-xmldata"
 license = ["Apache-2.0"]
-distribution = "2201.8.5"
+distribution = "2201.8.6"
 export = ["data.xmldata"]
 
 [[platform.java17.dependency]]
-groupId = "io.ballerina.stdlib"
+groupId = "io.ballerina.lib"
 artifactId = "data-native"
 version = "0.1.0"
 path = "../native/build/libs/data.xmldata-native-0.1.0-SNAPSHOT.jar"
diff --git a/ballerina/CompilerPlugin.toml b/ballerina/CompilerPlugin.toml
@@ -1,6 +1,6 @@
 [plugin]
 id = "constraint-compiler-plugin"
-class = "io.ballerina.stdlib.data.xmldata.compiler.XmldataCompilerPlugin"
+class = "io.ballerina.lib.data.xmldata.compiler.XmldataCompilerPlugin"
 
 [[dependency]]
 path = "../compiler-plugin/build/libs/data.xmldata-compiler-plugin-0.1.0-SNAPSHOT.jar"
diff --git a/ballerina/Dependencies.toml b/ballerina/Dependencies.toml
@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.8.4"
+distribution-version = "2201.8.6"
 
 [[package]]
 org = "ballerina"

diff --git a/ballerina/Package.md b/ballerina/Package.md
@@ -1,6 +1,6 @@
-# Package overview
+# Ballerina XML Data Library
 
-This package is designed to facilitate the handling and manipulation of XML data within Ballerina applications. It streamlines the process of converting XML data to native Ballerina data types, enabling developers to work with XML content seamlessly and efficiently.
+The Ballerina XML Data Library is a comprehensive toolkit designed to facilitate the handling and manipulation of XML data within Ballerina applications. It streamlines the process of converting XML data to native Ballerina data types, enabling developers to work with XML content seamlessly and efficiently.
 
 This library is the refined successor of the `ballerina/xmldata` module, incorporating enhanced functionalities and improved performance.
 
@@ -14,10 +14,10 @@ This library is the refined successor of the `ballerina/xmldata` module, incorpo
 
 ### Converting an XML value to a Record value
 
-To convert an XML value to a Record value, you can utilize the `fromXmlWithType` function provided by the library. The example below showcases the transformation of an XML value into a Record value.
+To convert an XML value to a Record value, you can utilize the `parseAsType` function provided by the library. The example below showcases the transformation of an XML value into a Record value.
 
 ```ballerina
-import ballerina/data.xml as xmldata;
+import ballerina/data.xmldata;
 import ballerina/io;
 
 public function main() returns error? {
@@ -27,7 +27,7 @@ public function main() returns error? {
         <author>string</author>
     </book>`;
 
-    Book book = check xmldata:fromXmlWithType(data, Book);
+    Book book = check xmldata:parseAsType(data);
     io:println(book);
 }
 
@@ -40,15 +40,15 @@ type Book record {
 
 ### Converting an external XML document to a Record value
 
-For transforming XML content from an external source into a Record value, the `fromXmlStringWithType` function can be used. This external source can be in the form of a string or a byte array/byte stream that houses the XML data. This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an XML value from an external source into a Record value.
+For transforming XML content from an external source into a Record value, the `parseString`, `parseBytes`, `parseStream` functions can be used. This external source can be in the form of a string or a byte array/byte-block-stream that houses the XML data. This is commonly extracted from files or network sockets. The example below demonstrates the conversion of an XML value from an external source into a Record value.
 
 ```ballerina
-import ballerina/data.xml as xmldata;
+import ballerina/data.xmldata;
 import ballerina/io;
 
 public function main() returns error? {
     string xmlContent = check io:fileReadString("path/to/file.xml");
-    Book book = check xmldata:fromXmlStringWithType(xmlContent, Book);
+    Book book = check xmldata:parseString(xmlContent);
     io:println(book);
 }
 
@@ -69,7 +69,7 @@ Take for instance the following XML snippet:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>string</author>
 </book>
@@ -99,7 +99,7 @@ Consider the XML snippet:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title-name>string</title-name>
     <author-name>string</author-name>
 </book>
@@ -110,17 +110,17 @@ The canonical representation of the above XML as a Ballerina record is:
 ```ballerina
 type Book record {
     int id;
-    string 'title\-name';
-    string 'author\-name';
+    string title\-name;
+    string author\-name;
 };
 ```
 
-Observe how the XML element names `title-name` and `author-name` are represented using delimited identifiers in Ballerina; the `-` characters in the XML element names are escaped using the `\` character.
+Observe how the XML element names `title-name` and `author-name` are represented using delimited identifiers in Ballerina; the `-` characters in the XML element names are escaped using the `\ ` character.
 
 Moreover, the `@Name` annotation can be utilized to explicitly specify the name of the record field, providing control over the translation process:
 
 ```ballerina
-import ballerina/data.xml as xmldata;
+import ballerina/data.xmldata;
 
 type Book record {
     int id;
@@ -139,7 +139,7 @@ Consider the following XML snippet:
 
 ```xml
 <book lang="en" price="10.5">
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>string</author>
 </book>
@@ -157,7 +157,7 @@ type Book record {
 };
 ```
 
-Additionally the `@Attribute` annotation can be utilized to explicitly specify the name of the record field, providing control over the translation process.
+Additionally, the `@Attribute` annotation can be used to explicitly specify the field as an attribute providing control over the translation process. When element and attribute have same name in the same scope the priority is given to the element unless the expected record field has the `@Attribute` annotation.
 
 ### Child Elements
 
@@ -167,7 +167,7 @@ Examine the XML snippet below:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>
         <name>string</name>
@@ -216,7 +216,7 @@ Consider the XML snippet below:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>string</author>
     <available>true</available>
@@ -242,7 +242,7 @@ For instance, examine this XML:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title lang="en">string</title>
     <price>10.5</price>
 </book>
@@ -263,8 +263,6 @@ type Title record {
 };
 ```
 
-Modifications to the default behavior for converting numerical values can be achieved by providing `Options` mappings to the respective functions. This enables developers to choose specific data types and exert finer control over the conversion process.
-
 ### XML Namespaces
 
 XML namespaces are accommodated by the library, supporting the translation of XML data that contains namespace prefixes. However, the presence of XML namespaces is not mandatory, and the library is capable of processing XML data without namespaces. Should namespaces be present, they will be utilized to resolve the names of XML elements and attributes.
@@ -275,7 +273,7 @@ Examine the XML snippet below with default namespaces:
 
 ```xml
 <book xmlns="http://example.com/book">
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>string</author>
 </book>
@@ -294,7 +292,7 @@ type Book record {
 Incorporating namespace validation yields:
 
 ```ballerina
-import ballerina/data.xml as xmldata;
+import ballerina/data.xmldata;
 
 @xmldata:Namespace {
     uri: "http://example.com/book"
@@ -310,7 +308,7 @@ Here is the same XML snippet with a namespace prefix:
 
 ```xml
 <bk:book xmlns:bk="http://example.com/book">
-    <bk:id>0</bk:id>
+    <bk:id>601970</bk:id>
     <bk:title>string</bk:title>
     <bk:author>string</bk:author>
 </bk:book>
@@ -319,17 +317,67 @@ Here is the same XML snippet with a namespace prefix:
 The translation into a Ballerina record would be:
 
 ```ballerina
-import ballerina/data.xml as xmldata;
+import ballerina/data.xmldata;
+
+@xmldata:Namespace {
+    prefix: "bk",
+    uri: "http://example.com/book"
+}
+type Book record {|
+    @xmldata:Namespace {
+        prefix: "bk",
+        uri: "http://example.com/book"
+    }
+    int id;
+    @xmldata:Namespace {
+        prefix: "bk",
+        uri: "http://example.com/book"
+    }
+    string title;
+    @xmldata:Namespace {
+        prefix: "bk",
+        uri: "http://example.com/book"
+    }
+    string author;
+|};
+```
+
+Here is the same XML snippet with a namespace prefix:
+
+```xml
+<bk:book xmlns:bk="http://example.com/book" xmlns:au="http://example.com/author">
+    <bk:id>601970</bk:id>
+    <bk:title>string</bk:title>
+    <au:author>string</au:author>
+</bk:book>
+```
+
+The translation into a Ballerina record would be:
+
+```ballerina
+import ballerina/data.xmldata;
 
 @xmldata:Namespace {
     uri: "http://example.com/book",
     prefix: "bk"
 }
-type Book record {
+type Book record {|
+    @xmldata:Namespace {
+        uri: "http://example.com/book",
+        prefix: "bk"
+    }
     int id;
+    @xmldata:Namespace {
+        uri: "http://example.com/book",
+        prefix: "bk"
+    }
     string title;
+    @xmldata:Namespace {
+        uri: "http://example.com/author",
+        prefix: "au"
+    }
     string author;
-};
+|};
 ```
 
 In these examples, the XML namespaces are appropriately acknowledged, ensuring the integrity of the XML structure within the Ballerina records.
@@ -342,7 +390,7 @@ Take the following XML snippet as an example:
 
 ```xml
 <book>
-    <id>0</id>
+    <id>601970</id>
     <title>string</title>
     <author>string</author>
     <author>string</author>
@@ -368,7 +416,7 @@ Take this XML snippet as an example:
 
 ```xml
 <book lang="en">
-    <id>0</id>
+    <id>601970</id>
     <title lang="en">string</title>
     <author>string</author>
     <price>10.5</price>

diff --git a/ballerina/build.gradle b/ballerina/build.gradle
@@ -63,6 +63,7 @@ ballerina {
     packageOrganization = packageOrg
     module = packageName
     langVersion = ballerinaLangVersion
+    testCoverageParam = "--code-coverage --coverage-format=xml --includes=io.ballerina.lib.data.xmldata*:ballerina.*"
 }
 
 task updateTomlFiles {

diff --git a/ballerina/init.bal b/ballerina/init.bal
@@ -21,5 +21,5 @@ isolated function init() {
 }
 
 isolated function setModule() = @java:Method {
-    'class: "io.ballerina.stdlib.data.xmldata.utils.ModuleUtils"
+    'class: "io.ballerina.lib.data.xmldata.utils.ModuleUtils"
 } external;