Package com.mongodb

Class ReadPreference

java.lang.Object

com.mongodb.ReadPreference

Direct Known Subclasses:

TaggableReadPreference

@Immutable
public abstract class ReadPreference
extends Object

A class that represents preferred replica set members to which a query or command can be sent.

MongoDB documentation

Read Preference

Method Summary

Modifier and Type	Method	Description
final List<ServerDescription>	choose(ClusterDescription clusterDescription)	Chooses the servers from the given cluster than match this read preference.
protected abstract List<ServerDescription>	chooseForNonReplicaSet(ClusterDescription clusterDescription)	Choose for non-replica sets.
protected abstract List<ServerDescription>	chooseForReplicaSet(ClusterDescription clusterDescription)	Choose for replica sets.
abstract String	getName()	Gets the name of this read preference.
abstract boolean	isSecondaryOk()	True if this read preference allows reading from a secondary member of a replica set.
static ReadPreference	nearest()	Gets a read preference that forces reads to a primary or a secondary.
static ReadPreference	nearest(long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a primary or a secondary that is less stale than the given maximum.
static TaggableReadPreference	nearest(TagSet tagSet)	Gets a read preference that forces reads to the primary or a secondary with the given set of tags.
static TaggableReadPreference	nearest(TagSet tagSet, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to the primary or a secondary with the given set of tags that is less stale than the given maximum.
static TaggableReadPreference	nearest(List<TagSet> tagSetList)	Gets a read preference that forces reads to the primary or a secondary with one of the given sets of tags.
static TaggableReadPreference	nearest(List<TagSet> tagSetList, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to the primary or a secondary with one of the given sets of tags that is less stale than the given maximum.
static ReadPreference	primary()	Gets a read preference that forces read to the primary.
static ReadPreference	primaryPreferred()	Gets a read preference that forces reads to the primary if available, otherwise to a secondary.
static ReadPreference	primaryPreferred(long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to the primary if available, otherwise to a secondary.
static TaggableReadPreference	primaryPreferred(TagSet tagSet)	Gets a read preference that forces reads to the primary if available, otherwise to a secondary with the given set of tags.
static TaggableReadPreference	primaryPreferred(TagSet tagSet, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to the primary if available, otherwise to a secondary with the given set of tags that is less stale than the given maximum.
static TaggableReadPreference	primaryPreferred(List<TagSet> tagSetList)	Gets a read preference that forces reads to the primary if available, otherwise to a secondary with one of the given sets of tags.
static TaggableReadPreference	primaryPreferred(List<TagSet> tagSetList, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to the primary if available, otherwise to a secondary with one of the given sets of tags that is less stale than the given maximum.
static ReadPreference	secondary()	Gets a read preference that forces reads to a secondary.
static ReadPreference	secondary(long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary that is less stale than the given maximum.
static TaggableReadPreference	secondary(TagSet tagSet)	Gets a read preference that forces reads to a secondary with the given set of tags.
static TaggableReadPreference	secondary(TagSet tagSet, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary with the given set of tags that is less stale than the given maximum.
static TaggableReadPreference	secondary(List<TagSet> tagSetList)	Gets a read preference that forces reads to a secondary with one of the given sets of tags.
static TaggableReadPreference	secondary(List<TagSet> tagSetList, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary with one of the given sets of tags that is less stale than the given maximum.
static ReadPreference	secondaryPreferred()	Gets a read preference that forces reads to a secondary if one is available, otherwise to the primary.
static ReadPreference	secondaryPreferred(long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary that is less stale than the given maximumm if one is available, otherwise to the primary.
static TaggableReadPreference	secondaryPreferred(TagSet tagSet)	Gets a read preference that forces reads to a secondary with the given set of tags, or the primary is none are available.
static TaggableReadPreference	secondaryPreferred(TagSet tagSet, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary with the given set of tags that is less stale than the given maximum, or the primary is none are available.
static TaggableReadPreference	secondaryPreferred(List<TagSet> tagSetList)	Gets a read preference that forces reads to a secondary with one of the given sets of tags.
static TaggableReadPreference	secondaryPreferred(List<TagSet> tagSetList, long maxStaleness, TimeUnit timeUnit)	Gets a read preference that forces reads to a secondary with one of the given sets of tags that is less stale than the given maximum.
abstract BsonDocument	toDocument()	Gets a document representing this read preference in the wire protocol.
static ReadPreference	valueOf(String name)	Creates a read preference from the given read preference name.
static TaggableReadPreference	valueOf(String name, List<TagSet> tagSetList)	Creates a taggable read preference from the given read preference name and list of tag sets.
static TaggableReadPreference	valueOf(String name, List<TagSet> tagSetList, long maxStaleness, TimeUnit timeUnit)	Creates a taggable read preference from the given read preference name, list of tag sets, and max allowable staleness of secondaries.
abstract ReadPreference	withHedgeOptions(ReadPreferenceHedgeOptions hedgeOptions)	Create a new ReadPreference instance with hedge options.
abstract ReadPreference	withMaxStalenessMS(Long maxStalenessMS, TimeUnit timeUnit)	Create a new ReadPreference instance with the maximum acceptable staleness of a secondary in order to be considered for read operations.
abstract ReadPreference	withTagSet(TagSet tagSet)	Create a new ReadPreference instance with a new tag set.
abstract ReadPreference	withTagSetList(List<TagSet> tagSet)	Create a new ReadPreference instance with a new tag set list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

withTagSet

public abstract ReadPreference withTagSet(TagSet tagSet)

Create a new ReadPreference instance with a new tag set.

Note: this method is not supported for a primary read preference.

Parameters:

tagSet - the new tag set

Returns:

a new ReadPreference instance with a new tag set

Since:

4.1

withTagSetList

public abstract ReadPreference withTagSetList(List<TagSet> tagSet)

Create a new ReadPreference instance with a new tag set list.

Note: this method is not supported for a primary read preference.

Parameters:

tagSet - the new tag set list

Returns:

a new ReadPreference instance with a new tag set list

Since:

4.1

withMaxStalenessMS

public abstract ReadPreference withMaxStalenessMS(Long maxStalenessMS,
 TimeUnit timeUnit)

Create a new ReadPreference instance with the maximum acceptable staleness of a secondary in order to be considered for read operations.

Note: this method is not supported for a primary read preference.

Parameters:

maxStalenessMS - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

a new ReadPreference instance with a new maximum allowable staleness

Since:

4.1

Since server release

3.4

withHedgeOptions

public abstract ReadPreference withHedgeOptions(ReadPreferenceHedgeOptions hedgeOptions)

Create a new ReadPreference instance with hedge options.

Note: this method is not supported for a primary read preference.

Parameters:

hedgeOptions - the hedge options

Returns:

a new ReadPreference instance with hedge options

Since:

4.1

Since server release

4.4

isSecondaryOk

public abstract boolean isSecondaryOk()

True if this read preference allows reading from a secondary member of a replica set.

Returns:

if reading from a secondary is ok

Since:

4.4

getName

public abstract String getName()

Gets the name of this read preference.

Returns:

the name

toDocument

public abstract BsonDocument toDocument()

Gets a document representing this read preference in the wire protocol.

Returns:

the document

choose

public final List<ServerDescription> choose(ClusterDescription clusterDescription)

Chooses the servers from the given cluster than match this read preference.

Parameters:

clusterDescription - the cluster description

Returns:

a list of matching server descriptions, which may be empty but may not be null

chooseForNonReplicaSet

protected abstract List<ServerDescription> chooseForNonReplicaSet(ClusterDescription clusterDescription)

Choose for non-replica sets.

Parameters:

clusterDescription - the cluster description

Returns:

the list of matching server descriptions

chooseForReplicaSet

protected abstract List<ServerDescription> chooseForReplicaSet(ClusterDescription clusterDescription)

Choose for replica sets.

Parameters:

clusterDescription - the cluster description

Returns:

the list of matching server descriptions

primary

public static ReadPreference primary()

Gets a read preference that forces read to the primary.

Returns:

ReadPreference which reads from primary only

primaryPreferred

public static ReadPreference primaryPreferred()

Gets a read preference that forces reads to the primary if available, otherwise to a secondary.

Returns:

ReadPreference which reads primary if available.

secondary

public static ReadPreference secondary()

Gets a read preference that forces reads to a secondary.

Returns:

ReadPreference which reads secondary.

secondaryPreferred

public static ReadPreference secondaryPreferred()

Gets a read preference that forces reads to a secondary if one is available, otherwise to the primary.

Returns:

ReadPreference which reads secondary if available, otherwise from primary.

nearest

public static ReadPreference nearest()

Gets a read preference that forces reads to a primary or a secondary.

Returns:

ReadPreference which reads nearest

primaryPreferred

public static ReadPreference primaryPreferred(long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to the primary if available, otherwise to a secondary.

Parameters:

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads primary if available.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondary

public static ReadPreference secondary(long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary that is less stale than the given maximum.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondaryPreferred

public static ReadPreference secondaryPreferred(long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary that is less stale than the given maximumm if one is available, otherwise to the primary.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

*

Parameters:

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary if available, otherwise from primary.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

nearest

public static ReadPreference nearest(long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a primary or a secondary that is less stale than the given maximum.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads nearest

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

primaryPreferred

public static TaggableReadPreference primaryPreferred(TagSet tagSet)

Gets a read preference that forces reads to the primary if available, otherwise to a secondary with the given set of tags.

Parameters:

tagSet - the set of tags to limit the list of secondaries to.

Returns:

ReadPreference which reads primary if available, otherwise a secondary respective of tags.\

Since:

2.13

secondary

public static TaggableReadPreference secondary(TagSet tagSet)

Gets a read preference that forces reads to a secondary with the given set of tags.

Parameters:

tagSet - the set of tags to limit the list of secondaries to

Returns:

ReadPreference which reads secondary respective of tags.

Since:

2.13

secondaryPreferred

public static TaggableReadPreference secondaryPreferred(TagSet tagSet)

Gets a read preference that forces reads to a secondary with the given set of tags, or the primary is none are available.

Parameters:

tagSet - the set of tags to limit the list of secondaries to

Returns:

ReadPreference which reads secondary if available respective of tags, otherwise from primary irrespective of tags.

Since:

2.13

nearest

public static TaggableReadPreference nearest(TagSet tagSet)

Gets a read preference that forces reads to the primary or a secondary with the given set of tags.

Parameters:

tagSet - the set of tags to limit the list of secondaries to

Returns:

ReadPreference which reads nearest node respective of tags.

Since:

2.13

primaryPreferred

public static TaggableReadPreference primaryPreferred(TagSet tagSet,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to the primary if available, otherwise to a secondary with the given set of tags that is less stale than the given maximum.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSet - the set of tags to limit the list of secondaries to.

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads primary if available, otherwise a secondary respective of tags.\

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondary

public static TaggableReadPreference secondary(TagSet tagSet,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary with the given set of tags that is less stale than the given maximum.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSet - the set of tags to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary respective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondaryPreferred

public static TaggableReadPreference secondaryPreferred(TagSet tagSet,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary with the given set of tags that is less stale than the given maximum, or the primary is none are available.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

*

Parameters:

tagSet - the set of tags to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary if available respective of tags, otherwise from primary irrespective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

nearest

public static TaggableReadPreference nearest(TagSet tagSet,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to the primary or a secondary with the given set of tags that is less stale than the given maximum.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSet - the set of tags to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads nearest node respective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

primaryPreferred

public static TaggableReadPreference primaryPreferred(List<TagSet> tagSetList)

Gets a read preference that forces reads to the primary if available, otherwise to a secondary with one of the given sets of tags. The driver will look for a secondary with each tag set in the given list, stopping after one is found, or failing if no secondary can be found that matches any of the tag sets in the list.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

Returns:

ReadPreference which reads primary if available, otherwise a secondary respective of tags.

Since:

2.13

secondary

public static TaggableReadPreference secondary(List<TagSet> tagSetList)

Gets a read preference that forces reads to a secondary with one of the given sets of tags. The driver will look for a secondary with each tag set in the given list, stopping after one is found, or failing if no secondary can be found that matches any of the tag sets in the list.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

Returns:

ReadPreference which reads secondary respective of tags.

Since:

2.13

secondaryPreferred

public static TaggableReadPreference secondaryPreferred(List<TagSet> tagSetList)

Gets a read preference that forces reads to a secondary with one of the given sets of tags. The driver will look for a secondary with each tag set in the given list, stopping after one is found, or the primary if none are available.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

Returns:

ReadPreference which reads secondary if available respective of tags, otherwise from primary irrespective of tags.

Since:

2.13

nearest

public static TaggableReadPreference nearest(List<TagSet> tagSetList)

Gets a read preference that forces reads to the primary or a secondary with one of the given sets of tags. The driver will look for a secondary with each tag set in the given list, stopping after one is found, or the primary if none are available.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

Returns:

ReadPreference which reads nearest node respective of tags.

Since:

2.13

primaryPreferred

public static TaggableReadPreference primaryPreferred(List<TagSet> tagSetList,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to the primary if available, otherwise to a secondary with one of the given sets of tags that is less stale than the given maximum.

The driver will look for a secondary with each tag set in the given list, stopping after one is found, or failing if no secondary can be found that matches any of the tag sets in the list.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads primary if available, otherwise a secondary respective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondary

public static TaggableReadPreference secondary(List<TagSet> tagSetList,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary with one of the given sets of tags that is less stale than the given maximum.

The driver will look for a secondary with each tag set in the given list, stopping after one is found, or failing if no secondary can be found that matches any of the tag sets in the list.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary respective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

secondaryPreferred

public static TaggableReadPreference secondaryPreferred(List<TagSet> tagSetList,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to a secondary with one of the given sets of tags that is less stale than the given maximum.

The driver will look for a secondary with each tag set in the given list, stopping after one is found, or the primary if none are available.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads secondary if available respective of tags, otherwise from primary irrespective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

nearest

public static TaggableReadPreference nearest(List<TagSet> tagSetList,
 long maxStaleness,
 TimeUnit timeUnit)

Gets a read preference that forces reads to the primary or a secondary with one of the given sets of tags that is less stale than the given maximum.

The driver will look for a secondary with each tag set in the given list, stopping after one is found, or the primary if none are available.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

tagSetList - the list of tag sets to limit the list of secondaries to

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

ReadPreference which reads nearest node respective of tags.

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)

valueOf

public static ReadPreference valueOf(String name)

Creates a read preference from the given read preference name.

Parameters:

name - the name of the read preference

Returns:

the read preference

valueOf

public static TaggableReadPreference valueOf(String name,
 List<TagSet> tagSetList)

Creates a taggable read preference from the given read preference name and list of tag sets.

Parameters:

name - the name of the read preference

tagSetList - the list of tag sets

Returns:

the taggable read preference

Since:

2.13

valueOf

public static TaggableReadPreference valueOf(String name,
 List<TagSet> tagSetList,
 long maxStaleness,
 TimeUnit timeUnit)

Creates a taggable read preference from the given read preference name, list of tag sets, and max allowable staleness of secondaries.

The driver estimates the staleness of each secondary, based on lastWriteDate values provided in server hello responses, and selects only those secondaries whose staleness is less than or equal to maxStaleness.

Parameters:

name - the name of the read preference

tagSetList - the list of tag sets

maxStaleness - the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency plus 10 seconds, whichever is greatest.

timeUnit - the time unit of maxStaleness

Returns:

the taggable read preference

Since:

3.4

See Also:

• TaggableReadPreference.getMaxStaleness(TimeUnit)