001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2019–2020 microBean™.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
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,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.settings;
018
019import java.io.Serializable;
020
021import java.util.function.Function;
022
023/**
024 * A {@link Function} that can convert a {@link Value} into some other
025 * kind of object.
026 *
027 * @param <T> the conversion type
028 *
029 * @author <a href="https://about.me/lairdnelson"
030 * target="_parent">Laird Nelson</a>
031 *
032 * @see #convert(Value)
033 */
034@FunctionalInterface
035public interface Converter<T> extends Function<Value, T>, Serializable {
036
037
038  /*
039   * Static fields.
040   */
041
042
043  /**
044   * The version of this interface for {@link Serializable
045   * serialization purposes}.
046   */
047  static final long serialVersionUID = 1L;
048
049
050  /*
051   * Default methods.
052   */
053
054
055  /**
056   * Calls the {@link #convert(Value)} method and returns its result.
057   *
058   * @param value the {@link Value} to convert; may be {@code null}
059   *
060   * @return the result of the conversion (possibly {@code null})
061   *
062   * @nullability This method and its overrides may return {@code
063   * null}.
064   *
065   * @idempotency No guarantees with respect to idempotency are made
066   * about this method or its overrides.
067   *
068   * @threadsafety This method is and its overrides must be safe for
069   * concurrent use by multiple threads.
070   */
071  default public T apply(final Value value) {
072    return this.convert(value);
073  }
074
075   /**
076   * Converts the supplied {@link Value} into the appropriate kind of
077   * object and returns the result.
078   *
079   * <p>Implementations of this method must not call the {@link
080   * #apply(Value)} method.</p>
081   *
082   * @param value the {@link Value} to convert; may be {@code null}
083   *
084   * @return the result of the conversion (possibly {@code null})
085   *
086   * @nullability This method's implementations may return {@code
087   * null}.
088   *
089   * @idempotency No guarantees with respect to idempotency are made
090   * about this method's implementations.
091   *
092   * @threadsafety This method is and its overrides must be safe for
093   * concurrent use by multiple threads.
094   */
095  public T convert(final Value value);
096  
097}