com.mongodb

Class WriteConcern

java.lang.Object

com.mongodb.WriteConcern

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

WriteConcern.Majority

public class WriteConcern
extends Object
implements Serializable

Controls the acknowledgment of write operations with various options.

w

• 0: Don't wait for acknowledgement from the server
• 1: Wait for acknowledgement, but don't wait for secondaries to replicate
• >=2: Wait for one or more secondaries to also acknowledge

wtimeout - how long to wait for slaves before failing

• 0: indefinite
• >0: time to wait in milliseconds

Other options:

• j: If true block until write operations have been committed to the journal. Cannot be used in combination with fsync. Prior to MongoDB 2.6 this option was ignored if the server was running without journaling. Starting with MongoDB 2.6 write operations will fail with an exception if this option is used when the server is running without journaling.
• fsync: If true and the server is running without journaling, blocks until the server has synced all data files to disk. If the server is running with journaling, this acts the same as the j option, blocking until write operations have been committed to the journal. Cannot be used in combination with j. In almost all cases the j flag should be used in preference to this one.

See Also:

Serialized Form

MongoDB documentation

Write Concern

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WriteConcern.Majority A write concern that blocks acknowledgement of a write operation until a majority of replica set members have applied it.

Field Summary

Fields

Modifier and Type	Field and Description
static WriteConcern	ACKNOWLEDGED Write operations that use this write concern will wait for acknowledgement from the primary server before returning.
static WriteConcern	ERRORS_IGNORED Deprecated. There is no replacement for this write concern. The closest would be to use WriteConcern#UNACKNOWLEDGED, then catch and ignore any exceptions of type MongoSocketException.
static WriteConcern	FSYNC_SAFE Exceptions are raised for network issues, and server errors; the write operation waits for the server to flush the data to disk.
static WriteConcern	FSYNCED Exceptions are raised for network issues, and server errors; the write operation waits for the server to flush the data to disk.
static WriteConcern	JOURNAL_SAFE Exceptions are raised for network issues, and server errors; the write operation waits for the server to group commit to the journal file on disk.
static WriteConcern	JOURNALED Exceptions are raised for network issues, and server errors; the write operation waits for the server to group commit to the journal file on disk.
static WriteConcern	MAJORITY Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.
static WriteConcern	NONE Deprecated.
static WriteConcern	NORMAL Write operations that use this write concern will return as soon as the message is written to the socket.
static WriteConcern	REPLICA_ACKNOWLEDGED Exceptions are raised for network issues, and server errors; waits for at least 2 servers for the write operation.
static WriteConcern	REPLICAS_SAFE Exceptions are raised for network issues, and server errors; waits for at least 2 servers for the write operation.
static WriteConcern	SAFE Write operations that use this write concern will wait for acknowledgement from the primary server before returning.
static WriteConcern	UNACKNOWLEDGED Write operations that use this write concern will return as soon as the message is written to the socket.

Constructor Summary

Constructors

Constructor and Description
WriteConcern() Default constructor keeping all options as default.
WriteConcern(boolean fsync) Calls WriteConcern(int, int, boolean) with w=1 and wtimeout=0
WriteConcern(int w) Calls WriteConcern(int, int, boolean) with wtimeout=0 and fsync=false
WriteConcern(int w, int wtimeout) Calls WriteConcern(int, int, boolean) with fsync=false
WriteConcern(int w, int wtimeout, boolean fsync) Creates a WriteConcern object.
WriteConcern(int w, int wtimeout, boolean fsync, boolean j) Creates a WriteConcern object.
WriteConcern(int w, int wtimeout, boolean fsync, boolean j, boolean continueOnError) Deprecated. the preferred way to specify continueOnError is to use write methods that explicitly specify the value of this property
WriteConcern(String w) Tag based Write Concern with wtimeout=0, fsync=false, and j=false
WriteConcern(String w, int wtimeout, boolean fsync, boolean j) Creates a WriteConcern object.
WriteConcern(String w, int wtimeout, boolean fsync, boolean j, boolean continueOnError) Deprecated. the preferred way to specify continueOnError is to use write methods that explicitly specify the value of this property

Method Summary

Methods

Modifier and Type	Method and Description
boolean	callGetLastError() Returns whether "getlasterror" should be called (w > 0)
WriteConcern	continueOnError(boolean continueOnError) Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property
WriteConcern	continueOnErrorForInsert(boolean continueOnErrorForInsert) Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property
boolean	equals(Object o)
boolean	fsync() Gets the fsync flag (fsync to disk on the server)
BasicDBObject	getCommand() Deprecated. This will be removed in 3.0
boolean	getContinueOnError() Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property
boolean	getContinueOnErrorForInsert() Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property
boolean	getFsync() Gets the fsync flag (fsync to disk on the server)
boolean	getJ() Gets the j parameter (journal syncing)
int	getW() Gets the w parameter (the write strategy)
Object	getWObject() Gets the w value (the write strategy)
String	getWString() Gets the w parameter (the write strategy) in String format
int	getWtimeout() Gets the write timeout (in milliseconds)
int	hashCode()
static WriteConcern.Majority	majorityWriteConcern(int wtimeout, boolean fsync, boolean j) Create a Majority Write Concern that requires a majority of servers to acknowledge the write.
boolean	raiseNetworkErrors() Deprecated. There is no replacement for this method.
void	setWObject(Object w) Deprecated. construct a new instance instead. This method will be removed in a future major release, as instances of this class should really be immutable.
String	toString()
static WriteConcern	valueOf(String name) Gets the WriteConcern constants by name (matching is done case insensitively).

Methods inherited from class java.lang.Object

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

Field Detail

ERRORS_IGNORED

@Deprecated
public static final WriteConcern ERRORS_IGNORED

Deprecated. There is no replacement for this write concern. The closest would be to use WriteConcern#UNACKNOWLEDGED, then catch and ignore any exceptions of type MongoSocketException.

No exceptions are raised, even for network issues.

See Also:

UNACKNOWLEDGED, MongoSocketException

ACKNOWLEDGED

public static final WriteConcern ACKNOWLEDGED

Write operations that use this write concern will wait for acknowledgement from the primary server before returning. Exceptions are raised for network issues, and server errors.

Since:

2.10.0

UNACKNOWLEDGED

public static final WriteConcern UNACKNOWLEDGED

Write operations that use this write concern will return as soon as the message is written to the socket. Exceptions are raised for network issues, but not server errors.

Since:

2.10.0

FSYNCED

public static final WriteConcern FSYNCED

Exceptions are raised for network issues, and server errors; the write operation waits for the server to flush the data to disk.

JOURNALED

public static final WriteConcern JOURNALED

Exceptions are raised for network issues, and server errors; the write operation waits for the server to group commit to the journal file on disk.

REPLICA_ACKNOWLEDGED

public static final WriteConcern REPLICA_ACKNOWLEDGED

Exceptions are raised for network issues, and server errors; waits for at least 2 servers for the write operation.

NONE

@Deprecated
public static final WriteConcern NONE

Deprecated.

No exceptions are raised, even for network issues.

This field has been superseded by WriteConcern.ERRORS_IGNORED, and may be deprecated in a future release.

See Also:

ERRORS_IGNORED

NORMAL

public static final WriteConcern NORMAL

Write operations that use this write concern will return as soon as the message is written to the socket. Exceptions are raised for network issues, but not server errors.

This field has been superseded by WriteConcern.UNACKNOWLEDGED, and may be deprecated in a future release.

See Also:

UNACKNOWLEDGED

SAFE

public static final WriteConcern SAFE

Write operations that use this write concern will wait for acknowledgement from the primary server before returning. Exceptions are raised for network issues, and server errors.

This field has been superseded by WriteConcern.ACKNOWLEDGED, and may be deprecated in a future release.

See Also:

ACKNOWLEDGED

MAJORITY

public static final WriteConcern MAJORITY

Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.

FSYNC_SAFE

public static final WriteConcern FSYNC_SAFE

Exceptions are raised for network issues, and server errors; the write operation waits for the server to flush the data to disk.

This field has been superseded by WriteConcern.FSYNCED, and may be deprecated in a future release.

See Also:

FSYNCED

JOURNAL_SAFE

public static final WriteConcern JOURNAL_SAFE

Exceptions are raised for network issues, and server errors; the write operation waits for the server to group commit to the journal file on disk.

This field has been superseded by WriteConcern.JOURNALED, and may be deprecated in a future release.

See Also:

JOURNALED

REPLICAS_SAFE

public static final WriteConcern REPLICAS_SAFE

Exceptions are raised for network issues, and server errors; waits for at least 2 servers for the write operation.

This field has been superseded by WriteConcern.REPLICA_ACKNOWLEDGED, and may be deprecated in a future release.

See Also:

REPLICA_ACKNOWLEDGED

Constructor Detail

WriteConcern

public WriteConcern()

Default constructor keeping all options as default. Be careful using this constructor, as it's equivalent to WriteConcern.UNACKNOWLEDGED, so writes may be lost without any errors being reported.

See Also:

UNACKNOWLEDGED

WriteConcern

public WriteConcern(int w)

Calls WriteConcern(int, int, boolean) with wtimeout=0 and fsync=false

Parameters:

w - number of writes

WriteConcern

public WriteConcern(String w)

Tag based Write Concern with wtimeout=0, fsync=false, and j=false

Parameters:

w - Write Concern tag

WriteConcern

public WriteConcern(int w,
            int wtimeout)

Calls WriteConcern(int, int, boolean) with fsync=false

Parameters:

w - number of writes

wtimeout - timeout for write operation

WriteConcern

public WriteConcern(boolean fsync)

Calls WriteConcern(int, int, boolean) with w=1 and wtimeout=0

Parameters:

fsync - whether or not to fsync

WriteConcern

public WriteConcern(int w,
            int wtimeout,
            boolean fsync)

Creates a WriteConcern object.

Specifies the number of servers to wait for on the write operation, and exception raising behavior

w represents the number of servers:

• w=0 None, network socket errors raised
• w=1 Checks server for errors as well as network socket errors raised
• w>1 Checks servers (w) for errors as well as network socket errors raised

Parameters:

w - number of writes

wtimeout - timeout for write operation

fsync - whether or not to fsync

WriteConcern

public WriteConcern(int w,
            int wtimeout,
            boolean fsync,
            boolean j)

Creates a WriteConcern object.

Specifies the number of servers to wait for on the write operation, and exception raising behavior

w represents the number of servers:

• w=0 None, network socket errors raised
• w=1 Checks server for errors as well as network socket errors raised
• w>1 Checks servers (w) for errors as well as network socket errors raised

Parameters:

w - number of writes

wtimeout - timeout for write operation

fsync - whether or not to fsync

j - whether writes should wait for a journaling group commit

WriteConcern

@Deprecated
public WriteConcern(int w,
                       int wtimeout,
                       boolean fsync,
                       boolean j,
                       boolean continueOnError)

Deprecated. the preferred way to specify continueOnError is to use write methods that explicitly specify the value of this property

Creates a WriteConcern object.

Specifies the number of servers to wait for on the write operation, and exception raising behavior

w represents the number of servers:

• w=0 None, network socket errors raised
• w=1 Checks server for errors as well as network socket errors raised
• w>1 Checks servers (w) for errors as well as network socket errors raised

Parameters:

w - number of writes

wtimeout - timeout for write operation

fsync - whether or not to fsync

j - whether writes should wait for a journaling group commit

continueOnError - if batch writes should continue after the first error

See Also:

WriteConcern(int, int, boolean), DBCollection.insert(java.util.List, InsertOptions), InsertOptions.continueOnError(boolean), DBCollection.initializeUnorderedBulkOperation()

WriteConcern

public WriteConcern(String w,
            int wtimeout,
            boolean fsync,
            boolean j)

Creates a WriteConcern object.

Specifies the number of servers to wait for on the write operation, and exception raising behavior

w represents the number of servers:

• w=0 None, network socket errors raised
• w=1 Checks server for errors as well as network socket errors raised
• w>1 Checks servers (w) for errors as well as network socket errors raised

Parameters:

w - number of writes

wtimeout - timeout for write operation

fsync - whether or not to fsync

j - whether writes should wait for a journaling group commit

WriteConcern

@Deprecated
public WriteConcern(String w,
                       int wtimeout,
                       boolean fsync,
                       boolean j,
                       boolean continueOnError)

Deprecated. the preferred way to specify continueOnError is to use write methods that explicitly specify the value of this property

Creates a WriteConcern object.

Specifies the number of servers to wait for on the write operation, and exception raising behavior

w represents the number of servers:

• w=0 None, network socket errors raised
• w=1 Checks server for errors as well as network socket errors raised
• w>1 Checks servers (w) for errors as well as network socket errors raised

Parameters:

w - number of writes

wtimeout - timeout for write operation

fsync - whether or not to fsync

j - whether writes should wait for a journaling group commit

continueOnError - if batched writes should continue after the first error

See Also:

WriteConcern(String, int, boolean, boolean), DBCollection.insert(java.util.List, InsertOptions), InsertOptions.continueOnError(boolean), DBCollection.initializeUnorderedBulkOperation()

Method Detail

getCommand

@Deprecated
public BasicDBObject getCommand()

Deprecated. This will be removed in 3.0

Gets the getlasterror command for this write concern.

Returns:

getlasterror command, even if w <= 0

setWObject

@Deprecated
public void setWObject(Object w)

Deprecated. construct a new instance instead. This method will be removed in a future major release, as instances of this class should really be immutable.

Sets the w value (the write strategy).

Parameters:

w - the value of w.

getWObject

public Object getWObject()

Gets the w value (the write strategy)

Returns:

w, either an instance of Integer or String

getW

public int getW()

Gets the w parameter (the write strategy)

Returns:

w, as an int

Throws:

ClassCastException - if w is not an integer

getWString

public String getWString()

Gets the w parameter (the write strategy) in String format

Returns:

w as a string

Throws:

ClassCastException - if w is not a String

getWtimeout

public int getWtimeout()

Gets the write timeout (in milliseconds)

Returns:

the timeout

getFsync

public boolean getFsync()

Gets the fsync flag (fsync to disk on the server)

Returns:

the fsync flag

fsync

public boolean fsync()

Gets the fsync flag (fsync to disk on the server)

Returns:

the fsync flag

raiseNetworkErrors

@Deprecated
public boolean raiseNetworkErrors()

Deprecated. There is no replacement for this method.

Returns whether network error may be raised

Returns:

true if network errors should throw exceptions

See Also:

ERRORS_IGNORED

callGetLastError

public boolean callGetLastError()

Returns whether "getlasterror" should be called (w > 0)

Returns:

whether this write concern will result in an an acknowledged write

valueOf

public static WriteConcern valueOf(String name)

Gets the WriteConcern constants by name (matching is done case insensitively).

Parameters:

name - the name of the WriteConcern

Returns:

the WriteConcern instance

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getJ

public boolean getJ()

Gets the j parameter (journal syncing)

Returns:

true if j is set

continueOnError

@Deprecated
public WriteConcern continueOnError(boolean continueOnError)

Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property

Toggles the "continue inserts on error" mode. This only applies to server side errors. If there is a document which does not validate in the client, an exception will still be thrown in the client. This will return a new instance of WriteConcern with your preferred continueOnInsert value

Parameters:

continueOnError - whether to continue on error after a failure

Returns:

the new write concern

See Also:

DBCollection.insert(java.util.List, InsertOptions), InsertOptions.continueOnError(boolean), DBCollection.initializeUnorderedBulkOperation()

getContinueOnError

@Deprecated
public boolean getContinueOnError()

Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property

Gets the "continue inserts on error" mode

Returns:

the continue on error mode

See Also:

DBCollection.insert(java.util.List, InsertOptions), InsertOptions.isContinueOnError(), DBCollection.initializeUnorderedBulkOperation()

continueOnErrorForInsert

@Deprecated
public WriteConcern continueOnErrorForInsert(boolean continueOnErrorForInsert)

Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property

Toggles the "continue inserts on error" mode. This only applies to server side errors. If there is a document which does not validate in the client, an exception will still be thrown in the client. This will return a new instance of WriteConcern with your preferred continueOnInsert value

Parameters:

continueOnErrorForInsert - whether to continue on error after a failure

Returns:

the new write concern

See Also:

DBCollection.insert(java.util.List, InsertOptions), InsertOptions.continueOnError(boolean), DBCollection.initializeUnorderedBulkOperation()

getContinueOnErrorForInsert

@Deprecated
public boolean getContinueOnErrorForInsert()

Deprecated. the preferred way to specify this is to use write methods that explicitly specify the value of this property

Gets the "continue inserts on error" mode.

Returns:

whether to continue on error after a failure

See Also:

DBCollection.insert(java.util.List, InsertOptions), InsertOptions.isContinueOnError(), DBCollection.initializeUnorderedBulkOperation()

majorityWriteConcern

public static WriteConcern.Majority majorityWriteConcern(int wtimeout,
                                         boolean fsync,
                                         boolean j)

Create a Majority Write Concern that requires a majority of servers to acknowledge the write.

Parameters:

wtimeout - timeout for write operation

fsync - whether or not to fsync

j - whether writes should wait for a journal group commit

Returns:

Majority, a subclass of WriteConcern that represents the write concern requiring most servers to acknowledge the write