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