001/*
002 *  Copyright 2010 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.metadata;
017
018import java.util.Date;
019import java.util.Locale;
020
021import org.ametys.core.user.UserIdentity;
022import org.ametys.plugins.repository.AmetysObject;
023import org.ametys.plugins.repository.AmetysRepositoryException;
024import org.ametys.plugins.repository.TraversableAmetysObject;
025
026/**
027 * Metadata container for an {@link AmetysObject}.<br>
028 * Note that this can be recursive so that a CompositeMetadata can handle other CompositeMetadata.
029 */
030public interface CompositeMetadata
031{
032    /**
033     * Enumeration for metadata types.
034     */
035    public enum MetadataType 
036    {
037        /** Constant for composite metadata */
038        COMPOSITE,
039        /** Constant for type binary */
040        BINARY,
041        /** Constant for type richtext */
042        RICHTEXT,
043        /** Constant for type string */
044        STRING,
045        /** Constant for type a multilingual string */
046        MULTILINGUAL_STRING,
047        /** Constant for type boolean */
048        BOOLEAN,
049        /** Constant for type date */
050        DATE,
051        /** Constant for type double */
052        DOUBLE,
053        /** Constant for type long */
054        LONG,
055        /** Constant for object collection metadata */
056        OBJECT_COLLECTION,
057        /** Constant for type user */
058        USER
059    }
060
061    /**
062     * Tests if a metadata with a given name exists.
063     * @param metadataName the metadataName to test.
064     * @return <code>true</code> if the given metadata exists, <code>false</code> otherwise.
065     * @throws AmetysRepositoryException if an error occurs.
066     */
067    public boolean hasMetadata(String metadataName);
068
069    /**
070     * Returns the type of the given metadata.
071     * @param metadataName metadata name.
072     * @return the type of the given metadata.
073     * @throws UnknownMetadataException if the named metadata does not exist.
074     * @throws AmetysRepositoryException if an error occurs.
075     */
076    public MetadataType getType(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
077    
078    /**
079     * Returns the named metadata's value as {@link BinaryMetadata}.<br> 
080     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown. 
081     * @param metadataName the metadata name.
082     * @return the metadata value as BinaryMetadata.
083     * @throws UnknownMetadataException if the named metadata does not exist.
084     * @throws AmetysRepositoryException if an error occurs.
085     */
086    public BinaryMetadata getBinaryMetadata(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
087
088    /**
089     * Returns the named metadata's value as {@link RichText}.<br> 
090     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown. 
091     * @param metadataName the metadata name.
092     * @return the metadata value as RichText.
093     * @throws UnknownMetadataException if the named metadata does not exist.
094     * @throws AmetysRepositoryException if an error occurs.
095     */
096    public RichText getRichText(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
097    
098    /**
099     * Returns the named metadata's value as String.<br> 
100     * If the metadata is multi-valued, one of the value is returned.<br>
101     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
102     * @param metadataName the metadata name.
103     * @return the metadata value as String.
104     * @throws UnknownMetadataException if the named metadata does not exist.
105     * @throws AmetysRepositoryException if an error occurs.
106     */
107    public String getString(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
108
109    /**
110     * Returns the named metadata's value as String.<br> 
111     * If the metadata is multi-valued, one of the value is returned.<br>
112     * If the metadata does not exist, the default value is returned.
113     * @param metadataName the metadata name.
114     * @param defaultValue the default value.
115     * @return the metadata value as String or the default value if metadata is not set.
116     * @throws AmetysRepositoryException if an error occurs.
117     */
118    public String getString(String metadataName, String defaultValue) throws AmetysRepositoryException;
119
120    /**
121     * Returns the named metadata's value of a multilingual metadata as String.<br> 
122     * @param metadataName the metadata name.
123     * @param locale the locale of value to retrieve
124     * @return the metadata value as String
125     * @throws UnknownMetadataException if the named metadata does not exist for the given locale.
126     * @throws AmetysRepositoryException if an error occurs.
127     */
128    public String getLocalizedString (String metadataName, Locale locale) throws UnknownMetadataException, AmetysRepositoryException;
129    
130    /**
131     * Returns the named metadata's value of a multilingual metadata as String.<br> 
132     * If the metadata does not exist, the default value is returned.
133     * @param metadataName the metadata name.
134     * @param locale the locale of value to retrieve
135     * @param defaultValue the default value.
136     * @return the metadata value as String or the default value if metadata is not set.
137     * @throws AmetysRepositoryException if an error occurs.
138     */
139    public String getLocalizedString (String metadataName, Locale locale, String defaultValue) throws AmetysRepositoryException;
140    
141    /**
142     * Returns the named metadata's values of a multilingual metadata.<br> 
143     * @param metadataName the metadata name.
144     * @return the metadata values for all existing locales
145     * @throws AmetysRepositoryException if an error occurs.
146     */
147    public MultilingualString getMultilingualString(String metadataName) throws AmetysRepositoryException;
148    
149    /**
150     * Returns the named metadata's value as String array.
151     * @param metadataName metadata name.
152     * @return metadata value as String array.
153     * @throws UnknownMetadataException if the named metadata does not exist.
154     * @throws AmetysRepositoryException if an error occurs.
155     */
156    public String[] getStringArray(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
157
158    /**
159     * Returns the named metadata's value as String array.<br>
160     * If the metadata does not exist, the default values are returned.
161     * @param metadataName metadata name.
162     * @param defaultValues the default values.
163     * @return metadata value as String array or the default values if metadata is not set.
164     * @throws AmetysRepositoryException if an error occurs.
165     */
166    public String[] getStringArray(String metadataName, String[] defaultValues) throws AmetysRepositoryException;
167
168    /**
169     * Returns the named metadata's value as Date.<br> 
170     * If the metadata is multi-valued, one of the value is returned.<br>
171     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
172     * @param metadataName the metadata name.
173     * @return the metadata value as Date.
174     * @throws UnknownMetadataException if the named metadata does not exist.
175     * @throws AmetysRepositoryException if an error occurs.
176     */
177    public Date getDate(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
178
179    /**
180     * Returns the named metadata's value as Date.<br> 
181     * If the metadata is multi-valued, one of the value is returned.<br>
182     * If the metadata does not exist, the default value is returned.
183     * @param metadataName the metadata name.
184     * @param defaultValue the default value.
185     * @return the metadata value as Date or the default value if metadata is not set.
186     * @throws AmetysRepositoryException if an error occurs.
187     */
188    public Date getDate(String metadataName, Date defaultValue) throws AmetysRepositoryException;
189
190    /**
191     * Returns the named metadata's value as Date array.
192     * @param metadataName metadata name.
193     * @return metadata value as Date array.
194     * @throws UnknownMetadataException if the named metadata does not exist.
195     * @throws AmetysRepositoryException if an error occurs.
196     */
197    public Date[] getDateArray(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
198    
199    /**
200     * Returns the named metadata's value as Date array.<br>
201     * If the metadata does not exist, the default values are returned.
202     * @param metadataName metadata name.
203     * @param defaultValues the default values.
204     * @return metadata value as Date array or the default values if metadata is not set.
205     * @throws AmetysRepositoryException if an error occurs.
206     */
207    public Date[] getDateArray(String metadataName, Date[] defaultValues) throws AmetysRepositoryException;
208
209    /**
210     * Returns the named metadata's value as long.<br> 
211     * If the metadata is multi-valued, one of the value is returned.<br>
212     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
213     * @param metadataName the metadata name.
214     * @return the metadata value as long.
215     * @throws UnknownMetadataException if the named metadata does not exist.
216     * @throws AmetysRepositoryException if an error occurs.
217     */
218    public long getLong(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
219
220    /**
221     * Returns the named metadata's value as long.<br> 
222     * If the metadata is multi-valued, one of the value is returned.<br>
223     * If the metadata does not exist, the default value is returned.
224     * @param metadataName the metadata name.
225     * @param defaultValue the default value.
226     * @return the metadata value as long or the default value if metadata is not set.
227     * @throws AmetysRepositoryException if an error occurs.
228     */
229    public long getLong(String metadataName, long defaultValue) throws AmetysRepositoryException;
230    
231    /**
232     * Returns the named metadata's value as long array.
233     * @param metadataName metadata name.
234     * @return metadata value as long array.
235     * @throws UnknownMetadataException if the named metadata does not exist.
236     * @throws AmetysRepositoryException if an error occurs.
237     */
238    public long[] getLongArray(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
239    
240    /**
241     * Returns the named metadata's value as long array.<br>
242     * If the metadata does not exist, the default values are returned.
243     * @param metadataName metadata name.
244     * @param defaultValues the default values.
245     * @return metadata value as long array or the default values if metadata is not set.
246     * @throws AmetysRepositoryException if an error occurs.
247     */
248    public long[] getLongArray(String metadataName, long[] defaultValues) throws AmetysRepositoryException;
249
250    /**
251     * Returns the named metadata's value as double.<br> 
252     * If the metadata is multi-valued, one of the value is returned.<br>
253     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
254     * @param metadataName the metadata name.
255     * @return the metadata value as double.
256     * @throws UnknownMetadataException if the named metadata does not exist.
257     * @throws AmetysRepositoryException if an error occurs.
258     */
259    public double getDouble(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
260    
261    /**
262     * Returns the named metadata's value as double.<br> 
263     * If the metadata is multi-valued, one of the value is returned.<br>
264     * If the metadata does not exist, the default value is returned.
265     * @param metadataName the metadata name.
266     * @param defaultValue the default value.
267     * @return the metadata value as double or the default value if metadata is not set.
268     * @throws AmetysRepositoryException if an error occurs.
269     */
270    public double getDouble(String metadataName, double defaultValue) throws AmetysRepositoryException;
271    
272    /**
273     * Returns the named metadata's value as double array.
274     * @param metadataName metadata name.
275     * @return metadata value as double array.
276     * @throws UnknownMetadataException if the named metadata does not exist.
277     * @throws AmetysRepositoryException if an error occurs.
278     */
279    public double[] getDoubleArray(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
280    
281    /**
282     * Returns the named metadata's value as double array.<br>
283     * If the metadata does not exist, the default values are returned.
284     * @param metadataName metadata name.
285     * @param defaultValues the default values.
286     * @return metadata value as double array or the default values if metadata is not set.
287     * @throws AmetysRepositoryException if an error occurs.
288     */
289    public double[] getDoubleArray(String metadataName, double[] defaultValues) throws AmetysRepositoryException;
290
291    /**
292     * Returns the named metadata's value as boolean.<br> 
293     * If the metadata is multi-valued, one of the value is returned.<br>
294     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
295     * @param metadataName the metadata name.
296     * @return the metadata value as boolean.
297     * @throws UnknownMetadataException if the named metadata does not exist.
298     * @throws AmetysRepositoryException if an error occurs.
299     */
300    public boolean getBoolean(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
301    
302    /**
303     * Returns the named metadata's value as boolean.<br> 
304     * If the metadata is multi-valued, one of the value is returned.<br>
305     * If the metadata does not exist, the default value is returned.
306     * @param metadataName the metadata name.
307     * @param defaultValue the default value.
308     * @return the metadata value as boolean or the default value if metadata is not set.
309     * @throws AmetysRepositoryException if an error occurs.
310     */
311    public boolean getBoolean(String metadataName, boolean defaultValue) throws AmetysRepositoryException;
312    
313    /**
314     * Returns the named metadata's value as boolean array.
315     * @param metadataName metadata name.
316     * @return metadata value as boolean array.
317     * @throws UnknownMetadataException if the named metadata does not exist.
318     * @throws AmetysRepositoryException if an error occurs.
319     */
320    public boolean[] getBooleanArray(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
321    
322    /**
323     * Returns the named metadata's value as boolean array.<br>
324     * If the metadata does not exist, the default values are returned.
325     * @param metadataName metadata name.
326     * @param defaultValues the default values.
327     * @return metadata value as boolean array or the default values if metadata is not set.
328     * @throws AmetysRepositoryException if an error occurs.
329     */
330    public boolean[] getBooleanArray(String metadataName, boolean[] defaultValues) throws AmetysRepositoryException;
331    
332    /**
333     * Returns the named metadata's value as {@link UserIdentity}.<br> 
334     * If the metadata does not exist, an {@link UnknownMetadataException} is thrown.
335     * @param metadataName the metadata name.
336     * @return the metadata value as user identity.
337     * @throws AmetysRepositoryException if an error occurs.
338     */
339    public UserIdentity getUser(String metadataName) throws AmetysRepositoryException;
340    
341    /**
342     * Returns the named metadata's value as {@link UserIdentity}.<br> 
343     * If the metadata does not exist, the default value is returned.
344     * @param metadataName the metadata name.
345     * @param defaultValue  the default value.
346     * @return the metadata value as user identity or the default value if metadata is not set.
347     * @throws AmetysRepositoryException if an error occurs.
348     */
349    public UserIdentity getUser(String metadataName, UserIdentity defaultValue) throws AmetysRepositoryException;
350    
351    /**
352     * Returns the named metadata's value as {@link UserIdentity} array.
353     * @param metadataName the metadata name.
354     * @return metadata value as user identity array.
355     * @throws AmetysRepositoryException if an error occurs.
356     */
357    public UserIdentity[] getUserArray(String metadataName) throws AmetysRepositoryException;
358    
359    /**
360     * Returns the named metadata's value as {@link UserIdentity} array.<br>
361     * If the metadata does not exist, the default values are returned.
362     * @param metadataName the metadata name.
363     * @param defaultValues  the default values.
364     * @return metadata value as user identity array or the default values if metadata is not set.
365     * @throws AmetysRepositoryException if an error occurs.
366     */
367    public UserIdentity[] getUserArray(String metadataName, UserIdentity[] defaultValues) throws AmetysRepositoryException;
368
369    /**
370     * Returns the named metadata's value as {@link CompositeMetadata}.<br> 
371     * If the metadata is multi-valued, one of the value is returned.<br>
372     * If the metadata does not exist an {@link UnknownMetadataException} is thrown.
373     * @param metadataName the metadata name.
374     * @return the metadata value as {@link CompositeMetadata}.
375     * @throws UnknownMetadataException if the named metadata does not exist.
376     * @throws AmetysRepositoryException if an error occurs.
377     */
378    public CompositeMetadata getCompositeMetadata(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
379    
380    /**
381     * Returns an object collection metadata as a {@link TraversableAmetysObject}<br>.
382     * @param metadataName the metadata name.
383     * @return the metadata as a {@link TraversableAmetysObject}.
384     * @throws UnknownMetadataException if the named metadata does not exist.
385     * @throws AmetysRepositoryException if an error occurs.
386     */
387    TraversableAmetysObject getObjectCollection(String metadataName) throws AmetysRepositoryException;
388    
389    /**
390     * Returns an array containing metadata names.
391     * @return an array containing metadata names.
392     * @throws AmetysRepositoryException if an error occurs.
393     */
394    public String[] getMetadataNames() throws AmetysRepositoryException;
395
396    /**
397     * Test if the given metadata is multiple.
398     * @param metadataName the metadata name.
399     * @return <code>true</code> if the given metadata is multiple,
400     *         <code>false</code> otherwise.
401     * @throws UnknownMetadataException if the named metadata does not exist.
402     * @throws AmetysRepositoryException if an error occurs.
403     */
404    public boolean isMultiple(String metadataName) throws UnknownMetadataException, AmetysRepositoryException;
405    
406    /**
407     * Copy the current {@link CompositeMetadata} to the given composite metadata.
408     * @param metadata The parent composite metadata. Can not be null.
409     * @throws AmetysRepositoryException if an error occurs.
410     */
411    public void copyTo (ModifiableCompositeMetadata metadata) throws AmetysRepositoryException;
412}