Interface IRemoteServiceConsumer
-
- All Superinterfaces:
org.eclipse.core.runtime.IAdaptable
- All Known Subinterfaces:
IOSGiRemoteServiceContainerAdapter,IRemoteServiceClientContainerAdapter,IRemoteServiceContainerAdapter
- All Known Implementing Classes:
AbstractClientContainer,AbstractRestClientContainer,AbstractRSAClientContainer,RegistrySharedObject,RemoteServiceContainer,RemoteServiceContainerAdapterImpl,RestClientContainer,RSARemoteServiceContainerAdapter,ServletServerContainer
public interface IRemoteServiceConsumer extends org.eclipse.core.runtime.IAdaptable- Since:
- 5.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidaddRemoteServiceListener(IRemoteServiceListener listener)Add listener for remote service registration/unregistration for this containerorg.eclipse.equinox.concurrent.future.IFutureasyncGetRemoteServiceReferences(ID[] idFilter, String clazz, String filter)Asynchronously returns an array ofIRemoteServiceReferenceobjects.org.eclipse.equinox.concurrent.future.IFutureasyncGetRemoteServiceReferences(ID target, String clazz, String filter)Asynchronously returns an array ofIRemoteServiceReferenceobjects.org.eclipse.equinox.concurrent.future.IFutureasyncGetRemoteServiceReferences(ID target, ID[] idFilter, String clazz, String filter)Asynchronously returns an array ofIRemoteServiceReferenceobjects.IRemoteFiltercreateRemoteFilter(String filter)Creates aIRemoteFilterobject.IRemoteServiceReference[]getAllRemoteServiceReferences(String clazz, String filter)Returns an array ofIRemoteServiceReferenceobjects.IRemoteServicegetRemoteService(IRemoteServiceReference reference)Get remote service for given IRemoteServiceReference.IRemoteServiceIDgetRemoteServiceID(ID containerID, long containerRelativeID)Get a remote service ID from a containerID and a containerRelative long value.NamespacegetRemoteServiceNamespace()Get namespace to use for this remote service provider.IRemoteServiceReferencegetRemoteServiceReference(IRemoteServiceID serviceID)Get the remote service reference known to this container for the given IRemoteServiceID.IRemoteServiceReference[]getRemoteServiceReferences(ID[] idFilter, String clazz, String filter)Returns an array ofIRemoteServiceReferenceobjects.IRemoteServiceReference[]getRemoteServiceReferences(ID target, String clazz, String filter)Returns an array ofIRemoteServiceReferenceobjects.IRemoteServiceReference[]getRemoteServiceReferences(ID target, ID[] idFilter, String clazz, String filter)Returns an array ofIRemoteServiceReferenceobjects.voidremoveRemoteServiceListener(IRemoteServiceListener listener)Remove remote service registration/unregistration listener for this container.voidsetConnectContextForAuthentication(IConnectContext connectContext)Set connect context for authentication upon subsequent calls togetRemoteServiceReferences(ID[], String, String)orasyncGetRemoteServiceReferences(ID[], String, String).booleanungetRemoteService(IRemoteServiceReference reference)Unget IRemoteServiceReference.
-
-
-
Method Detail
-
addRemoteServiceListener
void addRemoteServiceListener(IRemoteServiceListener listener)
Add listener for remote service registration/unregistration for this container- Parameters:
listener- notified of service registration/unregistration events. Must not benull.
-
removeRemoteServiceListener
void removeRemoteServiceListener(IRemoteServiceListener listener)
Remove remote service registration/unregistration listener for this container.- Parameters:
listener- to remove. Must not benull.
-
getRemoteServiceReferences
IRemoteServiceReference[] getRemoteServiceReferences(ID target, ID[] idFilter, String clazz, String filter) throws InvalidSyntaxException, ContainerConnectException
Returns an array ofIRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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.
targetis a remote container to connect to. Ifnull, no connection attempt is made.idFilteris 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. IfidFilterisnull, all containers are considered to match the filter.filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax. Iffilterisnull, all registered services are considered to match the filter. Iffiltercannot be parsed, anInvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- Parameters:
target- a target container to connect to if enclosing container is not already connected. May benull.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 benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- Returns:
- Array of IRemoteServiceReferences matching given search criteria or
nullif no services are found that match the search. - Throws:
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, String clazz, String filter)
Asynchronously returns an array ofIRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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()orIFuture.get(long)will return the actual results received. The type of the Object returned fromIFuture.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.
targetis a remote container to connect to. Ifnull, no connection attempt is made.idFilteris 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. IfidFilterisnull, all containers are considered to match the filter.filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax. Iffilterisnull, all registered services are considered to match the filter. Iffiltercannot be parsed, anInvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- Parameters:
target- an target to connect to if enclosing container is not already connected. May benull.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 benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- 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, String clazz, String filter) throws InvalidSyntaxException
Returns an array ofIRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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.
idFilteris 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
idFilterisnull, all containers are considered to match the filter.filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax.If
filterisnull, all registered services are considered to match the filter. Iffiltercannot be parsed, anInvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- 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 benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- Returns:
- Array of IRemoteServiceReferences matching given search criteria or
nullif no services are found that match the search. - Throws:
InvalidSyntaxException- If filter contains an invalid filter string that cannot be parsed.
-
getRemoteServiceReferences
IRemoteServiceReference[] getRemoteServiceReferences(ID target, String clazz, String filter) throws InvalidSyntaxException, ContainerConnectException
Returns an array of
IRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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.
filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax.If
filterisnull, all registered services are considered to match the filter. Iffiltercannot be parsed, anInvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- Parameters:
target- an target to connect to if enclosing container is not already connected. May benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- Returns:
- Array of IRemoteServiceReferences matching given search criteria or
nullif no services are found that match the search. - Throws:
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, String clazz, String filter)
Asynchronously returns an array ofIRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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()orIFuture.get(long)will return the actual results received. The type of the Object returned fromIFuture.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.
idFilteris 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
idFilterisnull, all containers are considered to match the filter.filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax.- 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 benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- 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, String clazz, String filter)
Asynchronously returns an array ofIRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects 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()orIFuture.get(long)will return the actual results received. The type of the Object returned fromIFuture.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.
idFilteris 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.
filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax.- Parameters:
target- an target to connect to if enclosing container is not already connected. May benull.clazz- the fully qualified name of the interface class that describes the desired service. Must not benull.filter- The filter criteria. May benull.- 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(String clazz, String filter) throws InvalidSyntaxException
Returns an array of
IRemoteServiceReferenceobjects. The returned array ofIRemoteServiceReferenceobjects contains services that were registered under the specified class, or if the clazz parameter isnullall 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.
filteris used to select the registered service whose properties objects contain keys and values which satisfy the filter. SeeFilterfor a description of the filter string syntax.If
filterisnull, all registered services are considered to match the filter. Iffiltercannot be parsed, anInvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- Parameters:
clazz- the fully qualified name of the interface class that describes the desired service. May benull.filter- The filter criteria. May benull.- Returns:
- Array of IRemoteServiceReferences matching given search criteria or
nullif no services are found that match the search. - Throws:
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.- 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.nullif not.- Parameters:
containerID- the containerID that is the server/host for the remote service. Must not benull. 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,
nullif 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.- Parameters:
serviceID- the serviceID to retrieve the IRemoteServiceReference for.- Returns:
- IRemoteServiceReference the remote service reference associated with the given serviceID.
Will return
nullif 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 callIRemoteServiceContainerAdapter.ungetRemoteService(IRemoteServiceReference)when the IRemoteService will no longer be used.- Parameters:
reference- the IRemoteServiceReference for the desired service. Must not benull.- Returns:
- IRemoteService representing the remote service. If remote service
no longer exists for reference, then
nullis 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 calledIRemoteServiceContainerAdapter.getRemoteService(IRemoteServiceReference). If this method returns true, then the previously used IRemoteService will no longer be usable.- 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(String filter) throws InvalidSyntaxException
Creates aIRemoteFilterobject. ThisIRemoteFilterobject may be used to match aIRemoteServiceReferenceobject or aDictionaryobject.If the filter cannot be parsed, an
InvalidSyntaxExceptionwill be thrown with a human readable message where the filter became unparsable.- Parameters:
filter- The filter string.- Returns:
- A
IRemoteFilterobject encapsulating the filter string. - Throws:
InvalidSyntaxException- Iffiltercontains an invalid filter string that cannot be parsed.NullPointerException- Iffilteris null.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 togetRemoteServiceReferences(ID[], String, String)orasyncGetRemoteServiceReferences(ID[], String, String). This method should be called with a non-null connectContext in order to allow authentication to occur during.- Parameters:
connectContext- the connect context to use for authenticating. Ifnull, then no authentication will be attempted.- Since:
- 3.0
-
-