001/* 002 * ============================================================================ 003 * Copyright © 2002-2023 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; 019 020import static java.lang.String.format; 021import static org.apiguardian.api.API.Status.STABLE; 022import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument; 023import static org.tquadrat.foundation.xml.builder.XMLBuilderUtils.getElementNameValidator; 024 025import java.util.Optional; 026 027import org.apiguardian.api.API; 028import org.tquadrat.foundation.annotation.ClassVersion; 029import org.tquadrat.foundation.xml.builder.spi.InvalidXMLNameException; 030import org.tquadrat.foundation.xml.builder.spi.XMLElementFactoryBase; 031 032/** 033 * The definition of a helper class for the creation of 034 * {@link XMLElement} 035 * instances with an element name belonging to a specified namespace. 036 * 037 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 038 * @version $Id: XMLElementFactory.java 1071 2023-09-30 01:49:32Z tquadrat $ 039 * @since 0.0.5 040 * 041 * @UMLGraph.link 042 */ 043@ClassVersion( sourceVersion = "$Id: XMLElementFactory.java 1071 2023-09-30 01:49:32Z tquadrat $" ) 044@API( status = STABLE, since = "0.0.5" ) 045public sealed interface XMLElementFactory 046 permits XMLElementFactoryBase 047{ 048 /*---------*\ 049 ====** Methods **========================================================== 050 \*---------*/ 051 /** 052 * Composes the name of an XML element from the prefix and the given 053 * element name.<br> 054 * <br>The given element name is validated using the method that is 055 * provided by 056 * {@link XMLBuilderUtils#getElementNameValidator()}. 057 * 058 * @param elementName The name of an XML element without any namespace 059 * prefix. 060 * @return The final element name. 061 */ 062 public default String composeElementName( final String elementName ) 063 { 064 requireNotEmptyArgument( elementName, "elementName" ); 065 final var retValue = getPrefix().map( prefix -> format( "%s:%s", prefix, elementName ) ).orElse( elementName ); 066 if( !getElementNameValidator().test( retValue ) ) 067 { 068 throw new InvalidXMLNameException( elementName ); 069 } 070 071 //---* Done *---------------------------------------------------------- 072 return retValue; 073 } // composeElementName() 074 075 /** 076 * Creates an XML element for the given element name that supports 077 * attributes, namespaces, children, text, {@code CDATA} and comments.<br> 078 * <br>The given element name is validated using the method that is 079 * provided by 080 * {@link XMLBuilderUtils#getElementNameValidator()}. 081 * 082 * @param elementName The element name. 083 * @return The new XML element. 084 */ 085 public default XMLElement createXMLElement( final String elementName ) 086 { 087 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ) ); 088 } // createXMLElement() 089 090 /** 091 * <p>{@summary Creates an XML element for the given element name that 092 * supports attributes, namespaces, children, text, {@code CDATA} and 093 * comments, and adds the given text.}</p> 094 * <p>The given element name is validated using the method that is 095 * provided by 096 * {@link XMLBuilderUtils#getElementNameValidator()}.</p> 097 * 098 * @param elementName The element name. 099 * @param text The text for the new element. 100 * @return The new XML element. 101 */ 102 public default XMLElement createXMLElement( final String elementName, final CharSequence text ) 103 { 104 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ), text ); 105 } // createXMLElement() 106 107 /** 108 * Creates an XML element for the given element name that supports 109 * attributes, namespaces, children, text, {@code CDATA} and comments, and 110 * adds it as child to the given parent.<br> 111 * <br>The given element name is validated using the method that is 112 * provided by 113 * {@link XMLBuilderUtils#getElementNameValidator()}. 114 * 115 * @param elementName The element name. 116 * @param parent The parent element. 117 * @return The new XML element. 118 */ 119 public default XMLElement createXMLElement( final String elementName, final XMLElement parent ) 120 { 121 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ), parent ); 122 } // createXMLElement() 123 124 /** 125 * Creates an XML element for the given element name that supports 126 * attributes, namespaces, children, text, {@code CDATA} and comments, 127 * adds the given text, and adds it as child to the given parent.<br> 128 * <br>The given element name is validated using the method that is 129 * provided by 130 * {@link XMLBuilderUtils#getElementNameValidator()}. 131 * 132 * @param elementName The element name. 133 * @param parent The parent element. 134 * @param text The text for the new element. 135 * @return The new XML element. 136 */ 137 public default XMLElement createXMLElement( final String elementName, final XMLElement parent, final CharSequence text ) 138 { 139 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ), parent, text ); 140 } // createXMLElement() 141 142 /** 143 * Creates an XML element for the given tag and adds it as child to the 144 * given document.<br> 145 * <br>The given element name is validated using the method that is 146 * provided by 147 * {@link XMLBuilderUtils#getElementNameValidator()}. 148 * 149 * @param elementName The element name. 150 * @param parent The document. 151 * @return The new XML element. 152 */ 153 public default XMLElement createXMLElement( final String elementName, final XMLDocument parent ) 154 { 155 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ), parent ); 156 } // createXMLElement() 157 158 /** 159 * Creates an XML element for the given tag and with the given text, and 160 * adds it as child to the given document.<br> 161 * <br>The given element name is validated using the method that is 162 * provided by 163 * {@link XMLBuilderUtils#getElementNameValidator()}. 164 * 165 * @param elementName The element name. 166 * @param parent The document. 167 * @param text The text for the new element. 168 * @return The new XML element. 169 */ 170 public default XMLElement createXMLElement( final String elementName, final XMLDocument parent, final CharSequence text ) 171 { 172 return XMLBuilderUtils.createXMLElement( composeElementName( elementName ), parent, text ); 173 } // createXMLElement() 174 175 /** 176 * Returns the namespace this XML element factory was created with. 177 * 178 * @return An instance of 179 * {@link Optional} 180 * that holds the namespace. 181 */ 182 public Optional<Namespace> getNamespace(); 183 184 /** 185 * Returns the prefix from the namespace this XML element factory was 186 * created with. 187 * 188 * @return An instance of 189 * {@link Optional} 190 * that holds the prefix. 191 */ 192 public default Optional<String> getPrefix() 193 { 194 final var retValue = getNamespace().flatMap( Namespace::getPrefix ); 195 196 //---* Done *---------------------------------------------------------- 197 return retValue; 198 } // getPrefix() 199} 200// interface XMLElementFactory 201 202/* 203 * End of File 204 */