Package org.apache.dubbo.rpc

Interface Protocol

All Known Implementing Classes:
AbstractProtocol, AbstractProxyProtocol, InvokerCountWrapper, MockProtocol, ProtocolListenerWrapper, ProtocolSecurityWrapper, ProtocolSerializationWrapper
@SPI(value="dubbo", scope=FRAMEWORK) public interface Protocol
RPC Protocol extension interface, which encapsulates the details of remote invocation.

Conventions:

  • When user invokes the 'invoke()' method in object that the method 'refer()' returns, the protocol needs to execute the 'invoke()' method of Invoker object that received by 'export()' method, which should have the same URL.
  • Invoker that returned by 'refer()' is implemented by the protocol. The remote invocation request should be sent by that Invoker.
  • The invoker that 'export()' receives will be implemented by framework. Protocol implementation should not care with that.

    • Attentions:

  • The Protocol implementation does not care the transparent proxy. The invoker will be converted to business interface by other layer.
  • The protocol doesn't need to be backed by TCP connection. It can also be backed by file sharing or inter-process communication.
    • (API/SPI, Singleton, ThreadSafe)

    • Method Summary

      Modifier and Type
      Method
      Description
      void
      destroy()
      Destroy protocol:
      1.
      <T> Exporter<T>
      export(Invoker<T> invoker)
      Export service for remote invocation:
      1.
      int
      getDefaultPort()
      Get default port when user doesn't config the port.
      default List<ProtocolServer>
      getServers()
      Get all servers serving this protocol
      <T> Invoker<T>
      refer(Class<T> type, URL url)
      Refer a remote service:
      1.

    • Method Details

      • getDefaultPort

        int getDefaultPort()
        Get default port when user doesn't config the port.
        Returns:
        default port

      • export

        @Adaptive <T> Exporter<T> export(Invoker<T> invoker) throws RpcException
        Export service for remote invocation:
        1. Protocol should record request source address after receive a request: RpcContext.getServerAttachment().setRemoteAddress();
        2. export() must be idempotent, that is, there's no difference between invoking once and invoking twice when export the same URL
        3. Invoker instance is passed in by the framework, protocol needs not to care
        Type Parameters:
        T - Service type
        Parameters:
        invoker - Service invoker
        Returns:
        exporter reference for exported service, useful for unexport the service later
        Throws:
        RpcException - thrown when error occurs during export the service, for example: port is occupied

      • refer

        @Adaptive <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException
        Refer a remote service:
        1. When user calls `invoke()` method of `Invoker` object which's returned from `refer()` call, the protocol needs to correspondingly execute `invoke()` method of `Invoker` object
        2. It's protocol's responsibility to implement `Invoker` which's returned from `refer()`. Generally speaking, protocol sends remote request in the `Invoker` implementation.
        3. When there's check=false set in URL, the implementation must not throw exception but try to recover when connection fails.
        Type Parameters:
        T - Service type
        Parameters:
        type - Service class
        url - URL address for the remote service
        Returns:
        invoker service's local proxy
        Throws:
        RpcException - when there's any error while connecting to the service provider

      • destroy

        void destroy()
        Destroy protocol:
        1. Cancel all services this protocol exports and refers
        2. Release all occupied resources, for example: connection, port, etc.
        3. Protocol can continue to export and refer new service even after it's destroyed.

      • getServers

        default List<ProtocolServer> getServers()
        Get all servers serving this protocol
        Returns: