001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.schematic.internal.document;
017
018import java.util.ArrayList;
019import java.util.Map;
020import org.modeshape.schematic.document.Document;
021import org.modeshape.schematic.document.EditableDocument;
022import org.modeshape.schematic.document.Editor;
023
024/**
025 * A mutable {@link Document} used when building a MutableBsonObject.
026 * 
027 * @author Randall Hauch <rhauch@redhat.com> (C) 2011 Red Hat Inc.
028 */
029public interface MutableDocument extends Document {
030
031    /**
032     * Sets a name/value pair in this object.
033     * 
034     * @param name The name; may not be null
035     * @param value The value; may be null
036     * @return the previous value
037     */
038    public Object put( String name,
039                       Object value );
040
041    /**
042     * Sets on this object all name/value pairs from the supplied object. If the supplied object is null, this method does
043     * nothing.
044     * 
045     * @param object the object containing the name/value pairs to be set on this object
046     */
047    public void putAll( Document object );
048
049    /**
050     * Sets on this object all key/value pairs from the supplied map. If the supplied map is null, this method does nothing.
051     * 
052     * @param map the map containing the name/value pairs to be set on this object
053     */
054    public void putAll( Map<? extends String, ?> map );
055
056    /**
057     * Removes from this object the name/value pair with the given name.
058     * 
059     * @param name The name of the pair to remove
060     * @return The value removed from this object, or null this object does not contain a pair with the supplied name
061     */
062    public Object remove( String name );
063
064    /**
065     * Remove all fields from this document.
066     */
067    public void removeAll();
068
069    @Override
070    MutableDocument clone();
071
072    @Override
073    default Editor edit(boolean clone) {
074        return clone ? new IncrementalDocumentEditor(this.clone(), new ArrayList<>()) : new IncrementalDocumentEditor(this, new ArrayList<>());
075    }
076
077    @Override
078    default EditableDocument editable() {
079        return new DocumentEditor(this);
080    }
081}