/*
 * ModeShape (http://www.modeshape.org)
 *
 * 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.
 */
package org.modeshape.schematic.document;

import java.text.ParseException;
import java.util.ArrayList;
import java.util.Date;
import java.util.Map;
import java.util.UUID;
import java.util.regex.Pattern;
import org.modeshape.schematic.document.Bson.BinaryType;
import org.modeshape.schematic.internal.document.IncrementalDocumentEditor;
import org.modeshape.schematic.internal.document.MutableDocument;

public interface EditableDocument extends Document {

    /**
     * Unwrap this editor to obtain the potentially wrapped document.
     * 
     * @return the wrapped document, or this object; never null
     */
    Document unwrap();

    /**
     * Remove the field with the supplied name, and return the value.
     * 
     * @param name The name of the field
     * @return the value that was removed, or null if there was no such value
     */
    Object remove( String name );

    /**
     * Returns the underlying mutable document. 
     * 
     * @return a {@link MutableDocument} instance; never null
     */
    MutableDocument asMutableDocument();

    /**
     * Remove all fields from this document.
     */
    void removeAll();

    /**
     * Sets on this object all name/value pairs from the supplied object. If the supplied object is null, this method does
     * nothing.
     * 
     * @param object the object containing the name/value pairs to be set on this object
     */
    void putAll( Document object );

    /**
     * Sets on this object all key/value pairs from the supplied map. If the supplied map is null, this method does nothing.
     * 
     * @param map the map containing the name/value pairs to be set on this object
     */
    void putAll( Map<? extends String, ? extends Object> map );

    /**
     * Merges the supplied document onto this document. This will set on this document each of the fields in the supplied
     * document; nested documents in the supplied document will be merged recursively.
     * <p>
     * Consider the following example. If this document contains:
     * 
     * <pre>
     * {
     *   "firstName" : "Jane",
     *   "lastName" : "Smith",
     *   "address" : {
     *     "street" : "Main Street",
     *     "city" : "Springfield"
     *   },
     *   "phone" : "(800)555-1212"
     * }
     * </pre>
     * 
     * and another document 'other' contains:
     * 
     * <pre>
     * {
     *   "lastName" : "Doe",
     *   "address" : {
     *     "city" : "Memphis",
     *     "zip" : 12345
     *   },
     *   "phone" : {
     *     "home" : "(800)555-1212"
     *   }
     * }
     * </pre>
     * 
     * then merging 'other' onto the first will result in the first being modified to contain:
     * 
     * <pre>
     * {
     *   "firstName" : "Jane",
     *   "lastName" : "Doe",
     *   "address" : {
     *     "street" : "Main Street",
     *     "city" : "Memphis",
     *     "zip" : 12345
     *   },
     *   "phone" : {
     *     "home" : "(800)555-1212"
     *   }
     * }
     * </pre>
     * 
     * @param other the other document whose values should be merged
     */
    void merge( Document other );

    /**
     * Set the value for the field with the given name to the supplied value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument set( String name,
                          Object value );

    /**
     * Set the value for the field with the given name to the supplied boolean value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setBoolean( String name,
                                 boolean value );

    /**
     * Set the value for the field with the given name to the supplied integer value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setNumber( String name,
                                int value );

    /**
     * Set the value for the field with the given name to the supplied long value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setNumber( String name,
                                long value );

    /**
     * Set the value for the field with the given name to the supplied float value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setNumber( String name,
                                float value );

    /**
     * Set the value for the field with the given name to the supplied double value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setNumber( String name,
                                double value );

    /**
     * Set the value for the field with the given name to the supplied string value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setString( String name,
                                String value );

    /**
     * Set the value for the field with the given name to a {@link Symbol} created from the supplied string value. Symbols are
     * defined in the BSON specification as being similar to a string but which exists for those languages that have a specific
     * symbol type. Symbols are serialized to JSON as a normal string.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     * @see #setString(String, String)
     */
    EditableDocument setSymbol( String name,
                                String value );

    /**
     * Set the value for the field with the given name to be a new, empty Document.
     * 
     * @param name The name of the field
     * @return The editable document that was just created; never null
     */
    EditableDocument setDocument( String name );

    /**
     * Set the value for the field with the given name to be the supplied Document.
     * 
     * @param name The name of the field
     * @param document the document
     * @return The editable document that was just set as the value for the named field; never null and may or may not be the same
     *         instance as the supplied <code>document</code>.
     */
    EditableDocument setDocument( String name,
                                  Document document );

    /**
     * Get the existing document value in this document for the given field name.
     * 
     * @param name The name of the pair
     * @return The editable document field value, if found, or null if there is no such pair or if the value is not a document
     */
    @Override
    EditableDocument getDocument( String name );

    /**
     * Get the existing document value in this document for the given field name, or create a new document if there is no existing
     * document at this field.
     * 
     * @param name The name of the pair
     * @return The editable document field value; never null
     */
    EditableDocument getOrCreateDocument( String name );

    /**
     * Set the value for the field with the given name to be a new, empty array.
     * 
     * @param name The name of the field
     * @return The editable array that was just created; never null
     */
    EditableArray setArray( String name );

    /**
     * Set the value for the field with the given name to be the supplied array.
     * 
     * @param name The name of the field
     * @param array the array
     * @return The editable array that was just set as the value for the named field; never null and may or may not be the same
     *         instance as the supplied <code>array</code>.
     */
    EditableArray setArray( String name,
                            Array array );

    /**
     * Set the value for the field with the given name to be the supplied array.
     * 
     * @param name The name of the field
     * @param values the (valid) values for the array
     * @return The editable array that was just set as the value for the named field; never null and may or may not be the same
     *         instance as the supplied <code>array</code>.
     */
    EditableArray setArray( String name,
                            Object... values );

    /**
     * Get the existing array value in this document for the given field name.
     * 
     * @param name The name of the pair
     * @return The editable array field value (as a list), if found, or null if there is no such pair or if the value is not an
     *         array
     */
    @Override
    EditableArray getArray( String name );

    /**
     * Get the existing array value in this document for the given field name, or create a new array if there is no existing array
     * at this field.
     * 
     * @param name The name of the pair
     * @return The editable array field value; never null
     */
    EditableArray getOrCreateArray( String name );

    /**
     * Set the value for the field with the given name to the supplied date value.
     * 
     * @param name The name of the field
     * @param value the new value for the field
     * @return This document, to allow for chaining methods
     */
    EditableDocument setDate( String name,
                              Date value );

    /**
     * Set the value for the field with the given name to the date value parsed from the ISO-8601 date representation.
     * Specifically, the date string must match one of these patterns:
     * <ul>
     * <li>"<code><i>yyyy</i>-<i>MM</i>-<i>dd</i>T<i>HH</i>:<i>mm</i>:<i>ss</i></code>" where "<code>T</code>" is a literal
     * character</li>
     * <li>"<code><i>yyyy</i>-<i>MM</i>-<i>dd</i>T<i>HH</i>:<i>mm</i>:<i>ss</i>Z</code>" where "<code>T</code>" and "
     * <code>Z</code>" are literal characters</li>
     * <li>"<code><i>yyyy</i>-<i>MM</i>-<i>dd</i>T<i>HH</i>:<i>mm</i>:<i>ss</i>GMT+<i>00</i>:<i>00</i></code>" where "
     * <code>T</code>", and "<code>GMT</code>" are literal characters</li>
     * </ul>
     * 
     * @param name The name of the field
     * @param isoDate the new value for the field
     * @return This document, to allow for chaining methods
     * @throws ParseException if the supplied value could not be parsed into a valid date
     */
    EditableDocument setDate( String name,
                              String isoDate ) throws ParseException;

    /**
     * Set the value for the field with the given name to a {@link Timestamp} with the supplied time in seconds and increment.
     * Note that {@link Date} values are recommended for most purposes, as they are better suited to most applications'
     * representations of time instants.
     * 
     * @param name The name of the field
     * @param timeInSeconds the time in seconds for the new Timestamp
     * @param increment the time increment for the new Timestamp
     * @return This document, to allow for chaining methods
     * @see #setDate(String, Date)
     */
    EditableDocument setTimestamp( String name,
                                   int timeInSeconds,
                                   int increment );

    /**
     * Set the value for the field with the given name to an {@link ObjectId} created from the supplied hexadecimal binary value.
     * Object IDs are defined by the BSON specification as 12-byte binary values designed to have a reasonably high probability of
     * being unique when allocated. Since there is no explicit way to represent these in a JSON document, each ObjectId value is
     * serialized in a JSON document as a nested document of the form:
     * 
     * <pre>
     * { "$oid" : "<i>12bytesOfIdInBase16</i>" }
     * </pre>
     * 
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to an ObjectId value.
     * <p>
     * For example, an ObjectId with time value of "1310745823", machine value of "1", process value of "2", and increment value
     * of "3" would be written as
     * 
     * <pre>
     * { "$oid" : "4e2064df0000010002000003" }
     * </pre>
     * 
     * </p>
     * 
     * @param name The name of the field
     * @param hex the hexadecimal binary value for the ObjectId
     * @return This document, to allow for chaining methods
     * @see #setObjectId(String, byte[])
     * @see #setObjectId(String, int, int, int, int)
     */
    EditableDocument setObjectId( String name,
                                  String hex );

    /**
     * Set the value for the field with the given name to an {@link ObjectId} created from the supplied 12-byte binary value.
     * Object IDs are defined by the BSON specification as 12-byte binary values designed to have a reasonably high probability of
     * being unique when allocated. Since there is no explicit way to represent these in a JSON document, each ObjectId value is
     * serialized in a JSON document as a nested document of the form:
     * 
     * <pre>
     * { "$oid" : "<i>12bytesOfIdInBase16</i>" }
     * </pre>
     * 
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to an ObjectId value.
     * <p>
     * For example, an ObjectId with time value of "1310745823", machine value of "1", process value of "2", and increment value
     * of "3" would be written as
     * 
     * <pre>
     * { "$oid" : "4e2064df0000010002000003" }
     * </pre>
     * 
     * </p>
     * 
     * @param name The name of the field
     * @param bytes the 12-byte value for the ObjectId
     * @return This document, to allow for chaining methods
     * @see #setObjectId(String, String)
     * @see #setObjectId(String, int, int, int, int)
     */
    EditableDocument setObjectId( String name,
                                  byte[] bytes );

    /**
     * Set the value for the field with the given name to an {@link ObjectId} created from the supplied hexadecimal binary value.
     * Object IDs are defined by the BSON specification as 12-byte binary values designed to have a reasonably high probability of
     * being unique when allocated. Since there is no explicit way to represent these in a JSON document, each ObjectId value is
     * serialized in a JSON document as a nested document of the form:
     * 
     * <pre>
     * { "$oid" : "<i>12bytesOfIdInBase16</i>" }
     * </pre>
     * 
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to an ObjectId value.
     * <p>
     * For example, an ObjectId with time value of "1310745823", machine value of "1", process value of "2", and increment value
     * of "3" would be written as
     * 
     * <pre>
     * { "$oid" : "4e2064df0000010002000003" }
     * </pre>
     * 
     * </p>
     * 
     * @param name The name of the field
     * @param time the Unix-style timestamp, which is a signed integer representing the number of seconds before or after January
     *        1st 1970 (UTC)
     * @param machine the first three bytes of the (md5) hash of the machine host name, or of the mac/network address, or the
     *        virtual machine id
     * @param process the 2 bytes of the process id (or thread id) of the process generating the object id
     * @param inc an ever incrementing value, or a random number if a counter can't be used in the language/runtime
     * @return This document, to allow for chaining methods
     * @see #setObjectId(String, String)
     * @see #setObjectId(String, byte[])
     */
    EditableDocument setObjectId( String name,
                                  int time,
                                  int machine,
                                  int process,
                                  int inc );

    /**
     * Set the value for the field with the given name to the supplied regular expression. Regular expression values are
     * represented in memory using {@link Pattern} instances, and are stored natively in BSON as regular expressions. However,
     * when serialized to JSON, regular expressions are written as nested documents of the form:
     * 
     * <pre>
     * { "$regex" : "<i>pattern</i>" }
     * </pre>
     * 
     * where "<i>pattern</i>" is the regular expression pattern.
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to a regular expression value.
     * </p>
     * 
     * @param name The name of the field
     * @param pattern the regular expression pattern string
     * @return This document, to allow for chaining methods
     * @see #setRegularExpression(String, String, int)
     */
    EditableDocument setRegularExpression( String name,
                                           String pattern );

    /**
     * Set the value for the field with the given name to the supplied regular expression. Regular expression values are
     * represented in memory using {@link Pattern} instances, and are stored natively in BSON as regular expressions. However,
     * when serialized to JSON, regular expressions are written as nested documents of the form:
     * 
     * <pre>
     * { "$regex" : "<i>pattern</i>", "$options" : "<i>flags</i>" }
     * </pre>
     * 
     * where "<i>pattern</i>" is the regular expression pattern, and "<i>flags</i>" is a string representation of the regular
     * expression options.
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to a regular expression value.
     * </p>
     * 
     * @param name The name of the field
     * @param pattern the regular expression pattern string
     * @param flags the bitwise-anded {@link Pattern} options: {@link Pattern#CANON_EQ}, {@link Pattern#CASE_INSENSITIVE},
     *        {@link Pattern#CASE_INSENSITIVE}, {@link Pattern#COMMENTS}, {@link Pattern#DOTALL}, {@link Pattern#LITERAL},
     *        {@link Pattern#MULTILINE}, {@link Pattern#UNICODE_CASE}, and {@link Pattern#UNIX_LINES}
     * @return This document, to allow for chaining methods
     * @see #setRegularExpression(String, String)
     */
    EditableDocument setRegularExpression( String name,
                                           String pattern,
                                           int flags );

    /**
     * Set the value for the field with the given name to be a null value. Both JSON and BSON formats support null values, and
     * {@link Null} is used for the value in the in-memory representation. The {@link #isNull(String)} methods can be used to
     * determine if a field has been set to null, or {@link #isNullOrMissing(String)} if the field has not be set or if it has
     * been set to null.
     * 
     * @param name The name of the field
     * @return This document, to allow for chaining methods
     * @see #isNull(String)
     * @see #isNullOrMissing(String)
     */
    EditableDocument setNull( String name );

    /**
     * Set the value for the field with the given name to be a binary value. JSON does not formally support binary values, and so
     * such values will be encoded using a nested document of the form:
     * 
     * <pre>
     * { "$type" : <i>typeAsInt</i>, "$base64" : "<i>bytesInBase64</i>" }
     * </pre>
     * 
     * where "<i>typeAsInt</i>" is the integer representation of the {@link BinaryType BSON type}, and "<i>bytesInBase64</i>" is
     * the Base64 encoding of the actual Binary {@link Binary#getBytes() bytes}.
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to Binary value.
     * </p>
     * 
     * @param name The name of the field
     * @param type one of the {@link BinaryType BSON type} constants denoting the type of the {@link Binary} value
     * @param data the bytes for the {@link Binary} value
     * @return This document, to allow for chaining methods
     */
    EditableDocument setBinary( String name,
                                byte type,
                                byte[] data );

    /**
     * Set the value for the field with the given name to be a {@link UUID}. JSON does not formally support binary values, and so
     * such values will be encoded using a nested document of the form:
     * 
     * <pre>
     * { "$uuid" : "<i>string-form-of-uuid</i>" }
     * </pre>
     * 
     * where "<i>string-form-of-uuid</i>" is the UUID's {@link UUID#toString() string representation}
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to UUID value.
     * </p>
     * 
     * @param name The name of the field
     * @param uuid the UUID value
     * @return This document, to allow for chaining methods
     */
    EditableDocument setUuid( String name,
                              UUID uuid );

    /**
     * Set the value for the field with the given name to be a {@link Code} or {@link CodeWithScope}. JSON does not formally
     * support such values, and so when written to JSON they will be encoded using a nested document of the form:
     * 
     * <pre>
     * { "$code" : "<i>code</i>" }
     * </pre>
     * 
     * or, if there is a scope document
     * 
     * <pre>
     * { "$code" : "<i>code</i>", "$scope" : <i>scope document</i> }
     * </pre>
     * 
     * where "<i>code</i>" is the {@link Code}'s {@link Code#getCode() JavaScript code} and <i>scopeDocument</i> is the nested
     * document representing the {@link CodeWithScope#getScope() scope} in which the JavaScript code should be evaluated.
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to {@link Code} or {@link CodeWithScope} value.
     * </p>
     * <p>
     * Note that when <code>includeScope</code> is <code>true</code>, the returned {@link EditableDocument} can be used to
     * populate the scope document.
     * 
     * @param name The name of the field
     * @param code the code
     * @param includeScope true if the code should include a scope (and if this method should return an {@link EditableDocument}
     *        for this scope document), or false otherwise
     * @return if <code>includeScope</code> is <code>true</code>, then the {@link EditableDocument} for the scope; otherwise, this
     *         document to allow for chaining methods
     * @see #setCode(String, String, Document)
     */
    EditableDocument setCode( String name,
                              String code,
                              boolean includeScope );

    /**
     * Set the value for the field with the given name to be a {@link Code} or {@link CodeWithScope}. JSON does not formally
     * support such values, and so when written to JSON they will be encoded using a nested document of the form:
     * 
     * <pre>
     * { "$code" : "<i>code</i>" }
     * </pre>
     * 
     * or, if there is a scope document
     * 
     * <pre>
     * { "$code" : "<i>code</i>", "$scope" : <i>scope document</i> }
     * </pre>
     * 
     * where "<i>code</i>" is the {@link Code}'s {@link Code#getCode() JavaScript code} and <i>scopeDocument</i> is the nested
     * document representing the {@link CodeWithScope#getScope() scope} in which the JavaScript code should be evaluated.
     * <p>
     * When nested documents of this form are read by this library's {@link Json JSON reader}, nested documents of this form will
     * be converted to {@link Code} or {@link CodeWithScope} value.
     * </p>
     * 
     * @param name The name of the field
     * @param code the code
     * @param scope the scope in which the JavaScript code should be evaulated, or null if there is no scope
     * @return the {@link EditableDocument} for the scope, or null if the <code>scope</code> reference is null
     * @see #setCode(String, String, boolean)
     */
    EditableDocument setCode( String name,
                              String code,
                              Document scope );

    @Override
    EditableDocument clone();

    @Override
    default Editor edit(boolean clone) {
        return clone ?
               new IncrementalDocumentEditor(this.clone().asMutableDocument(), new ArrayList<>()) :
               new IncrementalDocumentEditor(this.asMutableDocument(), new ArrayList<>());
    }

    @Override
    default EditableDocument editable() {
        return this;
    }
}