001/*
002 * ============================================================================
003 * Copyright © 2002-2022 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.util.Base64.getDecoder;
022import static java.util.Base64.getEncoder;
023import static org.apiguardian.api.API.Status.STABLE;
024import static org.tquadrat.foundation.lang.CommonConstants.ASCII;
025import static org.tquadrat.foundation.lang.CommonConstants.UTF8;
026import static org.tquadrat.foundation.lang.Objects.isNull;
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 *  <p>{@summary The implementation of
036 *  {@link StringConverter}
037 *  for
038 *  {@link String}
039 *  values in BASE64 format.}</p>
040 *  <p>The BASE64 format returned from
041 *  {@link #toString(String)}
042 *  contains the source String in
043 *  {@linkplain java.nio.charset.StandardCharsets#UTF_8 UTF-8}
044 *  encoding and it is itself encoded to
045 *  {@linkplain java.nio.charset.StandardCharsets#US_ASCII ASCII}.</p>
046 *  <p>Correspondingly,
047 *  {@link #fromString(CharSequence)}
048 *  expects an ASCII encoded BASE64 stream containing a UTF-8 encoded
049 *  String.</p>
050 *  <p>Both methods are using the BASE64 <i>basic</i> encoding scheme.</p>
051 *
052 *  @see java.util.Base64
053 *  @see java.util.Base64#getEncoder()
054 *  @see java.util.Base64#getDecoder()
055 *
056 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
057 *  @version $Id: BASE64StringConverter.java 1032 2022-04-10 17:27:44Z tquadrat $
058 *  @since 0.0.6
059 *
060 *  @UMLGraph.link
061 */
062@ClassVersion( sourceVersion = "$Id: BASE64StringConverter.java 1032 2022-04-10 17:27:44Z tquadrat $" )
063@API( status = STABLE, since = "0.0.6" )
064public final class BASE64StringConverter implements StringConverter<String>
065{
066        /*------------------------*\
067    ====** Static Initialisations **===========================================
068        \*------------------------*/
069    /**
070     *  An instance of this class.
071     */
072    public static final BASE64StringConverter INSTANCE = new BASE64StringConverter();
073
074    /**
075     *  The serial version UID for objects of this class: {@value}.
076     *
077     *  @hidden
078     */
079    @Serial
080    private static final long serialVersionUID = 1L;
081
082        /*--------------*\
083    ====** Constructors **=====================================================
084        \*--------------*/
085    /**
086     *  Creates a new instance of {@code BASE64StringConverter}.
087     */
088    public BASE64StringConverter() {}
089
090        /*---------*\
091    ====** Methods **==========================================================
092        \*---------*/
093    /**
094     *  {@inheritDoc}
095     */
096    @Override
097    public final String fromString( final CharSequence source ) throws IllegalArgumentException
098    {
099        final var retValue = isNull( source ) ? null : new String( getDecoder().decode( source.toString().getBytes( ASCII ) ), UTF8 );
100
101        //---* Done *----------------------------------------------------------
102        return retValue;
103    }   //  fromString()
104
105    /**
106     *  {@inheritDoc}
107     */
108    @Override
109    public final String toString( final String source )
110    {
111        final var retValue = isNull( source ) ? null : new String( getEncoder().encode( source.getBytes( UTF8 ) ), ASCII );
112
113        //---* Done *----------------------------------------------------------
114        return retValue;
115    }   //  toString()
116}
117//  class BASE64StringConverter
118
119/*
120 *  End of File
121 */