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.xml.sax.ContentHandler;
022import org.xml.sax.SAXException;
023
024import org.ametys.plugins.repository.data.UnknownDataException;
025import org.ametys.plugins.repository.data.holder.group.ModelLessComposite;
026import org.ametys.plugins.repository.data.type.ModelItemTypeExtensionPoint;
027import org.ametys.plugins.repository.data.type.RepositoryModelItemType;
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;
032import org.ametys.runtime.model.type.DataContext;
033
034/**
035 * Interface for data containers without models
036 */
037public interface ModelLessDataHolder extends DataHolder
038{
039    /**
040     * {@inheritDoc}
041     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
042     */
043    @Override
044    public ModelLessComposite getComposite(String compositePath) throws IllegalArgumentException, BadItemTypeException, BadDataPathCardinalityException;
045    
046    /**
047     * {@inheritDoc}
048     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
049     */
050    @Override
051    public boolean hasValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
052    
053    /**
054     * Checks if there is a non empty value for the data at the given path
055     * @param dataPath path of the data
056     * @param dataTypeId type identifier of the data
057     * @return <code>true</code> if there is a non empty value for the data, <code>false</code> otherwise
058     * @throws IllegalArgumentException if the given data path is null or empty
059     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
060     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
061     */
062    public boolean hasValue(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownTypeException, BadDataPathCardinalityException;
063    
064    /**
065     * {@inheritDoc}
066     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
067     */
068    @Override
069    public boolean hasValueOrEmpty(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
070    
071    /**
072     * Retrieves the value of the data at the given path
073     * The type of the value will be deduced from the stored data.
074     * 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
075     * @param <T> type of the value to retrieve. Should match the given data type
076     * @param dataPath path of the data
077     * @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.
078     * @throws IllegalArgumentException if the given data path is null or empty
079     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
080     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
081     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
082     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
083     */
084    public <T> T getValue(String dataPath) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, BadDataPathCardinalityException;
085    
086    /**
087     * Retrieves the value of the data at the given path if exists and is not empty, or the default value
088     * @param <T> type of the value to retrieve. Should match the given data type
089     * @param dataPath path of the data
090     * @param defaultValue default value
091     * @return the value of the data, <code>null</code> if the data exists but is empty, or the given default value
092     * @throws IllegalArgumentException if the given data path is null or empty
093     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
094     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
095     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
096     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
097     */
098    public <T> T getValue(String dataPath, T defaultValue) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, BadDataPathCardinalityException;
099    
100    /**
101     * Retrieves the value of the data at the given path
102     * @param <T> type of the value to retrieve. Should match the given data type
103     * @param dataPath path of the data
104     * @param dataTypeId type identifier of the data
105     * @return the value of the data or <code>null</code> if not exists or is empty
106     * @throws IllegalArgumentException if the given data path is null or empty
107     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
108     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
109     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
110     */
111    public <T> T getValueOfType(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, BadDataPathCardinalityException;
112    
113    /**
114     * Retrieves the value of the data at the given path if exists and is not empty, or the default value
115     * @param <T> type of the value to retrieve. Should match the given data type
116     * @param dataPath path of the data
117     * @param dataTypeId type identifier of the data
118     * @param defaultValue default value
119     * @return the value of the data, <code>null</code> if the data exists but is empty, or the given default value
120     * @throws IllegalArgumentException if the given data path is null or empty
121     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
122     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
123     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
124     */
125    public <T> T getValueOfType(String dataPath, String dataTypeId, T defaultValue) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, BadDataPathCardinalityException;
126    
127    /**
128     * Checks if the value of the data at the given path is multiple
129     * @param dataPath path of the data to check
130     * @return <code>true</code> if the value of the data is multiple, <code>false</code> otherwise
131     * @throws IllegalArgumentException if the given data path is null or empty
132     * @throws UnknownDataException the data at the given path does not exist
133     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
134     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
135     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
136     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
137     */
138    public boolean isMultiple(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, BadDataPathCardinalityException;
139    
140    /**
141     * Checks if the value of the data at the given path is multiple
142     * @param dataPath path of the data to check
143     * @param dataTypeId type identifier of the data
144     * @return <code>true</code> if the value of the data is multiple, <code>false</code> otherwise
145     * @throws IllegalArgumentException if the given data path is null or empty
146     * @throws UnknownDataException the data at the given path does not exist
147     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
148     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
149     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
150     */
151    public boolean isMultiple(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, BadItemTypeException, BadDataPathCardinalityException;
152    
153    /**
154     * Retrieves the type of the data at the given path
155     * @param dataPath path of the data
156     * @return the type of the data
157     * @throws IllegalArgumentException if the given data path is null or empty
158     * @throws UnknownDataException if there is no data stored at the given path
159     * @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
160     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
161     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
162     */
163    public RepositoryModelItemType getType(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadDataPathCardinalityException;
164    
165    /**
166     * Generates SAX events for data contained in this {@link DataHolder}
167     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
168     * @throws SAXException if an error occurs during the SAX events generation
169     * @throws UnknownTypeException if there is no compatible type with the saxed value
170     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
171     */
172    public default void dataToSAX(ContentHandler contentHandler) throws SAXException, UnknownTypeException, NotUniqueTypeException
173    {
174        dataToSAX(contentHandler, DataContext.newInstance());
175    }
176    
177    /**
178     * Generates SAX events for data contained in this {@link DataHolder}
179     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
180     * @param context The context of the data to SAX
181     * @throws SAXException if an error occurs during the SAX events generation
182     * @throws UnknownTypeException if there is no compatible type with the saxed value
183     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
184     */
185    public void dataToSAX(ContentHandler contentHandler, DataContext context) throws SAXException, UnknownTypeException, NotUniqueTypeException;
186    
187    /**
188     * Convert the data contained in this {@link DataHolder}
189     * @return The data of the current {@link DataHolder} as JSON
190     * @throws UnknownTypeException if there is no compatible type with the value to convert
191     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
192     */
193    public default Map<String, Object> dataToJSON() throws UnknownTypeException, NotUniqueTypeException
194    {
195        return dataToJSON(DataContext.newInstance());
196    }
197    
198    /**
199     * Convert the data contained in this {@link DataHolder}
200     * @param context The context of the data to convert
201     * @return The data of the current {@link DataHolder} as JSON
202     * @throws UnknownTypeException if there is no compatible type with the value to convert
203     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
204     */
205    public Map<String, Object> dataToJSON(DataContext context) throws UnknownTypeException, NotUniqueTypeException;
206    
207    @Override
208    public Optional<? extends ModelLessDataHolder> getParentDataHolder();
209    
210    @Override
211    public ModelLessDataHolder getRootDataHolder();
212    
213    /**
214     * Provide the ModelItemTypeExtensionPoint linked with the DataHolder
215     * @return the extension point
216     */
217    public ModelItemTypeExtensionPoint getModelItemTypeExtensionPoint();
218}