// Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.documentapi;

import com.yahoo.document.Document;
import com.yahoo.document.DocumentId;
import com.yahoo.document.DocumentPut;
import com.yahoo.document.DocumentRemove;
import com.yahoo.document.DocumentUpdate;
import com.yahoo.documentapi.messagebus.protocol.DocumentProtocol;

import java.time.Duration;

/**
 * A session for synchronous access to a document repository. This class
 * provides simple document access where throughput is not a concern.
 *
 * @author Simon Thoresen Hult
 * @author bjorncs
 */
public interface SyncSession extends Session {

    /**
     * Puts a document. When this method returns, the document is safely
     * received. This enables setting condition compared to using Document.
     *
     * @param documentPut the DocumentPut operation
     */
    void put(DocumentPut documentPut);

    /**
     * Puts a document. When this method returns, the document is safely received.
     *
     * @param documentPut the DocumentPut operation
     * @param priority the priority with which to perform this operation
     */
    default void put(DocumentPut documentPut, DocumentProtocol.Priority priority) {
        put(documentPut);
    }

    /**
     * Gets a document.
     *
     * @param id the id of the document to get.
     * @return the known document having this id, or null if there is no document having this id
     * @throws UnsupportedOperationException thrown if this access does not support retrieving
     */
    default Document get(DocumentId id) { return get(id, null); }

    /**
     * Gets a document with an unspecified timeout
     *
     * @param id       the id of the document to get
     * @param fieldSet a comma-separated list of fields to retrieve
     * @param priority the priority with which to perform this operation
     * @return the document with this id, or null if there is none
     * @throws UnsupportedOperationException thrown if this does not support retrieving
     */
    default Document get(DocumentId id, String fieldSet, DocumentProtocol.Priority priority) {
        return get(id, fieldSet, priority, null);
    }

    /**
     * Gets a document with timeout.
     *
     * @param id the id of the document to get
     * @param timeout timeout. If timeout is null, an unspecified default will be used
     * @return the document with this id, or null if there is none
     * @throws UnsupportedOperationException thrown if this access does not support retrieving
     * @throws DocumentAccessException on any messagebus error, including timeout ({@link com.yahoo.messagebus.ErrorCode#TIMEOUT}).
     */
    Document get(DocumentId id, Duration timeout);

    /**
     * Gets a document with timeout.
     *
     * @param id       the id of the document to get
     * @param fieldSet a comma-separated list of fields to retrieve
     * @param priority the priority with which to perform this operation
     * @param timeout timeout. If timeout is null, an unspecified default will be used
     * @return the known document having this id, or null if there is no document having this id
     * @throws UnsupportedOperationException thrown if this access does not support retrieving
     * @throws DocumentAccessException on any messagebus error, including timeout ({@link com.yahoo.messagebus.ErrorCode#TIMEOUT})
     */
    Document get(DocumentId id, String fieldSet, DocumentProtocol.Priority priority, Duration timeout);

    /**
     * Removes a document if it is present and condition is fulfilled.
     *
     * @param documentRemove document to delete
     * @return true if the document with this id was removed, false otherwise
     */
    boolean remove(DocumentRemove documentRemove);

    /**
     * Removes a document if it is present.
     *
     * @param documentRemove document remove operation
     * @param priority the priority with which to perform this operation
     * @return true if the document with this id was removed, false otherwise.
     * @throws UnsupportedOperationException thrown if this access does not support removal
     */
    boolean remove(DocumentRemove documentRemove, DocumentProtocol.Priority priority);

    /**
     * Updates a document.
     *
     * @param update the updates to perform
     * @return true, if the document was found and updated
     * @throws UnsupportedOperationException thrown if this access does not support update
     */
    boolean update(DocumentUpdate update);

    /**
     * Updates a document.
     *
     * @param update   the updates to perform.
     * @param priority the priority with which to perform this operation
     * @return true, if the document was found and updated
     * @throws UnsupportedOperationException thrown if this access does not support update
     */
    boolean update(DocumentUpdate update, DocumentProtocol.Priority priority);

}

@@ -341,16 +341,63 @@
 Update;%0A
+import com.yahoo.document.TestAndSetCondition;%0A
 import c
@@ -4417,506 +4417,1030 @@
 urn 
-true, if the document was found and updated%0A     * @throws UnsupportedOperationException thrown if this access does not support update%0A     */%0A    boolean update(DocumentUpdate update);%0A%0A    /**%0A     * Updates a document.%0A     *%0A     * @param update   the updates to perform.%0A     * @param priority the priority with which to perform this operation%0A     * @return true, if the document was found and updated%0A     * @throws UnsupportedOperationException thrown if this access does not support update
+false if the updates could not be applied as the document does not exist and%0A     * %7B@link DocumentUpdate#setCreateIfNonExistent(boolean) create-if-non-existent%7D is not set.%0A     * @throws DocumentAccessException on update error, including but not limited to: 1. timeouts,%0A     * 2. the document exists but the %7B@link DocumentUpdate#setCondition(TestAndSetCondition) condition%7D%0A     * is not met.%0A     */%0A    boolean update(DocumentUpdate update);%0A%0A    /**%0A     * Updates a document.%0A     *%0A     * @param update   the updates to perform.%0A     * @param priority the priority with which to perform this operation%0A     * @return false if the updates could not be applied as the document does not exist and%0A     * %7B@link DocumentUpdate#setCreateIfNonExistent(boolean) create-if-non-existent%7D is not set.%0A     * @throws DocumentAccessException on update error, including but not limited to: 1. timeouts,%0A     * 2. the document exists but the %7B@link DocumentUpdate#setCondition(TestAndSetCondition) condition%7D%0A     * is not met.
 %0A   

Update return and throws javadoc for SyncSession::update