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 java.util.Map;
26
27 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
28
29 /**
30 * A <code>MediaPackageElementRef</code> provides means of pointing to other elements in the media package.
31 * <p>
32 * A metadata catalog could for example contain a reference to the track that was used to extract the data contained in
33 * it.
34 * </p>
35 */
36 @XmlJavaTypeAdapter(MediaPackageReferenceImpl.Adapter.class)
37 public interface MediaPackageReference extends Cloneable {
38
39 String TYPE_MEDIAPACKAGE = "mediapackage";
40 String TYPE_TRACK = "track";
41 String TYPE_CATALOG = "catalog";
42 String TYPE_ATTACHMENT = "attachment";
43 String TYPE_SERIES = "series";
44 String SELF = "self";
45 String ANY = "*";
46
47 /**
48 * Returns the reference type.
49 * <p>
50 * There is a list of well known types describing media package elements:
51 * <ul>
52 * <li><code>mediapackage</code> a reference to the parent media package</li>
53 * <li><code>track</code> referes to a track inside the media package</li>
54 * <li><code>catalog</code> referes to a catalog inside the media package</li>
55 * <li><code>attachment</code> referes to an attachment inside the media package</li>
56 * <li><code>series</code> referes to a series</li>
57 * </ul>
58 *
59 * @return the reference type
60 */
61 String getType();
62
63 /**
64 * Returns the reference identifier.
65 * <p>
66 * The identifier will usually refer to the id of the media package element, should the reference point to an element
67 * inside the media package (see {@link MediaPackageElement#getIdentifier()}).
68 * <p>
69 * In case of a reference to another media package, this will reflect the media package id (see
70 * {@link MediaPackage#getIdentifier()}) or <code>self</code> if it refers to the parent media package.
71 *
72 * @return the reference identifier
73 */
74 String getIdentifier();
75
76 /**
77 * Returns <code>true</code> if this reference matches <code>reference</code> by means of type and identifier.
78 *
79 * @param reference
80 * the media package reference
81 * @return <code>true</code> if the reference matches
82 */
83 boolean matches(MediaPackageReference reference);
84
85 /**
86 * Returns additional properties that further define what the object is referencing.
87 * <p>
88 * An example would be the point in time for a slide preview:
89 *
90 * <pre>
91 * <attachment ref="track:track-7;time=8764">
92 * </attachment>
93 * </pre>
94 *
95 * @return the properties of this reference
96 */
97 Map<String, String> getProperties();
98
99 /**
100 * Returns the property with name <code>key</code> or <code>null</code> if no such property exists.
101 *
102 * @param key
103 * the property name
104 * @return the property value
105 */
106 String getProperty(String key);
107
108 /**
109 * Adds an additional property to further define the object reference. Set the value to null in order to remove a
110 * property.
111 *
112 * @param key
113 * The unique key
114 * @param value
115 * The value of the property
116 */
117 void setProperty(String key, String value);
118
119 /**
120 * Returns a deep copy of this reference.
121 *
122 * @return the clone
123 */
124 Object clone();
125
126 }