001/*
002 * ============================================================================
003 * Copyright © 2002-2020 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
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, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.xml.builder.spi;
019
020import static org.apiguardian.api.API.Status.MAINTAINED;
021import static org.tquadrat.foundation.xml.builder.spi.SGMLPrinter.composeDocumentString;
022
023import java.util.Collection;
024import java.util.List;
025import java.util.Map;
026import java.util.Optional;
027
028import org.apiguardian.api.API;
029import org.tquadrat.foundation.annotation.ClassVersion;
030import org.tquadrat.foundation.xml.builder.Namespace;
031
032/**
033 *  The definition for an SGML document.
034 *
035 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
036 *  @version $Id: Document.java 980 2022-01-06 15:29:19Z tquadrat $
037 *  @since 0.0.5
038 *
039 *  @param  <E> The implementation for the elements of this document.
040 *
041 *  @UMLGraph.link
042 */
043@SuppressWarnings( "InterfaceMayBeAnnotatedFunctional" )
044@ClassVersion( sourceVersion = "$Id: Document.java 980 2022-01-06 15:29:19Z tquadrat $" )
045@API( status = MAINTAINED, since = "0.0.5" )
046public interface Document<E extends Element>
047{
048        /*---------*\
049    ====** Methods **==========================================================
050        \*---------*/
051    /**
052     *  Returns the value for the attribute with the given name.<br>
053     *  <br>The attribute is assigned to the
054     *  {@linkplain #getRootElement() root element}
055     *  of the document as documents itself cannot have attributes.
056     *
057     *  @param  name    The attribute name.
058     *  @return An instance of
059     *      {@link Optional}
060     *      that holds the value for that attribute.
061     */
062    public default Optional<String> getAttribute( final String name ) { return getRootElement().getAttribute( name ); }
063
064    /**
065     *  Provides read access to the attributes of the
066     *  {@linkplain #getRootElement() root element}
067     *  of the document as documents itself cannot have attributes.
068     *
069     *  @return A reference to the attributes.
070     */
071    public default Map<String,String> getAttributes() { return getRootElement().getAttributes(); }
072
073    /**
074     *  Provides access to the children for this document; the returned
075     *  collection is not modifiable.<br>
076     *  <br>The
077     *  {@linkplain #getRootElement() root element}
078     *  is the last entry in the returned collection.
079     *
080     *  @return A reference to the children of this document.
081     */
082    public default Collection<? extends Element> getChildren() { return List.of( getRootElement() ); }
083
084    /**
085     *  Returns the name of the root element.
086     *
087     *  @return The name of the root element.
088     */
089    public default String getElementName() { return getRootElement().getElementName(); }
090
091    /**
092     *  Provides access to the namespaces for this document (although in fact,
093     *  it will be the namespaces for the root element); the returned
094     *  collection is not modifiable.
095     *
096     *  @return A reference to the namespaces for the root element of this
097     *      document; if it does not have namespaces assigned, an empty
098     *      collection will be returned.
099     *
100     *  @see Element#getNamespaces()
101     */
102    public default Collection<Namespace> getNamespaces() { return getRootElement().getNamespaces(); }
103
104    /**
105     *  Return the root element for this document.
106     *
107     *  @return The root element.
108     */
109    public E getRootElement();
110
111    /**
112     *  Returns a String representation for this element instance.
113     *
114     *  @param  prettyPrint The pretty print flag.
115     *  @return The String representation.
116     */
117    public default String toString( final boolean prettyPrint )
118    {
119        final var retValue = composeDocumentString( prettyPrint, this );
120
121        //---* Done *----------------------------------------------------------
122        return retValue;
123    }   //  toString()
124}
125//  interface Document
126
127/*
128 *  End of File
129 */