/*
 * Copyright (c) OSGi Alliance (2009, 2010). 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.remoteserviceadmin;

import java.util.Collection;
import java.util.Map;

import org.osgi.framework.ServiceReference;

/**
 * A Remote Service Admin manages the import and export of services.
 * 
 * A Distribution Provider can expose a control interface. This interface allows
 * a Topology Manager to control the export and import of services.
 * 
 * The API allows a Topology Manager to export a service, to import a service,
 * and find out about the current imports and exports.
 * 
 * @ThreadSafe
 * @noimplement
 * @version $Id: 7b2e01c324cc2d04a06f7d7addfe9ea1af1dc7ad $
 */
public interface RemoteServiceAdmin {

	/**
	 * Export a service to a given Endpoint. The Remote Service Admin must
	 * create an Endpoint from the given description that can be used by other
	 * Distribution Providers to connect to this Remote Service Admin and use
	 * the exported service.
	 * 
	 * The property keys of a Service Reference are case insensitive while the
	 * property keys of the specified {@code properties} map are case
	 * sensitive. A property key in the specified {@code properties} map
	 * must therefore override any case variant property key in the properties
	 * of the specified Service Reference.
	 * 
	 * <p>
	 * If the caller does not have the appropriate
	 * {@code EndpointPermission[endpoint,EXPORT]} for an Endpoint, and the
	 * Java Runtime Environment supports permissions, then the
	 * {@link ExportRegistration#getException() getException} method on the
	 * corresponding returned {@link ExportRegistration} will return a
	 * {@code SecurityException}.
	 * 
	 * @param reference The Service Reference to export.
	 * @param properties The properties to create a local Endpoint that can be
	 *        implemented by this Remote Service Admin. If this is
	 *        {@code null}, the Endpoint will be determined by the
	 *        properties on the service. The properties are the same as given
	 *        for an exported service. They override any properties in the
	 *        specified Service Reference (case insensitive). The properties
	 *        {@code objectClass} and {@code service.id}, in any case
	 *        variant, are ignored. Those properties in the Service Reference
	 *        cannot be overridden. This parameter can be {@code null},
	 *        this should be treated as an empty map.
	 * @return A {@code Collection} of {@link ExportRegistration}s for the
	 *         specified Service Reference and properties. Multiple Export
	 *         Registrations may be returned because a single service can be
	 *         exported to multiple Endpoints depending on the available
	 *         configuration type properties. The result is never
	 *         {@code null} but may be empty if this Remove Service Admin
	 *         does not recognize any of the configuration types.
	 * @throws IllegalArgumentException If any of the properties has a value
	 *         that is not syntactically correct or if the service properties
	 *         and the overlaid properties do not contain a
	 *         {@link RemoteConstants#SERVICE_EXPORTED_INTERFACES} entry.
	 * @throws UnsupportedOperationException If any of the intents expressed
	 *         through the properties is not supported by the distribution
	 *         provider.
	 */
	Collection<ExportRegistration> exportService(ServiceReference reference,
			Map<String, ? > properties);

	/**
	 * Import a service from an Endpoint. The Remote Service Admin must use the
	 * given Endpoint to create a proxy. This method can return
	 * {@code null} if the service could not be imported.
	 * 
	 * @param endpoint The Endpoint Description to be used for import.
	 * @return An Import Registration that combines the Endpoint Description and
	 *         the Service Reference or {@code null} if the Endpoint could
	 *         not be imported.
	 * @throws SecurityException If the caller does not have the appropriate
	 *         {@code EndpointPermission[endpoint,IMPORT]} for the
	 *         Endpoint, and the Java Runtime Environment supports permissions.
	 */
	ImportRegistration importService(EndpointDescription endpoint);

	/**
	 * Return the currently active Export References.
	 * 
	 * <p>
	 * If the caller does not have the appropriate
	 * {@code EndpointPermission[endpoint,READ]} for an Endpoint, and the
	 * Java Runtime Environment supports permissions, then returned collection
	 * will not contain a reference to the exported Endpoint.
	 * 
	 * @return A {@code Collection} of {@link ExportReference}s that are
	 *         currently active.
	 */
	Collection<ExportReference> getExportedServices();

	/**
	 * Return the currently active Import References.
	 * 
	 * <p>
	 * If the caller does not have the appropriate
	 * {@code EndpointPermission[endpoint,READ]} for an Endpoint, and the
	 * Java Runtime Environment supports permissions, then returned collection
	 * will not contain a reference to the imported Endpoint.
	 * 
	 * @return A {@code Collection} of {@link ImportReference}s that are
	 *         currently active.
	 */
	Collection<ImportReference> getImportedEndpoints();

}