Class ResilientBrowsingClient

Resilient Client.

Inheritance
System.Object
ResilientBrowsingClient
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: Gee.External.Browsing.Clients
Assembly: Gee.External.Browsing.dll
Syntax
public sealed class ResilientBrowsingClient : IBrowsingClient, IDisposable
Remarks

Represents a resilient client that automatically retries failed operations performed on a IBrowsingClient. The number of retry attempts is either caller or implementation specific if you do not specify a value. Between each retry attempt, the resilient client will pause for an implementation specific interval. If all retry attempts are exhausted and the attempted operation never succeeds, the exception the failed operation threw will be propagated up to you.

The Google Safe Browsing API requires clients to implement a "back-off" mode when an attempted operation fails. A failed operation, in this context, means an unsuccessful HTTP response for an HTTP request. A resilient client does not implement this "back-off" mode because, quite frankly, it is quite unrealistic to implement it in an API. The minimum and maximum intervals between retry attempts required by the "back-off" mode are 15 minutes and 24 hours, respectively. It is not realistic to declare a method in an API that, at best, returns after 15 minutes or, at worst, returns after 24 hours if it retries a failed operation. As such, a resilient client only considers network time-outs as failed operations and will only retry those. A network time-out means the Google Safe Browsing API is taking too long to reply to an HTTP request and there isn't an HTTP response to fulfill it in a predetermined period of time. As such, it should be exempt from the required "back-off" mode implementation.

If you specify a number of retry attempts when you create a resilient client, be practical with the value you specify. The resilient client will pause for an implementation specific interval between each retry attempt, which effectively means if an attempted operation always fails, the exception it threw will not be propagated up to you until all the retry attempts are exhausted. If you specify a very high number of retry attempts, this could have self inflicted performance implications.

When you create a resilient client, you can specify whether or not it takes ownership of the client you want to proxy to and dispose it when the resilient client itself is disposed. The recommended behavior is that you allow the resilient client to take ownership of the client you want to proxy to but take note that if you reference or dispose the client you want to proxy to after you create the resilient client, the behavior of the resilient client and client you want to proxy to is undefined.

Since a resilient client itself implements IBrowsingClient, it is technically possible to create a new resilient client for an existing resilient client, though the reasons for doing so, in most cases, are unjustified. To avoid doing do, consider creating a resilient client using Create(IBrowsingClient), or one of its overloads, instead of one of the constructor overloads. Create(IBrowsingClient) will conveniently create a resilient client if, and only if, the client you want to proxy to itself is not a resilient client.

Constructors

ResilientBrowsingClient(IBrowsingClient)

Create a Resilient Client.

Declaration
public ResilientBrowsingClient(IBrowsingClient client)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to. The resilient client takes ownership of client and will dispose it when the resilient cache itself is disposed. If you reference or dispose client after you create the resilient cache, the behavior of the resilient cache and client is undefined.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.

ResilientBrowsingClient(IBrowsingClient, Int32)

Create a Resilient Client.

Declaration
public ResilientBrowsingClient(IBrowsingClient client, int retryAttempts)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to. The resilient client takes ownership of client and will dispose it when the resilient cache itself is disposed. If you reference or dispose client after you create the resilient cache, the behavior of the resilient cache and client is undefined.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

ResilientBrowsingClient(IBrowsingClient, Int32, Boolean)

Create a Resilient Client.

Declaration
public ResilientBrowsingClient(IBrowsingClient client, int retryAttempts, bool ownClient)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
System.Boolean ownClient

A boolean flag indicating whether or not the resilient client takes ownership of client and disposes it when the resilient client itself is disposed. If the resilient client takes ownership of client and you reference or dispose client after you create the resilient client, the behavior of the resilient client and client is undefined.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

Methods

Create(IBrowsingClient)

Create a Resilient Client.

Declaration
public static ResilientBrowsingClient Create(IBrowsingClient client)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to. The resilient client takes ownership of client and will dispose it when the resilient cache itself is disposed. If you reference or dispose client after you create the resilient cache, the behavior of the resilient cache and client is undefined.
Returns
Type Description
ResilientBrowsingClient

A resilient client.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.

Create(IBrowsingClient, Int32)

Create a Resilient Client.

Declaration
public static ResilientBrowsingClient Create(IBrowsingClient client, int retryAttempts)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to. The resilient client takes ownership of client and will dispose it when the resilient cache itself is disposed. If you reference or dispose client after you create the resilient cache, the behavior of the resilient cache and client is undefined.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
Returns
Type Description
ResilientBrowsingClient
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

Create(IBrowsingClient, Int32, Boolean)

Create a Resilient Client.

Declaration
public static ResilientBrowsingClient Create(IBrowsingClient client, int retryAttempts, bool ownClient)
Parameters
Type Name Description
IBrowsingClient client

A IBrowsingClient to proxy to.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
System.Boolean ownClient

A boolean flag indicating whether or not the resilient client takes ownership of client and disposes it when the resilient client itself is disposed. If the resilient client takes ownership of client and you reference or dispose client after you create the resilient client, the behavior of the resilient client and client is undefined.
Returns
Type Description
ResilientBrowsingClient
Exceptions
Type Condition
System.ArgumentNullException

Thrown if client is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

Dispose()

Dispose Object.

Declaration
public void Dispose()

FindFullHashesAsync(FullHashRequest, CancellationToken)

Find Full Hashes Asynchronously.

Declaration
public Task<FullHashResponse> FindFullHashesAsync(FullHashRequest request, CancellationToken cancellationToken)
Parameters
Type Name Description
FullHashRequest request

A FullHashRequest.
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<FullHashResponse>

A FullHashResponse.
Exceptions
Type Condition
BrowsingClientException

Thrown if an error communicating with the Google Safe Browsing API occurs.
System.ArgumentNullException

Thrown if request is a null reference.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.
System.TimeoutException

Thrown if communication with the Google Safe Browsing API times out.

GetThreatListDescriptorsAsync(CancellationToken)

Get Threat List Descriptors Asynchronously.

Declaration
public Task<IEnumerable<ThreatListDescriptor>> GetThreatListDescriptorsAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<ThreatListDescriptor>>

A collection of ThreatListDescriptor.
Exceptions
Type Condition
BrowsingClientException

Thrown if an error communicating with the Google Safe Browsing API occurs.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.
System.TimeoutException

Thrown if communication with the Google Safe Browsing API times out.

GetThreatListUpdatesAsync(ThreatListUpdateRequest, CancellationToken)

Get Threat List Updates Asynchronously.

Declaration
public Task<ThreatListUpdateResponse> GetThreatListUpdatesAsync(ThreatListUpdateRequest request, CancellationToken cancellationToken)
Parameters
Type Name Description
ThreatListUpdateRequest request

A ThreatListUpdateRequest.
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<ThreatListUpdateResponse>

A ThreatListUpdateResponse.
Exceptions
Type Condition
BrowsingClientException

Thrown if an error communicating with the Google Safe Browsing API occurs.
System.ArgumentNullException

Thrown if request is a null reference.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.
System.TimeoutException

Thrown if communication with the Google Safe Browsing API times out.

Implements

System.IDisposable

Extension Methods