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 java.util.Arrays.stream;
021import static java.util.Collections.sort;
022import static org.apiguardian.api.API.Status.MAINTAINED;
023import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
024import static org.tquadrat.foundation.xml.builder.spi.SGMLPrinter.composeNamespaceString;
025
026import java.net.URI;
027import java.net.URISyntaxException;
028import java.util.ArrayList;
029import java.util.Collection;
030import java.util.HashSet;
031import java.util.List;
032import java.util.Set;
033
034import org.apiguardian.api.API;
035import org.tquadrat.foundation.annotation.ClassVersion;
036import org.tquadrat.foundation.annotation.MountPoint;
037import org.tquadrat.foundation.lang.Objects;
038import org.tquadrat.foundation.util.LazySet;
039import org.tquadrat.foundation.xml.builder.Namespace;
040
041/**
042 *  <p>{@summary This class provides the support for namespaces to
043 *  elements.}</p>
044 *  <p>Elements that also do support attributes should use
045 *  {@link AttributeSupport}
046 *  instead; that includes support for namespaces. In fact, that class extends
047 *  this one.</p>
048 *
049 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
050 *  @version $Id: NamespaceSupport.java 980 2022-01-06 15:29:19Z tquadrat $
051 *  @since 0.0.5
052 *
053 *  @UMLGraph.link
054 */
055@ClassVersion( sourceVersion = "$Id: NamespaceSupport.java 980 2022-01-06 15:29:19Z tquadrat $" )
056@API( status = MAINTAINED, since = "0.0.5" )
057public sealed class NamespaceSupport
058    permits AttributeSupport
059{
060        /*------------*\
061    ====** Attributes **=======================================================
062        \*------------*/
063    /**
064     *  The namespaces for the element.
065     */
066    private final Set<Namespace> m_Namespaces;
067
068    /**
069     *  The element that owns this {@code NamespaceSupport} instance.
070     */
071    private final Element m_Owner;
072
073        /*--------------*\
074    ====** Constructors **=====================================================
075        \*--------------*/
076    /**
077     *  Creates a new {@code NamespaceSupport} instance.
078     *
079     *  @param  owner   The element that owns this {@code NamespaceSupport}
080     *      instance.
081     */
082    public NamespaceSupport( final Element owner )
083    {
084        m_Owner = requireNonNullArgument( owner, "owner" );
085        m_Namespaces = LazySet.use( HashSet::new );
086    }   //  NamespaceSupport()
087
088        /*---------*\
089    ====** Methods **==========================================================
090        \*---------*/
091    /**
092     *  Provides access to the namespaces for this element; the returned
093     *  collection is not modifiable.
094     *
095     *  @return A reference the children of this element; if the element does
096     *      not have children, an empty collection will be returned.
097     */
098    public final Collection<Namespace> getNamespaces()
099    {
100        final List<Namespace> namespaces = new ArrayList<>( m_Namespaces );
101        sort( namespaces );
102        final var retValue = List.copyOf( namespaces );
103
104        //---* Done *----------------------------------------------------------
105        return retValue;
106    }   //  getNamespaces()
107
108    /**
109     *  Returns the reference to the owner of this instance of
110     *  {@code NamespaceSupport}.
111     *
112     *  @return The owner.
113     */
114    protected final Element getOwner() { return m_Owner; }
115
116    /**
117     *  Sets the given namespace.
118     *
119     *  @param  namespace   The namespace.
120     */
121    @SuppressWarnings( "UseOfConcreteClass" )
122    public final void setNamespace( final Namespace... namespace )
123    {
124        stream( requireNonNullArgument( namespace, "namespace" ) )
125            .filter( Objects::nonNull )
126            .forEach( m_Namespaces::add );
127    }   //  setNamespace()
128
129    /**
130     *  Sets the given namespace.
131     *
132     *  @param  identifier  The namespace identifier.
133     */
134    public final void setNamespace( final URI identifier )
135    {
136        setNamespace( new Namespace( identifier ) );
137    }   //  setNamespace()
138
139    /**
140     *  Sets the given namespace.
141     *
142     *  @param  identifier  The namespace identifier.
143     *  @throws URISyntaxException  The provided URI String is invalid.
144     */
145    public final void setNamespace( final String identifier ) throws URISyntaxException
146    {
147        setNamespace( new Namespace( identifier ) );
148    }   //  setNamespace()
149
150    /**
151     *  Sets the given namespace.<br>
152     *  <br>The given prefix is validated using the method that is
153     *  provided by
154     *  {@link org.tquadrat.foundation.xml.builder.XMLBuilderUtils#getPrefixValidator()}.
155     *
156     *  @param  prefix   The namespace prefix.
157     *  @param  identifier  The namespace identifier.
158     */
159    public final void setNamespace( final String prefix, final URI identifier )
160    {
161        setNamespace( new Namespace( prefix, identifier ) );
162    }   //  setNamespace()
163
164    /**
165     *  Sets the given namespace.<br>
166     *  <br>The given prefix is validated using the method that is
167     *  provided by
168     *  {@link org.tquadrat.foundation.xml.builder.XMLBuilderUtils#getPrefixValidator()}.
169     *
170     *  @param  prefix   The namespace prefix.
171     *  @param  identifier  The namespace identifier.
172     *  @throws URISyntaxException  The provided URI String is invalid.
173     */
174    public final void setNamespace( final String prefix, final String identifier ) throws URISyntaxException
175    {
176        setNamespace( new Namespace( prefix, identifier ) );
177    }   //  setNamespace()
178
179    /**
180     *  Returns the namespaces as a single formatted string.
181     *
182     *  @param  indentationLevel    The indentation level.
183     *  @param  prettyPrint The pretty print flag.
184     *  @return The attributes string.
185     */
186    @MountPoint
187    public String toString( final int indentationLevel, final boolean prettyPrint )
188    {
189        final var retValue = composeNamespaceString( indentationLevel, prettyPrint, m_Owner.getElementName(), getNamespaces() );
190
191        //---* Done *----------------------------------------------------------
192        return retValue;
193    }   //  toString()
194}
195//  class NamespaceSupport
196
197/*
198 *  End of File
199 */