/*******************************************************************************
 * Copyright (c) 2006, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.ui.menus;

import org.eclipse.jface.action.IContributionItem;
import org.eclipse.ui.services.IServiceLocator;

/**
 * ContributionFactories are used by the IMenuService to populate
 * ContributionManagers. In
 * {@link #createContributionItems(IServiceLocator, IContributionRoot)} you fill
 * in the additions List with {@link IContributionItem} to be inserted at this
 * factory's location. For example:
 *
 * <pre>
 * AbstractContributionFactory contributions = new AbstractContributionFactory(
 * 		&quot;menu:org.eclipse.ui.tests.api.MenuTestHarness?after=additions&quot;) {
 * 	public void createContributionItems(IMenuService menuService, List additions) {
 * 		CommandContributionItem item = new CommandContributionItem(&quot;org.eclipse.ui.tests.menus.helloWorld&quot;,
 * 				&quot;org.eclipse.ui.tests.commands.enabledHelloWorld&quot;, null, null, &quot;Say Hello&quot;, null);
 * 		additions.add(item);
 * 		item = new CommandContributionItem(&quot;org.eclipse.ui.tests.menus.refresh&quot;,
 * 				&quot;org.eclipse.ui.tests.commands.refreshView&quot;, null, null, &quot;Refresh&quot;, null);
 * 		menuService.registerVisibleWhen(item, new MyActiveContextExpression(&quot;org.eclipse.ui.tests.myview.context&quot;));
 * 		additions.add(item);
 * 	}
 *
 * 	public void releaseContributionItems(IMenuService menuService, List items) {
 * 		// we have nothing to do
 * 	}
 * };
 * IMenuService service = (IMenuService) PlatformUI.getWorkbench().getService(IMenuService.class);
 * service.addContributionFactory(contributions);
 * </pre>
 *
 * <p>
 * Clients who are providing factories via the <code>org.eclipse.ui.menus</code>
 * extension point should subclass {@link ExtensionContributionFactory} instead.
 * </p>
 *
 * <p>
 * Only the abstract methods may be implemented.
 * </p>
 *
 * @since 3.3
 * @see org.eclipse.ui.menus.IMenuService
 * @see org.eclipse.jface.action.MenuManager
 * @see org.eclipse.jface.action.ToolBarManager
 */
public abstract class AbstractContributionFactory {
	private String location = null;
	private String namespace;

	/**
	 * The contribution factories must be instantiated with their location, which
	 * which specifies the contributions insertion location.
	 *
	 * @param location  the addition location in Menu API URI format. It must not be
	 *                  <code>null</code>.
	 * @param namespace the namespace for this contribution. May be
	 *                  <code>null</code>.
	 * @see #getNamespace()
	 */
	public AbstractContributionFactory(String location, String namespace) {
		this.location = location;
		this.namespace = namespace;
	}

	/**
	 * Return the location as a String.
	 *
	 * @return the location - never <code>null</code>.
	 */
	public String getLocation() {
		return location;
	}

	/**
	 * This factory should create the IContributionItems that it wants to
	 * contribute, and add them to the additions list. The menu service will call
	 * this method at the appropriate time. It should always return new instances of
	 * its contributions in the additions list.
	 * <p>
	 * This method is not meant to be called by clients. It will be called by the
	 * menu service at the appropriate time.
	 * </p>
	 *
	 * @param serviceLocator a service locator that may be used in the construction
	 *                       of items created by this factory
	 * @param additions      A {@link IContributionRoot} supplied by the framework.
	 *                       It will never be <code>null</code>.
	 * @see org.eclipse.ui.menus.CommandContributionItem
	 * @see org.eclipse.jface.action.MenuManager
	 */
	public abstract void createContributionItems(IServiceLocator serviceLocator, IContributionRoot additions);

	/**
	 * Return the namespace for this cache. This corresponds to the plug-in that is
	 * contributing this factory.
	 *
	 * @return the namespace the namespace of this factory
	 */
	public String getNamespace() {
		return namespace;
	}
}
