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.lang.internal;
020
021import org.apiguardian.api.API;
022import org.tquadrat.foundation.annotation.ClassVersion;
023import org.tquadrat.foundation.annotation.MountPoint;
024import org.tquadrat.foundation.lang.StringConverter;
025
026import java.io.Serial;
027import java.util.Collection;
028import java.util.List;
029
030import static java.lang.String.format;
031import static java.util.Arrays.stream;
032import static org.apiguardian.api.API.Status.INTERNAL;
033import static org.tquadrat.foundation.lang.Objects.*;
034
035/**
036 *  The default implementation of
037 *  {@link StringConverter}
038 *  for types that are derived from
039 *  {@link Enum}.<br>
040 *  <br>The implementation of
041 *  {@link #fromString(CharSequence)}
042 *  provided here uses
043 *  {@link Class#getEnumConstants()}
044 *  to find the {@code enum} value:
045 *  <pre><code>  &hellip;
046 *  T result = stream( m_EnumType.getEnumConstants() )
047 *      .filter( constant -&gt; value.equals( constant.name() ) )
048 *      .findFirst()
049 *      .orElseThrow( () -&gt; new IllegalArgumentException( &hellip; );
050 *  &hellip;</code></pre>
051 *  <br>The implementation of
052 *  {@link #toString(Enum)}
053 *  in this class will return the value of
054 *  {@link Enum#name()}.
055 *
056 *  @param  <T> The concrete data type that is handled by this string converter
057 *      implementation.
058 *
059 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
060 *  @version $Id: DefaultEnumStringConverter.java 1119 2024-03-16 09:03:57Z tquadrat $
061 *  @since 0.1.0
062 *
063 *  @UMLGraph.link
064 */
065@ClassVersion( sourceVersion = "$Id: DefaultEnumStringConverter.java 1119 2024-03-16 09:03:57Z tquadrat $" )
066@API( status = INTERNAL, since = "0.1.0" )
067public class DefaultEnumStringConverter<T extends Enum<T>> implements StringConverter<T>
068{
069        /*-----------*\
070    ====** Constants **========================================================
071        \*-----------*/
072    /**
073     *  The error message for the name of an unknown class on the command line:
074     *  {@value}.
075     */
076    public static final String MSG_UnknownValue = "Unknown/invalid value: %1$s";
077
078        /*------------*\
079    ====** Attributes **=======================================================
080        \*------------*/
081    /**
082     *  The data type of the property to set.
083     *
084     *  @serial
085     */
086    private final Class<T> m_EnumType;
087
088        /*------------------------*\
089    ====** Static Initialisations **===========================================
090        \*------------------------*/
091    /**
092     *  The serial version UID for objects of this class: {@value}.
093     *
094     *  @hidden
095     */
096    @Serial
097    private static final long serialVersionUID = 1L;
098
099        /*--------------*\
100    ====** Constructors **=====================================================
101        \*--------------*/
102    /**
103     *  Creates a new {@code EnumValueHandler} instance.
104     *
105     *  @param  enumType    The data type for the property.
106     */
107    public DefaultEnumStringConverter( final Class<T> enumType )
108    {
109        m_EnumType = requireNonNullArgument( enumType, "enumType" );
110    }   //  EnumValueHandler()
111
112        /*---------*\
113    ====** Methods **==========================================================
114        \*---------*/
115    /**
116     *  {@inheritDoc}
117     */
118    @MountPoint
119    @Override
120    public T fromString( final CharSequence source ) throws IllegalArgumentException
121    {
122        T retValue = null;
123        if( nonNull( source ) )
124        {
125            if( source.isEmpty() ) throw new IllegalArgumentException( format( MSG_UnknownValue, source ) );
126            retValue = stream( m_EnumType.getEnumConstants() )
127                .filter( constant -> source.toString().equals( constant.name() ) )
128                .findFirst()
129                .orElseThrow( () -> new IllegalArgumentException( format( MSG_UnknownValue, source ) ) );
130        }
131
132        //---* Done *----------------------------------------------------------
133        return retValue;
134    }   //  fromString()
135
136    /**
137     *  Provides the subject class for this converter.
138     *
139     * @return The subject class.
140     */
141    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
142    public final Collection<Class<T>> getSubjectClass() { return List.of( m_EnumType ); }
143
144    /**
145     *  {@inheritDoc}
146     */
147    @MountPoint
148    @Override
149    public String toString( final T source )
150    {
151        final var retValue = isNull( source ) ? null : source.name();
152
153        //---* Done *----------------------------------------------------------
154        return retValue;
155    }   //  toString()
156}
157//  class DefaultEnumStringConverter
158
159/*
160 *  End of File
161 */