001/*
002 * ============================================================================
003 *  Copyright © 2002-2023 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.util.stringconverter;
019
020import static java.lang.String.format;
021import static org.tquadrat.foundation.lang.Objects.isNull;
022import static org.tquadrat.foundation.lang.Objects.nonNull;
023import static org.tquadrat.foundation.util.stringconverter.NumberStringConverter.MSG_InvalidNumberFormat;
024
025import java.util.Collection;
026import java.util.Date;
027import java.util.List;
028
029import org.apiguardian.api.API;
030import org.apiguardian.api.API.Status;
031import org.tquadrat.foundation.annotation.ClassVersion;
032import org.tquadrat.foundation.lang.StringConverter;
033
034/**
035 *  <p>{@summary An implementation for the interface
036 *  {@link StringConverter}
037 *  for
038 *  {@link Date}.}</p>
039 *  <p>This converter translates an instance of {@code Date} into a String
040 *  containing an number that represents the milliseconds since the begin of
041 *  the epoch (1970-01-01T00:00:00 UTC); conversely it expects such a String to
042 *  convert it to an instance of {@code Date}. This approach circumvents the
043 *  issues that exists with the numerous String formats that otherwise exists
044 *  for {@code Date}, especially when it comes to parsing based on different
045 *  locales.</p>
046 *
047 *  @see Date#Date(long)
048 *  @see Date#getTime()
049 *
050 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
051 *  @version $Id: DateLongStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
052 *  @since 0.0.1
053 *
054 *  @UMLGraph.link
055 */
056@SuppressWarnings( "UseOfObsoleteDateTimeApi" ) // Obviously unavoidable …
057@ClassVersion( sourceVersion = "$Id: DateLongStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
058@API( status = Status.STABLE, since = "0.1.0" )
059public class DateLongStringConverter implements StringConverter<Date>
060{
061        /*-----------*\
062    ====** Constants **========================================================
063        \*-----------*/
064    /**
065     *  An instance of this class.
066     */
067    public static final DateLongStringConverter INSTANCE = new DateLongStringConverter();
068
069        /*--------------*\
070    ====** Constructors **=====================================================
071        \*--------------*/
072    /**
073     *  Creates a new instance of {@code DateLongStringConverter}.
074     */
075    public DateLongStringConverter() {}
076
077        /*---------*\
078    ====** Methods **==========================================================
079        \*---------*/
080    /**
081     *  {@inheritDoc}
082     */
083    @Override
084    public final Date fromString( final CharSequence source ) throws IllegalArgumentException
085    {
086        Date retValue = null;
087        if( nonNull( source ) )
088        {
089            try
090            {
091                final var time = Long.parseLong( source.toString() );
092                retValue = new Date( time );
093            }
094            catch( final NumberFormatException e )
095            {
096                throw new IllegalArgumentException( format( MSG_InvalidNumberFormat, source ), e );
097            }
098        }
099
100        //---* Done *----------------------------------------------------------
101        return retValue;
102    }   //  fromString()
103
104    /**
105     *  Provides the subject class for this converter.
106     *
107     * @return The subject class.
108     */
109    @SuppressWarnings( "PublicMethodNotExposedInInterface" )
110    public final Collection<Class<?>> getSubjectClass() { return List.of( Date.class); }
111
112    /**
113     *  {@inheritDoc}
114     */
115    @Override
116    public final String toString( final Date source )
117    {
118        final var retValue = isNull( source ) ? null : Long.toString( source.getTime() );
119
120        //---* Done *----------------------------------------------------------
121        return retValue;
122    }   //  toString()
123}
124//  class DateLongStringConverter
125
126/*
127 *  End of File
128 */