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.mediapackage;
23
24 import org.w3c.dom.Document;
25
26 import java.io.IOException;
27 import java.io.OutputStream;
28
29 import javax.xml.parsers.ParserConfigurationException;
30 import javax.xml.transform.TransformerException;
31
32 /**
33 * Definition for a plain xml catalog.
34 */
35 public interface XMLCatalog {
36
37 /**
38 * Serializes the catalog to a DOM.
39 *
40 * todo think about hiding technical exceptions
41 *
42 * @throws ParserConfigurationException
43 * if the xml parser environment is not correctly configured
44 * @throws TransformerException
45 * if serialization of the metadata document fails
46 * @throws IOException
47 * if an error with catalog file handling occurs
48 */
49 Document toXml() throws ParserConfigurationException, TransformerException, IOException;
50
51 /**
52 * Serializes the catalog to a JSON string.
53 *
54 * @return the json string
55 * @throws IOException
56 * if an error with the catalog file handling occurs
57 */
58 String toJson() throws IOException;
59
60 /**
61 * Writes an xml representation of this Catalog to a string.
62 *
63 * @return the Catalog serialized to a string
64 */
65 String toXmlString() throws IOException;
66
67 /**
68 * Writes an xml representation of this Catalog to a stream.
69 *
70 * @param out
71 * The output stream
72 * @param format
73 * Whether to format the output for readability, or not (false gives better performance)
74 */
75 void toXml(OutputStream out, boolean format) throws IOException;
76
77 /**
78 * Marshal elements with empty values to support
79 * remove existing values during catalog merge.
80 *
81 * @param includeEmpty
82 */
83 void includeEmpty(boolean includeEmpty);
84
85 }