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