org.eclipse.ecf.remoteservice

Interface IRemoteServiceContainerAdapter

All Superinterfaces:

org.eclipse.core.runtime.IAdaptable, IRemoteServiceConsumer, IRemoteServiceHost

All Known Subinterfaces:

IOSGiRemoteServiceContainerAdapter, IRemoteServiceClientContainerAdapter

All Known Implementing Classes:

AbstractClientContainer, AbstractRestClientContainer, AbstractRSAClientContainer, RegistrySharedObject, RemoteServiceContainer, RemoteServiceContainerAdapterImpl, RestClientContainer, RSARemoteServiceContainerAdapter, ServletServerContainer

public interface IRemoteServiceContainerAdapter
extends IRemoteServiceHost, IRemoteServiceConsumer

Entry point remote service container adapter. This is the entry point interface for accessing remote services through ECF containers.

Method Summary

Modifier and Type	Method and Description
void	addRemoteServiceListener(IRemoteServiceListener listener) Add listener for remote service registration/unregistration for this container
org.eclipse.equinox.concurrent.future.IFuture	asyncGetRemoteServiceReferences(ID[] idFilter, java.lang.String clazz, java.lang.String filter) Asynchronously returns an array of IRemoteServiceReference objects.
org.eclipse.equinox.concurrent.future.IFuture	asyncGetRemoteServiceReferences(ID target, ID[] idFilter, java.lang.String clazz, java.lang.String filter) Asynchronously returns an array of IRemoteServiceReference objects.
org.eclipse.equinox.concurrent.future.IFuture	asyncGetRemoteServiceReferences(ID target, java.lang.String clazz, java.lang.String filter) Asynchronously returns an array of IRemoteServiceReference objects.
IRemoteFilter	createRemoteFilter(java.lang.String filter) Creates a IRemoteFilter object.
IRemoteServiceReference[]	getAllRemoteServiceReferences(java.lang.String clazz, java.lang.String filter) Returns an array of IRemoteServiceReference objects.
IRemoteService	getRemoteService(IRemoteServiceReference reference) Get remote service for given IRemoteServiceReference.
IRemoteServiceID	getRemoteServiceID(ID containerID, long containerRelativeID) Get a remote service ID from a containerID and a containerRelative long value.
Namespace	getRemoteServiceNamespace() Get namespace to use for this remote service provider.
IRemoteServiceReference	getRemoteServiceReference(IRemoteServiceID serviceID) Get the remote service reference known to this container for the given IRemoteServiceID.
IRemoteServiceReference[]	getRemoteServiceReferences(ID[] idFilter, java.lang.String clazz, java.lang.String filter) Returns an array of IRemoteServiceReference objects.
IRemoteServiceReference[]	getRemoteServiceReferences(ID target, ID[] idFilter, java.lang.String clazz, java.lang.String filter) Returns an array of IRemoteServiceReference objects.
IRemoteServiceReference[]	getRemoteServiceReferences(ID target, java.lang.String clazz, java.lang.String filter) Returns an array of IRemoteServiceReference objects.
IRemoteServiceRegistration	registerRemoteService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties) Register a new remote service.
void	removeRemoteServiceListener(IRemoteServiceListener listener) Remove remote service registration/unregistration listener for this container.
void	setConnectContextForAuthentication(IConnectContext connectContext) Set connect context for authentication upon subsequent calls to getRemoteServiceReferences(ID[], String, String) or asyncGetRemoteServiceReferences(ID[], String, String).
boolean	setRemoteServiceCallPolicy(IRemoteServiceCallPolicy policy) Set the remote service call policy to enable authorization on remote service method calls
boolean	ungetRemoteService(IRemoteServiceReference reference) Unget IRemoteServiceReference.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Method Detail

addRemoteServiceListener

void addRemoteServiceListener(IRemoteServiceListener listener)

Add listener for remote service registration/unregistration for this container

Specified by:

addRemoteServiceListener in interface IRemoteServiceConsumer

Specified by:

addRemoteServiceListener in interface IRemoteServiceHost

Parameters:

listener - notified of service registration/unregistration events. Must not be null .

removeRemoteServiceListener

void removeRemoteServiceListener(IRemoteServiceListener listener)

Remove remote service registration/unregistration listener for this container.

Specified by:

removeRemoteServiceListener in interface IRemoteServiceConsumer

Specified by:

removeRemoteServiceListener in interface IRemoteServiceHost

Parameters:

listener - to remove. Must not be null .

registerRemoteService

IRemoteServiceRegistration registerRemoteService(java.lang.String[] clazzes,
                                                 java.lang.Object service,
                                                 java.util.Dictionary properties)

Register a new remote service. This method is to be called by the service server...i.e. the client that wishes to make available a service to other client within this container.

Specified by:

registerRemoteService in interface IRemoteServiceHost

Parameters:

clazzes - the interface classes that the service exposes to remote clients. Must not be null and must not be an empty array.

service - the service object. Under normal conditions this object must

• not be null
• implement all of the classes specified by the first parameter

The only situation when the service object may be null is if the service property Constants.SERVICE_REGISTER_PROXY is set in the properties. If Constants.SERVICE_REGISTER_PROXY is set in the properties parameter (to an arbitrary value), then the service object may then be null.

properties - to be associated with service

Returns:

IRemoteServiceRegistration the service registration. Will not return null .

getRemoteServiceReferences

IRemoteServiceReference[] getRemoteServiceReferences(ID target,
                                                     ID[] idFilter,
                                                     java.lang.String clazz,
                                                     java.lang.String filter)
                                              throws org.osgi.framework.InvalidSyntaxException,
                                                     ContainerConnectException

Returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

Note this method assumes that the enclosing container has previously been connected, and uses the idFilter to filter among targets within the previously connected set of container IDs. To request connection as part of reference lookup, see getRemoteServiceReferences(ID, String, String).

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

target is a remote container to connect to. If null, no connection attempt is made.

idFilter is used to select a registered services that were registered by a given set of containers with id in idFilter. Only services exposed by a container with id in idFilter will be returned. If idFilter is null, all containers are considered to match the filter.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax. If filter is null, all registered services are considered to match the filter. If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

getRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

target - a target container to connect to if enclosing container is not already connected. May be null.

idFilter - an array of ID instances that will restrict the search for matching container ids If null, all remote containers will be considered in search for matching IRemoteServiceReference instances. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

Array of IRemoteServiceReferences matching given search criteria or null if no services are found that match the search.

Throws:

org.osgi.framework.InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

ContainerConnectException - if container cannot connect

Since:

5.0

asyncGetRemoteServiceReferences

org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID target,
                                                                              ID[] idFilter,
                                                                              java.lang.String clazz,
                                                                              java.lang.String filter)

Asynchronously returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

The IFuture is returned immediately, and subsequent calls to IFuture.get() or IFuture.get(long) will return the actual results received. The type of the Object returned from IFuture.get() will be IRemoteServiceReference [].

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

target is a remote container to connect to. If null, no connection attempt is made.

idFilter is used to select a registered services that were registered by a given set of containers with id in idFilter. Only services exposed by a container with id in idFilter will be returned. If idFilter is null, all containers are considered to match the filter.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax. If filter is null, all registered services are considered to match the filter. If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

asyncGetRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

target - an target to connect to if enclosing container is not already connected. May be null.

idFilter - an array of ID instances that will restrict the search for matching container ids If null, all remote containers will be considered in search for matching IRemoteServiceReference instances. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

IFuture that through subsequent calls to IFuture#get() will return IRemoteServiceReference [] with IRemoteServiceReferences matching given search criteria. Will not return null.

Since:

5.0

getRemoteServiceReferences

IRemoteServiceReference[] getRemoteServiceReferences(ID[] idFilter,
                                                     java.lang.String clazz,
                                                     java.lang.String filter)
                                              throws org.osgi.framework.InvalidSyntaxException

Returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

Note this method assumes that the enclosing container has previously been connected, and uses the idFilter to filter among targets within the previously connected set of container IDs. To request connection as part of reference lookup, see getRemoteServiceReferences(ID, String, String).

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

idFilter is used to select a registered services that were registered by a given set of containers with id in idFilter. Only services exposed by a container with id in idFilter will be returned.

If idFilter is null, all containers are considered to match the filter.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax.

If filter is null, all registered services are considered to match the filter. If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

getRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

idFilter - an array of ID instances that will restrict the search for matching container ids If null, all remote containers will be considered in search for matching IRemoteServiceReference instances. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

Array of IRemoteServiceReferences matching given search criteria or null if no services are found that match the search.

Throws:

org.osgi.framework.InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

getRemoteServiceReferences

IRemoteServiceReference[] getRemoteServiceReferences(ID target,
                                                     java.lang.String clazz,
                                                     java.lang.String filter)
                                              throws org.osgi.framework.InvalidSyntaxException,
                                                     ContainerConnectException

Returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

target is a remote container to connect to.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax.

If filter is null, all registered services are considered to match the filter. If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

getRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

target - an target to connect to if enclosing container is not already connected. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

Array of IRemoteServiceReferences matching given search criteria or null if no services are found that match the search.

Throws:

org.osgi.framework.InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

ContainerConnectException - if container cannot connect

Since:

3.0

asyncGetRemoteServiceReferences

org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID[] idFilter,
                                                                              java.lang.String clazz,
                                                                              java.lang.String filter)

Asynchronously returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

Note this method assumes that the enclosing container has previously been connected, and uses the idFilter to filter among targets within the previously connected set of container IDs. To request connection as part of reference lookup, see getRemoteServiceReferences(ID, String, String).

The IFuture is returned immediately, and subsequent calls to IFuture.get() or IFuture.get(long) will return the actual results received. The type of the Object returned from IFuture.get() will be IRemoteServiceReference [].

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

idFilter is used to select a registered services that were registered by a given set of containers with id in idFilter. Only services exposed by a container with id in idFilter will be returned.

If idFilter is null, all containers are considered to match the filter.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax.

Specified by:

asyncGetRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

idFilter - an array of ID instances that will restrict the search for matching container ids If null, all remote containers will be considered in search for matching IRemoteServiceReference instances. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

IFuture that through subsequent calls to IFuture#get() will return IRemoteServiceReference [] with IRemoteServiceReferences matching given search criteria. Will not return null.

Since:

3.0

asyncGetRemoteServiceReferences

org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID target,
                                                                              java.lang.String clazz,
                                                                              java.lang.String filter)

Asynchronously returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class and match the specified idFilter, and filter criteria.

The IFuture is returned immediately, and subsequent calls to IFuture.get() or IFuture.get(long) will return the actual results received. The type of the Object returned from IFuture.get() will be IRemoteServiceReference [].

The list is valid at the time of the call to this method, however since the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

idFilter is used to select a registered services that were registered by a given set of containers with id in idFilter. Only services exposed by a container with id in idFilter will be returned.

target is a remote container to connect to.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax.

Specified by:

asyncGetRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

target - an target to connect to if enclosing container is not already connected. May be null.

clazz - the fully qualified name of the interface class that describes the desired service. Must not be null.

filter - The filter criteria. May be null.

Returns:

IFuture that through subsequent calls to IFuture#get() will return IRemoteServiceReference [] with IRemoteServiceReferences matching given search criteria. Will not return null.

Since:

3.0

getAllRemoteServiceReferences

IRemoteServiceReference[] getAllRemoteServiceReferences(java.lang.String clazz,
                                                        java.lang.String filter)
                                                 throws org.osgi.framework.InvalidSyntaxException

Returns an array of IRemoteServiceReference objects. The returned array of IRemoteServiceReference objects contains services that were registered under the specified class, or if the clazz parameter is null all services registered.

The list is valid at the time of the call to this method, however since the remote service container is a very dynamic environment, services can be modified or unregistered at anytime.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See Filter for a description of the filter string syntax.

If filter is null, all registered services are considered to match the filter. If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

getAllRemoteServiceReferences in interface IRemoteServiceConsumer

Parameters:

clazz - the fully qualified name of the interface class that describes the desired service. May be null.

filter - The filter criteria. May be null.

Returns:

Array of IRemoteServiceReferences matching given search criteria or null if no services are found that match the search.

Throws:

org.osgi.framework.InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

Since:

3.0

getRemoteServiceNamespace

Namespace getRemoteServiceNamespace()

Get namespace to use for this remote service provider.

Specified by:

getRemoteServiceNamespace in interface IRemoteServiceConsumer

Specified by:

getRemoteServiceNamespace in interface IRemoteServiceHost

Returns:

Namespace to use for creating IRemoteServiceID for this remote service provider. Will not return null.

Since:

3.0

getRemoteServiceID

IRemoteServiceID getRemoteServiceID(ID containerID,
                                    long containerRelativeID)

Get a remote service ID from a containerID and a containerRelative long value. Will return a non-null value if the IRemoteServiceRegistration/Reference is currently 'known' to this container adapter. null if not.

Specified by:

getRemoteServiceID in interface IRemoteServiceConsumer

Specified by:

getRemoteServiceID in interface IRemoteServiceHost

Parameters:

containerID - the containerID that is the server/host for the remote service. Must not be null. This must be the containerID for the server/host of the remote service.

containerRelativeID - the long value identifying the remote service relative to the container ID.

Returns:

IRemoteServiceID instance if the associated IRemoteServiceRegistration/Reference is known to this container adapter, null if it is not.

Since:

3.0

getRemoteServiceReference

IRemoteServiceReference getRemoteServiceReference(IRemoteServiceID serviceID)

Get the remote service reference known to this container for the given IRemoteServiceID. Note that this method must be guaranteed not to block by the provider implementation.

Specified by:

getRemoteServiceReference in interface IRemoteServiceConsumer

Parameters:

serviceID - the serviceID to retrieve the IRemoteServiceReference for.

Returns:

IRemoteServiceReference the remote service reference associated with the given serviceID. Will return null if no IRemoteServiceReference found for the given serviceID.

Since:

3.0

getRemoteService

IRemoteService getRemoteService(IRemoteServiceReference reference)

Get remote service for given IRemoteServiceReference. Note that clients that call this method successfully should later call ungetRemoteService(IRemoteServiceReference) when the IRemoteService will no longer be used.

Specified by:

getRemoteService in interface IRemoteServiceConsumer

Parameters:

reference - the IRemoteServiceReference for the desired service. Must not be null .

Returns:

IRemoteService representing the remote service. If remote service no longer exists for reference, then null is returned.

See Also:

ungetRemoteService(IRemoteServiceReference)

ungetRemoteService

boolean ungetRemoteService(IRemoteServiceReference reference)

Unget IRemoteServiceReference. Release all resources associated with the given IRemoteServiceReference. This method should be called by users of the IRemoteServiceReference that have previously called getRemoteService(IRemoteServiceReference). If this method returns true, then the previously used IRemoteService will no longer be usable.

Specified by:

ungetRemoteService in interface IRemoteServiceConsumer

Parameters:

reference - the IRemoteServiceReference to unget

Returns:

true if unget successful, false if not. If this method returns true, then the IRemoteService instance previously retrieved via the given IRemoteServiceReference instance provided will no longer be usable.

See Also:

getRemoteService(IRemoteServiceReference)

createRemoteFilter

IRemoteFilter createRemoteFilter(java.lang.String filter)
                          throws org.osgi.framework.InvalidSyntaxException

Creates a IRemoteFilter object. This IRemoteFilter object may be used to match a IRemoteServiceReference object or a Dictionary object.

If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

Specified by:

createRemoteFilter in interface IRemoteServiceConsumer

Parameters:

filter - The filter string.

Returns:

A IRemoteFilter object encapsulating the filter string.

Throws:

org.osgi.framework.InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

java.lang.NullPointerException - If filter is null.

java.lang.IllegalStateException - If this IRemoteServiceContainerAdapter is no longer valid.

Since:

3.0

See Also:

"Framework specification for a description of the filter string syntax.", FrameworkUtil.createFilter(String)

setConnectContextForAuthentication

void setConnectContextForAuthentication(IConnectContext connectContext)

Set connect context for authentication upon subsequent calls to getRemoteServiceReferences(ID[], String, String) or asyncGetRemoteServiceReferences(ID[], String, String). This method should be called with a non-null connectContext in order to allow authentication to occur during.

Specified by:

setConnectContextForAuthentication in interface IRemoteServiceConsumer

Parameters:

connectContext - the connect context to use for authenticating. If null, then no authentication will be attempted.

Since:

3.0

setRemoteServiceCallPolicy

boolean setRemoteServiceCallPolicy(IRemoteServiceCallPolicy policy)

Set the remote service call policy to enable authorization on remote service method calls

Parameters:

policy - Implementation of IRemoteServiceCallPolicy containing authorization specific code

Returns:

true if the underlying provider supports using the policy, false if it does not support using the policy.

Since:

6.0