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.Map;
019import java.util.Optional;
020
021import org.ametys.plugins.repository.data.UnknownDataException;
022import org.ametys.plugins.repository.data.holder.group.ModifiableComposite;
023import org.ametys.plugins.repository.data.holder.values.SynchronizationResult;
024import org.ametys.plugins.repository.data.repositorydata.ModifiableRepositoryData;
025import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
026import org.ametys.runtime.model.exception.BadItemTypeException;
027import org.ametys.runtime.model.exception.NotUniqueTypeException;
028import org.ametys.runtime.model.exception.UndefinedItemPathException;
029import org.ametys.runtime.model.exception.UnknownTypeException;
030
031/**
032 * Interface for modifiable data containers
033 */
034public interface ModifiableDataHolder extends DataHolder
035{
036    @Override
037    public ModifiableComposite getComposite(String compositePath) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
038    
039    /**
040     * Retrieves the composite at the given path
041     * @param compositePath path of the composite to retrieve
042     * @param createNew <code>true</code> to create the composite if it does not exist, <code>false</code> otherwise
043     * @return the composite or <code>null</code> if createNew is <code>false</code> and value not exists or is empty
044     * @throws IllegalArgumentException if the given composite path is null or empty
045     * @throws UnknownTypeException if the type composite is not available for this data holder
046     * @throws BadItemTypeException if the stored value at the given path is not a composite
047     * @throws UndefinedItemPathException if the data holder has a model and the given composite path is not defined by this model
048     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
049     */
050    public ModifiableComposite getComposite(String compositePath, boolean createNew) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
051    
052    /**
053     * Synchronizes the given values with the current ones
054     * @param <T> the type of the {@link SynchronizationResult}
055     * @param values the values to synchronize
056     * @return the {@link SynchronizationResult}
057     * @throws UnknownTypeException if there is no available type compatible with a given value for this data holder's type extension point
058     * @throws NotUniqueTypeException if there is more than one available types compatibles with the a value for this data holder's type extension point
059     * @throws BadItemTypeException if type of the a data doesn't match the corresponding given value to set
060     * @throws UndefinedItemPathException if the data holder has a model and a key in the given Map refers to a data that is not defined by the model
061     */
062    public <T extends SynchronizationResult> T synchronizeValues(Map<String, Object> values) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException;
063    
064    /**
065     * Sets the value of the data at the given path
066     * @param dataPath path of the data
067     * @param value the value to set. To empty a value, use {@link #setValue(String, Object, String)} with a <code>null</code> value
068     * @throws IllegalArgumentException if the given data path is null or empty
069     * @throws UnknownDataException if the given the data path is composed of an non existing group
070     * @throws UnknownTypeException if there is no available type compatible with the given value for this data holder's type extension point
071     * @throws NotUniqueTypeException if there is more than one available types compatibles with the given value for this data holder's type extension point
072     * @throws BadItemTypeException if type of the data at the given path doesn't match the given value to set
073     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by the model
074     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
075     */
076    public void setValue(String dataPath, Object value) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
077    
078    /**
079     * Sets the value of the data at the given path
080     * @param dataPath path of the data
081     * @param value the value to set. Give <code>null</code> to empty the value.  
082     * @param dataTypeId type identifier of the data
083     * @throws IllegalArgumentException if the given data path is null or empty
084     * @throws UnknownDataException if the given data path is composed of an non existing group
085     * @throws UnknownTypeException if the given type is not available for this data holder's type extension point
086     * @throws BadItemTypeException if the given type doesn't match the given value to set
087     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by the model
088     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
089     */
090    public void setValue(String dataPath, Object value, String dataTypeId) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
091    
092    /**
093     * Removes the stored value of the data at the given path
094     * @param dataPath path of the data
095     * @throws IllegalArgumentException if the given data path is null or empty
096     * @throws UnknownTypeException if the the data to remove is in a group and there is no available type compatible with this group
097     * @throws BadItemTypeException if the value of the parent of the given path is not an item container
098     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by the model
099     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
100     */
101    public void removeValue(String dataPath) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
102    
103    @Override
104    public ModifiableRepositoryData getRepositoryData();
105    
106    @Override
107    public Optional<? extends ModifiableDataHolder> getParentDataHolder();
108    
109    @Override
110    public ModifiableDataHolder getRootDataHolder();
111}