Enable configurable multi-lease acquisition per cycle in change feed processor

[stas-openai]

Description

This PR adds an opt-in configuration to Change Feed Processor (CFP) to allow acquiring more than one lease per lease-
acquire cycle, which can significantly improve rebalance/convergence time during scale-out and rolling deployments
(especially when hosts use ephemeral identities, e.g., Kubernetes rollouts).

Today, when multiple CFP workers exist, the default EqualPartitionsBalancingStrategy is intentionally conservative and
effectively attempts to take ownership of at most one lease per cycle. In large lease sets / high physical partition
counts, this can make rebalancing very gradual and can temporarily reduce processing throughput after deployments.

Changes included:

• Added ChangeFeedProcessorOptions#setMaxLeasesToAcquirePerCycle(int) (default 0 preserves legacy behavior).
• Updated EqualPartitionsBalancingStrategy to honor this option for expired/unowned lease acquisition
• Wired the option through both CFP implementations (EPK and PK/Incremental).
• Added unit tests covering strategy selection and ensuring the load balancer attempts all leases returned by the
  strategy.
• Updated CHANGELOG.

No Swagger regeneration involved.

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines (https://github.com/Azure/azure-sdk-for-java/blob/main/CONTRIBUTING.md).

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously
  merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR,
  see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[github-actions]

Thank you for your contribution @stas-openai! We will review the pull request and get back to you soon.

[Copilot]

Pull request overview

This PR introduces an opt-in configuration (setMaxLeasesToAcquirePerCycle) to the Change Feed Processor (CFP) that allows acquiring multiple leases per balancing cycle, improving rebalance/convergence time during scale-out and rolling deployments. The default value of 0 preserves the legacy conservative behavior of acquiring at most one lease per cycle when multiple workers exist.

Key Changes:

• Added maxLeasesToAcquirePerCycle field and accessors to ChangeFeedProcessorOptions with validation
• Updated EqualPartitionsBalancingStrategy to honor the new option for expired/unowned lease acquisition while keeping the legacy 1-lease-per-cycle behavior for stealing
• Wired the new option through both CFP implementations (EPK and PK/Incremental versions)

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
ChangeFeedProcessorOptions.java	Adds the new maxLeasesToAcquirePerCycle field with getter/setter and validation
IncrementalChangeFeedProcessorImpl.java	Passes the new option to the EqualPartitionsBalancingStrategy constructor
ChangeFeedProcessorImplBase.java	Passes the new option to the EqualPartitionsBalancingStrategy constructor
EqualPartitionsBalancingStrategy.java	Implements the multi-lease acquisition logic while maintaining legacy behavior for stealing
CHANGELOG.md	Documents the new feature in the changelog
PartitionLoadBalancerImplTests.java (pkversion)	Adds test verifying all leases returned by strategy are attempted
PartitionLoadBalancerImplTests.java (epkversion)	Adds test verifying all leases returned by strategy are attempted
EqualPartitionsBalancingStrategyTests.java	Adds comprehensive unit tests for the new multi-lease acquisition behavior

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

com.azure:azure-cosmos

[stas-openai]

@microsoft-github-policy-service agree company="OpenAI"

[kushagraThapar]

Thank you @stas-openai for your contributions to improve the Change feed processor logic, we will review this PR in the upcoming week (once everyone is back from vacation) and will get back to you with any comments, thanks again, your contributions are deeply appreciated!

[FabianMeiswinkel]

Looks good to me - Thanks for the contribution!

[tvaron3]

LGTM

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jeet1995]

/check-enforcer override

[jeet1995]

QueryValidationTests.queryPlanCacheSinglePartitionParameterizedQueriesCorrectness is failing which is unrelated to this change (follow up in a separate PR).

[stas-openai]

Woah, appreciate this! Thank you.