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.document;
017
018
019public interface Editor extends EditableDocument {
020
021    /**
022     * Get the changes that have been made to this document.
023     * 
024     * @return the changes; never null
025     */
026    Changes getChanges();
027
028    /**
029     * After making changes to another document, apply the same changes to this document. This allows a set of changes to be made,
030     * serialized, and applied to a different document (that often represents a different instance of the same document).
031     * 
032     * @param changes the changes that are to be applied to this document; may not be null
033     * @see #apply(Changes, Observer)
034     */
035    void apply( Changes changes );
036
037    /**
038     * After making changes to another document, apply the same changes to this document. This allows a set of changes to be made,
039     * serialized, and applied to a different document (that often represents a different instance of the same document).
040     * 
041     * @param changes the changes that are to be applied to this document; may not be null
042     * @param observer an observer that will be called as changes are undone; may be null
043     * @see #apply(Changes)
044     */
045    void apply( Changes changes,
046                Observer observer );
047
048    /**
049     * An interface that can be supplied to the {@link Editor#apply(Changes,Observer)} and {@link Editor#apply(Changes, Observer)}
050     * methods to receive notifications of the changes that were applied or undone.
051     * 
052     * @author Randall Hauch <rhauch@redhat.com> (C) 2011 Red Hat Inc.
053     * @since 5.1
054     */
055    public static interface Observer {
056
057        /**
058         * Set the supplied entry in the array at the given path.
059         * 
060         * @param path the path within the document of the array
061         * @param entry the entry containing the new value and the index
062         */
063        void setArrayValue( Path path,
064                            Array.Entry entry );
065
066        /**
067         * Insert the entry into the array at the given path.
068         * 
069         * @param path the path within the document of the array
070         * @param entry the entry containing the new value and the index
071         */
072        void addArrayValue( Path path,
073                            Array.Entry entry );
074
075        /**
076         * Remove the entry from the array at the given path.
077         * 
078         * @param path the path within the document of the array
079         * @param entry the entry containing the new value and the index
080         */
081        void removeArrayValue( Path path,
082                               Array.Entry entry );
083
084        /**
085         * Remove all fields from the document at the supplied path.
086         * 
087         * @param path the path to the document
088         */
089        void clear( Path path );
090
091        /**
092         * Set to the given value the field in the document at the supplied path.
093         * 
094         * @param parentPath the path to the parent document in which the field should be updated
095         * @param field the name of the field to be updated
096         * @param newValue the new value
097         */
098        void put( Path parentPath,
099                  String field,
100                  Object newValue );
101
102        /**
103         * Remove the field from the document at the supplied path.
104         * 
105         * @param parentPath the path to the parent document in which the field should be removed
106         * @param field the name of the field to be removed
107         */
108        void remove( Path parentPath,
109                     String field );
110
111    }
112
113}