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 java.util.TimeZone.getTimeZone;
023import static org.apiguardian.api.API.Status.STABLE;
024import static org.tquadrat.foundation.lang.Objects.isNull;
025import static org.tquadrat.foundation.lang.Objects.nonNull;
026
027import java.io.Serial;
028import java.util.Set;
029import java.util.TimeZone;
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 TimeZone}
040 *  values.}</p>
041 *  <p>The method
042 *  {@link #fromString(CharSequence)}
043 *  will use
044 *  {@link TimeZone#getTimeZone(String)}
045 *  to retrieve a {@code TimeZone} based on the given value.</p>
046 *  <p>The method
047 *  {@link #toString(TimeZone)}
048 *  will use
049 *  {@link TimeZone#getID()}
050 *  to do the conversion to a String.</p>
051 *
052 *  @note The class {@code TimeZone} is considered outdated.
053 *
054 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
055 *  @version $Id: TimeZoneStringConverter.java 1091 2024-01-25 23:10:08Z tquadrat $
056 *  @since 0.0.6
057 *
058 *  @UMLGraph.link
059 */
060@SuppressWarnings( "UseOfObsoleteDateTimeApi" )
061@ClassVersion( sourceVersion = "$Id: TimeZoneStringConverter.java 1091 2024-01-25 23:10:08Z tquadrat $" )
062@API( status = STABLE, since = "0.0.6" )
063public final class TimeZoneStringConverter implements StringConverter<TimeZone>
064{
065        /*-----------*\
066    ====** Constants **========================================================
067        \*-----------*/
068    /**
069     *  The error message for an invalid or unknown time zone id on the command
070     *  line: {@value}.
071     */
072    public static final String MSG_UnknownTimeZone = "Unknown TimeZone: %1$s";
073
074        /*------------------------*\
075    ====** Static Initialisations **===========================================
076        \*------------------------*/
077    /**
078     *  The serial version UID for objects of this class: {@value}.
079     *
080     *  @hidden
081     */
082    @Serial
083    private static final long serialVersionUID = 1L;
084
085    /**
086     *  An instance of this class.
087     */
088    public static final TimeZoneStringConverter INSTANCE = new TimeZoneStringConverter();
089
090        /*--------------*\
091    ====** Constructors **=====================================================
092        \*--------------*/
093    /**
094     *  Creates a new instance of {@code TimeZoneStringConverter}.
095     */
096    public TimeZoneStringConverter() {}
097
098        /*---------*\
099    ====** Methods **==========================================================
100        \*---------*/
101    /**
102     *  {@inheritDoc}
103     */
104    @Override
105    public final TimeZone fromString( final CharSequence source ) throws IllegalArgumentException
106    {
107        TimeZone retValue = null;
108        if( nonNull( source ) )
109        {
110            final var timezone = source.toString();
111            retValue = getTimeZone( timezone );
112            if( retValue.equals( getTimeZone( "GMT") ) && !Set.of( TimeZone.getAvailableIDs() ).contains( timezone ) )
113            {
114                throw new IllegalArgumentException( format( MSG_UnknownTimeZone, timezone ) );
115            }
116        }
117
118        //---* Done *----------------------------------------------------------
119        return retValue;
120    }   //  fromString()
121
122    /**
123     *  This method is used by the
124     *  {@link java.util.ServiceLoader}
125     *  to obtain the instance for this
126     *  {@link org.tquadrat.foundation.lang.StringConverter}
127     *  implementation.
128     *
129     *  @return The instance for this {@code StringConverter} implementation.
130     */
131    public static final TimeZoneStringConverter provider() { return INSTANCE; }
132
133    /**
134     *  {@inheritDoc}
135     */
136    @Override
137    public final String toString( final TimeZone source )
138    {
139        final var retValue = isNull( source ) ? null : source.getID();
140
141        //---* Done *----------------------------------------------------------
142        return retValue;
143    }   //  toString()
144}
145//  class TimeZoneStringConverter
146
147/*
148 *  End of File
149 */