001/*
002 *  Copyright 2018 Anyware Services
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.ametys.plugins.repository.data.holder;
017
018import java.util.List;
019import java.util.Map;
020import java.util.Optional;
021
022import org.ametys.plugins.repository.data.DataComment;
023import org.ametys.plugins.repository.data.external.ExternalizableDataProvider.ExternalizableDataStatus;
024import org.ametys.plugins.repository.data.holder.group.ModifiableModelAwareComposite;
025import org.ametys.plugins.repository.data.holder.group.ModifiableModelAwareRepeater;
026import org.ametys.plugins.repository.data.holder.values.SynchronizationContext;
027import org.ametys.plugins.repository.data.holder.values.SynchronizationResult;
028import org.ametys.runtime.model.ViewItemAccessor;
029import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
030import org.ametys.runtime.model.exception.BadItemTypeException;
031import org.ametys.runtime.model.exception.UndefinedItemPathException;
032
033/**
034 * Interface for modifiable data containers with models
035 */
036public interface ModifiableModelAwareDataHolder extends ModifiableDataHolder, ModelAwareDataHolder
037{
038    @Override
039    public ModifiableModelAwareComposite getComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
040    
041    @Override
042    public ModifiableModelAwareComposite getLocalComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
043    
044    @Override
045    public ModifiableModelAwareComposite getExternalComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
046    
047    @Override
048    public ModifiableModelAwareRepeater getRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
049    
050    @Override
051    public ModifiableModelAwareRepeater getLocalRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
052    
053    @Override
054    public ModifiableModelAwareRepeater getExternalRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
055    
056    /**
057     * {@inheritDoc}
058     * @throws UndefinedItemPathException if the given composite path is not defined by the model
059     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
060     */
061    @Override
062    public ModifiableModelAwareComposite getComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
063    
064    /**
065     * Retrieves the local composite at the given path
066     * @param compositePath path of the externalizable composite to retrieve
067     * @param createNew <code>true</code> to create the composite if it does not exist, <code>false</code> otherwise
068     * @return the composite or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
069     * @throws IllegalArgumentException if the given composite path is null or empty
070     * @throws BadItemTypeException if the stored value at the given path is not a composite
071     * @throws UndefinedItemPathException if the given composite path is not defined by the model
072     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
073     */
074    public ModifiableModelAwareComposite getLocalComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
075    
076    /**
077     * Retrieves the external composite at the given path
078     * @param compositePath path of the externalizable composite to retrieve
079     * @param createNew <code>true</code> to create the composite if it does not exist, <code>false</code> otherwise
080     * @return the composite or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
081     * @throws IllegalArgumentException if the given composite path is null or empty
082     * @throws BadItemTypeException if the stored value at the given path is not a composite
083     * @throws UndefinedItemPathException if the given composite path is not defined by the model
084     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
085     */
086    public ModifiableModelAwareComposite getExternalComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
087    
088    /**
089     * Retrieves the repeater at the given path
090     * @param repeaterPath path of the repeater to retrieve
091     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
092     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
093     * @throws IllegalArgumentException if the given repeater path is null or empty
094     * @throws BadItemTypeException if the stored value at the given path is not a repeater
095     * @throws UndefinedItemPathException if the given composite path is not defined by the model
096     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
097     */
098    public ModifiableModelAwareRepeater getRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
099    
100    /**
101     * Retrieves the local repeater at the given path
102     * @param repeaterPath path of the externalizable repeater to retrieve
103     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
104     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
105     * @throws IllegalArgumentException if the given repeater path is null or empty
106     * @throws BadItemTypeException if the stored value at the given path is not a repeater
107     * @throws UndefinedItemPathException if the given composite path is not defined by the model
108     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
109     */
110    public ModifiableModelAwareRepeater getLocalRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
111    
112    /**
113     * Retrieves the external repeater at the given path
114     * @param repeaterPath path of the externalizable repeater to retrieve
115     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
116     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
117     * @throws IllegalArgumentException if the given repeater path is null or empty
118     * @throws BadItemTypeException if the stored value at the given path is not a repeater
119     * @throws UndefinedItemPathException if the given composite path is not defined by the model
120     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
121     */
122    public ModifiableModelAwareRepeater getExternalRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
123    
124    /**
125     * Synchronizes the given values with the current ones
126     * @param <T> the type of the {@link SynchronizationResult}
127     * @param values the values to synchronize
128     * @return the {@link SynchronizationResult}
129     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
130     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
131     */
132    public <T extends SynchronizationResult> T synchronizeValues(Map<String, Object> values) throws UndefinedItemPathException, BadItemTypeException;
133    
134    /**
135     * Synchronizes the given values with the current ones
136     * @param <T> the type of the {@link SynchronizationResult}
137     * @param values the values to synchronize
138     * @param context the context of the synchronization
139     * @return the {@link SynchronizationResult}
140     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
141     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
142     */
143    public <T extends SynchronizationResult> T synchronizeValues(Map<String, Object> values, SynchronizationContext context) throws UndefinedItemPathException, BadItemTypeException;
144    
145    /**
146     * Synchronizes the given values with the current ones
147     * @param <T> the type of the {@link SynchronizationResult}
148     * @param viewItemAccessor The {@link ViewItemAccessor} for all items to synchronize
149     * @param values the values to synchronize
150     * @return the {@link SynchronizationResult}
151     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
152     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
153     */
154    public <T extends SynchronizationResult> T synchronizeValues(ViewItemAccessor viewItemAccessor, Map<String, Object> values) throws UndefinedItemPathException, BadItemTypeException;
155    
156    /**
157     * Synchronizes the given values with the current {@link ModifiableModelAwareDataHolder}'s ones
158     * @param <T> the type of the {@link SynchronizationResult}
159     * @param viewItemAccessor The {@link ViewItemAccessor} for all items to synchronize
160     * @param values the values to synchronize
161     * @param context the context of the synchronization
162     * @return the {@link SynchronizationResult}
163     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
164     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
165     */
166    public <T extends SynchronizationResult> T synchronizeValues(ViewItemAccessor viewItemAccessor, Map<String, Object> values, SynchronizationContext context) throws UndefinedItemPathException, BadItemTypeException;
167    
168    /**
169     * Sets the value of the data at the given path
170     * @param dataPath path of the data
171     * @param value the value to set. Give <code>null</code> to empty the value.
172     * @throws IllegalArgumentException if the given data path is null or empty
173     * @throws UndefinedItemPathException if the given data path is not defined by the model
174     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
175     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
176     */
177    public void setValue(String dataPath, Object value) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
178    
179    /**
180     * Sets the local value of the data at the given path
181     * @param dataPath path of the externalizable data
182     * @param localValue the local value to set. Give <code>null</code> to empty the value.
183     * @throws IllegalArgumentException if the given data path is null or empty
184     * @throws UndefinedItemPathException if the given data path is not defined by the model
185     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
186     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
187     */
188    public void setLocalValue(String dataPath, Object localValue) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
189    
190    /**
191     * Sets the external value of the data at the given path
192     * @param dataPath path of the externalizable data
193     * @param externalValue the external value to set. Give <code>null</code> to empty the value.
194     * @throws IllegalArgumentException if the given data path is null or empty
195     * @throws UndefinedItemPathException if the given data path is not defined by the model
196     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
197     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
198     */
199    public void setExternalValue(String dataPath, Object externalValue) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
200
201    /**
202     * Set the status of the data at the given path
203     * @param dataPath path of the externalizable data
204     * @param status the new status
205     * @throws IllegalArgumentException if the given data path is null or empty
206     * @throws UndefinedItemPathException if the given data path is not defined by the model
207     * @throws BadItemTypeException if there is a type issue while getting the parent (part of the dataPath without the last segment) 
208     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
209     */
210    public void setStatus(String dataPath, ExternalizableDataStatus status) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
211    
212    /**
213     * Set the comments of the data with the given name 
214     * @param dataName name of the data
215     * @param comments the comments to set
216     * @throws IllegalArgumentException if the given data name is null or empty
217     * @throws UndefinedItemPathException if the given data name is not defined by the model
218     */
219    public void setComments(String dataName, List<DataComment> comments) throws IllegalArgumentException, UndefinedItemPathException;
220    
221    /**
222     * {@inheritDoc}
223     * @throws UndefinedItemPathException if the given data path is not defined by the model
224     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
225     */
226    @Override
227    public void removeValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
228    
229    /**
230     * Removes the local value of the data at the given path
231     * @param dataPath path of the externalizable data
232     * @throws IllegalArgumentException if the given data path is null or empty
233     * @throws UndefinedItemPathException if the given data path is not defined by the model
234     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
235     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
236     */
237    public void removeLocalValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
238    
239    /**
240     * Removes the external value of the data at the given path
241     * @param dataPath path of the externalizable data
242     * @throws IllegalArgumentException if the given data path is null or empty
243     * @throws UndefinedItemPathException if the given data path is not defined by the model
244     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
245     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
246     */
247    public void removeExternalValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
248    
249    /**
250     * Removes the stored metadata (status and alternative value) for externalizable (or ex-externalizable) data
251     * @param dataPath path of the data
252     * @throws IllegalArgumentException if the given data path is null or empty
253     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
254     * @throws UndefinedItemPathException if the given data path is not defined by the model
255     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
256     */
257    public void removeExternalizableMetadataIfExists(String dataPath) throws IllegalArgumentException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
258    
259    @Override
260    public Optional<? extends ModifiableModelAwareDataHolder> getParentDataHolder();
261    
262    @Override
263    public ModifiableModelAwareDataHolder getRootDataHolder();
264}