Package org.eclipse.ecf.provider.remoteservice.generic

## Class RegistrySharedObject

- java.lang.Object
- - org.eclipse.ecf.core.sharedobject.BaseSharedObject
  - - org.eclipse.ecf.provider.remoteservice.generic.RegistrySharedObject

All Implemented Interfaces:
  `org.eclipse.core.runtime.IAdaptable`, `IIdentifiable`, `ISharedObject`, `IRemoteServiceConsumer`, `IRemoteServiceContainerAdapter`, `IRemoteServiceHost`

    public class RegistrySharedObject
    extends BaseSharedObject
    implements IRemoteServiceContainerAdapter

### Field Summary

Fields
`protected static int` `ADD_REGISTRATION_REQUEST_TIMEOUT`
`protected Map` `addRegistrationRequests` Map of add registration requests.
`protected int` `addRegistrationRequestTimeout` Add registration request default timeout
`protected IConnectContext` `connectContext` Connect context to be used for connect.
`protected RemoteServiceRegistryImpl` `localRegistry` registry impl for local remote service registrations
`protected static boolean` `PROPAGATE_RESPONSE_ERROR`
`protected long` `registryUpdateRequestTimeout`
`protected Map` `remoteRegistrys` map of registry impls for remote registrys key: ID (identifier of remote container), value: RemoteServiceRegistryImpl (copy of remote service registry for remote container
`protected List` `requests` List of invocation requests...instances of Request
`protected boolean` `rsConnected` Whether or not we are connected
`protected Object` `rsConnectLock`
`protected int` `rsConnectTimeout` Add registration request default timeout.
`protected List` `serviceListeners` List of remote service listeners (added to/removed from by addRemoteServiceListener/removeRemoteServiceListener

### Fields inherited from class org.eclipse.ecf.core.sharedobject.BaseSharedObject

`DESTROYREMOTE_CODE, DESTROYSELFLOCAL_CODE`

### Constructor Summary

Constructors
`RegistrySharedObject()`

### Method Summary

All Methods Instance Methods Concrete Methods
`protected RemoteServiceRegistryImpl` `addRemoteRegistry​(RemoteServiceRegistryImpl registry)`
`void` `addRemoteServiceListener​(IRemoteServiceListener listener)` Add listener for remote service registration/unregistration for this container
`protected boolean` `addRequest​(Request request)`
`org.eclipse.equinox.concurrent.future.IFuture` `asyncGetRemoteServiceReferences​(ID[] idFilter, String clazz, String filter)` Asynchronously returns an array of `IRemoteServiceReference` objects.
`org.eclipse.equinox.concurrent.future.IFuture` `asyncGetRemoteServiceReferences​(ID target, String clazz, String filter)` Asynchronously returns an array of `IRemoteServiceReference` objects.
`org.eclipse.equinox.concurrent.future.IFuture` `asyncGetRemoteServiceReferences​(ID target, ID[] idFilter, String clazz, String filter)` Asynchronously returns an array of `IRemoteServiceReference` objects.
`protected Object` `callSynch​(RemoteServiceRegistrationImpl registration, IRemoteCall call)`
`protected void` `checkRequestServiceAuthorization​(ID remoteContainerID, AddRegistrationRequest request, Serializable credentials)`
`protected void` `clearRemoteRegistrys()`
`protected void` `connectToRemoteServiceTarget​(ID targetID)`
`protected IRemoteServiceRegisteredEvent` `createRegisteredEvent​(RemoteServiceRegistrationImpl registration)`
`IRemoteFilter` `createRemoteFilter​(String filter)` Creates a `IRemoteFilter` object.
`protected RemoteServiceImpl` `createRemoteService​(RemoteServiceRegistrationImpl registration)`
`protected org.eclipse.equinox.concurrent.future.IExecutor` `createRequestExecutor​(Request request)`
`protected IRemoteServiceUnregisteredEvent` `createUnregisteredEvent​(RemoteServiceRegistrationImpl registration)`
`protected Request` `deserializeCallRequest​(byte[] requestBytes)`
`protected Response` `deserializeCallResponse​(byte[] responseBytes)`
`void` `dispose​(ID containerID)` Method called by the ISharedObjectContainer upon ISharedObject destruction.
`protected void` `executeRequest​(org.eclipse.equinox.concurrent.future.IExecutor executor, Request request, ID responseTarget, RemoteServiceRegistrationImpl localRegistration, boolean respond)`
`protected void` `fireCallCompleteEvent​(IRemoteCallListener listener, long requestId, Object response, boolean hadException, Throwable exception)`
`protected void` `fireCallStartEvent​(IRemoteCallListener listener, long requestId, IRemoteServiceReference reference, IRemoteCall call)`
`protected void` `fireRemoteServiceListeners​(IRemoteServiceEvent event)`
`protected Serializable` `getAddRegistrationRequestCredentials​(AddRegistrationRequest request)`
`protected int` `getAddRegistrationRequestTimeout()`
`IRemoteServiceReference[]` `getAllRemoteServiceReferences​(String clazz, String filter)` Returns an array of `IRemoteServiceReference` objects.
`protected RemoteServiceRegistrationImpl` `getLocalRegistrationForRequest​(Request request)`
`protected long` `getRegistryUpdateRequestTimeout()`
`protected RemoteServiceRegistryImpl` `getRemoteRegistry​(ID containerID)`
`IRemoteService` `getRemoteService​(IRemoteServiceReference reference)` Get remote service for given IRemoteServiceReference.
`protected IRemoteServiceCallPolicy` `getRemoteServiceCallPolicy()`
`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, String clazz, String filter)` Returns an array of `IRemoteServiceReference` objects.
`IRemoteServiceReference[]` `getRemoteServiceReferences​(ID targetID, String clazz, String filter)` Returns an array of `IRemoteServiceReference` objects.
`IRemoteServiceReference[]` `getRemoteServiceReferences​(ID target, ID[] idFilter, String clazz, String filter)` Returns an array of `IRemoteServiceReference` objects.
`protected Request` `getRequest​(long requestId)`
`protected int` `getRSConnectTimeout()`
`protected ISharedObjectContext` `getSOContext()`
`protected ID[]` `getTargetsFromProperties​(Dictionary properties)`
`protected void` `handleAddRegistration​(ID remoteContainerID, Integer requestId, RemoteServiceRegistrationImpl registration)`
`protected void` `handleAddRegistration​(ID remoteContainerID, RemoteServiceRegistrationImpl registration)`
`protected void` `handleAddRegistrationRequestRefused​(ID remoteContainerID, Integer requestId, AccessControlException e)`
`protected void` `handleAddRegistrations​(ID remoteContainerID, Integer requestId, RemoteServiceRegistrationImpl[] registrations)`
`protected void` `handleCallRequest​(Request request)`
`protected void` `handleCallRequestBytes​(byte[] requestBytes)`
`protected void` `handleCallResponse​(Response response)`
`protected void` `handleCallResponseBytes​(byte[] responseBytes)`
`protected void` `handleContainerConnectedEvent​(IContainerConnectedEvent event)`
`protected void` `handleContainerDisconnectedEvent​(IContainerDisconnectedEvent event)`
`protected void` `handleContainerEjectedEvent​(IContainerEjectedEvent event)`
`protected void` `handleFireRequest​(Request request)`
`protected void` `handleRegistryActivatedEvent()`
`protected void` `handleRegistryUpdateRequest​(ID remoteContainerID)`
`protected void` `handleRegistryUpdateRequest​(ID remoteContainerID, Integer requestId)`
`protected void` `handleRequestService​(ID remoteContainerID, AddRegistrationRequest request, Integer requestId, Serializable credentials)`
`protected boolean` `handleSharedObjectMsg​(SharedObjectMsg msg)` SharedObjectMsg handler method.
`protected void` `handleTargetConnected​(ID targetID)`
`protected void` `handleUnregister​(ID containerID, Long serviceId)`
`void` `initialize()` Initialize this shared object.
`protected Object` `invokeLocal​(RemoteServiceRegistrationImpl reg, RemoteCallImpl call)`
`protected void` `log​(int code, String method, Throwable e)`
`protected void` `logException​(int code, String message, Throwable e)`
`protected void` `logRemoteCallException​(String message, Throwable e)`
`protected void` `notifyAddRegistrationResponse​(ID remoteContainerID, Integer requestId, AccessControlException exception)`
`IRemoteServiceRegistration` `registerRemoteService​(String[] clazzes, Object service, Dictionary properties)` Register a new remote service.
`protected RemoteServiceRegistryImpl` `removeRemoteRegistry​(ID containerID)`
`void` `removeRemoteServiceListener​(IRemoteServiceListener listener)` Remove remote service registration/unregistration listener for this container.
`protected boolean` `removeRequest​(Request request)`
`protected void` `sendAddRegistration​(ID receiver, Integer requestId, RemoteServiceRegistrationImpl reg)`
`protected void` `sendAddRegistration​(ID receiver, RemoteServiceRegistrationImpl reg)`
`protected AddRegistrationRequest` `sendAddRegistrationRequest​(ID receiver, AddRegistrationRequest request, Serializable credentials)`
`protected void` `sendAddRegistrationRequestRefused​(ID receiver, Integer requestId, Exception except)`
`protected void` `sendAddRegistrations​(ID receiver, Integer requestId, RemoteServiceRegistrationImpl[] regs)`
`protected Request` `sendCallRequest​(RemoteServiceRegistrationImpl remoteRegistration, IRemoteCall call)`
`protected void` `sendCallRequestWithListener​(RemoteServiceRegistrationImpl remoteRegistration, IRemoteCall call, IRemoteCallListener listener)`
`protected void` `sendCallResponse​(ID responseTarget, Response response)`
`protected Request` `sendFireRequest​(RemoteServiceRegistrationImpl remoteRegistration, IRemoteCall call)`
`protected void` `sendRegistryUpdate​(ID targetContainerID)`
`protected void` `sendRegistryUpdate​(ID targetContainerID, Integer requestId)`
`protected void` `sendRegistryUpdateRequest()`
`protected void` `sendRegistryUpdateRequest​(ID receiver, Integer requestId)`
`protected void` `sendUnregister​(RemoteServiceRegistrationImpl serviceRegistration)`
`protected byte[]` `serializeCallRequest​(Request request)`
`protected byte[]` `serializeCallResponse​(Response response)`
`void` `setConnectContextForAuthentication​(IConnectContext connectContext)` Set connect context for authentication upon subsequent calls to `IRemoteServiceContainerAdapter.getRemoteServiceReferences(ID[], String, String)` or `IRemoteServiceContainerAdapter.asyncGetRemoteServiceReferences(ID[], String, String)`.
`protected void` `setRegistryConnected​(boolean connected)`
`boolean` `setRemoteServiceCallPolicy​(IRemoteServiceCallPolicy policy)` Set the remote service call policy to enable authorization on remote service method calls
`boolean` `ungetRemoteService​(IRemoteServiceReference ref)` Unget IRemoteServiceReference.

### Methods inherited from class org.eclipse.ecf.core.sharedobject.BaseSharedObject

`addEventProcessor, clearEventProcessors, creationCompleted, destroyRemote, destroySelf, destroySelfLocal, fireEventProcessors, getAdapter, getConfig, getConnectedID, getContext, getGroupMemberIDs, getHomeContainerID, getID, getLocalContainerID, getProperties, getReplicaDescription, getReplicaDescriptions, getSharedObjectMsgFromEvent, handleEvent, handleEvents, handleSharedObjectCreateResponseEvent, handleSharedObjectMsg, handleSharedObjectMsgEvent, handleUnhandledEvent, init, isConnected, isPrimary, log, removeEventProcessor, replicateToRemoteContainers, sendSharedObjectMsgTo, sendSharedObjectMsgToPrimary, sendSharedObjectMsgToSelf, trace, traceCatching, traceEntering, traceEntering, traceEntering, traceExiting, traceExiting`

### 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`

### Field Detail

#### ADD_REGISTRATION_REQUEST_TIMEOUT

    protected static final int ADD_REGISTRATION_REQUEST_TIMEOUT

Since:
  3.3

#### PROPAGATE_RESPONSE_ERROR

    protected static final boolean PROPAGATE_RESPONSE_ERROR

Since:
  4.2

#### localRegistry

    protected RemoteServiceRegistryImpl localRegistry

registry impl for local remote service registrations

#### remoteRegistrys

    protected final Map remoteRegistrys

map of registry impls for remote registrys key: ID (identifier of remote container), value: RemoteServiceRegistryImpl (copy of remote service registry for remote container

#### serviceListeners

    protected final List serviceListeners

List of remote service listeners (added to/removed from by addRemoteServiceListener/removeRemoteServiceListener

#### addRegistrationRequests

    protected Map addRegistrationRequests

Map of add registration requests. key: Integer (unique Request id), value: AddRegistrationRequest

#### addRegistrationRequestTimeout

    protected int addRegistrationRequestTimeout

Add registration request default timeout

Since:
  3.0

#### requests

    protected List requests

List of invocation requests...instances of Request

#### connectContext

    protected IConnectContext connectContext

Connect context to be used for connect.

Since:
  3.0

#### rsConnectLock

    protected final Object rsConnectLock

Since:
  3.3

#### rsConnected

    protected boolean rsConnected

Whether or not we are connected

Since:
  3.3

#### rsConnectTimeout

    protected int rsConnectTimeout

Add registration request default timeout.

Since:
  3.3

#### registryUpdateRequestTimeout

    protected long registryUpdateRequestTimeout

Since:
  3.4

### Constructor Detail

#### RegistrySharedObject

    public RegistrySharedObject()

### Method Detail

#### getRemoteServiceReferences

    public IRemoteServiceReference[] getRemoteServiceReferences​(ID target,
                                                                ID[] idFilter,
                                                                String clazz,
                                                                String filter)
                                                         throws InvalidSyntaxException,
                                                                ContainerConnectException

Description copied from interface: `IRemoteServiceContainerAdapter`
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 `IRemoteServiceContainerAdapter.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:
  `InvalidSyntaxException` - If filter contains an invalid filter string that cannot be parsed.
  `ContainerConnectException` - if container cannot connect
Since:
  3.4

#### getRemoteServiceReferences

    public IRemoteServiceReference[] getRemoteServiceReferences​(ID[] idFilter,
                                                                String clazz,
                                                                String filter)
                                                         throws InvalidSyntaxException

Description copied from interface: `IRemoteServiceContainerAdapter`
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 `IRemoteServiceContainerAdapter.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:
  `InvalidSyntaxException` - If filter contains an invalid filter string that cannot be parsed.

#### getRemoteServiceReferences

    public IRemoteServiceReference[] getRemoteServiceReferences​(ID targetID,
                                                                String clazz,
                                                                String filter)
                                                         throws InvalidSyntaxException,
                                                                ContainerConnectException

Description copied from interface: `IRemoteServiceContainerAdapter`

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:
  `targetID` - 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:
  `InvalidSyntaxException` - If filter contains an invalid filter string that cannot be parsed.
  `ContainerConnectException` - if container cannot connect
Since:
  3.0

#### getAllRemoteServiceReferences

    public IRemoteServiceReference[] getAllRemoteServiceReferences​(String clazz,
                                                                   String filter)
                                                            throws InvalidSyntaxException

Description copied from interface: `IRemoteServiceContainerAdapter`

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:
  `InvalidSyntaxException` - If filter contains an invalid filter string that cannot be parsed.
Since:
  3.0

#### addRemoteServiceListener

    public void addRemoteServiceListener​(IRemoteServiceListener listener)

Description copied from interface: `IRemoteServiceContainerAdapter`
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` .

#### removeRemoteServiceListener

    public void removeRemoteServiceListener​(IRemoteServiceListener listener)

Description copied from interface: `IRemoteServiceContainerAdapter`
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` .

#### createRemoteService

    protected RemoteServiceImpl createRemoteService​(RemoteServiceRegistrationImpl registration)

Parameters:
  `registration` - registration
Returns:
  RemoteServiceImpl remote service implementation
Since:
  4.1

#### getRemoteService

    public IRemoteService getRemoteService​(IRemoteServiceReference reference)

Description copied from interface: `IRemoteServiceContainerAdapter`
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:
  `IRemoteServiceContainerAdapter.ungetRemoteService(IRemoteServiceReference)`

#### registerRemoteService

    public IRemoteServiceRegistration registerRemoteService​(String[] clazzes,
                                                            Object service,
                                                            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` .

#### ungetRemoteService

    public boolean ungetRemoteService​(IRemoteServiceReference ref)

Description copied from interface: `IRemoteServiceContainerAdapter`
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:
  `ref` - 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:
  `IRemoteServiceContainerAdapter.getRemoteService(IRemoteServiceReference)`

#### asyncGetRemoteServiceReferences

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

Description copied from interface: `IRemoteServiceContainerAdapter`
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 `IRemoteServiceContainerAdapter.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`.
Since:
  3.0

#### asyncGetRemoteServiceReferences

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

Description copied from interface: `IRemoteServiceContainerAdapter`
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:
  3.4

#### asyncGetRemoteServiceReferences

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

Description copied from interface: `IRemoteServiceContainerAdapter`
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`.
Since:
  3.0

#### getRemoteServiceNamespace

    public Namespace getRemoteServiceNamespace()

Description copied from interface: `IRemoteServiceContainerAdapter`
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`.
Since:
  3.0

#### createRemoteFilter

    public IRemoteFilter createRemoteFilter​(String filter)
                                     throws InvalidSyntaxException

Description copied from interface: `IRemoteServiceContainerAdapter`
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:
  `InvalidSyntaxException` - If `filter` contains an invalid filter string that cannot be parsed.
Since:
  3.0
See Also:
  "Framework specification for a description of the filter string syntax.", `FrameworkUtil.createFilter(String)`

#### getRemoteServiceReference

    public IRemoteServiceReference getRemoteServiceReference​(IRemoteServiceID serviceId)

Description copied from interface: `IRemoteServiceContainerAdapter`
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.
Since:
  3.0

#### getRemoteServiceID

    public IRemoteServiceID getRemoteServiceID​(ID containerId,
                                               long containerRelativeId)

Description copied from interface: `IRemoteServiceContainerAdapter`
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:
  `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

#### setConnectContextForAuthentication

    public void setConnectContextForAuthentication​(IConnectContext connectContext)

Description copied from interface: `IRemoteServiceContainerAdapter`
Set connect context for authentication upon subsequent calls to `IRemoteServiceContainerAdapter.getRemoteServiceReferences(ID[], String, String)` or `IRemoteServiceContainerAdapter.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.
Since:
  3.0

#### initialize

    public void initialize()
                    throws SharedObjectInitException

Description copied from class: `BaseSharedObject`
Initialize this shared object. Subclasses may override as appropriate to define custom initialization behavior. If initialization should fail, then a SharedObjectInitException should be thrown by implementing code. Also, subclasses overriding this method should call super.initialize() before running their own code.

Overrides:
  `initialize` in class `BaseSharedObject`
Throws:
  `SharedObjectInitException` - if initialization should throw

#### dispose

    public void dispose​(ID containerID)

Description copied from interface: `ISharedObject`
Method called by the ISharedObjectContainer upon ISharedObject destruction. Once this method is called, no more Events will be passed to a ISharedObject until the init method is called again.

Specified by:
  `dispose` in interface `ISharedObject`
Overrides:
  `dispose` in class `BaseSharedObject`
Parameters:
  `containerID` - the ID of the container that is disposing this ISharedObject

#### getRSConnectTimeout

    protected int getRSConnectTimeout()

Returns:
  int connect timeout
Since:
  3.3

#### getRegistryUpdateRequestTimeout

    protected long getRegistryUpdateRequestTimeout()

Returns:
  long registry update request timeout
Since:
  3.4

#### getAddRegistrationRequestTimeout

    protected int getAddRegistrationRequestTimeout()

Returns:
  int add registration request timeout
Since:
  3.0

#### connectToRemoteServiceTarget

    protected void connectToRemoteServiceTarget​(ID targetID)
                                         throws ContainerConnectException

Parameters:
  `targetID` - target ID to connect to
Throws:
  `ContainerConnectException` - if container cannot connect to target ID
Since:
  3.3 for preventing issues like bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=304427

#### getAddRegistrationRequestCredentials

    protected Serializable getAddRegistrationRequestCredentials​(AddRegistrationRequest request)

#### getTargetsFromProperties

    protected ID[] getTargetsFromProperties​(Dictionary properties)

#### getSOContext

    protected ISharedObjectContext getSOContext()

#### handleRegistryActivatedEvent

    protected void handleRegistryActivatedEvent()

Since:
  3.4

#### handleContainerEjectedEvent

    protected void handleContainerEjectedEvent​(IContainerEjectedEvent event)

Parameters:
  `event` - event to handle
Since:
  3.3

#### clearRemoteRegistrys

    protected void clearRemoteRegistrys()

Since:
  3.4

#### setRegistryConnected

    protected void setRegistryConnected​(boolean connected)

Parameters:
  `connected` - true if registry is connected, false otherwise
Since:
  3.3

#### handleContainerDisconnectedEvent

    protected void handleContainerDisconnectedEvent​(IContainerDisconnectedEvent event)

#### sendRegistryUpdate

    protected void sendRegistryUpdate​(ID targetContainerID)

#### sendRegistryUpdate

    protected void sendRegistryUpdate​(ID targetContainerID,
                                      Integer requestId)

Parameters:
  `targetContainerID` - target container ID
  `requestId` - requestId
Since:
  3.4

#### handleContainerConnectedEvent

    protected void handleContainerConnectedEvent​(IContainerConnectedEvent event)

#### handleTargetConnected

    protected void handleTargetConnected​(ID targetID)

Parameters:
  `targetID` - targetID
Since:
  3.4

#### fireRemoteServiceListeners

    protected void fireRemoteServiceListeners​(IRemoteServiceEvent event)

#### callSynch

    protected Object callSynch​(RemoteServiceRegistrationImpl registration,
                               IRemoteCall call)
                        throws ECFException

Throws:
  `ECFException`

#### fireCallStartEvent

    protected void fireCallStartEvent​(IRemoteCallListener listener,
                                      long requestId,
                                      IRemoteServiceReference reference,
                                      IRemoteCall call)

#### fireCallCompleteEvent

    protected void fireCallCompleteEvent​(IRemoteCallListener listener,
                                         long requestId,
                                         Object response,
                                         boolean hadException,
                                         Throwable exception)

#### sendRegistryUpdateRequest

    protected void sendRegistryUpdateRequest​(ID receiver,
                                             Integer requestId)

Parameters:
  `receiver` - receiver
  `requestId` - requestId
Since:
  3.4

#### handleRegistryUpdateRequest

    protected void handleRegistryUpdateRequest​(ID remoteContainerID,
                                               Integer requestId)

Parameters:
  `remoteContainerID` - remoteContainerID
  `requestId` - requestId
Since:
  3.4

#### sendRegistryUpdateRequest

    protected void sendRegistryUpdateRequest()

#### handleRegistryUpdateRequest

    protected void handleRegistryUpdateRequest​(ID remoteContainerID)

#### sendAddRegistrationRequest

    protected AddRegistrationRequest sendAddRegistrationRequest​(ID receiver,
                                                                AddRegistrationRequest request,
                                                                Serializable credentials)

#### checkRequestServiceAuthorization

    protected void checkRequestServiceAuthorization​(ID remoteContainerID,
                                                    AddRegistrationRequest request,
                                                    Serializable credentials)
                                             throws AccessControlException

Throws:
  `AccessControlException`

#### handleRequestService

    protected void handleRequestService​(ID remoteContainerID,
                                        AddRegistrationRequest request,
                                        Integer requestId,
                                        Serializable credentials)

#### sendAddRegistration

    protected void sendAddRegistration​(ID receiver,
                                       RemoteServiceRegistrationImpl reg)

#### sendAddRegistration

    protected void sendAddRegistration​(ID receiver,
                                       Integer requestId,
                                       RemoteServiceRegistrationImpl reg)

#### sendAddRegistrations

    protected void sendAddRegistrations​(ID receiver,
                                        Integer requestId,
                                        RemoteServiceRegistrationImpl[] regs)

Parameters:
  `receiver` - receiver
  `requestId` - requestId
  `regs` - registrations to send
Since:
  3.3

#### sendAddRegistrationRequestRefused

    protected void sendAddRegistrationRequestRefused​(ID receiver,
                                                     Integer requestId,
                                                     Exception except)

#### handleAddRegistrationRequestRefused

    protected void handleAddRegistrationRequestRefused​(ID remoteContainerID,
                                                       Integer requestId,
                                                       AccessControlException e)

#### handleAddRegistration

    protected void handleAddRegistration​(ID remoteContainerID,
                                         RemoteServiceRegistrationImpl registration)

#### handleAddRegistrations

    protected void handleAddRegistrations​(ID remoteContainerID,
                                          Integer requestId,
                                          RemoteServiceRegistrationImpl[] registrations)

Parameters:
  `remoteContainerID` - container id
  `requestId` - requestId
  `registrations` - the registrations to add
Since:
  3.3

#### handleAddRegistration

    protected void handleAddRegistration​(ID remoteContainerID,
                                         Integer requestId,
                                         RemoteServiceRegistrationImpl registration)

#### notifyAddRegistrationResponse

    protected void notifyAddRegistrationResponse​(ID remoteContainerID,
                                                 Integer requestId,
                                                 AccessControlException exception)

Parameters:
  `remoteContainerID` - remoteContainerID
  `requestId` - requestId
  `exception` - exception
Since:
  3.2

#### sendCallRequest

    protected Request sendCallRequest​(RemoteServiceRegistrationImpl remoteRegistration,
                                      IRemoteCall call)
                               throws IOException

Throws:
  `IOException`

#### serializeCallRequest

    protected byte[] serializeCallRequest​(Request request)
                                   throws IOException

Throws:
  `IOException`
Since:
  4.6

#### deserializeCallRequest

    protected Request deserializeCallRequest​(byte[] requestBytes)
                                      throws IOException

Throws:
  `IOException`
Since:
  4.6

#### serializeCallResponse

    protected byte[] serializeCallResponse​(Response response)
                                    throws IOException

Throws:
  `IOException`
Since:
  4.6

#### deserializeCallResponse

    protected Response deserializeCallResponse​(byte[] responseBytes)
                                        throws IOException

Throws:
  `IOException`
Since:
  4.6

#### createRequestExecutor

    protected org.eclipse.equinox.concurrent.future.IExecutor createRequestExecutor​(Request request)

Parameters:
  `request` - request
Returns:
  IExcecutor excecutor to use for given request
Since:
  3.4

#### invokeLocal

    protected Object invokeLocal​(RemoteServiceRegistrationImpl reg,
                                 RemoteCallImpl call)
                          throws InvocationTargetException,
                                 Exception,
                                 NoClassDefFoundError

Throws:
  `InvocationTargetException`
  `Exception`
  `NoClassDefFoundError`
Since:
  4.4

#### executeRequest

    protected void executeRequest​(org.eclipse.equinox.concurrent.future.IExecutor executor,
                                  Request request,
                                  ID responseTarget,
                                  RemoteServiceRegistrationImpl localRegistration,
                                  boolean respond)

Parameters:
  `executor` - executor to use to execute request
  `request` - the request to execute
  `responseTarget` - response target
  `localRegistration` - the local registration
  `respond` - true if response is expected, false otherwise
Since:
  3.4

#### handleCallRequestBytes

    protected void handleCallRequestBytes​(byte[] requestBytes)

Since:
  4.6

#### handleCallRequest

    protected void handleCallRequest​(Request request)

#### logRemoteCallException

    protected void logRemoteCallException​(String message,
                                          Throwable e)

Parameters:
  `message` - message
  `e` - the exception
Since:
  3.4

#### sendCallRequestWithListener

    protected void sendCallRequestWithListener​(RemoteServiceRegistrationImpl remoteRegistration,
                                               IRemoteCall call,
                                               IRemoteCallListener listener)

#### log

    protected void log​(int code,
                       String method,
                       Throwable e)

Overrides:
  `log` in class `BaseSharedObject`

#### sendCallResponse

    protected void sendCallResponse​(ID responseTarget,
                                    Response response)

#### handleCallResponse

    protected void handleCallResponse​(Response response)

#### handleCallResponseBytes

    protected void handleCallResponseBytes​(byte[] responseBytes)

Since:
  4.6

#### sendFireRequest

    protected Request sendFireRequest​(RemoteServiceRegistrationImpl remoteRegistration,
                                      IRemoteCall call)
                               throws ECFException

Throws:
  `ECFException`

#### handleFireRequest

    protected void handleFireRequest​(Request request)

#### sendUnregister

    protected void sendUnregister​(RemoteServiceRegistrationImpl serviceRegistration)

#### handleUnregister

    protected void handleUnregister​(ID containerID,
                                    Long serviceId)

#### createUnregisteredEvent

    protected IRemoteServiceUnregisteredEvent createUnregisteredEvent​(RemoteServiceRegistrationImpl registration)

#### createRegisteredEvent

    protected IRemoteServiceRegisteredEvent createRegisteredEvent​(RemoteServiceRegistrationImpl registration)

#### addRemoteRegistry

    protected RemoteServiceRegistryImpl addRemoteRegistry​(RemoteServiceRegistryImpl registry)

#### getRemoteRegistry

    protected RemoteServiceRegistryImpl getRemoteRegistry​(ID containerID)

#### removeRemoteRegistry

    protected RemoteServiceRegistryImpl removeRemoteRegistry​(ID containerID)

#### getLocalRegistrationForRequest

    protected RemoteServiceRegistrationImpl getLocalRegistrationForRequest​(Request request)

Parameters:
  `request` - request
Returns:
  RemoteServiceRegistrationImpl the registration
Since:
  3.2

#### addRequest

    protected boolean addRequest​(Request request)

Parameters:
  `request` - the request to add
Returns:
  true if added, false if not added
Since:
  3.2

#### getRequest

    protected Request getRequest​(long requestId)

Parameters:
  `requestId` - requestId
Returns:
  Request the request associated with the given requestId or `null`
Since:
  3.2

#### removeRequest

    protected boolean removeRequest​(Request request)

Parameters:
  `request` - request
Returns:
  boolean true if removed, false otherwise
Since:
  3.2

#### logException

    protected void logException​(int code,
                                String message,
                                Throwable e)

#### handleSharedObjectMsg

    protected boolean handleSharedObjectMsg​(SharedObjectMsg msg)

Description copied from class: `BaseSharedObject`
SharedObjectMsg handler method. This method will be called by `BaseSharedObject.handleSharedObjectMsgEvent(ISharedObjectMessageEvent)` when a SharedObjectMsg is received either from a local source or a remote source. This default implementation simply returns false so that other processing of of the given msg can occur. Subclasses should override this behavior to define custom logic for handling SharedObjectMsgs.

Overrides:
  `handleSharedObjectMsg` in class `BaseSharedObject`
Parameters:
  `msg` - the SharedObjectMsg received
Returns:
  true if the msg has been completely handled and subsequent processing should stop. False if processing should continue

#### getRemoteServiceCallPolicy

    protected IRemoteServiceCallPolicy getRemoteServiceCallPolicy()

Returns:
  IRemoteServiceCallPolicy the policy. May be `null`
Since:
  4.0

#### setRemoteServiceCallPolicy

    public boolean setRemoteServiceCallPolicy​(IRemoteServiceCallPolicy policy)

Description copied from interface: `IRemoteServiceContainerAdapter`
Set the remote service call policy to enable authorization on remote service method calls

Specified by:
  `setRemoteServiceCallPolicy` in interface `IRemoteServiceContainerAdapter`
Parameters:
  `policy` - the policy to set. May be `null`
Returns:
  boolean true if set, false if cannot be set.
Since:
  4.0