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;
025import static org.tquadrat.foundation.util.JavaUtils.getCallersClassLoader;
026import static org.tquadrat.foundation.util.StringUtils.isEmptyOrBlank;
027
028import java.io.Serial;
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 Class}
039 *  values.<br>
040 *  <br>The method
041 *  {@link #fromString(CharSequence)}
042 *  will use
043 *  {@link Class#forName(String, boolean, ClassLoader)}
044 *  to load the class with the given name. This means that the conversion may
045 *  fail even for an otherwise valid class name when the respective class is
046 *  not on the CLASSPATH or otherwise loadable.<br>
047 *  <br>It uses the
048 *  {@link ClassLoader} that was used to load the caller for this method,
049 *  and the {@code boolean} argument will be set to {@code false}, meaning that
050 *  the class will not be initialised if not loaded previously.
051 *
052 *  @see Class#forName(String, boolean, ClassLoader)
053 *  @see org.tquadrat.foundation.util.JavaUtils#getCallersClassLoader()
054 *
055 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
056 *  @version $Id: ClassStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
057 *  @since 0.0.6
058 *
059 *  @UMLGraph.link
060 */
061@ClassVersion( sourceVersion = "$Id: ClassStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
062@API( status = STABLE, since = "0.0.6" )
063public final class ClassStringConverter implements StringConverter<Class<?>>
064{
065        /*-----------*\
066    ====** Constants **========================================================
067        \*-----------*/
068    /**
069     *  The error message for the name of an unknown class on the command line:
070     *  {@value}.
071     */
072    public static final String MSG_UnknownClass = "'%s' cannot be parsed to the name of a known Java class";
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 ClassStringConverter INSTANCE = new ClassStringConverter();
089
090        /*--------------*\
091    ====** Constructors **=====================================================
092        \*--------------*/
093    /**
094     *  Creates a new instance of {@code ClassStringConverter}.
095     */
096    public ClassStringConverter() { /* Just exists */ }
097
098        /*---------*\
099    ====** Methods **==========================================================
100        \*---------*/
101    /**
102     *  {@inheritDoc}
103     */
104    @Override
105    public final Class<?> fromString( final CharSequence source ) throws IllegalArgumentException
106    {
107        Class<?> retValue = null;
108        if( nonNull( source ) )
109        {
110            if( isEmptyOrBlank( source ) ) throw new IllegalArgumentException( format( MSG_UnknownClass, source ) );
111            try
112            {
113                final var classLoader = getCallersClassLoader();
114                retValue = Class.forName( source.toString(), false, classLoader );
115            }
116            catch( final ClassNotFoundException e )
117            {
118                throw new IllegalArgumentException( format( MSG_UnknownClass, source ), e );
119            }
120        }
121
122        //---* Done *----------------------------------------------------------
123        return retValue;
124    }   //  fromString()
125
126    /**
127     *  This method is used by the
128     *  {@link java.util.ServiceLoader}
129     *  to obtain the instance for this
130     *  {@link org.tquadrat.foundation.lang.StringConverter}
131     *  implementation.
132     *
133     *  @return The instance for this {@code StringConverter} implementation.
134     */
135    public static final ClassStringConverter provider() { return INSTANCE; }
136
137    /**
138     *  {@inheritDoc}
139     */
140    @Override
141    public final String toString( final Class<?> source )
142    {
143        final var retValue = isNull( source) ? null : source.getName();
144
145        //---* Done *----------------------------------------------------------
146        return retValue;
147    }   //  toString()
148}
149//  class ClassStringConverter
150
151/*
152 *  End of File
153 */