001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.util.stringconverter;
020
021import static java.lang.String.format;
022import static org.apiguardian.api.API.Status.STABLE;
023import static org.tquadrat.foundation.lang.Objects.isNull;
024import static org.tquadrat.foundation.lang.Objects.nonNull;
025
026import java.io.Serial;
027import java.net.MalformedURLException;
028import java.net.URL;
029import java.util.Collection;
030import java.util.List;
031
032import org.apiguardian.api.API;
033import org.tquadrat.foundation.annotation.ClassVersion;
034import org.tquadrat.foundation.lang.StringConverter;
035
036/**
037 *  <p>{@summary An implementation of
038 *  {@link StringConverter}
039 *  for
040 *  {@link URL}
041 *  values.}</p>
042 *  <p>The method
043 *  {@link #fromString(CharSequence)}
044 *  will use the constructor
045 *  {@link URL#URL(String)}
046 *  to create a {@code URL} instance from the given value.</p>
047 *
048 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
049 *  @version $Id: URLStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
050 *  @since 0.0.6
051 *
052 *  @UMLGraph.link
053 */
054@ClassVersion( sourceVersion = "$Id: URLStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
055@API( status = STABLE, since = "0.0.6" )
056public sealed class URLStringConverter implements StringConverter<URL>
057    permits EncodedURLStringConverter
058{
059        /*-----------*\
060    ====** Constants **========================================================
061        \*-----------*/
062    /**
063     *  The error message for an invalid URL: {@value}.
064     */
065    public static final String MSG_InvalidURL = "'%1$s' cannot be parsed as a valid URL";
066
067        /*------------------------*\
068    ====** Static Initialisations **===========================================
069        \*------------------------*/
070    /**
071     *  The serial version UID for objects of this class: {@value}.
072     *
073     *  @hidden
074     */
075    @Serial
076    private static final long serialVersionUID = 1L;
077
078    /**
079     *  An instance of this class.
080     */
081    public static final URLStringConverter INSTANCE = new URLStringConverter();
082
083        /*--------------*\
084    ====** Constructors **=====================================================
085        \*--------------*/
086    /**
087     *  Creates a new instance of {@code URLStringConverter}.
088     */
089    public URLStringConverter() {}
090
091        /*---------*\
092    ====** Methods **==========================================================
093        \*---------*/
094    /**
095     *  {@inheritDoc}
096     */
097    @Override
098    public URL fromString( final CharSequence source ) throws IllegalArgumentException
099    {
100        URL retValue = null;
101        if( nonNull( source ) )
102        {
103            try
104            {
105                retValue = new URL( source.toString() );
106            }
107            catch( final MalformedURLException e )
108            {
109                throw new IllegalArgumentException( format( MSG_InvalidURL, source ), e );
110            }
111        }
112
113        //---* Done *----------------------------------------------------------
114        return retValue;
115    }   //  fromString()
116
117    /**
118     *  Provides the subject class for this converter.
119     *
120     *  @return The subject class.
121     */
122    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
123    public final Collection<Class<?>> getSubjectClass() { return List.of( URL.class ); }
124
125    /**
126     *  This method is used by the
127     *  {@link java.util.ServiceLoader}
128     *  to obtain the instance for this
129     *  {@link org.tquadrat.foundation.lang.StringConverter}
130     *  implementation.
131     *
132     *  @return The instance for this {@code StringConverter} implementation.
133     */
134    public static final URLStringConverter provider() { return INSTANCE; }
135
136    /**
137     *  {@inheritDoc}
138     */
139    @Override
140    public String toString( final URL source )
141    {
142        final var retValue = isNull( source ) ? null : source.toExternalForm();
143
144        //---* Done *----------------------------------------------------------
145        return retValue;
146    }   //  toString()
147}
148//  class URLStringConverter
149
150/*
151 *  End of File
152 */