/* | |
* Licensed to the Apache Software Foundation (ASF) under one or more | |
* contributor license agreements. See the NOTICE file distributed with | |
* this work for additional information regarding copyright ownership. | |
* The ASF licenses this file to You 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) | |
*/ | |
@SPI("dubbo") | |
public interface Protocol { | |
/** | |
* Get default port when user doesn't config the port. | |
* | |
* @return default port | |
*/ | |
int getDefaultPort(); | |
/** | |
* Export service for remote invocation: <br> | |
* 1. Protocol should record request source address after receive a request: | |
* RpcContext.getContext().setRemoteAddress();<br> | |
* 2. export() must be idempotent, that is, there's no difference between invoking once and invoking twice when | |
* export the same URL<br> | |
* 3. Invoker instance is passed in by the framework, protocol needs not to care <br> | |
* | |
* @param <T> Service type | |
* @param invoker Service invoker | |
* @return 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 | |
*/ | |
@Adaptive | |
<T> Exporter<T> export(Invoker<T> invoker) throws RpcException; | |
/** | |
* Refer a remote service: <br> | |
* 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 <br> | |
* 2. It's protocol's responsibility to implement `Invoker` which's returned from `refer()`. Generally speaking, | |
* protocol sends remote request in the `Invoker` implementation. <br> | |
* 3. When there's check=false set in URL, the implementation must not throw exception but try to recover when | |
* connection fails. | |
* | |
* @param <T> Service type | |
* @param type Service class | |
* @param url URL address for the remote service | |
* @return invoker service's local proxy | |
* @throws RpcException when there's any error while connecting to the service provider | |
*/ | |
@Adaptive | |
<T> Invoker<T> refer(Class<T> type, URL url) throws RpcException; | |
/** | |
* Destroy protocol: <br> | |
* 1. Cancel all services this protocol exports and refers <br> | |
* 2. Release all occupied resources, for example: connection, port, etc. <br> | |
* 3. Protocol can continue to export and refer new service even after it's destroyed. | |
*/ | |
void destroy(); | |
} |