com.allanbank.mongodb

Class Durability

java.lang.Object

com.allanbank.mongodb.Durability

All Implemented Interfaces:

Serializable

public class Durability
extends Object
implements Serializable

Represents the required durability of writes (inserts, updates, and deletes) on the server.

• The lowest durability (NONE) has no guarantees that the data will survive a catastrophic server failure.
• The next level of durability (ACK) ensures that the data has been received by the server.
• The next level of durability (journalDurable(int)) ensures that the data is written to the server's journal before returning.
• Next level (fsyncDurable(int)) is to ensure that the data has been fsync()'d to the server's disk.
• For the highest level of durability (replicaDurable(int)), the server ensure that the data has been received by 1 to N replicas in the replica set. Fine grain control can be achieved by specifying a replication mode instead of a count.

Generally, increasing the level of durability decreases performance.

See Also:

Data Center Awareness, 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 ©:

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

Field Summary

Fields

Modifier and Type	Field and Description
static Durability	ACK The durability that says no durability is required.
static String	MAJORITY_MODE Built in replication mode indicating that more than 50% of the MongoDB replica set servers have received a write.
static Durability	NONE The durability that says no durability is required.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Durability(boolean waitForFsync, boolean waitForJournal, int waitForReplicas, int waitTimeoutMillis) Create a new Durability.
protected	Durability(boolean waitForFsync, boolean waitForJournal, String waitForReplicasByMode, int waitTimeoutMillis) Create a new Durability.

Method Summary

Methods

Modifier and Type	Method and Description
Document	asDocument() Returns a suitable getlasterror command's document.
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.
static Durability	fsyncDurable(int waitTimeoutMillis) Creates an fsync() durability.
int	getWaitForReplicas() Returns if (value greater than zero) the durability requires that the response wait for the data to be received by a replica and the number of replicas of the data to wait for.
String	getWaitForReplicasByMode() If the value is non-null then wait for the specified replication mode configured on the server.
int	getWaitTimeoutMillis() Returns the number of milliseconds to wait for the durability requirements to be satisfied.
int	hashCode() Computes a reasonable hash code.
boolean	isWaitForFsync() Returns if the durability requires that the response wait for an fsync() of the data on the server to complete.
boolean	isWaitForJournal() Returns if the durability requires that the response wait for the data to be written to the server's journal.
boolean	isWaitForReply() Returns if the durability requires that the response wait for a reply from the server but potentially no special server processing.
static Durability	journalDurable(int waitTimeoutMillis) Creates an journal durability.
protected boolean	nullSafeEquals(Object rhs, Object lhs) Does a null safe equals comparison.
static Durability	replicaDurable(boolean ensureJournaled, int minimumReplicas, int waitTimeoutMillis) Creates a multiple replica durability.
static Durability	replicaDurable(boolean ensureJournaled, String waitForReplicasByMode, int waitTimeoutMillis) Creates a multiple replica durability.
static Durability	replicaDurable(int waitTimeoutMillis) Creates a single replica durability.
static Durability	replicaDurable(int minimumReplicas, int waitTimeoutMillis) Creates a multiple replica durability.
static Durability	replicaDurable(String waitForReplicasByMode, int waitTimeoutMillis) Creates a multiple replica durability.
String	toString()
static Durability	valueOf(String value) Converts a string into a Durability, if possible.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ACK

public static final Durability ACK

The durability that says no durability is required.

MAJORITY_MODE

public static final String MAJORITY_MODE

Built in replication mode indicating that more than 50% of the MongoDB replica set servers have received a write.

See Also:

Constant Field Values

NONE

public static final Durability NONE

The durability that says no durability is required.

Constructor Detail

Durability

protected Durability(boolean waitForFsync,
          boolean waitForJournal,
          int waitForReplicas,
          int waitTimeoutMillis)

Create a new Durability.

Parameters:

waitForFsync - True if the durability requires that the response wait for an fsync() of the data to complete, false otherwise.

waitForJournal - True if if the durability requires that the response wait for the data to be written to the server's journal, false otherwise.

waitForReplicas - If the value is value greater than zero the durability requires that the response wait for the data to be received by a replica and the number of replicas of the data to wait for.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Durability

protected Durability(boolean waitForFsync,
          boolean waitForJournal,
          String waitForReplicasByMode,
          int waitTimeoutMillis)

Create a new Durability.

Parameters:

waitForFsync - True if the durability requires that the response wait for an fsync() of the data to complete, false otherwise.

waitForJournal - True if if the durability requires that the response wait for the data to be written to the server's journal, false otherwise.

waitForReplicasByMode - If the value is non-null then wait for the specified replication mode configured on the server. A built-in mode of MAJORITY_MODE is also supported.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Method Detail

fsyncDurable

public static Durability fsyncDurable(int waitTimeoutMillis)

Creates an fsync() durability.

Will cause the server to wait for the write to be sync'd to disk. If the server is running with journaling enabled then only the journal will have been sync'd to disk. If running without journaling enabled then will wait for all data files to be sync'd to disk.

Parameters:

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure that the data has been fsync()'d to the server's disk.

journalDurable

public static Durability journalDurable(int waitTimeoutMillis)

Creates an journal durability.

Will cause the server to wait for the write to be sync'd to disk as part of the journal. As of MongoDB 2.6 this mode will cause a TBD exception to be thrown if the server is configured without journaling enabled. Prior to MongoDB 2.6 this mode would silently degrade to ACK.

Parameters:

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to the server's journal before returning.

replicaDurable

public static Durability replicaDurable(boolean ensureJournaled,
                        int minimumReplicas,
                        int waitTimeoutMillis)

Creates a multiple replica durability.

Parameters:

ensureJournaled - If true then ensure that the write has been committed to the journal in addition to replicated.

minimumReplicas - The minimum number of replicas to wait for.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to at least minimumReplicas of server's replicas before returning.

replicaDurable

public static Durability replicaDurable(boolean ensureJournaled,
                        String waitForReplicasByMode,
                        int waitTimeoutMillis)

Creates a multiple replica durability.

Parameters:

ensureJournaled - If true then ensure that the write has been committed to the journal in addition to replicated.

waitForReplicasByMode - If the value is non-null then wait for the specified replication mode configured on the server. A built-in mode of MAJORITY_MODE is also supported.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to at least minimumReplicas of server's replicas before returning.

replicaDurable

public static Durability replicaDurable(int waitTimeoutMillis)

Creates a single replica durability. This is a 'w' value of 2.

Parameters:

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to at least one of server's replicas before returning.

replicaDurable

public static Durability replicaDurable(int minimumReplicas,
                        int waitTimeoutMillis)

Creates a multiple replica durability.

Parameters:

minimumReplicas - The minimum number of replicas to wait for.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to at least minimumReplicas of server's replicas before returning.

replicaDurable

public static Durability replicaDurable(String waitForReplicasByMode,
                        int waitTimeoutMillis)

Creates a multiple replica durability.

Parameters:

waitForReplicasByMode - If the value is non-null then wait for the specified replication mode configured on the server. A built-in mode of MAJORITY_MODE is also supported.

waitTimeoutMillis - The number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

A durability that will ensure the data is written to at least minimumReplicas of server's replicas before returning.

valueOf

public static Durability valueOf(String value)

Converts a string into a Durability, if possible.

Two forms of strings can be converted:

• A name of the constant (ignoring case):
  • ACK
  • NONE
  • SAFE - for compatibility with the MongoDB Inc. driver, returns ACK.
• A JSON document representation of the Durability. The following fields are allowed in the document and the values for each should match those for a getlasterror command:
  • w
  • wtimeout
  • fsync
  • j
  • getlasterror
  If present the getlasterror field is ignored. An example JSON document might look like:

   
   { w : 'majority', wtimeout : 10000 }
   
   

If the string is not parse-able in either of these forms then null is returned.

Parameters:

value - The string representation of the Durability.

Returns:

The Durability represented by the string.

asDocument

public Document asDocument()

Returns a suitable getlasterror command's document.

Returns:

The getlasterror command's 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)

getWaitForReplicas

public int getWaitForReplicas()

Returns if (value greater than zero) the durability requires that the response wait for the data to be received by a replica and the number of replicas of the data to wait for.

Returns:

If (value greater than zero) the durability requires that the response wait for the data to be received by a replica and the number of replicas of the data to wait for.

getWaitForReplicasByMode

public String getWaitForReplicasByMode()

If the value is non-null then wait for the specified replication mode configured on the server. A built-in mode of MAJORITY_MODE is also supported.

Returns:

If the value is non-null then wait for the specified replication mode configured on the server.

See Also:

Data Center Awareness

getWaitTimeoutMillis

public int getWaitTimeoutMillis()

Returns the number of milliseconds to wait for the durability requirements to be satisfied.

Returns:

The number of milliseconds to wait for the durability requirements to be satisfied.

hashCode

public int hashCode()

Computes a reasonable hash code.

Overrides:

hashCode in class Object

Returns:

The hash code value.

isWaitForFsync

public boolean isWaitForFsync()

Returns if the durability requires that the response wait for an fsync() of the data on the server to complete.

Returns:

True if the durability requires that the response wait for an fsync() of the data to complete, false otherwise.

isWaitForJournal

public boolean isWaitForJournal()

Returns if the durability requires that the response wait for the data to be written to the server's journal.

Returns:

True if if the durability requires that the response wait for the data to be written to the server's journal, false otherwise.

isWaitForReply

public boolean isWaitForReply()

Returns if the durability requires that the response wait for a reply from the server but potentially no special server processing.

Returns:

True if the durability requires that the response wait for a reply from the server but potentially no special server processing.

toString

public String toString()

Overriden to return the durability as JSON text.

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.