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