001/*
002 * ============================================================================
003 * Copyright © 2002-2024 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.email;
019
020import static java.lang.String.format;
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.lang.Objects.nonNull;
023
024import java.io.Serial;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028import org.tquadrat.foundation.lang.StringConverter;
029import jakarta.mail.internet.AddressException;
030import jakarta.mail.internet.InternetAddress;
031
032/**
033 *  <p>{@summary The implementation of
034 *  {@link StringConverter}
035 *  for an email address (implemented through
036 *  {@link InternetAddress}).}</p>
037 *  <p>The implementation of
038 *  {@link #toString(Object)}
039 *  uses
040 *  {@link InternetAddress#toString()}
041 *  to get the String representation of the email address.</p>
042 *  <p>{@link #fromString(CharSequence)}
043 *  calls the constructor
044 *  {@link InternetAddress#InternetAddress(String)}.</p>
045 *
046 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
047 *  @version $Id: EmailAddressStringConverter.java 1110 2024-03-04 15:26:06Z tquadrat $
048 *  @since 0.4.2
049 *
050 *  @UMLGraph.link
051 */
052@ClassVersion( sourceVersion = "$Id: EmailAddressStringConverter.java 1110 2024-03-04 15:26:06Z tquadrat $" )
053@API( status = STABLE, since = "0.4.2" )
054public final class EmailAddressStringConverter implements StringConverter<InternetAddress>
055{
056        /*-----------*\
057    ====** Constants **========================================================
058        \*-----------*/
059    /**
060     *  The error message about an invalid email address: {@value}.
061     */
062    public static final String MSG_InvalidEmailAddress = "'%1$s' is not a valid email address";
063
064        /*------------------------*\
065    ====** Static Initialisations **===========================================
066        \*------------------------*/
067    /**
068     *  The serial version UID for objects of this class: {@value}.
069     *
070     *  @hidden
071     */
072    @Serial
073    private static final long serialVersionUID = 1L;
074
075    /**
076     *  An instance of this class.
077     */
078    public static final EmailAddressStringConverter INSTANCE = new EmailAddressStringConverter();
079
080        /*--------------*\
081    ====** Constructors **=====================================================
082        \*--------------*/
083    /**
084     *  Creates a new instance of {@code EmailAddressStringConverter}.
085     */
086    public EmailAddressStringConverter() { /* Just exists */ }
087
088        /*---------*\
089    ====** Methods **==========================================================
090        \*---------*/
091    /**
092     *  {@inheritDoc}
093     */
094    @Override
095    public final InternetAddress fromString( final CharSequence source ) throws IllegalArgumentException
096    {
097        InternetAddress retValue = null;
098        if( nonNull( source ) )
099        {
100            final var sourceString = source.toString();
101            if( sourceString.isBlank() ) throw new IllegalArgumentException( format( MSG_InvalidEmailAddress, source ) );
102            try
103            {
104                retValue = new InternetAddress( sourceString );
105            }
106            catch( final AddressException e )
107            {
108                throw new IllegalArgumentException( format( MSG_InvalidEmailAddress, 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 StringConverter}
121     *  implementation.
122     *
123     *  @return The instance for this {@code StringConverter} implementation.
124     */
125    public static final EmailAddressStringConverter provider() { return INSTANCE; }
126}
127//  class EmailAddressStringConverter
128
129/*
130 *  End of File
131 */