Merge pull request #54 from Nuvindu/examples

ballerina/types.bal

@@ -33,13 +33,13 @@ public type ConnectionConfig record {|
 # + resultCode - The operation status of the response
 # + diagnosticMessage - The diagnostic message from the response
 # + operationType - The protocol operation type
-# + refferal - The referral URIs
+# + referral - The referral URIs
 public type LdapResponse record {|
-    string matchedDN;
+    string? matchedDN;
     Status resultCode;
-    string diagnosticMessage;
-    string operationType;
-    string[] refferal;
+    string? diagnosticMessage;
+    string? operationType;
+    string[]? referral;
 |};
 
 # LDAP search result type.

build.gradle

@@ -80,6 +80,7 @@ subprojects {
 task build {
     dependsOn(":ldap-native:build")
     dependsOn(":ldap-ballerina:build")
+    dependsOn(":ldap-examples:build")
 }
 
 def moduleVersion = project.version.replace("-SNAPSHOT", "")

examples/access-directory-server/.github/README.md

@@ -0,0 +1 @@
+../access-directory-server.md

examples/access-directory-server/Ballerina.toml

@@ -0,0 +1,8 @@
+[package]
+org = "ballerina"
+name = "access_directory_server"
+version = "0.1.0"
+distribution = "2201.8.0"
+
+[build-options]
+observabilityIncluded = true

examples/access-directory-server/access-directory-server.md

@@ -0,0 +1,30 @@
+# Employee Directory and Authentication System
+
+This example demonstrates using the Ballerina LDAP module to integrate with a directory server to manage employees in a corporation. The functionalities include authenticating with the directory server, adding a new user, searching for users, updating user details, and deleting a user.
+
+## Running an Example
+
+### 1. Start the directory server
+
+Run the following docker command to start the LDAP server.
+
+```sh
+cd resources
+docker compose up
+```
+
+### 2. Run the Ballerina project
+
+Execute the following commands to build an example from the source:
+
+* To build an example:
+
+    ```bash
+    bal build
+    ```
+
+* To run an example:
+
+    ```bash
+    bal run
+    ```

examples/access-directory-server/main.bal

@@ -0,0 +1,59 @@
+// Copyright (c) 2024 WSO2 LLC. (http://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you under the Apache License,
+// Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import ballerina/ldap;
+import ballerina/io;
+
+configurable string hostName = ?;
+configurable int port = ?;
+configurable string domainName = ?;
+configurable string password = ?;
+configurable string userDN = ?;
+
+type Employee record {
+    string[] objectClass;
+    string sn;
+};
+
+public function main() returns error? {
+    ldap:Client ldapClient = check new ({
+        hostName,
+        port,
+        domainName,
+        password
+    });
+
+    ldap:Entry employee = {
+        "objectClass": ["top", "person"],
+        "sn": "New User"
+    };
+
+    // Add a new employee to the directory server.
+    ldap:LdapResponse addResponse = check ldapClient->add("cn=User,dc=mycompany,dc=com", employee);
+    io:println(addResponse);
+
+    // Search for the employee.
+    Employee[] result = check ldapClient->searchWithType("dc=mycompany,dc=com", "(sn=New User)", ldap:SUB);
+    io:println(result);
+
+    // Update the employee.
+    ldap:LdapResponse updateResponse = check ldapClient->modify("cn=User,dc=mycompany,dc=com", { "sn": "Updated User" });
+    io:println(updateResponse);
+
+    // Delete the employee.
+    ldap:LdapResponse response = check ldapClient->delete("CN=User,dc=mycompany,dc=com");
+    io:println(response);
+}

examples/access-directory-server/resources/docker-compose.yml

@@ -0,0 +1,14 @@
+version: '3.7'
+
+services:
+    ldap_server:
+        image: osixia/openldap:latest
+        container_name: my-openldap-container
+        environment:
+            LDAP_ORGANISATION: "My Company"
+            LDAP_DOMAIN: "mycompany.com"
+            LDAP_ADMIN_PASSWORD: "adminpassword"
+        ports:
+            - "389:389"
+            - "636:636"
+        command: --copy-service

examples/build.gradle

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2024, WSO2 LLC. (http://www.wso2.com)
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import org.apache.tools.ant.taskdefs.condition.Os
+
+description = 'Ballerina - LDAP Examples'
+
+def ballerinaDist = "${project.rootDir}/target/ballerina-runtime"
+def examples = ["access-directory-server"]
+def graalvmFlag = ""
+
+tasks.register('clean') {
+    examples.forEach { example ->
+        delete "${projectDir}/${example}/target"
+        delete "${projectDir}/${example}/Dependencies.toml"
+    }
+}
+
+task testExamples {
+    if (project.hasProperty("balGraalVMTest")) {
+        graalvmFlag = "--graalvm"
+    }
+    doLast {
+        examples.each { example ->
+            try {
+                exec {
+                    workingDir project.projectDir
+                    if (Os.isFamily(Os.FAMILY_WINDOWS)) {
+                        commandLine 'cmd', '/c', "${ballerinaDist}/bin/bal.bat test ${graalvmFlag} ${example} && exit %%ERRORLEVEL%%"
+                    } else {
+                        commandLine 'sh', '-c', "${ballerinaDist}/bin/bal test ${graalvmFlag} ${example}"
+                    }
+                }
+            } catch (Exception e) {
+                println("Example '${example}' Build failed: " + e.message)
+                throw e
+            }
+        }
+    }
+}
+
+task buildExamples {
+    gradle.taskGraph.whenReady { graph ->
+        if (graph.hasTask(":ldap-examples:test")) {
+            buildExamples.enabled = false
+        } else {
+            testExamples.enabled = false
+        }
+    }
+    doLast {
+        examples.each { example ->
+            try {
+                exec {
+                    workingDir project.projectDir
+                    if (Os.isFamily(Os.FAMILY_WINDOWS)) {
+                        commandLine 'cmd', '/c', "${ballerinaDist}/bin/bal.bat build ${example} && exit %%ERRORLEVEL%%"
+                    } else {
+                        commandLine 'sh', '-c', "${ballerinaDist}/bin/bal build ${example}"
+                    }
+                }
+            } catch (Exception e) {
+                println("Example '${example}' Build failed: " + e.message)
+                throw e
+            }
+        }
+    }
+}
+
+task build {
+    dependsOn buildExamples
+
+}
+
+task test {
+    dependsOn testExamples
+}
+
+buildExamples.dependsOn ":ldap-ballerina:build"
+testExamples.dependsOn ":ldap-ballerina:build"

examples/library-managment-system/.github/README.md

@@ -0,0 +1 @@
+../library-managment-system.md

examples/library-managment-system/Ballerina.toml

@@ -0,0 +1,5 @@
+[package]
+org = "ballerina"
+name = "library_managment_system"
+version = "0.1.0"
+distribution = "2201.8.0"

examples/library-managment-system/library-managment-system.md

@@ -0,0 +1,30 @@
+# Employee Directory and Authentication System
+
+This example demonstrates using the Ballerina LDAP module to integrate with a directory server for managing users in a library system. The functionalities include adding new users, searching for books, and updating books.
+
+## Running an Example
+
+### 1. Start the directory server
+
+Run the following docker command to start the LDAP server.
+
+```sh
+cd resources
+docker-compose up
+```
+
+### 2. Run the Ballerina project
+
+Execute the following commands to build an example from the source:
+
+* To build an example:
+
+    ```bash
+    bal build
+    ```
+
+* To run an example:
+
+    ```bash
+    bal run
+    ```

examples/library-managment-system/main.bal

@@ -0,0 +1,57 @@
+// Copyright (c) 2024 WSO2 LLC. (http://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you under the Apache License,
+// Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import ballerina/ldap;
+import ballerina/io;
+
+configurable string hostName = ?;
+configurable int port = ?;
+configurable string domainName = ?;
+configurable string password = ?;
+
+public function main() returns error? {
+    ldap:Client ldapClient = check new ({
+        hostName,
+        port,
+        domainName,
+        password
+    });
+
+    ldap:Entry user = {
+        "objectClass": "inetOrgPerson",
+        "sn": "Alice",
+        "cn": "Alice",
+        "uid": "alice",
+        "displayName": "Alice Parker"
+    };
+
+    // Add a new user to the library system.
+    _ = check ldapClient->add("uid=alice,ou=Users,dc=library,dc=org", user);
+
+    // Search for a book.
+    ldap:SearchResult result = check ldapClient->search("ou=Books,dc=library,dc=org", "(cn=Dracula)", ldap:SUB);
+    io:println(result.entries);
+
+    ldap:Entry updateBook = {
+        "member": "uid=alice,ou=Users,dc=library,dc=org"
+    };
+
+    // Updates the book.
+    _ = check ldapClient->modify("cn=Dracula,ou=Books,dc=library,dc=org", updateBook);
+
+    result = check ldapClient->search("ou=Books,dc=library,dc=org", "(cn=Dracula)", ldap:SUB);
+    io:println(result.entries);
+}

examples/library-managment-system/resources/bootstrap.ldif

@@ -0,0 +1,43 @@
+dn: ou=Users,dc=library,dc=org
+changetype: add
+objectClass: organizationalUnit
+ou: Users
+
+dn: ou=Groups,dc=library,dc=org
+changetype: add
+objectClass: organizationalUnit
+ou: Groups
+
+dn: ou=Books,dc=library,dc=org
+changetype: add
+objectClass: organizationalUnit
+ou: Books
+
+dn: uid=john,ou=Users,dc=library,dc=org
+changetype: add
+objectClass: inetOrgPerson
+cn: John
+givenName: John
+sn: John
+uid: john
+displayName: John Doe
+mail: [email protected]
+userPassword: johndoe@123
+
+dn: cn=Users,ou=Groups,dc=library,dc=org
+changetype: add
+cn: Users
+objectClass: groupOfNames
+member: uid=john,ou=Users,dc=library,dc=org
+
+dn: cn=Books,ou=Groups,dc=library,dc=org
+changetype: add
+cn: Books
+objectClass: groupOfNames
+member: uid=john,ou=Users,dc=library,dc=org
+
+dn: cn=Dracula,ou=Books,dc=library,dc=org
+changetype: add
+objectClass: groupOfNames
+cn: Dracula
+member: uid=john,ou=Users,dc=library,dc=org

examples/library-managment-system/resources/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.7'
+
+services:
+  ldap_server:
+    image: osixia/openldap:latest
+    container_name: my-openldap-container
+    environment:
+      LDAP_ORGANISATION: "Library"
+      LDAP_DOMAIN: "library.org"
+      LDAP_ADMIN_PASSWORD: "adminpassword"
+    ports:
+      - "389:389"
+      - "636:636"
+    command: --copy-service
+    volumes:
+      - ./bootstrap.ldif:/container/service/slapd/assets/config/bootstrap/ldif/50-bootstrap.ldif