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