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 package org.opencastproject.caption.api;
23
24 import org.opencastproject.mediapackage.MediaPackageElement;
25
26 import java.io.IOException;
27 import java.io.InputStream;
28 import java.io.OutputStream;
29 import java.util.List;
30
31 /**
32 * Imports caption catalogs to a list of caption objects and exports these objects to catalog presentations.
33 */
34 public interface CaptionConverter {
35
36 /**
37 * Imports captions to {@link List}. If caption format is capable of containing more than one language, language
38 * parameter is used to define which captions are parsed.
39 *
40 * @param inputStream
41 * stream from where captions are read
42 * @param language
43 * (optional) captions' language
44 * @return {@link List} List of captions
45 * @throws CaptionConverterException
46 * if parser encounters an exception
47 */
48 List<Caption> importCaption(InputStream inputStream, String language) throws CaptionConverterException;
49
50 /**
51 * Exports caption collection. Language parameter is used to set language of the captions for those caption format
52 * that are capable of storing information about language.
53 *
54 * @param outputStream
55 * stream to which captions are written
56 * @param captions
57 * collection to be exported
58 * @param language
59 * (optional) captions' language
60 * @throws IOException
61 * if exception occurs writing to output stream
62 */
63 void exportCaption(OutputStream outputStream, List<Caption> captions, String language) throws IOException;
64
65 /**
66 * Reads captions and return information about language if such information is available. Returns empty list
67 * otherwise.
68 *
69 * @param inputStream
70 * stream from where captions are read
71 * @return Array containing languages in captions
72 * @throws CaptionConverterException
73 * if parser encounters exception
74 */
75 String[] getLanguageList(InputStream inputStream) throws CaptionConverterException;
76
77 /**
78 * Get extension of specific caption format.
79 *
80 * @return caption format extension
81 */
82 String getExtension();
83
84 /**
85 * Get type of specific caption element (Catalog, Attachment).
86 *
87 * @return type
88 */
89 MediaPackageElement.Type getElementType();
90
91 }