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.Collection;
019import java.util.List;
020import org.modeshape.schematic.document.Array;
021
022public interface MutableArray extends Array, MutableDocument {
023
024    /**
025     * Modifiable method that adds the supplied value if not already in the array. This method should <i>not</i> be called by
026     * client code.
027     * 
028     * @param value the value to be added
029     * @return true if the value was added, or false if the value was already in the array.
030     */
031    boolean addValueIfAbsent( Object value );
032
033    /**
034     * Modifiable method that adds the supplied value. This method should <i>not</i> be called by client code.
035     * 
036     * @param value the value to be added
037     * @return the index at which the value was added, or -1 if the value could not be added
038     */
039    int addValue( Object value );
040
041    /**
042     * Modifiable method that adds the supplied value at the supplied index, shifting any existing values to the next higher index
043     * value. This method should <i>not</i> be called by client code.
044     * 
045     * @param index the index
046     * @param value the value to be added
047     */
048    void addValue( int index,
049                   Object value );
050
051    /**
052     * Modifiable method that sets the supplied value at the given index. This method should <i>not</i> be called by client code.
053     * 
054     * @param index the index
055     * @param value the value to be added
056     * @return true if the value was added, or false if it could not be added
057     */
058    Object setValue( int index,
059                     Object value );
060
061    /**
062     * Modifiable method that removes the supplied value. This method should <i>not</i> be called by client code.
063     * 
064     * @param value the value to be removed
065     * @return true if the value was removed, or false if the value was not in the array
066     */
067    boolean removeValue( Object value );
068
069    /**
070     * Modifiable method that removes the value at the supplied index. This method should <i>not</i> be called by client code.
071     * 
072     * @param index the index of the value to be removed
073     * @return the value that was at the index
074     */
075    Object removeValue( int index );
076
077    /**
078     * Modifiable method that adds the supplied values at the end of this array. This method should <i>not</i> be called by client
079     * code.
080     * 
081     * @param values the values to be added
082     * @return true if this array changed as a result of the operation
083     */
084    boolean addAllValues( Collection<?> values );
085
086    /**
087     * Modifiable method that adds the supplied values at the supplied index, shifting any existing values to the next higher
088     * index value. This method should <i>not</i> be called by client code.
089     * 
090     * @param index the index at which the values are to be inserted
091     * @param values the values to be added
092     * @return true if this array changed as a result of the operation
093     */
094    boolean addAllValues( int index,
095                          Collection<?> values );
096
097    /**
098     * Modifiable method that removes all of the values from this array. This method should <i>not</i> be called by client code.
099     */
100    @Override
101    void removeAll();
102
103    /**
104     * Modifiable method that removes all of the supplied values from this array. This method should <i>not</i> be called by
105     * client code.
106     * 
107     * @param values the values to be removed
108     * @return the entries that were removed; never null but possibly empty if this array was not modified by this operation
109     */
110    List<Entry> removeAllValues( Collection<?> values );
111
112    /**
113     * Modifiable method that removes all of the values in this array except the supplied values. This method should <i>not</i> be
114     * called by client code.
115     * 
116     * @param values the values to be kept, while all others are removed
117     * @return the entries that were removed; never null but possibly empty if this array was not modified by this operation
118     */
119    List<Entry> retainAllValues( Collection<?> values );
120
121    @Override
122    MutableArray clone();
123}