/*******************************************************************************
 * Copyright (c) 2009, 2013 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.e4.core.contexts;

import org.osgi.framework.BundleContext;

/**
 * A context function encapsulates evaluation of some code within an
 * {@link IEclipseContext}. The result of the function must be derived purely
 * from the provided arguments and context objects, and must be free from
 * side-effects other than the function's return value. In particular, the
 * function must be idempotent - subsequent invocations of the same function
 * with the same inputs must produce the same result.
 * <p>
 * A common use for context functions is as a place holder for an object that
 * has not yet been created. These place holders can be stored as values in an
 * {@link IEclipseContext}, allowing the concrete value they represent to be
 * computed lazily only when requested.
 * </p>
 * <p>
 * Context functions can optionally be registered as OSGi services. Context
 * implementations may use such registered services to seed context instances
 * with initial values. Registering your context function as a service is a
 * signal that contexts are free to add an instance of your function to their
 * context automatically, using the key specified by the
 * {@link #SERVICE_CONTEXT_KEY} service property.
 * </p>
 * 
 * @see IEclipseContext#set(String, Object)
 * @noimplement This interface is not intended to be implemented by clients.
 *              Function implementations must subclass {@link ContextFunction}
 *              instead.
 * @since 1.3
 */
public interface IContextFunction {
	/**
	 * The OSGi service name for a context function service. This name can be
	 * used to obtain instances of the service.
	 * 
	 * @see BundleContext#getServiceReference(String)
	 */
	public static final String SERVICE_NAME = IContextFunction.class.getName();

	/**
	 * An OSGi service property used to indicate the context key this function
	 * should be registered in.
	 * 
	 * @see BundleContext#getServiceReference(String)
	 */
	public static final String SERVICE_CONTEXT_KEY = "service.context.key"; //$NON-NLS-1$

	/**
	 * Evaluates the function based on the provided arguments and context to
	 * produce a consistent result.
	 * 
	 * @param context
	 *            The context in which to perform the value computation.
	 * @param contextKey
	 *            The context key used to find this function; may be {@code null} such
	 *            as if invoked directly.
	 * @return The concrete value. Implementations may return {@link org.eclipse.e4.core.di.IInjector#NOT_A_VALUE}
	 * 		to cause lookup to continue up the context hierarchy.
	 */
	public Object compute(IEclipseContext context, String contextKey);

}