org.eclipse.ecf.remoteservice.client
Class AbstractClientContainer

java.lang.Object
  extended by org.eclipse.ecf.core.AbstractContainer
      extended by org.eclipse.ecf.remoteservice.client.AbstractClientContainer
All Implemented Interfaces:
org.eclipse.core.runtime.IAdaptable, IContainer, IIdentifiable, IRemoteServiceClientContainerAdapter, IRemoteServiceConsumer, IRemoteServiceContainerAdapter, IRemoteServiceHost
Direct Known Subclasses:
RestClientContainer, RpcClientContainer

public abstract class AbstractClientContainer
extends AbstractContainer
implements IRemoteServiceClientContainerAdapter

Remote service client abstract superclass.

Since:
4.0

Field Summary
protected  boolean alwaysSendDefaultParameters
           
protected  IConnectContext connectContext
           
protected  ID connectedID
           
protected  java.lang.Object connectLock
           
protected  ID containerID
           
protected  IRemoteCallParameterSerializer parameterSerializer
           
protected  java.lang.Object parameterSerializerLock
           
protected  RemoteServiceClientRegistry registry
           
protected  IRemoteResponseDeserializer remoteResponseDeserializer
           
protected  java.lang.Object remoteResponseDeserializerLock
           
protected  java.util.List remoteServiceListeners
           
 
Constructor Summary
AbstractClientContainer(ID containerID)
           
 
Method Summary
 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.
 void connect(ID targetID, IConnectContext connectContext1)
          Connect to a target remote process or process group.
 IRemoteCallable[][] createCallablesFromClasses(java.lang.Class[] cls, java.util.List callables)
           
 IRemoteFilter createRemoteFilter(java.lang.String filter)
          Creates a IRemoteFilter object.
protected abstract  IRemoteService createRemoteService(RemoteServiceClientRegistration registration)
          Create an implementer of IRemoteService for the given registration.
protected  RemoteServiceClientRegistration createRestServiceRegistration(IRemoteCallable[] callables, java.util.Dictionary properties)
           
protected  RemoteServiceClientRegistration createRestServiceRegistration(java.lang.String[] clazzes, IRemoteCallable[][] callables, java.util.Dictionary properties)
           
 void disconnect()
          Disconnect.
 void dispose()
          Dispose this IContainer instance.
protected  IRemoteCallable findCallableForName(java.lang.String fqMethodName, java.util.List callables)
           
 IRemoteServiceReference[] getAllRemoteServiceReferences(java.lang.String clazz, java.lang.String filter)
           Returns an array of IRemoteServiceReference objects.
protected  IRemoteCallable[] getCallablesForMethods(java.lang.reflect.Method[] methods, java.util.List callables)
           
 java.lang.Class[] getClazzesFromStrings(java.lang.String[] clazzes)
           
 java.lang.Class getClazzFromString(java.lang.String className)
           
 IConnectContext getConnectContextForAuthentication()
           
 ID getConnectedID()
          Get the target ID that this container instance has connected to.
 ID getID()
          Return the ID for this 'identifiable' object.
protected  IRemoteCallParameterSerializer getParameterSerializer()
           
protected  IRemoteCallParameterSerializer getParameterSerializer(IRemoteCallParameter parameter, java.lang.Object value)
           
protected  ID getRemoteCallTargetID()
           
 IRemoteService getRemoteService(IRemoteServiceReference reference)
          Get remote service for given IRemoteServiceReference.
 IRemoteServiceID getRemoteServiceID(ID containerID1, 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.
 IRemoteResponseDeserializer getResponseDeserializer()
           
protected  IRemoteResponseDeserializer getResponseDeserializer(IRemoteCall call, IRemoteCallable callable, java.util.Map responseHeaders)
           
protected  void logException(java.lang.String string, java.lang.Throwable e)
           
protected abstract  java.lang.String prepareEndpointAddress(IRemoteCall call, IRemoteCallable callable)
          Prepare an endpoint address for the given call and callable.
protected  IRemoteCallParameter[] prepareParameters(java.lang.String uri, IRemoteCall call, IRemoteCallable callable)
           
protected  java.lang.Object processResponse(java.lang.String uri, IRemoteCall call, IRemoteCallable callable, java.util.Map responseHeaders, java.lang.String responseBody)
           
 IRemoteServiceRegistration registerCallables(IRemoteCallable[] callables, java.util.Dictionary properties)
          Register remoteCallables for remote service client.
 IRemoteServiceRegistration registerCallables(java.lang.String[] clazzes, IRemoteCallable[][] callables, java.util.Dictionary properties)
           Register remoteCallables for given serviceInterfaceNames.
 IRemoteServiceRegistration registerRemoteCallables(java.lang.Class[] clazzes, java.util.List callablesList, java.util.Dictionary properties)
           
 IRemoteServiceRegistration registerRemoteCallables(java.lang.String[] clazzes, java.util.List callables, java.util.Dictionary properties)
           
 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.
protected  IRemoteCallParameter serializeParameter(java.lang.String uri, IRemoteCall call, IRemoteCallable callable, IRemoteCallParameter defaultParameter, java.lang.Object parameterValue)
          Serialze the parameter using the container's parameterSerializer.
 void setAlwaysSendDefaultParameters(boolean alwaysSendDefaultParameters)
          Set the flag to true to include default parameters (which are specified when the callables are created) with every request to the remote service.
 void setConnectContextForAuthentication(IConnectContext connectContext)
          Set connect context for authentication upon subsequent calls to IRemoteServiceConsumer.getRemoteServiceReferences(ID[], String, String) or IRemoteServiceConsumer.asyncGetRemoteServiceReferences(ID[], String, String).
 void setParameterSerializer(IRemoteCallParameterSerializer serializer)
          Set the remote call parameter serializer.
 void setResponseDeserializer(IRemoteResponseDeserializer resource)
           
 boolean ungetRemoteService(IRemoteServiceReference reference)
          Unget IRemoteServiceReference.
 
Methods inherited from class org.eclipse.ecf.core.AbstractContainer
addListener, fireContainerEvent, getAdapter, getPasswordFromConnectContext, removeListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.eclipse.core.runtime.IAdaptable
getAdapter
 
Methods inherited from interface org.eclipse.core.runtime.IAdaptable
getAdapter
 
Methods inherited from interface org.eclipse.ecf.core.IContainer
getConnectNamespace
 

Field Detail

containerID

protected ID containerID

connectedID

protected ID connectedID

connectLock

protected java.lang.Object connectLock

connectContext

protected IConnectContext connectContext

remoteResponseDeserializerLock

protected java.lang.Object remoteResponseDeserializerLock

remoteResponseDeserializer

protected IRemoteResponseDeserializer remoteResponseDeserializer

parameterSerializerLock

protected java.lang.Object parameterSerializerLock

parameterSerializer

protected IRemoteCallParameterSerializer parameterSerializer

registry

protected RemoteServiceClientRegistry registry

remoteServiceListeners

protected java.util.List remoteServiceListeners

alwaysSendDefaultParameters

protected boolean alwaysSendDefaultParameters
Since:
4.1
Constructor Detail

AbstractClientContainer

public AbstractClientContainer(ID containerID)
Method Detail

setConnectContextForAuthentication

public void setConnectContextForAuthentication(IConnectContext connectContext)
Description copied from interface: IRemoteServiceConsumer
Set connect context for authentication upon subsequent calls to IRemoteServiceConsumer.getRemoteServiceReferences(ID[], String, String) or IRemoteServiceConsumer.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
Specified by:
setConnectContextForAuthentication in interface IRemoteServiceContainerAdapter
Parameters:
connectContext - the connect context to use for authenticating. If null, then no authentication will be attempted.

getConnectContextForAuthentication

public IConnectContext getConnectContextForAuthentication()

setResponseDeserializer

public void setResponseDeserializer(IRemoteResponseDeserializer resource)
Specified by:
setResponseDeserializer in interface IRemoteServiceClientContainerAdapter

getResponseDeserializer

public IRemoteResponseDeserializer getResponseDeserializer()

setParameterSerializer

public void setParameterSerializer(IRemoteCallParameterSerializer serializer)
Description copied from interface: IRemoteServiceClientContainerAdapter
Set the remote call parameter serializer.

Specified by:
setParameterSerializer in interface IRemoteServiceClientContainerAdapter
Parameters:
serializer - the remote call parameter serializer to set for this container. May be null.

getParameterSerializer

protected IRemoteCallParameterSerializer getParameterSerializer()

getResponseDeserializer

protected IRemoteResponseDeserializer getResponseDeserializer(IRemoteCall call,
                                                              IRemoteCallable callable,
                                                              java.util.Map responseHeaders)

getParameterSerializer

protected IRemoteCallParameterSerializer getParameterSerializer(IRemoteCallParameter parameter,
                                                                java.lang.Object value)

setAlwaysSendDefaultParameters

public void setAlwaysSendDefaultParameters(boolean alwaysSendDefaultParameters)
Set the flag to true to include default parameters (which are specified when the callables are created) with every request to the remote service.

Setting to false will only send those parameter specified when the call is invoked.

Parameters which are specifed with the call override the defaults. Default parameters with a value of null are not included.

Parameters:
alwaysSendDefaultParameters - whether to send default parameters with every remote call
Since:
4.1

addRemoteServiceListener

public void addRemoteServiceListener(IRemoteServiceListener listener)
Description copied from interface: IRemoteServiceConsumer
Add listener for remote service registration/unregistration for this container

Specified by:
addRemoteServiceListener in interface IRemoteServiceConsumer
Specified by:
addRemoteServiceListener in interface IRemoteServiceContainerAdapter
Specified by:
addRemoteServiceListener in interface IRemoteServiceHost
Parameters:
listener - notified of service registration/unregistration events. Must not be null .

asyncGetRemoteServiceReferences

public org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID[] idFilter,
                                                                                     java.lang.String clazz,
                                                                                     java.lang.String filter)
Description copied from interface: IRemoteServiceConsumer
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 IRemoteServiceConsumer.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
Specified by:
asyncGetRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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.

asyncGetRemoteServiceReferences

public org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID target,
                                                                                     java.lang.String clazz,
                                                                                     java.lang.String filter)
Description copied from interface: IRemoteServiceConsumer
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
Specified by:
asyncGetRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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.

asyncGetRemoteServiceReferences

public org.eclipse.equinox.concurrent.future.IFuture asyncGetRemoteServiceReferences(ID target,
                                                                                     ID[] idFilter,
                                                                                     java.lang.String clazz,
                                                                                     java.lang.String filter)
Description copied from interface: IRemoteServiceConsumer
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
Specified by:
asyncGetRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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

createRemoteFilter

public IRemoteFilter createRemoteFilter(java.lang.String filter)
                                 throws org.osgi.framework.InvalidSyntaxException
Description copied from interface: IRemoteServiceConsumer
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
Specified by:
createRemoteFilter in interface IRemoteServiceContainerAdapter
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.
See Also:
"Framework specification for a description of the filter string syntax.", FrameworkUtil.createFilter(String)

getAllRemoteServiceReferences

public IRemoteServiceReference[] getAllRemoteServiceReferences(java.lang.String clazz,
                                                               java.lang.String filter)
                                                        throws org.osgi.framework.InvalidSyntaxException
Description copied from interface: IRemoteServiceConsumer

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
Specified by:
getAllRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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.

getRemoteService

public IRemoteService getRemoteService(IRemoteServiceReference reference)
Description copied from interface: IRemoteServiceConsumer
Get remote service for given IRemoteServiceReference. Note that clients that call this method successfully should later call IRemoteServiceContainerAdapter.ungetRemoteService(IRemoteServiceReference) when the IRemoteService will no longer be used.

Specified by:
getRemoteService in interface IRemoteServiceConsumer
Specified by:
getRemoteService in interface IRemoteServiceContainerAdapter
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:
IRemoteServiceConsumer.ungetRemoteService(IRemoteServiceReference)

getRemoteServiceID

public IRemoteServiceID getRemoteServiceID(ID containerID1,
                                           long containerRelativeID)
Description copied from interface: IRemoteServiceConsumer
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 IRemoteServiceContainerAdapter
Specified by:
getRemoteServiceID in interface IRemoteServiceHost
Parameters:
containerID1 - 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.

getRemoteServiceNamespace

public Namespace getRemoteServiceNamespace()
Description copied from interface: IRemoteServiceConsumer
Get namespace to use for this remote service provider.

Specified by:
getRemoteServiceNamespace in interface IRemoteServiceConsumer
Specified by:
getRemoteServiceNamespace in interface IRemoteServiceContainerAdapter
Specified by:
getRemoteServiceNamespace in interface IRemoteServiceHost
Returns:
Namespace to use for creating IRemoteServiceID for this remote service provider. Will not return null.

getRemoteServiceReference

public IRemoteServiceReference getRemoteServiceReference(IRemoteServiceID serviceID)
Description copied from interface: IRemoteServiceConsumer
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
Specified by:
getRemoteServiceReference in interface IRemoteServiceContainerAdapter
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.

getRemoteServiceReferences

public IRemoteServiceReference[] getRemoteServiceReferences(ID[] idFilter,
                                                            java.lang.String clazz,
                                                            java.lang.String filter)
                                                     throws org.osgi.framework.InvalidSyntaxException
Description copied from interface: IRemoteServiceConsumer
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 IRemoteServiceConsumer.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
Specified by:
getRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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

public IRemoteServiceReference[] getRemoteServiceReferences(ID target,
                                                            java.lang.String clazz,
                                                            java.lang.String filter)
                                                     throws org.osgi.framework.InvalidSyntaxException,
                                                            ContainerConnectException
Description copied from interface: IRemoteServiceConsumer

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
Specified by:
getRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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

getRemoteServiceReferences

public IRemoteServiceReference[] getRemoteServiceReferences(ID target,
                                                            ID[] idFilter,
                                                            java.lang.String clazz,
                                                            java.lang.String filter)
                                                     throws org.osgi.framework.InvalidSyntaxException,
                                                            ContainerConnectException
Description copied from interface: IRemoteServiceConsumer
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 IRemoteServiceConsumer.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
Specified by:
getRemoteServiceReferences in interface IRemoteServiceContainerAdapter
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
Since:
5.0

registerRemoteService

public IRemoteServiceRegistration registerRemoteService(java.lang.String[] clazzes,
                                                        java.lang.Object service,
                                                        java.util.Dictionary properties)
Description copied from interface: IRemoteServiceContainerAdapter
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 IRemoteServiceContainerAdapter
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 .

removeRemoteServiceListener

public void removeRemoteServiceListener(IRemoteServiceListener listener)
Description copied from interface: IRemoteServiceConsumer
Remove remote service registration/unregistration listener for this container.

Specified by:
removeRemoteServiceListener in interface IRemoteServiceConsumer
Specified by:
removeRemoteServiceListener in interface IRemoteServiceContainerAdapter
Specified by:
removeRemoteServiceListener in interface IRemoteServiceHost
Parameters:
listener - to remove. Must not be null .

ungetRemoteService

public boolean ungetRemoteService(IRemoteServiceReference reference)
Description copied from interface: IRemoteServiceConsumer
Unget IRemoteServiceReference. Release all resources associated with the given IRemoteServiceReference. This method should be called by users of the IRemoteServiceReference that have previously called IRemoteServiceContainerAdapter.getRemoteService(IRemoteServiceReference). If this method returns true, then the previously used IRemoteService will no longer be usable.

Specified by:
ungetRemoteService in interface IRemoteServiceConsumer
Specified by:
ungetRemoteService in interface IRemoteServiceContainerAdapter
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:
IRemoteServiceConsumer.getRemoteService(IRemoteServiceReference)

registerCallables

public IRemoteServiceRegistration registerCallables(IRemoteCallable[] callables,
                                                    java.util.Dictionary properties)
Description copied from interface: IRemoteServiceClientContainerAdapter
Register remoteCallables for remote service client. This method allows providers to register IRemoteCallable instances, so that subsequent lookup operations result in appropriate remote service registrations.

Specified by:
registerCallables in interface IRemoteServiceClientContainerAdapter
Parameters:
callables - the IRemoteCallables to register. Each IRemoteCallable represents a specific method->resourcePath mapping. Must not be null.
properties - any service properties to associate with the given registration.
Returns:
IRemoteServiceRegistration to use to unregister the remote service. Will not be null.

registerCallables

public IRemoteServiceRegistration registerCallables(java.lang.String[] clazzes,
                                                    IRemoteCallable[][] callables,
                                                    java.util.Dictionary properties)
Description copied from interface: IRemoteServiceClientContainerAdapter

Register remoteCallables for given serviceInterfaceNames. This method allows providers to register IRemoteCallable instances and associate an array of IRemoteCallables with each given serviceInterfaceName, so that subsequent lookup operations result in appropriate remote service registrations. The IRemoteCallable instances should correspond to methods within the particular service interface class.

Note that the number of serviceInterfaceNames (i.e. the length of the given String[]) must be equal to the number of rows of the remoteCallable two-dimensional array.

For example, suppose we have a service interface "org.eclipse.ecf.IFoo":

 public interface IFoo {
     public String getFoo();
 }
 
We can define for this service inteface the following two dimensional array of callables:
 IRemoteCallable[][] callables = new IRemoteCallable[] { new RemoteCallable("foo","foo/bar/resourcePath",null,requestType) }};
 
and then register with this method:
 IRemoteServiceRegistration reg = this.registerRemoteCallable(new String[] { "org.eclipse.ecf.IFoo" }, callables, null);
 

Specified by:
registerCallables in interface IRemoteServiceClientContainerAdapter
callables - the IRemoteCallables to register. Each IRemoteCallable represents a specific method->resourcePath mapping. Must not be null.
properties - any service properties to associate with the given registration.
Returns:
IRemoteServiceRegistration to use to unregister the remote service. Will not be null.

registerRemoteCallables

public IRemoteServiceRegistration registerRemoteCallables(java.lang.Class[] clazzes,
                                                          java.util.List callablesList,
                                                          java.util.Dictionary properties)

registerRemoteCallables

public IRemoteServiceRegistration registerRemoteCallables(java.lang.String[] clazzes,
                                                          java.util.List callables,
                                                          java.util.Dictionary properties)

createCallablesFromClasses

public IRemoteCallable[][] createCallablesFromClasses(java.lang.Class[] cls,
                                                      java.util.List callables)

getCallablesForMethods

protected IRemoteCallable[] getCallablesForMethods(java.lang.reflect.Method[] methods,
                                                   java.util.List callables)

findCallableForName

protected IRemoteCallable findCallableForName(java.lang.String fqMethodName,
                                              java.util.List callables)

getClazzesFromStrings

public java.lang.Class[] getClazzesFromStrings(java.lang.String[] clazzes)
                                        throws java.lang.IllegalArgumentException
Throws:
java.lang.IllegalArgumentException

getClazzFromString

public java.lang.Class getClazzFromString(java.lang.String className)
                                   throws java.lang.IllegalArgumentException
Throws:
java.lang.IllegalArgumentException

connect

public void connect(ID targetID,
                    IConnectContext connectContext1)
             throws ContainerConnectException
Description copied from interface: IContainer
Connect to a target remote process or process group. The target identified by the first parameter (targetID) is connected the implementation class. If authentication information is required, the required information is given via via the second parameter (connectContext). Callers note that depending upon the provider implementation this method may block. It is suggested that callers use a separate thread to call this method. This method provides an implementation independent way for container implementations to connect, authenticate, and communicate with a remote service or group of services. Providers are responsible for implementing this operation in a way appropriate to the given remote service (or group) via expected protocol.

Specified by:
connect in interface IContainer
Parameters:
targetID - the ID of the remote server or group to connect to. See IContainer.getConnectNamespace() for a explanation of the constraints upon this parameter.
connectContext1 - any required context to allow this container to authenticate. May be null if underlying provider does not have any authentication requirements for connection.
Throws:
ContainerConnectException - thrown if communication cannot be established with remote service. Causes can include network connection failure, authentication failure, server error, or if container is already connected.

disconnect

public void disconnect()
Description copied from interface: IContainer
Disconnect. This operation will disconnect the local container instance from any previously joined target or group. Subsequent calls to getConnectedID() will return null.

Specified by:
disconnect in interface IContainer

getConnectedID

public ID getConnectedID()
Description copied from interface: IContainer
Get the target ID that this container instance has connected to. Returns null if not connected.

Specified by:
getConnectedID in interface IContainer
Returns:
ID of the target we are connected to. Returns null if container not connected.

getID

public ID getID()
Description copied from interface: IIdentifiable
Return the ID for this 'identifiable' object. The returned ID should be unique within its namespace. May return null.

Specified by:
getID in interface IIdentifiable
Returns:
the ID for this identifiable object. May return null.

dispose

public void dispose()
Description copied from interface: IContainer
Dispose this IContainer instance. The container instance will be made inactive after the completion of this method and will be unavailable for subsequent usage.

Specified by:
dispose in interface IContainer
Overrides:
dispose in class AbstractContainer

createRestServiceRegistration

protected RemoteServiceClientRegistration createRestServiceRegistration(java.lang.String[] clazzes,
                                                                        IRemoteCallable[][] callables,
                                                                        java.util.Dictionary properties)

createRestServiceRegistration

protected RemoteServiceClientRegistration createRestServiceRegistration(IRemoteCallable[] callables,
                                                                        java.util.Dictionary properties)

logException

protected void logException(java.lang.String string,
                            java.lang.Throwable e)

getRemoteCallTargetID

protected ID getRemoteCallTargetID()

prepareParameters

protected IRemoteCallParameter[] prepareParameters(java.lang.String uri,
                                                   IRemoteCall call,
                                                   IRemoteCallable callable)
                                            throws java.io.NotSerializableException
Throws:
java.io.NotSerializableException

serializeParameter

protected IRemoteCallParameter serializeParameter(java.lang.String uri,
                                                  IRemoteCall call,
                                                  IRemoteCallable callable,
                                                  IRemoteCallParameter defaultParameter,
                                                  java.lang.Object parameterValue)
                                           throws java.io.NotSerializableException
Serialze the parameter using the container's parameterSerializer. If there is no serializer for this container, return null.

Returns:
the serialized parameter or null if there is no parameterSerializer for this container
Throws:
java.io.NotSerializableException
Since:
4.1
See Also:
IRemoteCallParameterSerializer.serializeParameter(String, IRemoteCall, IRemoteCallable, IRemoteCallParameter, Object)

processResponse

protected java.lang.Object processResponse(java.lang.String uri,
                                           IRemoteCall call,
                                           IRemoteCallable callable,
                                           java.util.Map responseHeaders,
                                           java.lang.String responseBody)
                                    throws java.io.NotSerializableException
Throws:
java.io.NotSerializableException

createRemoteService

protected abstract IRemoteService createRemoteService(RemoteServiceClientRegistration registration)
Create an implementer of IRemoteService for the given registration.

Parameters:
registration - registration from which to create the associated IRemoteService. Will not be null.
Returns:
IRemoteService the remote service associated with this client container. Should not return null.

prepareEndpointAddress

protected abstract java.lang.String prepareEndpointAddress(IRemoteCall call,
                                                           IRemoteCallable callable)
Prepare an endpoint address for the given call and callable.

Parameters:
call - to create an endpoint for. Will not be null.
callable - to create an endpoing for. Will not be null.
Returns:
String that represents the endpoing for the given call and callable. May only return null if the given call should not be completed (i.e. there is no endpoint associated with the given call).