ReadPreference (mongodb-async-driver 2.0.1 API)

java.lang.Object
- com.allanbank.mongodb.ReadPreference

All Implemented Interfaces:

DocumentAssignable, Serializable
```
public class ReadPreference
extends Object
implements Serializable, DocumentAssignable
```
ReadPreference encapsulates a ReadPreference.Mode and a set of tag matching documents. The ReadPreference.Mode specified if primary and/or secondary servers in a replica set can be used and which should be tried first. The tag matching documents control which secondary servers can be used.
Each tag matching document specified the minimum set of key/values that the secondary server must be tagged with. As an example a tag matching document of { a : 1, b : 2 } would match a server with the tags { a : 1, b : 2, c : 3 } but would not match a server with tags { a : 1, c : 3, d : 4 }.

The tag matching documents and server tags must match exactly so a server with tags { a: true, b : 2 } would not match the { a : 1, b : 2 } tag matching document. Neither would a server with the tags { c: 1, b : 2 }.

Each tag matching document specifies a disjoint condition so a server has to match only one for the tag matching document. If the tag matching documents { a : 1, b : 2 } and { a : 1, c : 3 } are provided then both the server { a : 1, b : 2, c : 3 } and { a : 1, c : 3, d : 4 } would match.

If no tag matching documents are specified then all secondary servers may be used.

See Also:
Serialized Form
API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2012-2013, Allanbank Consulting, Inc., All Rights Reserved

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ReadPreference.Mode
Enumeration of the basic ReadPreference modes of service.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ReadPreference.Mode` Enumeration of the basic `ReadPreference` modes of service.

Field Summary

Fields
Modifier and Type	Field and Description
`static ReadPreference`	`CLOSEST` `ReadPreference` to read from the closest/`ReadPreference.Mode.NEAREST` primary of secondary server.
`static String`	`FIELD_NAME` The name of the field in the query document for the read preferences.
`static ReadPreference`	`PREFER_PRIMARY` `ReadPreference` to prefer reading from the primary but to fallback to a secondary if the primary is not available.
`static ReadPreference`	`PREFER_SECONDARY` `ReadPreference` to prefer reading from a secondary but to 'fallback' to a primary if a secondary is not available.
`static ReadPreference`	`PRIMARY` The default `ReadPreference` to read from the primary only.
`static ReadPreference`	`SECONDARY` `ReadPreference` to read only from a secondary but using any secondary.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`ReadPreference(ReadPreference.Mode mode, DocumentAssignable... tagMatchDocuments)` Creates a new ReadPreference.
`protected`	`ReadPreference(ReadPreference.Mode mode, String address)` Creates a new ReadPreference.

Method Summary

Methods
Modifier and Type	Method and Description
`Document`	`asDocument()` Converts the object into a document.
`static ReadPreference`	`closest(DocumentAssignable... tagMatchDocuments)` Creates a `ReadPreference` to read from the closest/ `ReadPreference.Mode.NEAREST` primary of secondary server.
`boolean`	`equals(Object object)` Determines if the passed object is of this same type as this object and if so that its fields are equal.
`ReadPreference.Mode`	`getMode()` Returns the read preference mode controlling if primary or secondary servers can be used and which to prefer.
`String`	`getServer()` Returns the server to read from.
`List<Document>`	`getTagMatchingDocuments()` Returns the list of tag matching documents to control the secondaries used.
`int`	`hashCode()` Computes a reasonable hash code.
`boolean`	`isLegacy()` Returns true if the read preference is compatible with the legacy "slaveOk", e.g., is one of `ReadPreference.Mode.PRIMARY_ONLY`, `ReadPreference.Mode.SECONDARY_ONLY`, or `ReadPreference.Mode.SERVER` and has no tag matching documents.
`boolean`	`isSecondaryOk()` Returns true if the mode allows reading from secondaries, false otherwise.
`boolean`	`matches(Document tags)` Returns true if this `ReadPreference` matches the `tags` document.
`protected boolean`	`nullSafeEquals(Object rhs, Object lhs)` Does a null safe equals comparison.
`static ReadPreference`	`preferPrimary(DocumentAssignable... tagMatchDocuments)` Creates a `ReadPreference` to prefer reading from the primary but to fallback to a secondary if the primary is not available.
`static ReadPreference`	`preferSecondary(DocumentAssignable... tagMatchDocuments)` Creates a `ReadPreference` to prefer reading from a secondary but to 'fallback' to a primary if a secondary is not available.
`static ReadPreference`	`primary()` Returns the default `ReadPreference` to read from the primary only: `PRIMARY`.
`static ReadPreference`	`secondary(DocumentAssignable... tagMatchDocuments)` Creates a `ReadPreference` to read only from a secondary.
`static ReadPreference`	`server(String address)` Creates a `ReadPreference` to read only from a specific server.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - CLOSEST
```
public static final ReadPreference CLOSEST
```
    ReadPreference to read from the closest/ReadPreference.Mode.NEAREST primary of secondary server.
  - FIELD_NAME
```
public static final String FIELD_NAME
```
    The name of the field in the query document for the read preferences.
    
    See Also:
    Constant Field Values
  - PREFER_PRIMARY
```
public static final ReadPreference PREFER_PRIMARY
```
    ReadPreference to prefer reading from the primary but to fallback to a secondary if the primary is not available.
  - PREFER_SECONDARY
```
public static final ReadPreference PREFER_SECONDARY
```
    ReadPreference to prefer reading from a secondary but to 'fallback' to a primary if a secondary is not available.
  - PRIMARY
```
public static final ReadPreference PRIMARY
```
    The default ReadPreference to read from the primary only.
  - SECONDARY
```
public static final ReadPreference SECONDARY
```
    ReadPreference to read only from a secondary but using any secondary.
- Constructor Detail
  - ReadPreference
```
protected ReadPreference(ReadPreference.Mode mode,
              DocumentAssignable... tagMatchDocuments)
```
    Creates a new ReadPreference.
    
    Parameters:
    mode - The read preference mode controlling if primary or secondary servers can be used and which to prefer.
    tagMatchDocuments - Set of tag matching "documents" controlling which secondary servers are used.
  - ReadPreference
```
protected ReadPreference(ReadPreference.Mode mode,
              String address)
```
    Creates a new ReadPreference.
    
    Parameters:
    mode - The read preference mode controlling if primary or secondary servers can be used and which to prefer.
    address - The server to read from.
- Method Detail
  - closest
```
public static ReadPreference closest(DocumentAssignable... tagMatchDocuments)
```
    Creates a ReadPreference to read from the closest/ ReadPreference.Mode.NEAREST primary of secondary server.
    If tag matching documents are specified then only servers matching the specified tag matching documents would be used.
    
    If no tag matching documents are specified then returns CLOSEST.
    
    Parameters:
    tagMatchDocuments - Set of tag matching "documents" controlling which servers are used.
    
    Returns:
    The creates ReadPreference.
  - preferPrimary
```
public static ReadPreference preferPrimary(DocumentAssignable... tagMatchDocuments)
```
    Creates a ReadPreference to prefer reading from the primary but to fallback to a secondary if the primary is not available.
    If tag matching documents are specified then only secondary servers matching the specified tag matching documents would be used.
    
    If no tag matching documents are specified then returns PREFER_PRIMARY.
    
    Parameters:
    tagMatchDocuments - Set of tag matching "documents" controlling which secondary servers are used.
    
    Returns:
    The creates ReadPreference.
  - preferSecondary
```
public static ReadPreference preferSecondary(DocumentAssignable... tagMatchDocuments)
```
    Creates a ReadPreference to prefer reading from a secondary but to 'fallback' to a primary if a secondary is not available.
    If tag matching documents are specified then only secondary servers matching the specified tag matching documents would be used.
    
    If no tag matching documents are specified then returns PREFER_SECONDARY.
    
    Parameters:
    tagMatchDocuments - Set of tag matching "documents" controlling which secondary servers are used.
    
    Returns:
    The creates ReadPreference.
  - primary
```
public static ReadPreference primary()
```
    Returns the default ReadPreference to read from the primary only: PRIMARY.
    
    Returns:
    The PRIMARY ReadPreference.
  - secondary
```
public static ReadPreference secondary(DocumentAssignable... tagMatchDocuments)
```
    Creates a ReadPreference to read only from a secondary.
    If tag matching documents are specified then only secondary servers matching the specified tag matching documents would be used.
    
    If no tag matching documents are specified then returns PREFER_SECONDARY.
    
    Parameters:
    tagMatchDocuments - Set of tag matching "documents" controlling which secondary servers are used.
    
    Returns:
    The creates ReadPreference.
  - server
```
public static ReadPreference server(String address)
```
    Creates a ReadPreference to read only from a specific server.
    Used by the MongoIterator to ensure cursor fetch and terminate requests use the originating server.
    
    Note: Use this form of ReadPreference with caution. If the specified server fails all requests will fail.
    
    Parameters:
    address - The server to read from.
    
    Returns:
    The creates ReadPreference.
  - asDocument
```
public Document asDocument()
```
    Converts the object into a document.
    Overridden to return the read preference document.
    
    The document contains:
    - The mode string value as returned by ReadPreference.Mode.getToken().
    - An optional tags array containing the tag matching documents
    - An optional server containing the server to read from. This should only used for cursors to ensure the correct server is used to request more documents.
    Specified by:
    
    asDocument in interface DocumentAssignable
    
    Returns:
    The object as a Document.
  - equals
```
public boolean equals(Object object)
```
    Determines if the passed object is of this same type as this object and if so that its fields are equal.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    object - The object to compare to.
    See Also:
    Object.equals(java.lang.Object)
  - getMode
```
public ReadPreference.Mode getMode()
```
    Returns the read preference mode controlling if primary or secondary servers can be used and which to prefer.
    
    Returns:
    The read preference mode controlling if primary or secondary servers can be used and which to prefer.
  - getServer
```
public String getServer()
```
    Returns the server to read from. Used by the MongoIterator to ensure cursor fetch and terminate requests use the originating server.
    
    Returns:
    The server to read from.
  - getTagMatchingDocuments
```
public List<Document> getTagMatchingDocuments()
```
    Returns the list of tag matching documents to control the secondaries used.
    
    Returns:
    The list of tag matching documents to control the secondaries used.
  - hashCode
```
public int hashCode()
```
    Computes a reasonable hash code.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    The hash code value.
  - isLegacy
```
public boolean isLegacy()
```
    Returns true if the read preference is compatible with the legacy "slaveOk", e.g., is one of ReadPreference.Mode.PRIMARY_ONLY, ReadPreference.Mode.SECONDARY_ONLY, or ReadPreference.Mode.SERVER and has no tag matching documents.
    
    Returns:
    True if the mode allows reading from secondaries, false otherwise.
  - isSecondaryOk
```
public boolean isSecondaryOk()
```
    Returns true if the mode allows reading from secondaries, false otherwise.
    
    Returns:
    True if the mode allows reading from secondaries, false otherwise.
  - matches
```
public boolean matches(Document tags)
```
    Returns true if this ReadPreference matches the tags document.
    
    Parameters:
    tags - The tags to be matched against.
    
    Returns:
    True if this ReadPreference matches the tags, false otherwise.
  - toString
```
public String toString()
```
    Overridden to return a string representation of the read preference..
    
    Overrides:
    
    toString in class Object
  - nullSafeEquals
```
protected boolean nullSafeEquals(Object rhs,
                     Object lhs)
```
    Does a null safe equals comparison.
    
    Parameters:
    rhs - The right-hand-side of the comparison.
    lhs - The left-hand-side of the comparison.
    
    Returns:
    True if the rhs equals the lhs. Note: nullSafeEquals(null, null) returns true.

Class ReadPreference

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLOSEST

FIELD_NAME

PREFER_PRIMARY

PREFER_SECONDARY

PRIMARY

SECONDARY

Constructor Detail

ReadPreference

ReadPreference

Method Detail

closest

preferPrimary

preferSecondary

primary

secondary

server

asDocument

equals

getMode

getServer

getTagMatchingDocuments

hashCode

isLegacy

isSecondaryOk

matches

toString

nullSafeEquals