001package ball.xml;
002/*-
003 * ##########################################################################
004 * Utilities
005 * %%
006 * Copyright (C) 2008 - 2022 Allen D. Ball
007 * %%
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *      http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 * ##########################################################################
020 */
021import java.util.stream.IntStream;
022import java.util.stream.Stream;
023import org.w3c.dom.Node;
024import org.w3c.dom.NodeList;
025
026/**
027 * Common XML services.
028 *
029 * @author {@link.uri mailto:ball@hcf.dev Allen D. Ball}
030 */
031public interface XMLServices {
032    FluentDocument document();
033
034    /**
035     * Create a {@link org.w3c.dom.DocumentFragment} {@link Node}
036     * (see {@link FluentNode#fragment(Node...)}).
037     *
038     * @param   stream          The {@link Stream} of {@link Node}s to
039     *                          append to the newly created
040     *                          {@link org.w3c.dom.DocumentFragment}.
041     *
042     * @return  The newly created {@link org.w3c.dom.DocumentFragment}.
043     */
044    default FluentNode fragment(Stream<Node> stream) {
045        return document().fragment(stream);
046    }
047
048    /**
049     * Create a {@link org.w3c.dom.DocumentFragment} {@link Node}
050     * (see {@link FluentNode#fragment(Node...)}).
051     *
052     * @param   nodes           The {@link Node}s to append to the newly
053     *                          created
054     *                          {@link org.w3c.dom.DocumentFragment}.
055     *
056     * @return  The newly created {@link org.w3c.dom.DocumentFragment}.
057     */
058    default FluentNode fragment(Node... nodes) {
059        return document().fragment(nodes);
060    }
061
062    /**
063     * Create an {@link org.w3c.dom.Element} {@link Node}
064     * (see {@link FluentNode#element(String,Node...)}).
065     *
066     * @param   name            The {@link org.w3c.dom.Element} name.
067     * @param   stream          The {@link Stream} of {@link Node}s to
068     *                          append to the newly created
069     *                          {@link org.w3c.dom.Element}.
070     *
071     * @return  The newly created {@link org.w3c.dom.Element}.
072     */
073    default FluentNode element(String name, Stream<Node> stream) {
074        return document().element(name, stream);
075    }
076
077    /**
078     * Create an {@link org.w3c.dom.Element} {@link Node}
079     * (see {@link FluentNode#element(String,Node...)}).
080     *
081     * @param   name            The {@link org.w3c.dom.Element} name.
082     * @param   nodes           The {@link Node}s to append to the newly
083     *                          created {@link org.w3c.dom.Element}.
084     *
085     * @return  The newly created {@link org.w3c.dom.Element}.
086     */
087    default FluentNode element(String name, Node... nodes) {
088        return document().element(name, nodes);
089    }
090
091    /**
092     * Create an {@link org.w3c.dom.Attr} {@link Node}
093     * (see {@link FluentNode#attr(String)}).
094     *
095     * @param   name            The {@link org.w3c.dom.Attr} name.
096     *
097     * @return  The newly created {@link org.w3c.dom.Attr}.
098     */
099    default FluentNode attr(String name) { return document().attr(name); }
100
101    /**
102     * Create an {@link org.w3c.dom.Attr} {@link Node}
103     * (see {@link FluentNode#attr(String,String)}).
104     *
105     * @param   name            The {@link org.w3c.dom.Attr} name.
106     * @param   value           The {@link org.w3c.dom.Attr} value.
107     *
108     * @return  The newly created {@link org.w3c.dom.Attr}.
109     */
110    default FluentNode attr(String name, String value) {
111        return document().attr(name, value);
112    }
113
114    /**
115     * Create a {@link org.w3c.dom.Text} {@link Node}
116     * (see {@link FluentNode#text(String)}).
117     *
118     * @param   content         The {@link org.w3c.dom.Text} content.
119     *
120     * @return  The newly created {@link org.w3c.dom.Text}.
121     */
122    default FluentNode text(String content) {
123        return document().text(content);
124    }
125
126    /**
127     * Create a {@link org.w3c.dom.CDATASection} {@link Node}
128     * (see {@link FluentNode#cdata(String)}).
129     *
130     * @param   data            The {@link org.w3c.dom.CDATASection} data.
131     *
132     * @return  The newly created {@link org.w3c.dom.CDATASection}.
133     */
134    default FluentNode cdata(String data) {
135        return document().cdata(data);
136    }
137
138    /**
139     * Create a {@link org.w3c.dom.Comment} {@link Node}
140     * (see {@link FluentNode#comment(String)}).
141     *
142     * @param   data            The {@link org.w3c.dom.Comment} data.
143     *
144     * @return  The newly created {@link org.w3c.dom.Comment}.
145     */
146    default FluentNode comment(String data) {
147        return document().comment(data);
148    }
149
150    /**
151     * Convert a {@link NodeList} to a {@link Stream}.
152     *
153     * @param   list            The {@link NodeList}.
154     *
155     * @return  A {@link Stream} of {@link Node}s.
156     */
157    default Stream<Node> asStream(NodeList list) {
158        return IntStream.range(0, list.getLength()).mapToObj(list::item);
159    }
160}