/*******************************************************************************
*   Copyright 2014 Analog Devices, Inc.
*
*   Licensed under the Apache License, Version 2.0 (the "License");
*   you may not use this file except in compliance with the License.
*   You may obtain a copy of the License at
*
*       http://www.apache.org/licenses/LICENSE-2.0
*
*   Unless required by applicable law or agreed to in writing, software
*   distributed under the License is distributed on an "AS IS" BASIS,
*   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*   See the License for the specific language governing permissions and
*   limitations under the License.
********************************************************************************/

package com.analog.lyric.options;

import java.io.ObjectStreamException;
import java.io.Serializable;
import java.lang.reflect.Field;

import org.eclipse.jdt.annotation.NonNull;
import org.eclipse.jdt.annotation.Nullable;

import com.analog.lyric.dimple.exceptions.DimpleException;

import net.jcip.annotations.Immutable;

/**
 * Base implementation of {@link IOptionKey} interface.
 * <p>
 * This is the preferred base class for implementing option key classes and also
 * provides useful static methods for naming and construction.
 * <p>
 * @param <T> is the type of  the values of the option indexed by this key.
 * @since 0.07
 * @author Christopher Barber
 */
@Immutable
public abstract class OptionKey<T extends Serializable> implements IOptionKey<T>
{
	/*-------
	 * State
	 */
	
	private static final long serialVersionUID = 1L;
	
	private final Class<?> _declaringClass;
	
	private final String _name;
	
	private final boolean _local;
	
	/*--------------
	 * Construction
	 */
	
	protected OptionKey(Class<?> declaringClass, String name, IOptionKey.Lookup lookupMethod)
	{
		_declaringClass = declaringClass;
		_name = name;
		_local = lookupMethod == IOptionKey.Lookup.LOCAL;
	}
	
	protected OptionKey(Class<?> declaringClass, String name)
	{
		this(declaringClass, name, IOptionKey.Lookup.NONLOCAL);
	}
	
	/**
	 * Returns key with specified {@code name} in {@code declaringClass} using Java reflection.
	 * <p>
	 * @see OptionRegistry#addFromClasses
	 * <p>
	 * @since 0.07
	 */
	@SuppressWarnings("unchecked")
	public static <T extends Serializable> IOptionKey<T> inClass(Class<?> declaringClass, String name)
	{
		try
		{
			Field field = declaringClass.getDeclaredField(name);
			return (IOptionKey<T>)field.get(declaringClass);
		}
		catch (Exception ex)
		{
			throw new DimpleException("Error loading option key '%s' from '%s': %s",
				name, declaringClass, ex.toString());
		}
	}
	
	/**
	 * Returns key with specified {@code canonicalName} using Java reflection to load the
	 * declaring class.
	 * <p>
	 * Because this uses reflection it is not expected to be very fast so it is better to put keys
	 * in a {@link OptionRegistry} if you need frequent lookup by name.
	 * <p>
	 * @since 0.07
	 */
	public static <T extends Serializable> IOptionKey<T> forCanonicalName(String canonicalName)
	{
		int i = canonicalName.lastIndexOf('.');
		if (i < 0)
		{
			throw new DimpleException("'%s' is not a canonical option key name", canonicalName);
		}
		
		String className = canonicalName.substring(0, i);
		String name = canonicalName.substring(i + 1);
		
		Class<?> declaringClass;
		try
		{
			declaringClass = Class.forName(className, false, OptionKey.class.getClassLoader());
		}
		catch (ClassNotFoundException ex)
		{
			throw new DimpleException(ex);
		}
		
		return inClass(declaringClass, name);
	}
	
	/*-----------------------
	 * Serialization methods
	 */
	
	/**
	 * Replaces deserialized instance with canonical declaration in field.
	 * 
	 * @throws ObjectStreamException
	 */
	protected Object readResolve() throws ObjectStreamException
	{
		IOptionKey<T> canonical = getCanonicalInstance(this);
		return canonical != null ? canonical : this;
	}
	
	/*----------------
	 * Object methods
	 */
	
	@Override
	public String toString()
	{
		return qualifiedName();
	}
	
	/*--------------------
	 * IOptionKey methods
	 */
	
	@NonNull // FIXME - workaround for Eclipse JDT bug (467610?)
	@Override
	public T convertToValue(@Nullable Object value)
	{
		return type().cast(value);
	}
	
	@Override
	public Object convertToExternal(T value)
	{
		return value;
	}
	
	@Override
	public final Class<?> getDeclaringClass()
	{
		return _declaringClass;
	}
	
	@Override
	public final boolean local()
	{
		return _local;
	}
	
	@Override
	public final IOptionKey.Lookup lookupMethod()
	{
		return _local ? IOptionKey.Lookup.LOCAL : IOptionKey.Lookup.NONLOCAL;
	}
	
	@Override
	public final String name()
	{
		return _name;
	}
	
	@NonNull // FIXME - workaround for Eclipse JDT bug (467610?)
	@Override
	public T getOrDefault(IOptionHolder holder)
	{
		return holder.getOptionOrDefault(this);
	}
	
	@Override
	public @Nullable T get(IOptionHolder holder)
	{
		return holder.getOption(this);
	}
	
	@Override
	public void set(IOptionHolder holder, T value)
	{
		holder.setOption(this, value);
	}
	
	@Override
	public void unset(IOptionHolder holder)
	{
		holder.unsetOption(this);
	}
	
	@Override
	public boolean validForDelegator(T value, IOptionHolder delegator)
	{
		return true;
	}
	
	@NonNull // FIXME - workaround for Eclipse JDT bug (467610?)
	@Override
	public T validate(T value, @Nullable IOptionHolder optionHolder)
	{
		return type().cast(value);
	}
	
	/*--------------------
	 * OptionKey methods
	 */
	
	/**
	 * Returns the canonical instance of {@code key}.
	 * <p>
	 * Returns the instance of the key that is publicly declared as
	 * a static field of {@link #getDeclaringClass()} with given {@link #name()}
	 * or returns null if there isn't one.
	 * <p>
	 * This method is implemented using reflection and is not expected to be very fast.
	 * <p>
	 * @since 0.07
	 */
	public static @Nullable<T extends Serializable> IOptionKey<T> getCanonicalInstance(IOptionKey<T> key)
	{
		IOptionKey<T> canonical = null;
		
		Class<?> declaringClass = key.getDeclaringClass();
		String name = key.name();
		
		try
		{
			@SuppressWarnings("unchecked")
			IOptionKey<T> option = (IOptionKey<T>)declaringClass.getDeclaredField(name).get(null);
			if (name.equals(option.name()) && option.type() == key.type())
			{
				canonical = option;
			}
		}
		catch (Exception ex)
		{
		}

		return canonical;
	}
	
	/**
	 * Computes the canonical name of the option.
	 * <p>
	 * Shorthand for
	 * <blockquote>
	 * {@linkplain #canonicalName(IOptionKey) OptionKey.canonicalName}(this)
	 * </blockquote>
	 * @since 0.07
	 */
	public String canonicalName()
	{
		return canonicalName(this);
	}
	
	/**
	 * Computes the fully qualified canonical name of the option.
	 * <p>
	 * This name uniquely identifies the option key. It consists of the fully qualified name of
	 * {@link #getDeclaringClass()} and {@link #name} separated by '.'. For instance:
	 * <blockquote>
	 * "com.analog.lyric.dimple.options.SolverOptions.iterations"
	 * </blockquote>
	 * 
	 * @param option is a non-null option key.
	 * @since 0.07
	 */
	public static String canonicalName(IOptionKey<?> option)
	{
		return String.format("%s.%s", option.getDeclaringClass().getName(), option.name());
	}
	
	/**
	 * Converts value and sets it in given option holder.
	 * <p>
	 * Invokes {@link #set} after value is converted by {@link #convertToValue}.
	 * <p>
	 * @param holder is a non-null option holder.
	 * @param value is a value that will be converted to the target value.
	 * @since 0.07
	 */
	public void convertAndSet(IOptionHolder holder, Object value)
	{
		set(holder, convertToValue(value));
	}
	
	/**
	 * Computes the option name qualified by its simple declaring class name.
	 * <p>
	 * Shorthand for
	 * <blockquote>
	 * {@linkplain #qualifiedName(IOptionKey) OptionKey.qualifiedName}(this)
	 * </blockquote>
	 * @since 0.07
	 */
	public String qualifiedName()
	{
		return qualifiedName(this);
	}
	
	/**
	 * Computes the option name qualified by its simple declaring class name.
	 * <p>
	 * This may be used to disambiguate option keys that may have the same simple name.
	 * The name consits of the {@linkplain Class#getSimpleName() simple name} of the option's
	 * {@linkplain IOptionKey#getDeclaringClass() declaring class} and the {@link #name} separated
	 * by '.'. For instance:
	 * <blockquote>
	 * "SolverOptions.iterations"
	 * </blockquote>
	 * <p>
	 * @param option is a non-null option key.
	 * @since 0.07
	 */
	public static String qualifiedName(IOptionKey<?> option)
	{
		return String.format("%s.%s", option.getDeclaringClass().getSimpleName(), option.name());
	}
}
