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