1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22
23 package org.opencastproject.mediapackage;
24
25 import org.opencastproject.util.Checksum;
26 import org.opencastproject.util.MimeType;
27
28 import java.net.URI;
29 import java.util.Collection;
30
31 /**
32 * All classes that will be part of a media package must implement this interface.
33 */
34 public interface MediaPackageElement extends ManifestContributor, Comparable<MediaPackageElement>, Cloneable {
35
36 /**
37 * The element type todo is the type definitely needed or can the flavor take its responsibilities?
38 */
39 enum Type {
40 Manifest, Timeline, Track, Catalog, Attachment, Publication, Other
41 }
42
43 /**
44 * Returns the element identifier.
45 *
46 * @return the element identifier, may be null
47 */
48 String getIdentifier();
49
50 /**
51 * Sets the element identifier.
52 *
53 * @param id
54 * the new element identifier
55 */
56 void setIdentifier(String id);
57
58 /**
59 * Generate a new random identifier for this element.
60 *
61 * @return The new identifier.
62 */
63 String generateIdentifier();
64
65 /**
66 * Returns the element's manifest type.
67 *
68 * @return the manifest type
69 */
70 Type getElementType();
71
72 /**
73 * Returns a human readable name for this media package element. If no name was provided, the filename is returned
74 * instead.
75 *
76 * @return the element name
77 */
78 String getElementDescription();
79
80 /**
81 * Sets the element description of this media package element.
82 *
83 * @param description
84 * the new element description
85 */
86 void setElementDescription(String description);
87
88 /**
89 * Sets the given tags for the media package element, overwriting any that may have been set previously.
90 *
91 * @param tags
92 * array of tags
93 */
94 void setTags(String [] tags);
95
96 /**
97 * Tags the media package element with the given tag.
98 *
99 * @param tag
100 * the tag
101 */
102 void addTag(String tag);
103
104 /**
105 * Removes the tag from the media package element.
106 *
107 * @param tag
108 * the tag
109 */
110 void removeTag(String tag);
111
112 /**
113 * Returns <code>true</code> if the media package element contains the given tag.
114 *
115 * @param tag
116 * the tag
117 * @return <code>true</code> if the element is tagged
118 */
119 boolean containsTag(String tag);
120
121 /**
122 * Returns <code>true</code> if the media package element contains at least one of the given tags. If there are no
123 * tags contained in the set, then the element is considered to match as well.
124 *
125 * @param tags
126 * the set of tag
127 * @return <code>true</code> if the element is tagged accordingly
128 */
129 boolean containsTag(Collection<String> tags);
130
131 /**
132 * Returns the tags for this media package element or an empty array if there are no tags.
133 *
134 * @return the tags
135 */
136 String[] getTags();
137
138 /** Removes all tags associated with this element */
139 void clearTags();
140
141 /**
142 * Returns the media package if the element has been added, <code>null</code> otherwise.
143 *
144 * @return the media package
145 */
146 MediaPackage getMediaPackage();
147
148 /**
149 * Returns a reference to another entitiy, both inside or outside the media package.
150 *
151 * @return the reference
152 */
153 MediaPackageReference getReference();
154
155 /**
156 * Sets the element reference.
157 *
158 * @param reference
159 * the reference
160 */
161 void setReference(MediaPackageReference reference);
162
163 /**
164 * Returns a reference to the element location.
165 *
166 * @return the element location
167 */
168 URI getURI();
169
170 /**
171 * Sets the elements location.
172 *
173 * @param uri
174 * the element location
175 */
176 void setURI(URI uri);
177
178 /**
179 * Returns the file's checksum.
180 *
181 * @return the checksum
182 */
183 Checksum getChecksum();
184
185 /**
186 * Sets the new checksum on this media package element.
187 *
188 * @param checksum
189 * the checksum
190 */
191 void setChecksum(Checksum checksum);
192
193 /**
194 * Returns the element's mimetype as found in the ISO Mime Type Registrations.
195 * <p>
196 * For example, in case of motion jpeg slides, this method will return the mime type for <code>video/mj2</code>.
197 *
198 * @return the mime type
199 */
200 MimeType getMimeType();
201
202 /**
203 * Sets the mime type on this media package element.
204 *
205 * @param mimeType
206 * the new mime type
207 */
208 void setMimeType(MimeType mimeType);
209
210 /**
211 * Returns the element's type as defined for the specific media package element.
212 * <p>
213 * For example, in case of a video track, the type could be <code>video/x-presentation</code>.
214 *
215 * @return the element flavor
216 */
217 MediaPackageElementFlavor getFlavor();
218
219 /**
220 * Sets the flavor on this media package element.
221 *
222 * @param flavor
223 * the new flavor
224 */
225 void setFlavor(MediaPackageElementFlavor flavor);
226
227 /**
228 * Returns the number of bytes that are occupied by this media package element.
229 *
230 * @return the size
231 */
232 long getSize();
233
234 /**
235 * Sets the file size in bytes
236 *
237 * @param size
238 */
239 void setSize(long size);
240
241 /**
242 * Verifies the integrity of the media package element.
243 *
244 * @throws MediaPackageException
245 * if the media package element is in an incosistant state
246 */
247 void verify() throws MediaPackageException;
248
249 /**
250 * Adds a reference to the media package element <code>element</code>.
251 * <p>
252 * Note that an element can only refere to one object. Therefore, any existing reference will be replaced. Also note
253 * that if this element is part of a media package, a consistency check will be made making sure the refered element
254 * is also part of the same media package. If not, a {@link MediaPackageException} will be thrown.
255 *
256 * @param element
257 * the element to refere to
258 */
259 void referTo(MediaPackageElement element);
260
261 /**
262 * Adds an arbitrary reference.
263 * <p>
264 * Note that an element can only have one reference. Therefore, any existing reference will be replaced. Also note
265 * that if this element is part of a media package, a consistency check will be made making sure the refered element
266 * is also part of the same media package. If not, a {@link MediaPackageException} will be thrown.
267 *
268 * @param reference
269 * the reference
270 */
271 void referTo(MediaPackageReference reference);
272
273 /**
274 * Removes any reference.
275 */
276 void clearReference();
277
278 /**
279 * Create a deep copy of this object.
280 *
281 * @return The copy
282 */
283 Object clone();
284
285 }