001 /*
002 * Java Genetic Algorithm Library (jenetics-3.9.0).
003 * Copyright (c) 2007-2017 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 * Franz Wilhelmstötter (franz.wilhelmstoetter@gmx.at)
019 */
020 package org.jenetics.xml.stream;
021
022 import static java.util.Objects.requireNonNull;
023
024 import java.io.InputStream;
025 import java.io.OutputStream;
026
027 import javax.xml.stream.XMLInputFactory;
028 import javax.xml.stream.XMLOutputFactory;
029 import javax.xml.stream.XMLStreamException;
030
031 /**
032 * This class contains helper methods for creating
033 * {@link javax.xml.stream.XMLStreamReader} and
034 * {@link javax.xml.stream.XMLStreamWriter} objects.
035 * <p>
036 * Creating a new XML stream reader:
037 * <pre>{@code
038 * try (AutoCloseableXMLStreamReader xml = XML.reader(in)) {
039 * // Move XML stream to first element.
040 * xml.next();
041 * return reader.read(xml);
042 * }
043 * }</pre>
044 *
045 * Create a new XML stream reader:
046 * <pre>{@code
047 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out)) {
048 * writer.write(value, xml);
049 * }
050 * }</pre>
051 *
052 * Create a new XML stream reader with pretty-print-indentation:
053 * <pre>{@code
054 * final String indent = " ";
055 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out, indent)) {
056 * writer.write(value, xml);
057 * }
058 * }</pre>
059 *
060 * @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
061 * @version 3.9
062 * @since 3.9
063 */
064 public final class XML {
065 private XML() {}
066
067 /**
068 * Create a new XML stream reader from the given {@code input} stream.
069 * <em>
070 * The caller is responsible for closing the returned {@code XMLStreamReader}.
071 * </em>
072 *
073 * <pre>{@code
074 * try (AutoCloseableXMLStreamReader xml = XML.reader(in)) {
075 * // Move XML stream to first element.
076 * xml.next();
077 * return reader.read(xml);
078 * }
079 * }</pre>
080 *
081 * @param input the input stream
082 * @return a new {@code Closeable} XML stream reader
083 * @throws XMLStreamException if the creation of the XML stream reader fails
084 * @throws NullPointerException if the given {@code input} stream is
085 * {@code null}
086 */
087 public static AutoCloseableXMLStreamReader reader(final InputStream input)
088 throws XMLStreamException
089 {
090 requireNonNull(input);
091
092 final XMLInputFactory factory = XMLInputFactory.newFactory();
093 return new XMLReaderProxy(factory.createXMLStreamReader(input));
094 }
095
096 /**
097 * Create a new {@code XMLStreamWriter} from the given output stream.
098 * <em>
099 * The caller is responsible for closing the returned {@code XMLStreamWriter}.
100 * </em>
101 *
102 * <pre>{@code
103 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out, " ")) {
104 * writer.write(value, xml);
105 * }
106 * }</pre>
107 *
108 * @param output the underlying output stream
109 * @param indent the element indent used for the XML output
110 * @return a new {@code XMLStreamWriter} instance
111 * @throws XMLStreamException if an error occurs while creating the XML
112 * stream writer
113 * @throws NullPointerException if the given {@code output} stream is
114 * {@code null}
115 */
116 public static AutoCloseableXMLStreamWriter writer(
117 final OutputStream output,
118 final String indent
119 )
120 throws XMLStreamException
121 {
122 requireNonNull(output);
123
124 final XMLOutputFactory factory = XMLOutputFactory.newFactory();
125 return indent != null
126 ? new IndentingXMLWriter(factory.createXMLStreamWriter(output), indent)
127 : new XMLWriterProxy(factory.createXMLStreamWriter(output));
128 }
129
130 /**
131 * Create a new {@code XMLStreamWriter} from the given output stream.
132 * <em>
133 * The caller is responsible for closing the returned {@code XMLStreamWriter}.
134 * </em>
135 *
136 * <pre>{@code
137 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out)) {
138 * writer.write(value, xml);
139 * }
140 * }</pre>
141 *
142 * @param output the underlying output stream
143 * @return a new {@code XMLStreamWriter} instance
144 * @throws XMLStreamException if an error occurs while creating the XML
145 * stream writer
146 * @throws NullPointerException if the given {@code output} stream is
147 * {@code null}
148 */
149 public static AutoCloseableXMLStreamWriter writer(final OutputStream output)
150 throws XMLStreamException
151 {
152 return writer(output, null);
153 }
154
155 }
|