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 java.net.InetAddress.getByName;
023import static org.apiguardian.api.API.Status.STABLE;
024import static org.tquadrat.foundation.lang.Objects.nonNull;
025import static org.tquadrat.foundation.util.StringUtils.isEmpty;
026
027import java.io.Serial;
028import java.net.InetAddress;
029import java.net.UnknownHostException;
030
031import org.apiguardian.api.API;
032import org.tquadrat.foundation.annotation.ClassVersion;
033import org.tquadrat.foundation.lang.StringConverter;
034
035/**
036 *  The implementation of
037 *  {@link StringConverter}
038 *  for
039 *  {@link InetAddress}
040 *  values.<br>
041 *  <br>The method
042 *  {@link #fromString(CharSequence)}
043 *  will use
044 *  {@link InetAddress#getByName(String)}
045 *  to create a {@code InetAddress} instance from the given value; this means,
046 *  that when a host name is given as an argument &ndash; instead of an IP4 or
047 *  IP6 address String &ndash; an
048 *  {@link IllegalArgumentException}
049 *  is thrown when that host is unknown (cannot be resolved by DNS). But
050 *  {@code fromString()} will not accept {@code null} or the empty String for
051 *  {@code localhost}; for these values it will also throw an
052 *  {@code IllegalArgumentException}.<br>
053 *  <br>The method
054 *  {@link #toString(InetAddress)}
055 *  uses
056 *  {@link InetAddress#getHostAddress()}
057 *  to get the IP address as a String.
058 *
059 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
060 *  @version $Id: InetAddressStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
061 *  @since 0.0.6
062 *
063 *  @UMLGraph.link
064 */
065@ClassVersion( sourceVersion = "$Id: InetAddressStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
066@API( status = STABLE, since = "0.0.6" )
067public final class InetAddressStringConverter implements StringConverter<InetAddress>
068{
069        /*-----------*\
070    ====** Constants **========================================================
071        \*-----------*/
072    /**
073     *  The error message about an invalid address or an unknown host name:
074     *  {@value}.
075     */
076    public static final String MSG_InvalidAddress = "'%1$s' is invalid or unknown";
077
078        /*------------------------*\
079    ====** Static Initialisations **===========================================
080        \*------------------------*/
081    /**
082     *  The serial version UID for objects of this class: {@value}.
083     *
084     *  @hidden
085     */
086    @Serial
087    private static final long serialVersionUID = 1L;
088
089    /**
090     *  An instance of this class.
091     */
092    public static final InetAddressStringConverter INSTANCE = new InetAddressStringConverter();
093
094        /*--------------*\
095    ====** Constructors **=====================================================
096        \*--------------*/
097    /**
098     *  Creates a new instance of {@code InetAddressStringConverter}.
099     */
100    public InetAddressStringConverter() {}
101
102        /*---------*\
103    ====** Methods **==========================================================
104        \*---------*/
105    /**
106     *  {@inheritDoc}
107     */
108    @Override
109    public final InetAddress fromString( final CharSequence source ) throws IllegalArgumentException
110    {
111        InetAddress retValue = null;
112        if( nonNull( source ) )
113        {
114            if( isEmpty( source ) ) throw new IllegalArgumentException( format( MSG_InvalidAddress, source ) );
115            try
116            {
117                retValue = getByName( source.toString() );
118            }
119            catch( final UnknownHostException e )
120            {
121                throw new IllegalArgumentException( format( MSG_InvalidAddress, source ), e );
122            }
123        }
124
125        //---* Done *----------------------------------------------------------
126        return retValue;
127    }   //  fromString()
128
129    /**
130     *  This method is used by the
131     *  {@link java.util.ServiceLoader}
132     *  to obtain the instance for this
133     *  {@link org.tquadrat.foundation.lang.StringConverter}
134     *  implementation.
135     *
136     *  @return The instance for this {@code StringConverter} implementation.
137     */
138    public static final InetAddressStringConverter provider() { return INSTANCE; }
139
140    /**
141     *  {@inheritDoc}
142     */
143    @Override
144    public final String toString( final InetAddress source )
145    {
146        final var retValue = nonNull( source ) ? source.getHostAddress() : null;
147
148        //---* Done *----------------------------------------------------------
149        return retValue;
150    }   //  toString()
151}
152//  class InetAddressStringConverter
153
154/*
155 *  End of File
156 */