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.nonNull;
024import static org.tquadrat.foundation.util.StringUtils.isEmpty;
025import static org.tquadrat.foundation.util.stringconverter.FileStringConverter.MSG_InvalidFileName;
026
027import java.io.Serial;
028import java.nio.file.InvalidPathException;
029import java.nio.file.Path;
030
031import org.apiguardian.api.API;
032import org.tquadrat.foundation.annotation.ClassVersion;
033import org.tquadrat.foundation.lang.StringConverter;
034
035/**
036 *  An implementation of
037 *  {@link StringConverter}
038 *  for
039 *  {@link Path}
040 *  values.<br>
041 *  <br>The method
042 *  {@link #fromString(CharSequence)}
043 *  uses
044 *  {@link Path#of(String, String...)}
045 *  to create the {@code Path} instance for the given value.<br>
046 *  <br>The file or folder that will be identified by the respective
047 *  {@code Path} object do not need to exist nor is it guaranteed that it can
048 *  be accessed or create through the current user.<br>
049 *  <br>Names will not be normalised or canonicalized.<br>
050 *  <br>A path name of only blanks will be accepted as valid, while the empty
051 *  String will cause an
052 *  {@link IllegalArgumentException}.
053 *
054 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
055 *  @version $Id: PathStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $
056 *  @since 0.0.6
057 *
058 *  @UMLGraph.link
059 */
060@ClassVersion( sourceVersion = "$Id: PathStringConverter.java 1060 2023-09-24 19:21:40Z tquadrat $" )
061@API( status = STABLE, since = "0.0.6" )
062public final class PathStringConverter implements StringConverter<Path>
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 PathStringConverter INSTANCE = new PathStringConverter();
079
080        /*--------------*\
081    ====** Constructors **=====================================================
082        \*--------------*/
083    /**
084     *  Creates a new instance of {@code PathStringConverter}.
085     */
086    public PathStringConverter() {}
087
088        /*---------*\
089    ====** Methods **==========================================================
090        \*---------*/
091    /**
092     *  {@inheritDoc}
093     */
094    @Override
095    public Path fromString( final CharSequence source ) throws IllegalArgumentException
096    {
097        Path retValue = null;
098        if( nonNull( source ) )
099        {
100            if( isEmpty( source ) ) throw new IllegalArgumentException( format( MSG_InvalidFileName, source ) );
101            try
102            {
103                retValue = Path.of( source.toString() );
104            }
105            catch( final InvalidPathException e )
106            {
107                throw new IllegalArgumentException( format( MSG_InvalidFileName, source ), e );
108            }
109        }
110
111        //---* Done *----------------------------------------------------------
112        return retValue;
113    }   //  fromString()
114
115    /**
116     *  This method is used by the
117     *  {@link java.util.ServiceLoader}
118     *  to obtain the instance for this
119     *  {@link org.tquadrat.foundation.lang.StringConverter}
120     *  implementation.
121     *
122     *  @return The instance for this {@code StringConverter} implementation.
123     */
124    public static final PathStringConverter provider() { return INSTANCE; }
125}
126//  class PathStringConverter
127
128/*
129 *  End of File
130 */