/*
 * Copyright (c) OSGi Alliance (2008, 2013). All Rights Reserved.
 *
 * 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 org.osgi.service.blueprint.reflect;

import java.util.Collection;
import java.util.List;
import org.osgi.annotation.versioning.ConsumerType;

/**
 * Metadata for a service to be registered by the Blueprint Container when
 * enabled.
 * 
 * <p>
 * This is specified by the {@code service} element.
 * 
 * @ThreadSafe
 * @author $Id: 8c4ddb6239c2247906ceeb2b61226be64dfc24ab $
 */
@ConsumerType
public interface ServiceMetadata extends ComponentMetadata {

	/**
	 * Do not auto-detect types for advertised service interfaces
	 * 
	 * @see #getAutoExport()
	 */
	static final int	AUTO_EXPORT_DISABLED		= 1;

	/**
	 * Advertise all Java interfaces implemented by the component instance type
	 * as service interfaces.
	 * 
	 * @see #getAutoExport()
	 */
	static final int	AUTO_EXPORT_INTERFACES		= 2;

	/**
	 * Advertise all Java classes in the hierarchy of the component instance
	 * type as service interfaces.
	 * 
	 * @see #getAutoExport()
	 */
	static final int	AUTO_EXPORT_CLASS_HIERARCHY	= 3;

	/**
	 * Advertise all Java classes and interfaces in the component instance type
	 * as service interfaces.
	 * 
	 * @see #getAutoExport()
	 */
	static final int	AUTO_EXPORT_ALL_CLASSES		= 4;

	/**
	 * Return the Metadata for the component to be exported as a service.
	 * 
	 * This is specified inline or via the {@code ref} attribute of the service.
	 * 
	 * @return The Metadata for the component to be exported as a service.
	 */
	Target getServiceComponent();

	/**
	 * Return the type names of the interfaces that the service should be
	 * advertised as supporting.
	 * 
	 * This is specified in the {@code interface} attribute or child
	 * {@code interfaces} element of the service.
	 * 
	 * @return An immutable List of {@code String} for the type names of the
	 *         interfaces that the service should be advertised as supporting.
	 *         The List is empty if using {@code auto-export} or no interface
	 *         names are specified for the service.
	 */
	List<String> getInterfaces();

	/**
	 * Return the auto-export mode for the service.
	 * 
	 * This is specified by the {@code auto-export} attribute of the service.
	 * 
	 * @return The auto-export mode for the service.
	 * @see #AUTO_EXPORT_DISABLED
	 * @see #AUTO_EXPORT_INTERFACES
	 * @see #AUTO_EXPORT_CLASS_HIERARCHY
	 * @see #AUTO_EXPORT_ALL_CLASSES
	 */
	int getAutoExport();

	/**
	 * Return the user declared properties to be advertised with the service.
	 * 
	 * This is specified by the {@code service-properties} element of the
	 * service.
	 * 
	 * @return An immutable List of {@link MapEntry} objects for the user
	 *         declared properties to be advertised with the service. The List
	 *         is empty if no service properties are specified for the service.
	 */
	List<MapEntry> getServiceProperties();

	/**
	 * Return the ranking value to use when advertising the service. If the
	 * ranking value is zero, the service must be registered without a
	 * {@code service.ranking} service property.
	 * 
	 * This is specified by the {@code ranking} attribute of the service.
	 * 
	 * @return The ranking value to use when advertising the service.
	 */
	int getRanking();

	/**
	 * Return the registration listeners to be notified when the service is
	 * registered and unregistered with the framework.
	 * 
	 * This is specified by the {@code registration-listener} elements of the
	 * service.
	 * 
	 * @return An immutable Collection of {@link RegistrationListener} objects
	 *         to be notified when the service is registered and unregistered
	 *         with the framework. The Collection is empty if no registration
	 *         listeners are specified for the service.
	 */
	Collection<RegistrationListener> getRegistrationListeners();
}
