Class AbstractClientContainer

    • Field Detail

      • containerID

        protected ID containerID
      • connectedID

        protected ID connectedID
      • connectLock

        protected Object connectLock
      • remoteResponseDeserializerLock

        protected Object remoteResponseDeserializerLock
      • parameterSerializerLock

        protected Object parameterSerializerLock
      • remoteServiceListeners

        protected List remoteServiceListeners
      • alwaysSendDefaultParameters

        protected boolean alwaysSendDefaultParameters
        Since:
        4.1
    • Constructor Detail

      • AbstractClientContainer

        public AbstractClientContainer​(ID containerID)
    • Method Detail

      • setRemoteServiceFactory

        public void setRemoteServiceFactory​(IRemoteServiceFactory factory)
        Since:
        8.12
      • getConnectContextForAuthentication

        public IConnectContext getConnectContextForAuthentication()
      • 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
      • 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.
      • 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.
      • 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:
        5.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.
      • getRemoteServiceID

        public IRemoteServiceID getRemoteServiceID​(ID containerID1,
                                                   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:
        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.
      • 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 target,
                                                                    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:
        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:
        InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.
        ContainerConnectException - if container cannot connect
      • 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:
        5.0
      • 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 .
      • registerCallables

        public IRemoteServiceRegistration registerCallables​(IRemoteCallable[] callables,
                                                            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 to 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​(Class<?> serviceType,
                                                            IRemoteCallable[] callables,
                                                            Dictionary properties)
        Parameters:
        serviceType - serviceType
        callables - callables
        properties - properties
        Returns:
        IRemoteServiceRegistration registration created for registration
        Since:
        8.5
      • registerCallables

        public IRemoteServiceRegistration registerCallables​(String[] clazzes,
                                                            IRemoteCallable[][] callables,
                                                            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
        Parameters:
        clazzes - service interface names
        callables - the IRemoteCallables to register. Each IRemoteCallable represents a specific method to 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.
      • 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
      • logException

        protected void logException​(String string,
                                    Throwable e)
      • getRemoteCallTargetID

        protected ID getRemoteCallTargetID()
      • serializeParameter

        protected IRemoteCallParameter[] serializeParameter​(String uri,
                                                            IRemoteCall call,
                                                            IRemoteCallable callable,
                                                            List currentParameters,
                                                            Object[] parameterValue)
                                                     throws NotSerializableException
        Serialize the parameter using the container's parameterSerializer. If there is no serializer for this container, return null.
        Parameters:
        uri - uri
        call - call
        callable - callable
        currentParameters - current parameters
        parameterValue - parameter value
        Returns:
        IRemoteCallParameter[] parameters for given
        Throws:
        NotSerializableException - thrown if parameters cannot be serialized
        Since:
        8.0
      • processResponse

        protected Object processResponse​(String uri,
                                         IRemoteCall call,
                                         IRemoteCallable callable,
                                         Map responseHeaders,
                                         byte[] responseBody)
                                  throws NotSerializableException
        Parameters:
        uri - uri
        call - call
        callable - callable
        responseHeaders - http response headers
        responseBody - response body as byte[]
        Returns:
        Object response deserialized via response deserializer
        Throws:
        NotSerializableException - if response cannot be deserialized for processing
        Since:
        8.0
      • createRemoteService

        protected IRemoteService createRemoteService​(RemoteServiceClientRegistration registration)
        Create a remote service for a given remote service registration. This method will be called as part of the RemoteServiceAdmin.importService.
        Parameters:
        registration - the remote service client registration associated with the service being imported. Will not be null.
      • prepareEndpointAddress

        protected abstract 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).