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.Locale;
019
020import org.xml.sax.ContentHandler;
021import org.xml.sax.SAXException;
022
023import org.ametys.plugins.repository.data.holder.group.impl.ModelAwareComposite;
024import org.ametys.plugins.repository.data.holder.group.impl.ModelAwareRepeater;
025import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
026import org.ametys.runtime.model.exception.BadItemTypeException;
027import org.ametys.runtime.model.exception.UndefinedItemPathException;
028import org.ametys.runtime.model.type.ModelItemType;
029
030/**
031 * Interface for data containers with models
032 */
033public interface ModelAwareDataHolder extends DataHolder
034{
035    /**
036     * {@inheritDoc}
037     * @throws UndefinedItemPathException if the given composite path is not defined by the model
038     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple 
039     */
040    @Override
041    public ModelAwareComposite getComposite(String compositePath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
042    
043    /**
044     * {@inheritDoc}
045     * @throws UndefinedItemPathException if the given repeater path is not defined by the model
046     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
047     */
048    @Override
049    public ModelAwareRepeater getRepeater(String repeaterPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
050    
051    /**
052     * {@inheritDoc}
053     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
054     */
055    @Override
056    public boolean hasValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
057    
058    /**
059     * Retrieves the value of the data at the given path
060     * @param <T> type of the value to retrieve
061     * @param dataPath path of the data
062     * @return the value of the data or <code>null</code> if not exists. The object returned may be of a generic class defined by the storage (if the model is unknown). For example, an url may be returned as a String.
063     * @throws IllegalArgumentException if the given data path is null or empty
064     * @throws UndefinedItemPathException if the given data path is not defined by the model
065     * @throws BadItemTypeException if the type defined by the model doesn't match the value stored in the repository
066     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
067     */
068    public <T extends Object> T getValue(String dataPath) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
069    
070    /**
071     * Retrieves the value of the data at the given path, or the default value
072     * @param <T> type of the value to retrieve
073     * @param dataPath path of the data
074     * @param useDefaultFromModel true to use the default value from the model, false to use the given default value
075     * @param defaultValue default value used if value is null and useDefaultFromModel is false, or if there is no default value on model
076     * @return the value of the data or <code>null</code> if not exists.
077     * @throws IllegalArgumentException if the given data path is null or empty
078     * @throws UndefinedItemPathException if the given data path is not defined by the model
079     * @throws BadItemTypeException if the type defined by the model doesn't match the value stored in the repository
080     * @throws BadDataPathCardinalityException if the definition of a part of the data path is multiple. Only the last part can be multiple
081     */
082    public <T extends Object> T getValue(String dataPath, boolean useDefaultFromModel, T defaultValue) throws IllegalArgumentException, UndefinedItemPathException, BadItemTypeException, BadDataPathCardinalityException;
083    
084    /**
085     * Checks if the definition of the element at the given path is multiple
086     * @param path path of the element. No matter if it is a definition or data path (with repeater entry positions)
087     * @return <code>true</code> if the element is multiple, <code>false</code> otherwise
088     * @throws IllegalArgumentException if the given path is null or empty
089     * @throws UndefinedItemPathException if the given path is not defined by the model
090     */
091    public boolean isMultiple(String path) throws IllegalArgumentException, UndefinedItemPathException;
092    
093    /**
094     * Retrieves the type of the data at the given path
095     * @param path path of the data. No matter if it is a definition or data path (with repeater entry positions)
096     * @return the type of the data
097     * @throws IllegalArgumentException if the given data path is null or empty
098     * @throws UndefinedItemPathException if the given data path is not defined by the model
099     */
100    public ModelItemType getType(String path) throws IllegalArgumentException, UndefinedItemPathException;
101    
102    /**
103     * {@inheritDoc}
104     * @throws UndefinedItemPathException if the saxed value's path is not defined by the model
105     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
106     */
107    public default void toSAX(ContentHandler contentHandler) throws SAXException, UndefinedItemPathException, BadItemTypeException
108    {
109        DataHolder.super.toSAX(contentHandler);
110    }
111    
112    /**
113     * {@inheritDoc}
114     * @throws UndefinedItemPathException if the saxed value's path is not defined by the model
115     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
116     */
117    public default void toSAX(ContentHandler contentHandler, Locale locale) throws SAXException, UndefinedItemPathException, BadItemTypeException
118    {
119        DataHolder.super.toSAX(contentHandler, locale);
120    }
121}