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.Locale;
020
021import org.xml.sax.ContentHandler;
022import org.xml.sax.SAXException;
023
024import org.ametys.plugins.repository.data.UnknownDataException;
025import org.ametys.plugins.repository.data.holder.group.impl.ModelLessComposite;
026import org.ametys.plugins.repository.data.type.RepositoryModelItemType;
027import org.ametys.plugins.repository.metadata.MultilingualString;
028import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
029import org.ametys.runtime.model.exception.BadItemTypeException;
030import org.ametys.runtime.model.exception.NotUniqueTypeException;
031import org.ametys.runtime.model.exception.UnknownTypeException;
032
033/**
034 * Interface for data containers without models
035 */
036public interface ModelLessDataHolder extends DataHolder
037{
038    /**
039     * {@inheritDoc}
040     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
041     */
042    @Override
043    public ModelLessComposite getComposite(String compositePath) throws IllegalArgumentException, BadItemTypeException, BadDataPathCardinalityException;
044    
045    /**
046     * {@inheritDoc}
047     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
048     */
049    @Override
050    public boolean hasValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
051    
052    /**
053     * Retrieves the value of the data at the given path
054     * The type of the value will be deduced from the stored data.
055     * In some cases, the type can be wrong. For example, it is impossible to know if a stored date is a date or a date time
056     * @param <T> type of the value to retrieve. Should match the given data type
057     * @param dataPath path of the data
058     * @return the value of the data or <code>null</code> if not exists or is empty. The object returned may be of a generic class defined by the storage. For example, an url may be returned as a String. Use the 2 arguments version to ensure to get the right kind of Object.
059     * @throws IllegalArgumentException if the given data path is null or empty
060     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
061     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
062     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
063     */
064    public <T> T getValue(String dataPath) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadDataPathCardinalityException;
065    
066    /**
067     * Retrieves the value of the data at the given path if exists and is not empty, or the default value
068     * @param <T> type of the value to retrieve. Should match the given data type
069     * @param dataPath path of the data
070     * @param defaultValue default value
071     * @return the value of the data, <code>null</code> if the data exists but is empty, or the given default value
072     * @throws IllegalArgumentException if the given data path is null or empty
073     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
074     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
075     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
076     */
077    public <T> T getValue(String dataPath, T defaultValue) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadDataPathCardinalityException;
078    
079    /**
080     * Retrieves the value of the data at the given path
081     * @param <T> type of the value to retrieve. Should match the given data type
082     * @param dataPath path of the data
083     * @param dataTypeId type identifier of the data
084     * @return the value of the data or <code>null</code> if not exists or is empty
085     * @throws IllegalArgumentException if the given data path is null or empty
086     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
087     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
088     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
089     */
090    public <T> T getValueOfType(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, BadDataPathCardinalityException;
091    
092    /**
093     * Retrieves the value of the data at the given path if exists and is not empty, or the default value
094     * @param <T> type of the value to retrieve. Should match the given data type
095     * @param dataPath path of the data
096     * @param dataTypeId type identifier of the data
097     * @param defaultValue default value
098     * @return the value of the data, <code>null</code> if the data exists but is empty, or the given default value
099     * @throws IllegalArgumentException if the given data path is null or empty
100     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
101     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
102     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
103     */
104    public <T> T getValueOfType(String dataPath, String dataTypeId, T defaultValue) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, BadDataPathCardinalityException;
105    
106    /**
107     * Checks if the value of the data at the given path is multiple
108     * @param dataPath path of the data to check
109     * @return <code>true</code> if the value of the data is multiple, <code>false</code> otherwise
110     * @throws IllegalArgumentException if the given data path is null or empty
111     * @throws UnknownDataException the data at the given path does not exist
112     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
113     */
114    public boolean isMultiple(String dataPath) throws IllegalArgumentException, UnknownDataException, BadDataPathCardinalityException;
115    
116    /**
117     * Retrieves the type of the data at the given path
118     * @param dataPath path of the data
119     * @return the type of the data
120     * @throws IllegalArgumentException if the given data path is null or empty
121     * @throws UnknownDataException if there is no data stored at the given path
122     * @throws UnknownTypeException if there is no compatible type with the data at the given data path or if the data is a repeater entry but the composite type is not available
123     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
124     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
125     */
126    public RepositoryModelItemType getType(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadDataPathCardinalityException;
127    
128    /**
129     * Generates SAX events for data contained in this {@link DataHolder}
130     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
131     * @throws SAXException if an error occurs during the SAX events generation
132     * @throws IOException if an error occurs while reading a value using the I/O API
133     * @throws UnknownTypeException if there is no compatible type with the saxed value
134     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
135     */
136    public default void dataToSAX(ContentHandler contentHandler) throws SAXException, IOException, UnknownTypeException, NotUniqueTypeException
137    {
138        dataToSAX(contentHandler, (Locale) null);
139    }
140    
141    /**
142     * Generates SAX events for data contained in this {@link DataHolder}
143     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
144     * @param locale The locale to use for localized data, such as {@link MultilingualString}. Can be <code>null</code> to generate SAX events for all existing {@link Locale}s.
145     * @throws SAXException if an error occurs during the SAX events generation
146     * @throws IOException if an error occurs while reading a value using the I/O API
147     * @throws UnknownTypeException if there is no compatible type with the saxed value
148     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
149     */
150    public void dataToSAX(ContentHandler contentHandler, Locale locale) throws SAXException, IOException, UnknownTypeException, NotUniqueTypeException;
151}