dubbo:reference element

The configuration of service consumer. The corresponding class isorg.apache.dubbo.config.ReferenceConfig

AttributeCorresponding URL parameterTypeRequiredDefault ValueFunctionDescriptionCompatibility
idstringTrueConfiguration associationBean Id of the service referenceAbove 1.0.0
interfaceclassTrueService discoveryInterface name of the serviceAbove 1.0.0
versionversionstringFalseService discoveryService version, must be equal to the provider’s versionAbove 1.0.0
groupgroupstringFalseService discoveryThe group of the service reference, must be equal to the provider’s group. It can distinguish services when it has multiple implements.Above 1.0.7
timeouttimeoutlongFalseBy default, use <dubbo:consumer> timeoutPerformance optimizeThe RPC timeout(ms)Above 1.0.5
retriesretriesintFalseBy default, use <dubbo:consumer> retriesPerformance optimizeThe retry count for RPC, not including the first invoke. Please set it to 0 if don’t need to retry.Above 2.0.0
connectionsconnectionsintFalseBy default, use <dubbo:consumer> connectionsPerformance optimizeThe maximum connections of every provider. For short connection such as rmi, http and hessian, it’s connection limit, but for long connection such as dubbo, it’s connection count.Above 2.0.0
loadbalanceloadbalancestringFalseBy default, use <dubbo:consumer> loadbalancePerformance optimizeStrategy of load balance, random, roundrobin and leastactive are available.Above 2.0.0
asyncasyncbooleanFalseBy default, use <dubbo:consumer> asyncPerformance optimizeAsynchronous execution, not reliable. It does not block the execution thread just only ignores the return value.Above 2.0.0
genericgenericbooleanFalseBy default, use <dubbo:consumer> genericService governanceEnable generic interface. If true, the reference will return GenericServiceAbove 2.0.0
checkcheckbooleanFalseBy default, use <dubbo:consumer> checkService governanceCheck the exist of the provider. If true, it will throw exception when provider is not exist. If false, will ignore.Above 2.0.0
urlurlstringFalseService governanceConnect to the provider directly via this url. It will bypass the registry.Above 1.0.6
stubstubclass/booleanFalseService governanceThe local proxy class name of the client, it’s used to execute local logic such as caching. The proxy class must have a constructor with the remote proxy object as a parameter, such as public XxxServiceLocal(XxxService xxxService)Above 2.0.0
mockmockclass/booleanFalseService governanceThe mock class name. It’s called when the RPC is failed, such as timeout or IO exception. The mock class must carry a none parameter constructor. The difference between mock and local proxy is that local proxy is always invoked before RPC but mock is invoked only when exception after RPC.Above 1.0.13
cachecachestring/booleanFalseService governancelru, threadlocal, jcache等Using RPC parameters as the key to cache the result. lru, threadlocal and jcache are available.Above 2.1.0
validationvalidationbooleanFalseService governanceEnable JSR303 annotation validation. If true, it will validate the method parameters' annotations.Above 2.1.0
proxyproxybooleanFalsejavassistPerformance optimizeThe proxy implement, jdk/javassist are available.Above 2.0.2
clientclientstringFalsePerformance optimizeThe transport type of the client, such as netty and mina for dubbo protocol.Above 2.0.0
registrystringFalseBy default, it will merge all the service providers that getting from all registriesConfiguration associationGet provider lists from the specified registry. It is the id value of the <dubbo:registry>, use , to separate multiple regsitries id.Above 2.0.0
ownerownerstringFalseService governanceThe owner of the service. It’s used for service governance.Above 2.0.5
activesactivesintFalse0Performance optimizeThe maximum concurrent calls per method per service of the consumer.Above 2.0.5
clusterclusterstringFalsefailoverPerformance optimizefailover/failfast/failsafe/failback/forking are available.Above 2.0.5
filterreference.filterstringFalsedefaultPerformance optimizeThe filter name of the RPC process of the reference, use , to separate multiple filter names.Above 2.0.5
listenerinvoker.listenerstringFalsedefaultPerformance optimizeThe listener name of the reference, use , to separate multiple listener names.Above 2.0.5
layerlayerstringFalseService governanceThe biz layer of the service provider, such as biz, dao, intl:web and china:acton.Above 2.0.7
initinitbooleanFalsefalsePerformance optimizeIf true, init the service reference when afterPropertiesSet()is invoked, or it will init later only when it is referenced and autowired.Above 2.0.10
protocolprotocolstringFalseService governanceOnly invoke the providers with specified protocol, and ignore other protocol providers.Above 2.2.0

Last modified November 25, 2020: fix sample code issue for SPI.md (#659) (0576d68)