com.alibaba.dubbo.rpc.Protocol Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dubbo2 Show documentation
The all in one project of dubbo2
The newest version!
/*
 * Copyright 1999-2011 Alibaba Group.
 *  
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *  
 *      http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.alibaba.dubbo.rpc;

import com.alibaba.dubbo.common.URL;
import com.alibaba.dubbo.common.extension.Adaptive;
import com.alibaba.dubbo.common.extension.SPI;

/**
 * Protocol. (API/SPI, Singleton, ThreadSafe)
 * 
 * @author william.liangf
 */
@SPI("dubbo")
public interface Protocol {
    
    /**
     * 获取缺省端口，当用户没有配置端口时使用。
     * 
     * @return 缺省端口
     */
    int getDefaultPort();

    /**
     * 暴露远程服务：

     * 1. 协议在接收请求时，应记录请求来源方地址信息：RpcContext.getContext().setRemoteAddress();

     * 2. export()必须是幂等的，也就是暴露同一个URL的Invoker两次，和暴露一次没有区别。

     * 3. export()传入的Invoker由框架实现并传入，协议不需要关心。

     * 
     * @param  服务的类型
     * @param invoker 服务的执行体
     * @return exporter 暴露服务的引用，用于取消暴露
     * @throws RpcException 当暴露服务出错时抛出，比如端口已占用
     */
    @Adaptive
     Exporter export(Invoker invoker) throws RpcException;

    /**
     * 引用远程服务：

     * 1. 当用户调用refer()所返回的Invoker对象的invoke()方法时，协议需相应执行同URL远端export()传入的Invoker对象的invoke()方法。

     * 2. refer()返回的Invoker由协议实现，协议通常需要在此Invoker中发送远程请求。

     * 3. 当url中有设置check=false时，连接失败不能抛出异常，并内部自动恢复。

     * 
     * @param  服务的类型
     * @param type 服务的类型
     * @param url 远程服务的URL地址
     * @return invoker 服务的本地代理
     * @throws RpcException 当连接服务提供方失败时抛出
     */
    @Adaptive
     Invoker refer(Class type, URL url) throws RpcException;

    /**
     * 释放协议：

     * 1. 取消该协议所有已经暴露和引用的服务。

     * 2. 释放协议所占用的所有资源，比如连接和端口。

     * 3. 协议在释放后，依然能暴露和引用新的服务。

     */
    void destroy();

}