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.elementbuilder;
24
25 import org.opencastproject.mediapackage.MediaPackageElement;
26 import org.opencastproject.mediapackage.MediaPackageElementFlavor;
27 import org.opencastproject.mediapackage.MediaPackageSerializer;
28 import org.opencastproject.mediapackage.UnsupportedElementException;
29
30 import org.w3c.dom.Node;
31
32 import java.net.URI;
33
34 /**
35 * An element builder plugin is an object that is able to recognize one ore more filetypes slated for ingest into
36 * Opencast.
37 * <p>
38 * <strong>Implementation note:</strong> Builder plugins may be stateful. They are intended to be used as throw-away
39 * objects.
40 */
41 @Deprecated
42 public interface MediaPackageElementBuilderPlugin {
43
44 /**
45 * This method is called once in a plugin's life cycle. When this method is called, the plugin can make sure that
46 * everything is in place for it to work properly. If this isn't the case, it should throw an exception so it will no
47 * longer be bothered by the element builder.
48 *
49 * @throws Exception
50 * if some unrecoverable state is reached
51 */
52 void init() throws Exception;
53
54 /**
55 * This method is called before the plugin is abandoned by the element builder.
56 */
57 void destroy();
58
59 /**
60 * This method is called if the media package builder tries to create a new media package element of type
61 * <code>elementType</code>.
62 * <p>
63 * Every registered builder plugin will then be asked whether it is able to create a media package element from the
64 * given element type. If this is the case for a plugin, it will then be asked to create such an element by a call to
65 * {@link #newElement(org.opencastproject.mediapackage.MediaPackageElement.Type ,MediaPackageElementFlavor)}.
66 * </p>
67 *
68 * @param type
69 * the type
70 * @param flavor
71 * the element flavor
72 * @return <code>true</code> if the plugin is able to create such an element
73 */
74 boolean accept(MediaPackageElement.Type type, MediaPackageElementFlavor flavor);
75
76 /**
77 * This method is called on every registered media package builder plugin until one of these plugins returns
78 * <code>true</code>. If no plugin recognises the file, it is rejected.
79 * <p>
80 * The parameters <code>type</code> and <code>flavor</code> may be taken as strong hints and may both be
81 * <code>null</code>.
82 * </p>
83 * <p>
84 * Implementers schould return the correct mime type for the given file if they are absolutely sure about the file.
85 * Otherwise, <code>null</code> should be returned.
86 * </p>
87 *
88 * @param uri
89 * the element location
90 * @param type
91 * the element type
92 * @param flavor
93 * the element flavor
94 * @return <code>true</code> if the plugin can handle the element
95 */
96 boolean accept(URI uri, MediaPackageElement.Type type, MediaPackageElementFlavor flavor);
97
98 /**
99 * This method is called while the media package builder parses a media package manifest.
100 * <p>
101 * Every registered builder plugin will then be asked, whether it is able to create a media package element from the
102 * given element definition.
103 * </p>
104 * <p>
105 * The element must then be constructed and returned in the call to
106 * {@link #elementFromManifest(Node, MediaPackageSerializer)}.
107 * </p>
108 *
109 * @param elementNode
110 * the node
111 * @return <code>true</code> if the plugin is able to create such an element
112 */
113 boolean accept(Node elementNode);
114
115 /**
116 * Creates a media package element from the given url that was previously accepted.
117 *
118 * @param uri
119 * the element location
120 * @return the new media package element
121 * @throws UnsupportedElementException
122 * if creating the media package element fails
123 */
124 MediaPackageElement elementFromURI(URI uri) throws UnsupportedElementException;
125
126 /**
127 * Creates a media package element from the DOM element.
128 *
129 * @param elementNode
130 * the DOM node
131 * @param serializer
132 * the media package serializer
133 * @return the media package element
134 * @throws UnsupportedElementException
135 */
136 MediaPackageElement elementFromManifest(Node elementNode, MediaPackageSerializer serializer)
137 throws UnsupportedElementException;
138
139 /**
140 * Creates a new media package element of the specified type.
141 *
142 * @param type
143 * the element type
144 * @param flavor
145 * the element flavor
146 * @return the new media package element
147 */
148 MediaPackageElement newElement(MediaPackageElement.Type type, MediaPackageElementFlavor flavor);
149
150 }