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.nonNull;
024import static org.tquadrat.foundation.util.UniqueIdUtils.uuidFromString;
025
026import java.io.Serial;
027import java.util.UUID;
028
029import org.apiguardian.api.API;
030import org.tquadrat.foundation.annotation.ClassVersion;
031import org.tquadrat.foundation.exception.NullArgumentException;
032import org.tquadrat.foundation.lang.StringConverter;
033
034/**
035 *  <p>{@summary An implementation of
036 *  {@link StringConverter}
037 *  for
038 *  {@link UUID}
039 *  values.}</p>
040 *  <p>The method
041 *  {@link #fromString(CharSequence)}
042 *  will use
043 *  {@link org.tquadrat.foundation.util.UniqueIdUtils#uuidFromString(CharSequence)}
044 *  to create a {@code UUID} instance based on the given value.</p>
045 *
046 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
047 *  @version $Id: UUIDStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
048 *  @since 0.0.6
049 *
050 *  @UMLGraph.link
051 */
052@ClassVersion( sourceVersion = "$Id: UUIDStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
053@API( status = STABLE, since = "0.0.6" )
054public final class UUIDStringConverter implements StringConverter<UUID>
055{
056        /*-----------*\
057    ====** Constants **========================================================
058        \*-----------*/
059    /**
060     *  The error message for an invalid UUID on the command line: {@value}.
061     */
062    public static final String MSG_InvalidUUIDFormat = "'%1$s' cannot be parsed as a valid UUID";
063
064        /*------------------------*\
065    ====** Static Initialisations **===========================================
066        \*------------------------*/
067    /**
068     *  The serial version UID for objects of this class: {@value}.
069     *
070     *  @hidden
071     */
072    @Serial
073    private static final long serialVersionUID = 1L;
074
075    /**
076     *  An instance of this class.
077     */
078    public static final UUIDStringConverter INSTANCE = new UUIDStringConverter();
079
080        /*--------------*\
081    ====** Constructors **=====================================================
082        \*--------------*/
083    /**
084     *  Creates a new instance of {@code UUIDStringConverter}.
085     */
086    public UUIDStringConverter() {}
087
088        /*---------*\
089    ====** Methods **==========================================================
090        \*---------*/
091    /**
092     *  {@inheritDoc}
093     */
094    @Override
095    public final UUID fromString( final CharSequence source ) throws IllegalArgumentException
096    {
097        UUID retValue = null;
098        if( nonNull( source ) )
099        {
100            try
101            {
102                retValue = uuidFromString( source );
103            }
104            catch( @SuppressWarnings( "OverlyBroadCatchBlock" ) final NullArgumentException e )
105            {
106                throw e;
107            }
108            catch( final IllegalArgumentException e )
109            {
110                throw new IllegalArgumentException( format( MSG_InvalidUUIDFormat, source ), e );
111            }
112        }
113
114        //---* Done *----------------------------------------------------------
115        return retValue;
116    }   //  fromString()
117
118    /**
119     *  This method is used by the
120     *  {@link java.util.ServiceLoader}
121     *  to obtain the instance for this
122     *  {@link org.tquadrat.foundation.lang.StringConverter}
123     *  implementation.
124     *
125     *  @return The instance for this {@code StringConverter} implementation.
126     */
127    public static final UUIDStringConverter provider() { return INSTANCE; }
128}
129//  class UUIDStringConverter
130
131/*
132 *  End of File
133 */