Package org.apache.dubbo.config.annotation

Annotation Type DubboReference

@Documented
@Retention(RUNTIME)
@Target({FIELD,METHOD,ANNOTATION_TYPE})
public @interface DubboReference

An annotation used for referencing a Dubbo service.

It is recommended to use @DubboReference on the @Bean method in the Java-config class, but not on the fields or setter methods to be injected.

Step 1: Register ReferenceBean in Java-config class:

 @Configuration
 public class ReferenceConfiguration {
     @Bean
     @DubboReference(group = "demo")
     public ReferenceBean<HelloService> helloService() {
         return new ReferenceBean();
     }

     @Bean
     @DubboReference(group = "demo", interfaceClass = HelloService.class)
     public ReferenceBean<GenericService> genericHelloService() {
         return new ReferenceBean();
     }
 }
 

Step 2: Inject ReferenceBean by @Autowired

 public class FooController {
     @Autowired
     private HelloService helloService;

     @Autowired
     private GenericService genericHelloService;
 }
 

Since:

2.7.7

See Also:

• ReferenceBeanBuilder
• ReferenceBean

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
int	actives	Maximum active requests allowed, default value is 0
String	application	Deprecated. This attribute was deprecated, use bind application/module of spring ApplicationContext
boolean	async	Whether to enable async invocation, default value is false
String	cache	Specify cache implementation for service invocation, legal values include: lru, threadlocal, jcache
int	callbacks	The callback instance limit peer connection
boolean	check	Check if service provider is available during boot up, default value is true
String	client	Client transport type, default value is "netty"
String	cluster	Cluster strategy, legal values include: failover, failfast, failsafe, failback, forking you can use ClusterRules.FAIL_FAST ……
int	connections	Maximum connections service provider can accept, default value is 0 - connection is shared
String	consumer	Consumer associated name
String[]	filter	Filters for service invocation
boolean	generic	Deprecated. Do not need specify generic value, judge by injection type and interface class
String	group	Service group, default value is empty string
String	id	The id NOTE: The id attribute is ignored when using @DubboReference on @Bean method
boolean	init	Whether eager initialize the reference bean when all properties are set, default value is true ( null as true)
boolean	injvm	Deprecated. using scope="local" or scope="remote" instead
Class<?>	interfaceClass	Interface class, default value is void.class
String	interfaceName	Interface class name, default value is empty string
String	layer	Service layer, default value is empty string
boolean	lazy	Whether to make connection when the client is created, the default value is false
String[]	listener	Listeners for service exporting and unexporting
String	loadbalance	Load balance strategy, legal values include: random, roundrobin, leastactive you can use LoadbalanceRules.RANDOM ……
String	merger	Service merger
Method[]	methods	methods support
String	mock	Service mock name, use interface name + Mock if not set
String	module	Module associated name
String	monitor	Monitor associated name
String	onconnect	Callback method name when connected, default value is empty string
String	ondisconnect	Callback method name when disconnected, default value is empty string
String	owner	Service owner, default value is empty string
String[]	parameters	Customized parameter key-value pair, for example: {key1, value1, key2, value2} or {"key1=value1", "key2=value2"}
String	protocol	The communication protocol of Dubbo Service
String[]	providedBy	declares which app or service this interface belongs to
String	providerNamespace	assign the namespace that provider belong to
int	providerPort	The service port of the provider
String	proxy	How the proxy is generated, legal values include: jdk, javassist
String	reconnect	Whether to reconnect if connection is lost, if not specify, reconnect is enabled by default, and the interval for retry connecting is 2000 ms
boolean	referAsync	Weather the reference is refer asynchronously
String[]	registry	Registry associated name
int	retries	Service invocation retry times
String	scope	the scope for referring/exporting a service, if it's local, it means searching in current JVM only.
boolean	sent	Whether the async request has already been sent, the default value is false
String[]	services	Deprecated. using providedBy()
boolean	sticky	Whether to stick to the same node in the cluster, the default value is false
String	stub	Service stub name, use interface name + Stub if not set
boolean	stubevent	Export an stub service for event dispatch, default value is false.
String	tag	Service tag name
int	timeout	Timeout value for service invocation, default value is 0
boolean	unloadClusterRelated	unload Cluster related in mesh mode
String	url	Service target URL for direct invocation, if this is specified, then registry center takes no effect.
String	validation	Whether to use JSR303 validation, legal values are: true, false
String	version	Service version, default value is empty string

Element Details

interfaceClass

Class<?> interfaceClass

Interface class, default value is void.class

Default:

void.class

interfaceName

String interfaceName

Interface class name, default value is empty string

Default:

""

version

String version

Service version, default value is empty string

Default:

""

group

String group

Service group, default value is empty string

Default:

""

url

String url

Service target URL for direct invocation, if this is specified, then registry center takes no effect.

Default:

""

client

String client

Client transport type, default value is "netty"

Default:

""

generic

@Deprecated
boolean generic

Deprecated.

Do not need specify generic value, judge by injection type and interface class

Whether to enable generic invocation, default value is false

Default:

false

injvm

@Deprecated
boolean injvm

Deprecated.

using scope="local" or scope="remote" instead

When enable, prefer to call local service in the same JVM if it's present, default value is true

Default:

true

check

boolean check

Check if service provider is available during boot up, default value is true

Default:

true

init

boolean init

Whether eager initialize the reference bean when all properties are set, default value is true ( null as true)

See Also:

• ReferenceConfigBase.shouldInit()

Default:

true

lazy

boolean lazy

Whether to make connection when the client is created, the default value is false

Default:

false

stubevent

boolean stubevent

Export an stub service for event dispatch, default value is false.

see org.apache.dubbo.rpc.Constants#STUB_EVENT_METHODS_KEY

Default:

false

reconnect

String reconnect

Whether to reconnect if connection is lost, if not specify, reconnect is enabled by default, and the interval for retry connecting is 2000 ms

see org.apache.dubbo.remoting.Constants#DEFAULT_RECONNECT_PERIOD

Default:

""

sticky

boolean sticky

Whether to stick to the same node in the cluster, the default value is false

see Constants#DEFAULT_CLUSTER_STICKY

Default:

false

proxy

String proxy

How the proxy is generated, legal values include: jdk, javassist

Default:

""

stub

String stub

Service stub name, use interface name + Stub if not set

Default:

""

cluster

String cluster

Cluster strategy, legal values include: failover, failfast, failsafe, failback, forking you can use ClusterRules.FAIL_FAST ……

Default:

""

connections

int connections

Maximum connections service provider can accept, default value is 0 - connection is shared

Default:

-1

callbacks

int callbacks

The callback instance limit peer connection

see org.apache.dubbo.rpc.Constants#DEFAULT_CALLBACK_INSTANCES

Default:

-1

onconnect

String onconnect

Callback method name when connected, default value is empty string

Default:

""

ondisconnect

String ondisconnect

Callback method name when disconnected, default value is empty string

Default:

""

owner

String owner

Service owner, default value is empty string

Default:

""

layer

String layer

Service layer, default value is empty string

Default:

""

retries

int retries

Service invocation retry times

see Constants#DEFAULT_RETRIES

Default:

-1

loadbalance

String loadbalance

Load balance strategy, legal values include: random, roundrobin, leastactive you can use LoadbalanceRules.RANDOM ……

Default:

""

async

boolean async

Whether to enable async invocation, default value is false

Default:

false

actives

int actives

Maximum active requests allowed, default value is 0

Default:

-1

sent

boolean sent

Whether the async request has already been sent, the default value is false

Default:

false

mock

String mock

Service mock name, use interface name + Mock if not set

Default:

""

validation

String validation

Whether to use JSR303 validation, legal values are: true, false

Default:

""

timeout

int timeout

Timeout value for service invocation, default value is 0

Default:

-1

cache

String cache

Specify cache implementation for service invocation, legal values include: lru, threadlocal, jcache

Default:

""

filter

String[] filter

Filters for service invocation

see Filter

Default:

{}

listener

String[] listener

Listeners for service exporting and unexporting

see ExporterListener

Default:

{}

parameters

String[] parameters

Customized parameter key-value pair, for example: {key1, value1, key2, value2} or {"key1=value1", "key2=value2"}

Default:

{}

application

@Deprecated
String application

Deprecated.

This attribute was deprecated, use bind application/module of spring ApplicationContext

Application name

Default:

""

module

String module

Module associated name

Default:

""

consumer

String consumer

Consumer associated name

Default:

""

monitor

String monitor

Monitor associated name

Default:

""

registry

String[] registry

Registry associated name

Default:

{}

protocol

String protocol

The communication protocol of Dubbo Service

Returns:

the default value is ""

Since:

2.6.6

Default:

""

tag

String tag

Service tag name

Default:

""

merger

String merger

Service merger

Default:

""

methods

Method[] methods

methods support

Default:

{}

id

String id

The id NOTE: The id attribute is ignored when using @DubboReference on @Bean method

Returns:

default value is empty

Since:

2.7.3

Default:

""

services

@Deprecated
String[] services

Deprecated.

using providedBy()

Returns:

The service names that the Dubbo interface subscribed

Since:

2.7.8

See Also:

• RegistryConstants.SUBSCRIBED_SERVICE_NAMES_KEY

Default:

{}

providedBy

String[] providedBy

declares which app or service this interface belongs to

See Also:

• RegistryConstants.PROVIDED_BY

Default:

{}

providerPort

int providerPort

The service port of the provider

Since:

3.1.0

See Also:

• AbstractReferenceConfig.providerPort

Default:

-1

providerNamespace

String providerNamespace

assign the namespace that provider belong to

Since:

3.1.1

See Also:

• AbstractReferenceConfig.providerNamespace

Default:

""

scope

String scope

the scope for referring/exporting a service, if it's local, it means searching in current JVM only.

See Also:

• Constants.SCOPE_LOCAL
• Constants.SCOPE_REMOTE

Default:

""

referAsync

boolean referAsync

Weather the reference is refer asynchronously

Default:

false

unloadClusterRelated

boolean unloadClusterRelated

unload Cluster related in mesh mode

Since:

3.1.0

See Also:

• ReferenceConfigBase.unloadClusterRelated

Default:

false