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