PageIterator.cs

// ------------------------------------------------------------------------------
// Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information.
// ------------------------------------------------------------------------------

namespaceMicrosoft.Graph
{
usingSystem;
usingSystem.Collections.Generic;
usingSystem.Threading;
usingSystem.Threading.Tasks;
usingMicrosoft.Kiota.Abstractions;
usingMicrosoft.Kiota.Abstractions.Serialization;
#if NET5_0_OR_GREATER
usingSystem.Diagnostics.CodeAnalysis;
#endif

/*
 Spec https://github.com/microsoftgraph/msgraph-sdk-design/blob/main/tasks/PageIteratorTask.md
 */

/// <summary>
/// Use PageIterator&lt;TEntity&gt; to automatically page through result sets across multiple calls 
/// and process each item in the result set.
/// </summary>
/// <typeparam name="TEntity">The Microsoft Graph entity type returned in the result set.</typeparam>
/// <typeparam name="TCollectionPage">The Microsoft Graph collection response type returned in the collection response.</typeparam>
#if NET5_0_OR_GREATER
publicclassPageIterator<TEntity,[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicProperties)]TCollectionPage>whereTCollectionPage:IParsable,IAdditionalDataHolder,new()
#else
 public classPageIterator<TEntity,TCollectionPage>whereTCollectionPage:IParsable,IAdditionalDataHolder,new()
#endif
{
privateIRequestAdapter_requestAdapter;
privateTCollectionPage_currentPage;
privateQueue<TEntity>_pageItemQueue;
privateFunc<TEntity,bool>_processPageItemCallback;
privateFunc<TEntity,Task<bool>>_asyncProcessPageItemCallback;
privateFunc<RequestInformation,RequestInformation>_requestConfigurator;
privateDictionary<string,ParsableFactory<IParsable>>_errorMapping;

/// <summary>
/// The @odata.deltaLink returned from a delta query.
/// </summary>
publicstringDeltalink
{
get;privateset;
}
/// <summary>
/// The @odata.nextLink returned in a paged result.
/// </summary>
publicstringNextlink
{
get;privateset;
}
/// <summary>
/// The PageIterator state.
/// </summary>
publicPagingStateState
{
get;set;
}

/// <summary>
/// Boolean value representing if the callback is Async
/// </summary>
internalboolIsProcessPageItemCallbackAsync=>_processPageItemCallback==default;

/// <summary>
/// Creates the PageIterator with the results of an initial paged request. 
/// </summary>
/// <param name="client">The GraphServiceClient object used to execute the next request on paging </param>
/// <param name="page">A generated implementation of ICollectionPage.</param>
/// <param name="callback">A Func delegate that processes type TEntity in the result set and should return false if the iterator should cancel processing.</param>
/// <param name="requestConfigurator">A Func delegate that configures the NextPageRequest</param>
/// <param name="errorMapping">The error mappings to use in case of failed request during page iteration</param>
/// <returns>A PageIterator&lt;TEntity&gt; that will process additional result pages based on the rules specified in Func&lt;TEntity,bool&gt; processPageItems</returns>
publicstaticPageIterator<TEntity,TCollectionPage>CreatePageIterator(IBaseClientclient,TCollectionPagepage,Func<TEntity,bool>callback,Func<RequestInformation,RequestInformation>requestConfigurator=null,Dictionary<string,ParsableFactory<IParsable>>errorMapping=null)
{
if(client==null)
thrownewArgumentNullException(nameof(client));

returnCreatePageIterator(client.RequestAdapter,page,callback,requestConfigurator,errorMapping);
}

/// <summary>
/// Creates the PageIterator with the results of an initial paged request. 
/// </summary>
/// <param name="requestAdapter">The <see cref="IRequestAdapter"/> object used to create the NextPageRequest for a delta query.</param>
/// <param name="page">A generated implementation of ICollectionPage.</param>
/// <param name="callback">A Func delegate that processes type TEntity in the result set and should return false if the iterator should cancel processing.</param>
/// <param name="requestConfigurator">A Func delegate that configures the NextPageRequest</param>
/// <param name="errorMapping">The error mappings to use in case of failed request during page iteration</param>
/// <returns>A PageIterator&lt;TEntity&gt; that will process additional result pages based on the rules specified in Func&lt;TEntity,bool&gt; processPageItems</returns>
publicstaticPageIterator<TEntity,TCollectionPage>CreatePageIterator(IRequestAdapterrequestAdapter,TCollectionPagepage,Func<TEntity,bool>callback,Func<RequestInformation,RequestInformation>requestConfigurator=null,Dictionary<string,ParsableFactory<IParsable>>errorMapping=null)
{
if(requestAdapter==null)
thrownewArgumentNullException(nameof(requestAdapter));

if(page==null)
thrownewArgumentNullException(nameof(page));

if(callback==null)
thrownewArgumentNullException(nameof(callback));

if(!page.GetFieldDeserializers().ContainsKey("value"))
thrownewArgumentException("The Parsable does not contain a collection property");

varpageItems=ExtractEntityListFromParsable(page);

returnnewPageIterator<TEntity,TCollectionPage>()
{
_requestAdapter=requestAdapter,
_currentPage=page,
_pageItemQueue=newQueue<TEntity>(pageItems),
_processPageItemCallback=callback,
_requestConfigurator=requestConfigurator,
_errorMapping=errorMapping??newDictionary<string,ParsableFactory<IParsable>>(StringComparer.OrdinalIgnoreCase){
{"XXX",(parsable)=>newServiceException(ErrorConstants.Messages.PageIteratorRequestError,newException(parsable.GetErrorMessage()))}
},
State=PagingState.NotStarted
};
}

/// <summary>
/// Creates the PageIterator with the results of an initial paged request. 
/// </summary>
/// <param name="client">The GraphServiceClient object used to create the NextPageRequest for a delta query.</param>
/// <param name="page">A generated implementation of ICollectionPage.</param>
/// <param name="asyncCallback">A Func delegate that processes type TEntity in the result set aynchrnously and should return false if the iterator should cancel processing.</param>
/// <param name="requestConfigurator">A Func delegate that configures the NextPageRequest</param>
/// <param name="errorMapping">The error mappings to use in case of failed request during page iteration</param>
/// <returns>A PageIterator&lt;TEntity&gt; that will process additional result pages based on the rules specified in Func&lt;TEntity,bool&gt; processPageItems</returns>
publicstaticPageIterator<TEntity,TCollectionPage>CreatePageIterator(IBaseClientclient,TCollectionPagepage,Func<TEntity,Task<bool>>asyncCallback,Func<RequestInformation,RequestInformation>requestConfigurator=null,Dictionary<string,ParsableFactory<IParsable>>errorMapping=null)
{
if(client==null)
thrownewArgumentNullException(nameof(client));

returnCreatePageIterator(client.RequestAdapter,page,asyncCallback,requestConfigurator);
}

/// <summary>
/// Creates the PageIterator with the results of an initial paged request. 
/// </summary>
/// <param name="requestAdapter">The <see cref="IRequestAdapter"/> object used to execute the next request on paging .</param>
/// <param name="page">A generated implementation of ICollectionPage.</param>
/// <param name="asyncCallback">A Func delegate that processes type TEntity in the result set aynchrnously and should return false if the iterator should cancel processing.</param>
/// <param name="requestConfigurator">A Func delegate that configures the NextPageRequest</param>
/// <param name="errorMapping">The error mappings to use in case of failed request during page iteration</param>
/// <returns>A PageIterator&lt;TEntity&gt; that will process additional result pages based on the rules specified in Func&lt;TEntity,bool&gt; processPageItems</returns>
publicstaticPageIterator<TEntity,TCollectionPage>CreatePageIterator(IRequestAdapterrequestAdapter,TCollectionPagepage,Func<TEntity,Task<bool>>asyncCallback,Func<RequestInformation,RequestInformation>requestConfigurator=null,Dictionary<string,ParsableFactory<IParsable>>errorMapping=null)
{
if(requestAdapter==null)
thrownewArgumentNullException(nameof(requestAdapter));

if(page==null)
thrownewArgumentNullException(nameof(page));

if(asyncCallback==null)
thrownewArgumentNullException(nameof(asyncCallback));

if(!page.GetFieldDeserializers().ContainsKey("value"))
thrownewArgumentException("The Parsable does not contain a collection property");

varpageItems=ExtractEntityListFromParsable(page);

returnnewPageIterator<TEntity,TCollectionPage>()
{
_requestAdapter=requestAdapter,
_currentPage=page,
_pageItemQueue=newQueue<TEntity>(pageItems),
_asyncProcessPageItemCallback=asyncCallback,
_requestConfigurator=requestConfigurator,
_errorMapping=errorMapping??newDictionary<string,ParsableFactory<IParsable>>(StringComparer.OrdinalIgnoreCase){
{"XXX",(parsable)=>newServiceException(ErrorConstants.Messages.PageIteratorRequestError,newException(parsable.GetErrorMessage()))}
},
State=PagingState.NotStarted
};
}

/// <summary>
/// Iterate across the content of a single results page with the callback.
/// </summary>
/// <returns>A boolean value that indicates whether the callback cancelled 
/// iterating across the page results or whether there are more pages to page. 
/// A return value of false indicates that the iterator should stop iterating.</returns>
privateasyncTask<bool>IntrapageIterateAsync()
{
State=PagingState.IntrapageIteration;

while(_pageItemQueue.Count!=0)// && shouldContinue)
{
boolshouldContinue=IsProcessPageItemCallbackAsync?await_asyncProcessPageItemCallback(_pageItemQueue.Dequeue()):_processPageItemCallback(_pageItemQueue.Dequeue());

// Cancel processing of items in the page and stop requesting more pages.
if(!shouldContinue)
{
State=PagingState.Paused;
returnshouldContinue;
}
}

// Setup deltalink request. Using dynamic to access the NextPageRequest.
varnextLink=ExtractNextLinkFromParsable(_currentPage);
// There are more pages ready to be paged.
if(!string.IsNullOrEmpty(nextLink))
{
Nextlink=nextLink;
Deltalink=string.Empty;
returntrue;
}

// There are no pages CURRENTLY ready to be paged. Attempt to call delta query later.
if(_currentPage.AdditionalData!=null&&_currentPage.AdditionalData.TryGetValue(CoreConstants.OdataInstanceAnnotations.DeltaLink,outobjectdeltalink))
{
Deltalink=deltalink.ToString();
State=PagingState.Delta;
Nextlink=string.Empty;

returnfalse;
}
vardeltaLink=ExtractNextLinkFromParsable(_currentPage,"OdataDeltaLink");
// There are no pages CURRENTLY ready to be paged. Attempt to call delta query later.
if(!string.IsNullOrEmpty(deltaLink))
{
Deltalink=deltaLink;
State=PagingState.Delta;
Nextlink=string.Empty;

returnfalse;
}

// Paging has completed - no more nextlinks.
else
{
State=PagingState.Complete;
Nextlink=string.Empty;

returnfalse;
}
}

/// <summary>
/// Call the next page request when there is another page of data.
/// </summary>
/// <param name="token"></param>
/// <returns>The task object that represents the results of this asynchronous operation.</returns>
/// <exception cref="Microsoft.Graph.ServiceException">Thrown when the service encounters an error with
/// a request.</exception>
privateasyncTaskInterpageIterateAsync(CancellationTokentoken)
{
State=PagingState.InterpageIteration;

// Get the next page if it is available and queue the items for processing.
if(!string.IsNullOrEmpty(Nextlink)||!string.IsNullOrEmpty(Deltalink))
{
// Call the MSGraph API to get the next page of results and set that page as the currentPage.
varnextPageRequestInformation=newRequestInformation
{
HttpMethod=Method.GET,
UrlTemplate=string.IsNullOrEmpty(Nextlink)?Deltalink:Nextlink,
};
// if we have a request configurator, modify the request as desired then execute it to get the next page
nextPageRequestInformation=_requestConfigurator==null?nextPageRequestInformation:_requestConfigurator(nextPageRequestInformation);
_currentPage=await_requestAdapter.SendAsync<TCollectionPage>(nextPageRequestInformation,(parseNode)=>newTCollectionPage(),_errorMapping,token);

varpageItems=ExtractEntityListFromParsable(_currentPage);
// Add all of the items returned in the response to the queue.
if(pageItems!=null&&pageItems.Count>0)
{
foreach(TEntityentityinpageItems)
{
_pageItemQueue.Enqueue(entity);
}
}
}

// Detect nextLink loop
if(!string.IsNullOrEmpty(Nextlink)&&Nextlink.Equals(ExtractNextLinkFromParsable(_currentPage)))
{
thrownewServiceException($"Detected nextLink loop. Nextlink value: {Nextlink}");
}
}
#pragma warning disable CS1574
#pragma warning disable CS1587
/// <summary>
/// Fetches page collections and iterates through each page of items and processes it according to the Func&lt;TEntity, bool&gt; set in <see cref="CreatePageIterator"/>. 
/// </summary>
#pragma warning restore CS1587
#pragma warning restore CS1574
/// <returns>The task object that represents the results of this asynchronous operation.</returns>
/// <exception cref="Microsoft.Graph.ServiceException">Thrown when the service encounters an error with
/// a request.</exception>
publicasyncTaskIterateAsync()
{
awaitIterateAsync(newCancellationToken()).ConfigureAwait(false);
}

#pragma warning disable CS1574
#pragma warning disable CS1587
/// <summary>
/// Fetches page collections and iterates through each page of items and processes it according to the Func&lt;TEntity, bool&gt; set in <see cref="CreatePageIterator"/>. 
/// </summary>
#pragma warning restore CS1587
#pragma warning restore CS1574
/// <param name="token">The CancellationToken used to stop iterating calls for more pages.</param>
/// <returns>The task object that represents the results of this asynchronous operation.</returns>
/// <exception cref="Microsoft.Graph.ServiceException">Thrown when the service encounters an error with
/// a request or there is an internal error with the service.</exception>
publicasyncTaskIterateAsync(CancellationTokentoken)
{
// Occurs when we try to request new changes from MSGraph with a deltalink.
if(State==PagingState.Delta)
{
// Make a call to get the next page of results and add items to queue. 
awaitInterpageIterateAsync(token).ConfigureAwait(false);
}

// Iterate over the contents of queue. The queue could be from the initial page
// results passed to the iterator, the results of a delta query, or from a 
// previously cancelled iteration that gets resumed.
boolshouldContinueInterpageIteration=awaitIntrapageIterateAsync();

// Request more pages if they are available.
while(shouldContinueInterpageIteration&&!token.IsCancellationRequested)
{
// Make a call to get the next page of results and add items to queue. 
awaitInterpageIterateAsync(token).ConfigureAwait(false);

// Iterate over items added to the queue by InterpageIterateAsync and
// determine whether there are more pages to request.
shouldContinueInterpageIteration=awaitIntrapageIterateAsync();
}
}

#pragma warning disable CS1574
#pragma warning disable CS1587
/// <summary>
/// Resumes iterating through each page of items and processes it according to the Func&lt;TEntity, bool&gt; set in <see cref="CreatePageIterator"/>. 
/// </summary>
#pragma warning restore CS1587
#pragma warning restore CS1574
/// <returns>The task object that represents the results of this asynchronous operation.</returns>
publicasyncTaskResumeAsync()
{
awaitResumeAsync(newCancellationToken()).ConfigureAwait(false);
}

#pragma warning disable CS1574
#pragma warning disable CS1587
/// <summary>
/// Resumes iterating through each page of items and processes it according to the Func&lt;TEntity, bool&gt; set in <see cref="CreatePageIterator"/>. 
/// </summary>
#pragma warning restore CS1574
#pragma warning restore CS1587
/// <param name="token">The CancellationToken used to stop iterating calls for more pages.</param>
/// <returns>The task object that represents the results of this asynchronous operation.</returns>
/// <exception cref="Microsoft.Graph.ServiceException">Thrown when the service encounters an error with
/// a request.</exception>
publicasyncTaskResumeAsync(CancellationTokentoken)
{
awaitIterateAsync(token).ConfigureAwait(false);
}

/// <summary>
/// Helper method to extract the collection rom an <see cref="IParsable"/> instance.
/// </summary>
/// <param name="parsableCollection">The <see cref="IParsable"/> to extract the collection from</param>
/// <returns></returns>
/// <exception cref="ArgumentException">Thrown when the object doesn't contain a collection inside it</exception>
privatestaticList<TEntity>ExtractEntityListFromParsable(TCollectionPageparsableCollection)
{
returntypeof(TCollectionPage).GetProperty("Value")?.GetValue(parsableCollection,null)asList<TEntity>??thrownewArgumentException("The Parsable does not contain a collection property");
}

/// <summary>
/// Helper method to extract the nextLink property from an <see cref="IParsable"/> instance.
/// </summary>
/// <param name="parsableCollection">The <see cref="IParsable"/> to extract the nextLink from</param>
/// <param name="nextLinkPropertyName">The property name of the nextLink string</param>
/// <returns></returns>
privatestaticstringExtractNextLinkFromParsable(TCollectionPageparsableCollection,stringnextLinkPropertyName="OdataNextLink")
{
varnextLinkProperty=typeof(TCollectionPage).GetProperty(nextLinkPropertyName);
if(nextLinkProperty!=null&&
nextLinkProperty.GetValue(parsableCollection,null)isstringnextLinkString
&&!string.IsNullOrEmpty(nextLinkString))
{
returnnextLinkString;
}

// the next link property may not be defined in the response schema so we also check its presence in the additional data bag
returnparsableCollection.AdditionalData.TryGetValue(CoreConstants.OdataInstanceAnnotations.NextLink,outvarnextLink)?nextLink.ToString():string.Empty;
}
}

/// <summary>
/// Specifies the state of the PageIterator.
/// </summary>
publicenumPagingState
{
/// <summary>
/// The iterator has neither started iterating thorugh the initial page nor request more pages.
/// </summary>
NotStarted,
/// <summary>
/// The callback returned false or a cancellation token was set. The iterator is resumeable.
/// </summary>
Paused,
/// <summary>
/// Iterating across the contents of page.
/// </summary>
IntrapageIteration,
/// <summary>
/// Iterating across paged requests.
/// </summary>
InterpageIteration,
/// <summary>
/// A deltaToken was returned. The iterator is resumeable.
/// </summary>
Delta,
/// <summary>
/// Reached the end of a non-deltaLink paged result set.
/// </summary>
Complete
}
}