Add selective attribute retrieval support

[TharmiganK]

Description

This PR adds support for selective attribute retrieval in the LDAP client's getEntry, search, and searchWithType methods, addressing the need to retrieve specific attributes from LDAP directory entries rather than always fetching all attributes. This improvement is particularly beneficial for Active Directory use cases where directory entries may contain numerous attributes and retrieving only the required ones improves performance and reduces network overhead.

Fixes ballerina-platform/ballerina-library#8563

Changes Made:

• getEntry() method: Added optional attributes parameter to allow specifying which attributes to retrieve. When not provided, attributes are automatically extracted from the target record type definition. Supports both explicit attribute specification and type-based introspection.

• search() method: Added optional attributes parameter to enable selective attribute retrieval in search operations. When not provided or set to nil/empty array, all user attributes are retrieved.

• searchWithType() method: Added optional attributes parameter to allow explicit attribute specification. When not provided, the method automatically extracts attribute names from the target record type definition, providing type-safe selective attribute retrieval. Explicit attributes take precedence over type-inferred attributes when both are applicable.

Implementation Details:

• Explicit attributes parameter takes precedence when provided (overrides type introspection)
• Type introspection automatically extracts field names from record types when attributes not specified
• Record types with rest fields fall back to retrieving all attributes (since exact attributes cannot be determined)
• Added Utils.getAttributesFromEntryType() helper method for attribute extraction from record types
• Java native implementation updated in Client.java to handle attribute arrays and call appropriate LDAP SDK methods

All parameters are optional and default to nil/(), ensuring full backward compatibility with existing code.

One line release note:

• Add support for selective attribute retrieval in LDAP client's get and search methods with automatic attribute extraction from record types

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

The following test cases have been added to verify the changes:

getEntry() method tests (7 tests):

• testGetEntryWithSelectiveAttributes - Validates retrieving specific attributes ["sn", "cn"] using getEntry() with attributes parameter
• testGetEntryWithAllAttributes - Validates default behavior (all attributes) when no attributes parameter is provided
• testGetEntryWithSingleAttribute - Tests retrieving a single attribute ["sn"] only
• testGetEntryWithInvalidAttribute - Tests graceful handling of invalid/non-existent attribute names
• testGetEntryWithTypeIntrospection - Validates automatic attribute extraction from UserConfig type when attributes not provided
• testGetEntryWithRecordHavingRestField - Validates that Entry type with rest field retrieves all attributes
• testGetEntryExplicitAttributesOverrideType - Validates explicit ["cn"] overrides type-inferred attributes from UserConfig

search() method tests (3 tests):

• testSearchWithSelectiveAttributes - Tests selective attribute retrieval ["sn", "cn"] in search() method
• testSearchWithAllAttributes - Tests default behavior (all attributes) in search() method
• testSearchWithEmptyAttributesArray - Tests empty array [] behaves like nil (retrieves all attributes)

searchWithType() method tests (3 tests):

• testSearchWithTypeAutoAttributeExtraction - Validates automatic attribute extraction from UserConfig type
• testSearchWithTypeValidateAllFields - Validates that all record type fields are correctly populated
• testSearchWithTypeExplicitAttributes - Validates explicit ["sn", "cn"] parameter overrides type-inferred attributes

Test Configuration:

• Ballerina Version: Swan Lake Update 12 (2201.12.x)
• Operating System: Linux
• Java SDK: OpenJDK 21

Checklist:

• Updated the spec
• Update the changelog
• Check for breaking change in BIR level - Could not be able to produce a BIR level change. So the change should be safe

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines?
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (e913a69) to head (9e0c13d).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master       #97      +/-   ##
===========================================
+ Coverage   96.66%   100.00%   +3.33%     
===========================================
  Files           2         2              
  Lines          30        30              
  Branches       10        10              
===========================================
+ Hits           29        30       +1     
+ Misses          1         0       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR enhances the LDAP client library with selective attribute retrieval capabilities across getEntry(), search(), and searchWithType() methods. This feature is particularly beneficial for Active Directory scenarios where directory entries contain numerous attributes and retrieving only required ones improves performance and reduces network overhead.

Changes:

• Added optional attributes parameter to getEntry() and search() methods for explicit selective attribute retrieval
• Enhanced searchWithType() to automatically extract attribute names from the target record type for type-safe selective retrieval
• Updated specification, changelog, and comprehensive test coverage

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
native/src/main/java/io/ballerina/lib/ldap/Utils.java	Added getAttributesFromEntriesType() method to extract attribute names from record type for automatic selective retrieval
native/src/main/java/io/ballerina/lib/ldap/Client.java	Updated getEntry(), search(), and searchWithType() to support selective attribute retrieval with proper null handling
ballerina/client.bal	Updated method signatures with optional attributes parameters and enhanced documentation
docs/spec/spec.md	Added comprehensive documentation for selective attribute retrieval feature across all affected methods
changelog.md	Added detailed changelog entries documenting the new feature
ballerina/tests/test.bal	Added 8 comprehensive test cases covering selective and all-attribute retrieval scenarios
ballerina/Ballerina.toml	Version bump to 1.3.1
ballerina/Dependencies.toml	Updated crypto dependency version and package version

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Nuvindu]

LGTM