Coverage Report

Coverage Report - com.allanbank.mongodb.Durability

Classes in this File
Line Coverage
Branch Coverage
Complexity
Durability
97%
109/112
94%
74/78
2.87
 /*
  * #%L
  * Durability.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 package com.allanbank.mongodb;
 
 import java.io.Serializable;
 import java.io.StringWriter;
 
 import com.allanbank.mongodb.bson.Document;
 import com.allanbank.mongodb.bson.Element;
 import com.allanbank.mongodb.bson.NumericElement;
 import com.allanbank.mongodb.bson.builder.BuilderFactory;
 import com.allanbank.mongodb.bson.builder.DocumentBuilder;
 import com.allanbank.mongodb.bson.element.JsonSerializationVisitor;
 import com.allanbank.mongodb.bson.element.StringElement;
 import com.allanbank.mongodb.bson.element.SymbolElement;
 import com.allanbank.mongodb.bson.impl.ImmutableDocument;
 import com.allanbank.mongodb.bson.json.Json;
 import com.allanbank.mongodb.error.JsonParseException;
 
 /**
  * Represents the required durability of writes (inserts, updates, and deletes)
  * on the server.
  * <ul>
  * <li>The lowest durability ({@link #NONE}) has no guarantees that the data
  * will survive a catastrophic server failure.
  * <li>The next level of durability ({@link #ACK}) ensures that the data has
  * been received by the server.
  * <li>The next level of durability ({@link #journalDurable(int)}) ensures that
  * the data is written to the server's journal before returning.
  * <li>Next level ({@link #fsyncDurable(int)}) is to ensure that the data has
  * been fsync()'d to the server's disk.
  * <li>For the highest level of durability ({@link #replicaDurable(int)}), the
  * server ensure that the data has been received by 1 to
  * {@link #replicaDurable(int, int) N} replicas in the replica set. Fine grain
  * control can be achieved by specifying a {@link #replicaDurable(String, int)
  * replication mode} instead of a count.</li>
  * </ul>
  * <p>
  * Generally, increasing the level of durability decreases performance.
  * </p>
  * 
  * @see <a href="http://www.mongodb.org/display/DOCS/Data+Center+Awareness">Data
  *      Center Awareness</a>
  * @api.yes 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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;) before being
  *          removed or modified.
  * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
  */
 public class Durability implements Serializable {
 
     /** The durability that says no durability is required. */
     public final static Durability ACK = new Durability(true, false, false, 1,
             null, 0);
 
     /**
      * Built in replication mode indicating that more than 50% of the MongoDB
      * replica set servers have received a write.
      */
     public final static String MAJORITY_MODE = "majority";
 
     /** The durability that says no durability is required. */
     public final static Durability NONE = new Durability(false, false, false,
             0, null, 0);
 
     /** Serialization version for the class. */
     private static final long serialVersionUID = -6474266523435876385L;
 
     /**
      * Creates an fsync() durability.
      * <p>
      * 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.
      * 
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure that the data has been fsync()'d to
      *         the server's disk.
      */
     public static Durability fsyncDurable(final int waitTimeoutMillis) {
         return new Durability(true, false, 0, waitTimeoutMillis);
     }
 
     /**
      * Creates an journal durability.
      * <p>
      * 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 {@link #ACK}.
      * </p>
      * 
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to the server's
      *         journal before returning.
      */
     public static Durability journalDurable(final int waitTimeoutMillis) {
         return new Durability(false, true, 0, waitTimeoutMillis);
     }
 
     /**
      * Creates a multiple replica durability.
      * 
      * @param ensureJournaled
      *            If true then ensure that the write has been committed to the
      *            journal in addition to replicated.
      * @param minimumReplicas
      *            The minimum number of replicas to wait for.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to at least
      *         <tt>minimumReplicas</tt> of server's replicas before returning.
      */
     public static Durability replicaDurable(final boolean ensureJournaled,
             final int minimumReplicas, final int waitTimeoutMillis) {
         return new Durability(false, ensureJournaled, minimumReplicas,
                 waitTimeoutMillis);
     }
 
     /**
      * Creates a multiple replica durability.
      * 
      * @param ensureJournaled
      *            If true then ensure that the write has been committed to the
      *            journal in addition to replicated.
      * @param waitForReplicasByMode
      *            If the value is non-<code>null</code> then wait for the
      *            specified replication mode configured on the server. A
      *            built-in mode of {@link #MAJORITY_MODE} is also supported.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to at least
      *         <tt>minimumReplicas</tt> of server's replicas before returning.
      */
     public static Durability replicaDurable(final boolean ensureJournaled,
             final String waitForReplicasByMode, final int waitTimeoutMillis) {
         return new Durability(false, ensureJournaled, waitForReplicasByMode,
                 waitTimeoutMillis);
     }
 
     /**
      * Creates a single replica durability. This is a 'w' value of 2.
      * 
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to at least one
      *         of server's replicas before returning.
      */
     public static Durability replicaDurable(final int waitTimeoutMillis) {
         return new Durability(false, false, 2, waitTimeoutMillis);
     }
 
     /**
      * Creates a multiple replica durability.
      * 
      * @param minimumReplicas
      *            The minimum number of replicas to wait for.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to at least
      *         <tt>minimumReplicas</tt> of server's replicas before returning.
      */
     public static Durability replicaDurable(final int minimumReplicas,
             final int waitTimeoutMillis) {
         return new Durability(false, false, minimumReplicas, waitTimeoutMillis);
     }
 
     /**
      * Creates a multiple replica durability.
      * 
      * @param waitForReplicasByMode
      *            If the value is non-<code>null</code> then wait for the
      *            specified replication mode configured on the server. A
      *            built-in mode of {@link #MAJORITY_MODE} is also supported.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      * @return A durability that will ensure the data is written to at least
      *         <tt>minimumReplicas</tt> of server's replicas before returning.
      */
     public static Durability replicaDurable(final String waitForReplicasByMode,
             final int waitTimeoutMillis) {
         return new Durability(false, false, waitForReplicasByMode,
                 waitTimeoutMillis);
     }
 
     /**
      * Converts a string into a Durability, if possible.
      * <p>
      * Two forms of strings can be converted:
      * <ul>
      * <li>A name of the constant (ignoring case):
      * <ul>
      * <li>{@code ACK}</li>
      * <li>{@code NONE}</li>
      * <li>{@code SAFE} - for compatibility with the MongoDB Inc. driver,
      * returns {@link #ACK}.</li>
      * </ul>
      * </li>
      * <li>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 {@code getlasterror} command:
      * <ul>
      * <li>{@code w}</li>
      * <li>{@code wtimeout}</li>
      * <li>{@code fsync}</li>
      * <li>{@code j}</li>
      * <li>{@code getlasterror}</li>
      * </ul>
      * If present the {@code getlasterror} field is ignored. An example JSON
      * document might look like: <blockquote>
      * 
      * <pre>
      * <code>
      * { w : 'majority', wtimeout : 10000 }
      * </code>
      * </pre>
      * 
      * <blockquote></li>
      * </ul>
      * </p>
      * <p>
      * If the string is not parse-able in either of these forms then null is
      * returned.
      * </p>
      * 
      * @param value
      *            The string representation of the Durability.
      * @return The Durability represented by the string.
      */
     public static Durability valueOf(final String value) {
 
         Durability result = null;
 
         if ("ACK".equalsIgnoreCase(value) || "SAFE".equalsIgnoreCase(value)) {
             result = ACK;
         }
         else if ("NONE".equalsIgnoreCase(value)) {
             result = NONE;
         }
         else {
             // Try and parse as JSON.
             try {
                 boolean waitForReply = false;
                 boolean waitForFsync = false;
                 boolean waitForJournal = false;
                 int waitForReplicas = 0;
                 String waitForReplicasByMode = null;
                 int waitTimeoutMillis = 0;
 
                 final Document d = Json.parse(value);
                 for (final Element e : d) {
                     // Skip the getlasterror element.
                     if (!"getlasterror".equalsIgnoreCase(e.getName())) {
                         if ("w".equalsIgnoreCase(e.getName())) {
                             waitForReply = true;
                             if (e instanceof NumericElement) {
                                 waitForReplicas = ((NumericElement) e)
                                         .getIntValue();
                             }
                             else if (e instanceof StringElement) {
                                 waitForReplicasByMode = ((StringElement) e)
                                         .getValue();
                             }
                             else if (e instanceof SymbolElement) {
                                 waitForReplicasByMode = ((SymbolElement) e)
                                         .getSymbol();
                             }
                             else {
                                 // Unknown 'w' value type.
                                 return null;
                             }
                         }
                         else if ("wtimeout".equalsIgnoreCase(e.getName())) {
                             if (e instanceof NumericElement) {
                                 waitTimeoutMillis = ((NumericElement) e)
                                         .getIntValue();
                             }
                             else {
                                 // Unknown 'wtimeout' value type.
                                 return null;
                             }
                         }
                         else if ("fsync".equalsIgnoreCase(e.getName())) {
                             waitForReply = true;
                             waitForFsync = true;
                         }
                         else if ("j".equalsIgnoreCase(e.getName())) {
                             waitForReply = true;
                             waitForJournal = true;
                         }
                         else {
                             // Unknown field.
                             return null;
                         }
                     }
                 }
 
                 result = new Durability(waitForReply, waitForFsync,
                         waitForJournal, waitForReplicas, waitForReplicasByMode,
                         waitTimeoutMillis);
             }
             catch (final JsonParseException error) {
                 // Ignore and return null.
                 error.getCause(); // Shhh PMD.
             }
         }
 
         return result;
     }
 
     /** The durability in document form. */
     private Document myAsDocument;
 
     /**
      * True if the durability requires that the response wait for an fsync() of
      * the data to complete, false otherwise.
      */
     private final boolean myWaitForFsync;
 
     /**
      * True if if the durability requires that the response wait for the data to
      * be written to the server's journal, false otherwise.
      */
     private final boolean myWaitForJournal;
 
     /**
      * 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.
      */
     private final int myWaitForReplicas;
 
     /**
      * If the value is non-<code>null</code> then wait for the specified
      * replication mode configured on the server. A built-in mode of
      * {@link #MAJORITY_MODE} is also supported.
      * 
      * @see <a
      *      href="http://www.mongodb.org/display/DOCS/Data+Center+Awareness">Data
      *      Center Awareness</a>
      */
     private final String myWaitForReplicasByMode;
 
     /**
      * True if the durability requires that the response wait for a reply from
      * the server but no special server processing.
      */
     private final boolean myWaitForReply;
 
     /**
      * The number of milliseconds to wait for the durability requirements to be
      * satisfied.
      */
     private final int myWaitTimeoutMillis;
 
     /**
      * Create a new Durability.
      * 
      * @param waitForFsync
      *            True if the durability requires that the response wait for an
      *            fsync() of the data to complete, false otherwise.
      * @param waitForJournal
      *            True if if the durability requires that the response wait for
      *            the data to be written to the server's journal, false
      *            otherwise.
      * @param 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.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      */
     protected Durability(final boolean waitForFsync,
             final boolean waitForJournal, final int waitForReplicas,
             final int waitTimeoutMillis) {
         this(true, waitForFsync, waitForJournal, waitForReplicas, null,
                 waitTimeoutMillis);
     }
 
     /**
      * Create a new Durability.
      * 
      * @param waitForFsync
      *            True if the durability requires that the response wait for an
      *            fsync() of the data to complete, false otherwise.
      * @param waitForJournal
      *            True if if the durability requires that the response wait for
      *            the data to be written to the server's journal, false
      *            otherwise.
      * @param waitForReplicasByMode
      *            If the value is non-<code>null</code> then wait for the
      *            specified replication mode configured on the server. A
      *            built-in mode of {@link #MAJORITY_MODE} is also supported.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      */
     protected Durability(final boolean waitForFsync,
             final boolean waitForJournal, final String waitForReplicasByMode,
             final int waitTimeoutMillis) {
         this(true, waitForFsync, waitForJournal, 0, waitForReplicasByMode,
                 waitTimeoutMillis);
     }
 
     /**
      * Create a new Durability.
      * 
      * @param waitForReply
      *            True if the durability requires a reply from the server.
      * @param waitForFsync
      *            True if the durability requires that the response wait for an
      *            fsync() of the data to complete, false otherwise.
      * @param waitForJournal
      *            True if if the durability requires that the response wait for
      *            the data to be written to the server's journal, false
      *            otherwise.
      * @param 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.
      * @param waitForReplicasByMode
      *            If the value is non-<code>null</code> then wait for the
      *            specified replication mode configured on the server. A
      *            built-in mode of {@link #MAJORITY_MODE} is also supported.
      * @param waitTimeoutMillis
      *            The number of milliseconds to wait for the durability
      *            requirements to be satisfied.
      */
     private Durability(final boolean waitForReply, final boolean waitForFsync,
             final boolean waitForJournal, final int waitForReplicas,
             final String waitForReplicasByMode, final int waitTimeoutMillis) {
         myWaitForReply = waitForReply;
         myWaitForFsync = waitForFsync;
         myWaitForJournal = waitForJournal;
         myWaitForReplicas = waitForReplicas;
         myWaitTimeoutMillis = waitTimeoutMillis;
         myWaitForReplicasByMode = waitForReplicasByMode;
     }
 
     /**
      * Returns a suitable getlasterror command's document.
      * 
      * @return The getlasterror command's document.
      */
     public Document asDocument() {
         if (myAsDocument == null) {
             final DocumentBuilder builder = BuilderFactory.start();
             builder.addInteger("getlasterror", 1);
             if (isWaitForJournal()) {
                 builder.addBoolean("j", true);
             }
             if (isWaitForFsync()) {
                 builder.addBoolean("fsync", true);
             }
             if (getWaitTimeoutMillis() > 0) {
                 builder.addInteger("wtimeout", getWaitTimeoutMillis());
             }
 
             if (getWaitForReplicas() >= 1) {
                 builder.addInteger("w", getWaitForReplicas());
             }
             else if (getWaitForReplicasByMode() != null) {
                 builder.addString("w", getWaitForReplicasByMode());
             }
 
             myAsDocument = new ImmutableDocument(builder);
         }
         return myAsDocument;
     }
 
     /**
      * Determines if the passed object is of this same type as this object and
      * if so that its fields are equal.
      * 
      * @param object
      *            The object to compare to.
      * 
      * @see java.lang.Object#equals(java.lang.Object)
      */
     @Override
     public boolean equals(final Object object) {
         boolean result = false;
         if (this == object) {
             result = true;
         }
         else if ((object != null) && (getClass() == object.getClass())) {
             final Durability other = (Durability) object;
 
             result = (myWaitForReply == other.myWaitForReply)
                     && (myWaitForFsync == other.myWaitForFsync)
                     && (myWaitForJournal == other.myWaitForJournal)
                     && (myWaitForReplicas == other.myWaitForReplicas)
                     && (myWaitTimeoutMillis == other.myWaitTimeoutMillis)
                     && nullSafeEquals(myWaitForReplicasByMode,
                             other.myWaitForReplicasByMode);
         }
         return result;
     }
 
     /**
      * 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.
      * 
      * @return 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.
      */
     public int getWaitForReplicas() {
         return myWaitForReplicas;
     }
 
     /**
      * If the value is non-<code>null</code> then wait for the specified
      * replication mode configured on the server. A built-in mode of
      * {@link #MAJORITY_MODE} is also supported.
      * 
      * @return If the value is non-null then wait for the specified replication
      *         mode configured on the server.
      * @see <a
      *      href="http://www.mongodb.org/display/DOCS/Data+Center+Awareness">Data
      *      Center Awareness</a>
      */
     public String getWaitForReplicasByMode() {
         return myWaitForReplicasByMode;
     }
 
     /**
      * Returns the number of milliseconds to wait for the durability
      * requirements to be satisfied.
      * 
      * @return The number of milliseconds to wait for the durability
      *         requirements to be satisfied.
      */
     public int getWaitTimeoutMillis() {
         return myWaitTimeoutMillis;
     }
 
     /**
      * Computes a reasonable hash code.
      * 
      * @return The hash code value.
      */
     @Override
     public int hashCode() {
         int result = 1;
         result = (31 * result) + (myWaitForReply ? 1 : 3);
         result = (31 * result) + (myWaitForFsync ? 1 : 3);
         result = (31 * result) + (myWaitForJournal ? 1 : 3);
         result = (31 * result)
                 + ((myWaitForReplicasByMode != null) ? myWaitForReplicasByMode
                         .hashCode() : 3);
         result = (31 * result) + myWaitForReplicas;
         result = (31 * result) + myWaitTimeoutMillis;
         return result;
     }
 
     /**
      * Returns if the durability requires that the response wait for an fsync()
      * of the data on the server to complete.
      * 
      * @return True if the durability requires that the response wait for an
      *         fsync() of the data to complete, false otherwise.
      */
     public boolean isWaitForFsync() {
         return myWaitForFsync;
     }
 
     /**
      * Returns if the durability requires that the response wait for the data to
      * be written to the server's journal.
      * 
      * @return True if if the durability requires that the response wait for the
      *         data to be written to the server's journal, false otherwise.
      */
     public boolean isWaitForJournal() {
         return myWaitForJournal;
     }
 
     /**
      * Returns if the durability requires that the response wait for a reply
      * from the server but potentially no special server processing.
      * 
      * @return True if the durability requires that the response wait for a
      *         reply from the server but potentially no special server
      *         processing.
      */
     public boolean isWaitForReply() {
         return myWaitForReply;
     }
 
     /**
      * {@inheritDoc}
      * <p>
      * Overriden to return the durability as JSON text.
      * </p>
      */
     @Override
     public String toString() {
         String result;
         if (NONE.equals(this)) {
             result = "NONE";
         }
         else if (ACK.equals(this)) {
             result = "ACK";
         }
         else {
             // Render as a JSON Document on a single line.
             final StringWriter sink = new StringWriter();
             final JsonSerializationVisitor visitor = new JsonSerializationVisitor(
                     sink, true);
             asDocument().accept(visitor);
 
             result = sink.toString();
         }
         return result;
     }
 
     /**
      * Does a null safe equals comparison.
      * 
      * @param rhs
      *            The right-hand-side of the comparison.
      * @param lhs
      *            The left-hand-side of the comparison.
      * @return True if the rhs equals the lhs. Note: nullSafeEquals(null, null)
      *         returns true.
      */
     protected boolean nullSafeEquals(final Object rhs, final Object lhs) {
         return (rhs == lhs) || ((rhs != null) && rhs.equals(lhs));
     }
 
     /**
      * Hook into serialization to replace <tt>this</tt> object with the local
      * {@link #ACK} or {@link #NONE} instance as appropriate.
      * 
      * @return Either the {@link #ACK} or {@link #NONE} instance if
      *         <tt>this</tt> instance equals one of those instances otherwise
      *         <tt>this</tt> instance.
      */
     private Object readResolve() {
         if (this.equals(ACK)) {
             return ACK;
         }
         else if (this.equals(NONE)) {
             return NONE;
         }
         else {
             return this;
         }
     }
 }