001/*
002 * Java Genetic Algorithm Library (jenetics-8.1.0).
003 * Copyright (c) 2007-2024 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@gmail.com)
019 */
020package io.jenetics.xml.stream;
021
022import static java.util.Objects.requireNonNull;
023
024import java.io.InputStream;
025import java.io.OutputStream;
026
027import javax.xml.stream.XMLInputFactory;
028import javax.xml.stream.XMLOutputFactory;
029import 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 * {@snippet lang="java":
038 * try (AutoCloseableXMLStreamReader xml = XML.reader(in)) {
039 *     // Move XML stream to first element.
040 *     xml.next();
041 *     return reader.read(xml);
042 * }
043 * }
044 *
045 * Create a new XML stream reader:
046 * {@snippet lang="java":
047 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out)) {
048 *     writer.write(value, xml);
049 * }
050 * }
051 *
052 * Create a new XML stream reader with pretty-print-indentation:
053 * {@snippet lang="java":
054 * final String indent = "    ";
055 * try (AutoCloseableXMLStreamWriter xml = XML.writer(out, indent)) {
056 *     writer.write(value, xml);
057 * }
058 * }
059 *
060 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
061 * @version 3.9
062 * @since 3.9
063 */
064public 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         * {@snippet lang="java":
074         * try (AutoCloseableXMLStreamReader xml = XML.reader(in)) {
075         *     // Move XML stream to first element.
076         *     xml.next();
077         *     return reader.read(xml);
078         * }
079         * }
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
093                //      .newFactory(XMLInputFactory.class.getName(), null);
094                final XMLInputFactory factory = XMLInputFactory.newFactory();
095                return new XMLReaderProxy(
096                        factory.createXMLStreamReader(input, "UTF-8"));
097        }
098
099        /**
100         * Create a new {@code XMLStreamWriter} from the given output stream.
101         * <em>
102         * The caller is responsible for closing the returned {@code XMLStreamWriter}.
103         * </em>
104         *
105         * {@snippet lang="java":
106         * try (AutoCloseableXMLStreamWriter xml = XML.writer(out, "    ")) {
107         *     writer.write(value, xml);
108         * }
109         * }
110         *
111         * @param output the underlying output stream
112         * @param indent the element indent used for the XML output
113         * @return a new {@code XMLStreamWriter} instance
114         * @throws XMLStreamException if an error occurs while creating the XML
115         *         stream writer
116         * @throws NullPointerException if the given {@code output} stream is
117         *         {@code null}
118         */
119        public static AutoCloseableXMLStreamWriter writer(
120                final OutputStream output,
121                final String indent
122        )
123                throws XMLStreamException
124        {
125                requireNonNull(output);
126
127                final XMLOutputFactory factory = XMLOutputFactory.newFactory();
128                return indent != null
129                        ? new IndentingXMLWriter(
130                                factory.createXMLStreamWriter(output, "UTF-8"), indent)
131                        : new XMLWriterProxy(
132                                factory.createXMLStreamWriter(output, "UTF-8"));
133        }
134
135        /**
136         * Create a new {@code XMLStreamWriter} from the given output stream.
137         * <em>
138         * The caller is responsible for closing the returned {@code XMLStreamWriter}.
139         * </em>
140         *
141         * {@snippet lang="java":
142         * try (AutoCloseableXMLStreamWriter xml = XML.writer(out)) {
143         *     writer.write(value, xml);
144         * }
145         * }
146         *
147         * @param output the underlying output stream
148         * @return a new {@code XMLStreamWriter} instance
149         * @throws XMLStreamException if an error occurs while creating the XML
150         *         stream writer
151         * @throws NullPointerException if the given {@code output} stream is
152         *         {@code null}
153         */
154        public static AutoCloseableXMLStreamWriter writer(final OutputStream output)
155                throws XMLStreamException
156        {
157                return writer(output, null);
158        }
159
160}