org.osgi.service.remoteserviceadmin.RemoteServiceAdmin Maven / Gradle / Ivy
Show all versions of hello-world-plugin Show documentation
/*
* Copyright (c) OSGi Alliance (2009, 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.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
* @author $Id: b80a55cef13e0c0af6782d364f70f953f4dbbe53 $
*/
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.
*
*
* 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 exportService(ServiceReference reference, Map 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.
*
*
* 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 getExportedServices();
/**
* Return the currently active Import References.
*
*
* 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 getImportedEndpoints();
}