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.io.IOException;
019import java.util.Map;
020
021import org.ametys.plugins.repository.data.UnknownDataException;
022import org.ametys.plugins.repository.data.external.ExternalizableDataProvider.ExternalizableDataStatus;
023import org.ametys.plugins.repository.data.external.ExternalizableDataProviderExtensionPoint;
024import org.ametys.plugins.repository.data.holder.group.impl.ModifiableModelAwareComposite;
025import org.ametys.plugins.repository.data.holder.group.impl.ModifiableModelAwareRepeater;
026import org.ametys.runtime.model.ViewItemContainer;
027import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
028import org.ametys.runtime.model.exception.BadItemTypeException;
029import org.ametys.runtime.model.exception.UndefinedItemPathException;
030
031/**
032 * Interface for modifiable data containers with models
033 */
034public interface ModifiableModelAwareDataHolder extends ModifiableDataHolder, ModelAwareDataHolder
035{
036    @Override
037    public ModifiableModelAwareComposite getComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
038    
039    @Override
040    public ModifiableModelAwareComposite getLocalComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
041    
042    @Override
043    public ModifiableModelAwareComposite getExternalComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
044    
045    @Override
046    public ModifiableModelAwareRepeater getRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
047    
048    @Override
049    public ModifiableModelAwareRepeater getLocalRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
050    
051    @Override
052    public ModifiableModelAwareRepeater getExternalRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
053    
054    /**
055     * {@inheritDoc}
056     * @throws UndefinedItemPathException if the given composite path is not defined by the model
057     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
058     */
059    @Override
060    public ModifiableModelAwareComposite getComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
061    
062    /**
063     * Retrieves the local composite at the given path
064     * @param compositePath path of the externalizable composite to retrieve
065     * @param createNew <code>true</code> to create the composite if it does not exist, <code>false</code> otherwise
066     * @return the composite or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
067     * @throws IllegalArgumentException if the given composite path is null or empty
068     * @throws BadItemTypeException if the stored value at the given path is not a composite
069     * @throws UndefinedItemPathException if the given composite path is not defined by the model
070     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
071     */
072    public ModifiableModelAwareComposite getLocalComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
073    
074    /**
075     * Retrieves the external composite at the given path
076     * @param compositePath path of the externalizable composite to retrieve
077     * @param createNew <code>true</code> to create the composite if it does not exist, <code>false</code> otherwise
078     * @return the composite or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
079     * @throws IllegalArgumentException if the given composite path is null or empty
080     * @throws BadItemTypeException if the stored value at the given path is not a composite
081     * @throws UndefinedItemPathException if the given composite path is not defined by the model
082     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
083     */
084    public ModifiableModelAwareComposite getExternalComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
085    
086    /**
087     * Retrieves the repeater at the given path
088     * @param repeaterPath path of the repeater to retrieve
089     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
090     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
091     * @throws IllegalArgumentException if the given repeater path is null or empty
092     * @throws BadItemTypeException if the stored value at the given path is not a repeater
093     * @throws UndefinedItemPathException if the given composite path is not defined by the model
094     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
095     */
096    public ModifiableModelAwareRepeater getRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
097    
098    /**
099     * Retrieves the local repeater at the given path
100     * @param repeaterPath path of the externalizable repeater to retrieve
101     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
102     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
103     * @throws IllegalArgumentException if the given repeater path is null or empty
104     * @throws BadItemTypeException if the stored value at the given path is not a repeater
105     * @throws UndefinedItemPathException if the given composite path is not defined by the model
106     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
107     */
108    public ModifiableModelAwareRepeater getLocalRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
109    
110    /**
111     * Retrieves the external repeater at the given path
112     * @param repeaterPath path of the externalizable repeater to retrieve
113     * @param createNew <code>true</code> to create the repeater if it does not exist, <code>false</code> otherwise
114     * @return the repeater or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
115     * @throws IllegalArgumentException if the given repeater path is null or empty
116     * @throws BadItemTypeException if the stored value at the given path is not a repeater
117     * @throws UndefinedItemPathException if the given composite path is not defined by the model
118     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
119     */
120    public ModifiableModelAwareRepeater getExternalRepeater(String repeaterPath, boolean createNew) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
121    
122    /**
123     * Synchronizes the given values with the current ones
124     * @param values the values to synchronize
125     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
126     * @throws IOException if an error occurs while synchronizing I/O data
127     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
128     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
129     */
130    public default boolean synchronizeValues(Map<String, Object> values) throws UndefinedItemPathException, BadItemTypeException, IOException
131    {
132        return synchronizeValues(values, false);
133    }
134    
135    /**
136     * Synchronizes the given values with the current ones
137     * @param values the values to synchronize
138     * @param useDefaultFromModel <code>true</code> to use default values from the model if there is no value in the {@link Map} for an item present in the view
139     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
140     * @throws IOException if an error occurs while synchronizing I/O data
141     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
142     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
143     */
144    public default boolean synchronizeValues(Map<String, Object> values, boolean useDefaultFromModel) throws UndefinedItemPathException, BadItemTypeException, IOException
145    {
146        return synchronizeValues(values, null, useDefaultFromModel);
147    }
148    
149    /**
150     * Synchronizes the given values with the current {@link ModifiableModelAwareDataHolder}'s ones
151     * If the data is externalizable, the synchronized value is the external one
152     * @param values the values to synchronize
153     * @param externalizableDataProviderEP the extrernalizable data provider extension point 
154     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
155     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
156     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
157     * @throws IOException if an error occurs while synchronizing I/O data
158     */
159    public default boolean synchronizeValues(Map<String, Object> values, ExternalizableDataProviderExtensionPoint externalizableDataProviderEP) throws UndefinedItemPathException, BadItemTypeException, IOException
160    {
161        return synchronizeValues(values, externalizableDataProviderEP, false);
162    }
163    
164    /**
165     * Synchronizes the given values with the current {@link ModifiableModelAwareDataHolder}'s ones
166     * If the data is externalizable, the synchronized value is the external one
167     * @param values the values to synchronize
168     * @param externalizableDataProviderEP the extrernalizable data provider extension point
169     * @param useDefaultFromModel <code>true</code> to use default values from the model if there is no value in the {@link Map} for an item present in the view
170     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
171     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
172     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
173     * @throws IOException if an error occurs while synchronizing I/O data
174     */
175    public boolean synchronizeValues(Map<String, Object> values, ExternalizableDataProviderExtensionPoint externalizableDataProviderEP, boolean useDefaultFromModel) throws UndefinedItemPathException, BadItemTypeException, IOException;
176    
177    /**
178     * Synchronizes the given values with the current ones
179     * @param viewItemContainer The {@link ViewItemContainer} containing all items to synchronize
180     * @param values the values to synchronize
181     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
182     * @throws IOException if an error occurs while synchronizing I/O data
183     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
184     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
185     */
186    public default boolean synchronizeValues(ViewItemContainer viewItemContainer, Map<String, Object> values) throws UndefinedItemPathException, BadItemTypeException, IOException
187    {
188        return synchronizeValues(viewItemContainer, values, false);
189    }
190    
191    /**
192     * Synchronizes the given values with the current ones
193     * @param viewItemContainer The {@link ViewItemContainer} containing all items to synchronize
194     * @param values the values to synchronize
195     * @param useDefaultFromModel <code>true</code> to use default values from the model if there is no value in the {@link Map} for an item present in the view
196     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
197     * @throws IOException if an error occurs while synchronizing I/O data
198     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
199     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
200     */
201    public default boolean synchronizeValues(ViewItemContainer viewItemContainer, Map<String, Object> values, boolean useDefaultFromModel) throws UndefinedItemPathException, BadItemTypeException, IOException
202    {
203        return synchronizeValues(viewItemContainer, values, null, useDefaultFromModel);
204    }
205    
206    /**
207     * Synchronizes the given values with the current {@link ModifiableModelAwareDataHolder}'s ones
208     * If the data is externalizable, the synchronized value is the external one
209     * @param viewItemContainer The {@link ViewItemContainer} containing all items to synchronize
210     * @param values the values to synchronize
211     * @param externalizableDataProviderEP the extrernalizable data provider extension point 
212     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
213     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
214     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
215     * @throws IOException if an error occurs while synchronizing I/O data
216     */
217    public default boolean synchronizeValues(ViewItemContainer viewItemContainer, Map<String, Object> values, ExternalizableDataProviderExtensionPoint externalizableDataProviderEP) throws UndefinedItemPathException, BadItemTypeException, IOException
218    {
219        return synchronizeValues(viewItemContainer, values, externalizableDataProviderEP, false);
220    }
221    
222    /**
223     * Synchronizes the given values with the current {@link ModifiableModelAwareDataHolder}'s ones
224     * If the data is externalizable, the synchronized value is the external one
225     * @param viewItemContainer The {@link ViewItemContainer} containing all items to synchronize
226     * @param values the values to synchronize
227     * @param externalizableDataProviderEP the extrernalizable data provider extension point
228     * @param useDefaultFromModel <code>true</code> to use default values from the model if there is no value in the {@link Map} for an item present in the view
229     * @return <code>true</code> if some values have changed, <code>false</code> otherwise
230     * @throws UndefinedItemPathException if a key in the given Map refers to a data that is not defined by the model
231     * @throws BadItemTypeException if the type defined by the model of one of the Map's key doesn't match the corresponding value
232     * @throws IOException if an error occurs while synchronizing I/O data
233     */
234    public boolean synchronizeValues(ViewItemContainer viewItemContainer, Map<String, Object> values, ExternalizableDataProviderExtensionPoint externalizableDataProviderEP, boolean useDefaultFromModel) throws UndefinedItemPathException, BadItemTypeException, IOException;
235    
236    /**
237     * Sets the value of the data at the given path
238     * @param dataPath path of the data
239     * @param value the value to set. Give <code>null</code> to empty the value.
240     * @throws IllegalArgumentException if the given data path is null or empty
241     * @throws UndefinedItemPathException if the given data path is not defined by the model
242     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
243     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
244     */
245    public void setValue(String dataPath, Object value) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
246    
247    /**
248     * Sets the local value of the data at the given path
249     * @param dataPath path of the externalizable data
250     * @param localValue the local value to set. Give <code>null</code> to empty the value.
251     * @throws IllegalArgumentException if the given data path is null or empty
252     * @throws UndefinedItemPathException if the given data path is not defined by the model
253     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
254     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
255     */
256    public void setLocalValue(String dataPath, Object localValue) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
257    
258    /**
259     * Sets the external value of the data at the given path
260     * @param dataPath path of the externalizable data
261     * @param externalValue the external value to set. Give <code>null</code> to empty the value.
262     * @throws IllegalArgumentException if the given data path is null or empty
263     * @throws UndefinedItemPathException if the given data path is not defined by the model
264     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
265     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
266     */
267    public void setExternalValue(String dataPath, Object externalValue) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
268
269    /**
270     * Set the status of the data at the given path
271     * @param dataPath path of the externalizable data
272     * @param status the new status
273     * @throws IllegalArgumentException if the given data path is null or empty
274     * @throws UndefinedItemPathException if the given data path is not defined by the model
275     * @throws BadItemTypeException if the type defined by the model doesn't match the given value to set 
276     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
277     */
278    public void setStatus(String dataPath, ExternalizableDataStatus status) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
279    
280    /**
281     * {@inheritDoc}
282     * @throws UndefinedItemPathException if the given data path is not defined by the model
283     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
284     */
285    @Override
286    public void removeValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
287    
288    /**
289     * Removes the local value of the data at the given path
290     * @param dataPath path of the externalizable data
291     * @throws IllegalArgumentException if the given data path is null or empty
292     * @throws UnknownDataException if the value at the given data path does not exist
293     * @throws UndefinedItemPathException if the given data path is not defined by the model
294     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
295     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
296     */
297    public void removeLocalValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, UnknownDataException, BadDataPathCardinalityException;
298    
299    /**
300     * Removes the external value of the data at the given path
301     * @param dataPath path of the externalizable data
302     * @throws IllegalArgumentException if the given data path is null or empty
303     * @throws UnknownDataException if the value at the given data path does not exist
304     * @throws UndefinedItemPathException if the given data path is not defined by the model
305     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
306     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
307     */
308    public void removeExternalValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, UnknownDataException, BadDataPathCardinalityException;
309}