org.apache.dubbo.registry.client

Interface ServiceDiscovery

All Superinterfaces:

Comparable<Prioritized>, Prioritized

All Known Implementing Classes:

FileSystemServiceDiscovery

@SPI(value="zookeeper")
public interface ServiceDiscovery
extends Prioritized

The common operations of Service Discovery

Since:

2.7.5

Field Summary

Fields inherited from interface org.apache.dubbo.common.lang.Prioritized

COMPARATOR, MAX_PRIORITY, MIN_PRIORITY, NORMAL_PRIORITY

Method Summary

Modifier and Type	Method and Description
default void	addServiceInstancesChangedListener(ServiceInstancesChangedListener listener) Add an instance of ServiceInstancesChangedListener for specified service
void	destroy() Destroy the ServiceDiscovery
default void	dispatchServiceInstancesChangedEvent(ServiceInstancesChangedEvent event) Dispatch the ServiceInstancesChangedEvent
default void	dispatchServiceInstancesChangedEvent(String serviceName) Dispatch the ServiceInstancesChangedEvent
default void	dispatchServiceInstancesChangedEvent(String serviceName, Collection<ServiceInstance> serviceInstances) Dispatch the ServiceInstancesChangedEvent
default void	dispatchServiceInstancesChangedEvent(String serviceName, String... otherServiceNames) Dispatch the ServiceInstancesChangedEvent
default int	getDefaultPageSize() Get the default size of pagination query
default Map<String,Page<ServiceInstance>>	getInstances(Iterable<String> serviceNames, int offset, int requestSize) batch-get all service instances by the specified service names
default List<ServiceInstance>	getInstances(String serviceName) Gets all service instances by the specified service name.
default Page<ServiceInstance>	getInstances(String serviceName, int offset, int pageSize) Gets the pagination of service instances by the specified service name.
default Page<ServiceInstance>	getInstances(String serviceName, int offset, int pageSize, boolean healthyOnly) Get the pagination of service instances by the specified service name.
Set<String>	getServices() Gets all service names
void	initialize(URL registryURL) Initializes the ServiceDiscovery
void	register(ServiceInstance serviceInstance) Registers an instance of ServiceInstance.
String	toString() A human-readable description of the implementation
void	unregister(ServiceInstance serviceInstance) Unregisters an instance of ServiceInstance.
void	update(ServiceInstance serviceInstance) Updates the registered ServiceInstance.

Methods inherited from interface org.apache.dubbo.common.lang.Prioritized

compareTo, getPriority

Method Detail

initialize

void initialize(URL registryURL)
         throws Exception

Initializes the ServiceDiscovery

Parameters:

registryURL - the url to connect service registry

Throws:

Exception - If met with error

destroy

void destroy()
      throws Exception

Destroy the ServiceDiscovery

Throws:

Exception - If met with error

register

void register(ServiceInstance serviceInstance)
       throws RuntimeException

Registers an instance of ServiceInstance.

Parameters:

serviceInstance - an instance of ServiceInstance to be registered

Throws:

RuntimeException - if failed

update

void update(ServiceInstance serviceInstance)
     throws RuntimeException

Updates the registered ServiceInstance.

Parameters:

serviceInstance - the registered ServiceInstance

Throws:

RuntimeException - if failed

unregister

void unregister(ServiceInstance serviceInstance)
         throws RuntimeException

Unregisters an instance of ServiceInstance.

Parameters:

serviceInstance - an instance of ServiceInstance to be deregistered

Throws:

RuntimeException - if failed

getDefaultPageSize

default int getDefaultPageSize()

Get the default size of pagination query

Returns:

the default value is 100

getServices

Set<String> getServices()

Gets all service names

Returns:

non-null read-only Set

getInstances

default List<ServiceInstance> getInstances(String serviceName)
                                    throws NullPointerException

Gets all service instances by the specified service name.

Parameters:

serviceName - the service name

Returns:

non-null List

Throws:

NullPointerException - if serviceName is null is null

getInstances

default Page<ServiceInstance> getInstances(String serviceName,
                                           int offset,
                                           int pageSize)
                                    throws NullPointerException,
                                           IllegalArgumentException

Gets the pagination of service instances by the specified service name. It's equal to getInstances(String, int, int, boolean) with healthyOnly == true

Parameters:

serviceName - the service name

offset - the offset of request , the number "0" indicates first page

pageSize - the number of request, the max value indicates the range is unlimited

Returns:

non-null Page object

Throws:

NullPointerException - if serviceName is null is null

IllegalArgumentException - if offset or pageSize is negative number

UnsupportedOperationException - if not supported

getInstances

default Page<ServiceInstance> getInstances(String serviceName,
                                           int offset,
                                           int pageSize,
                                           boolean healthyOnly)
                                    throws NullPointerException,
                                           IllegalArgumentException,
                                           UnsupportedOperationException

Get the pagination of service instances by the specified service name. If healthyOnly == true, filter healthy instances only.

Parameters:

serviceName - the service name

offset - the offset of request , the number "0" indicates first page

pageSize - the number of request, the max value indicates the range is unlimited

healthyOnly - if true , filter healthy instances only

Returns:

non-null Page object

Throws:

NullPointerException - if serviceName is null is null

IllegalArgumentException - if offset or pageSize is negative number

UnsupportedOperationException - if not supported

getInstances

default Map<String,Page<ServiceInstance>> getInstances(Iterable<String> serviceNames,
                                                       int offset,
                                                       int requestSize)
                                                throws NullPointerException,
                                                       IllegalArgumentException

batch-get all service instances by the specified service names

Parameters:

serviceNames - the multiple service names

offset - the offset of request , the number "0" indicates first page

requestSize - the number of request, the max value indicates the range is unlimited

Returns:

non-null read-only Map whose key is the service name and value is the pagination of service instances

Throws:

NullPointerException - if serviceName is null is null

IllegalArgumentException - if offset or requestSize is negative number

UnsupportedOperationException - if not supported

addServiceInstancesChangedListener

default void addServiceInstancesChangedListener(ServiceInstancesChangedListener listener)
                                         throws NullPointerException,
                                                IllegalArgumentException

Add an instance of ServiceInstancesChangedListener for specified service

Default, Current method will be invoked by the ServiceDiscoveryRegistry on the subscription, and it's mandatory to add the ServiceInstancesChangedListener argument into EventDispatcher whether the subclass implements same approach or not, thus this method is used to trigger or adapt the vendor's change notification mechanism typically, like Zookeeper Watcher, Nacos EventListener. If the registry observes the change, It's suggested that the implementation could invoke dispatchServiceInstancesChangedEvent(String) method or variants

Parameters:

listener - an instance of ServiceInstancesChangedListener

Throws:

NullPointerException

IllegalArgumentException

See Also:

EventPublishingServiceDiscovery, EventDispatcher

dispatchServiceInstancesChangedEvent

default void dispatchServiceInstancesChangedEvent(String serviceName)

Dispatch the ServiceInstancesChangedEvent

Parameters:

serviceName - the name of service whose service instances have been changed

dispatchServiceInstancesChangedEvent

default void dispatchServiceInstancesChangedEvent(String serviceName,
                                                  String... otherServiceNames)

Dispatch the ServiceInstancesChangedEvent

Parameters:

serviceName - the name of service whose service instances have been changed

otherServiceNames - the names of other services

dispatchServiceInstancesChangedEvent

default void dispatchServiceInstancesChangedEvent(String serviceName,
                                                  Collection<ServiceInstance> serviceInstances)

Dispatch the ServiceInstancesChangedEvent

Parameters:

serviceName - the name of service whose service instances have been changed

serviceInstances - the service instances have been changed

dispatchServiceInstancesChangedEvent

default void dispatchServiceInstancesChangedEvent(ServiceInstancesChangedEvent event)

Dispatch the ServiceInstancesChangedEvent

Parameters:

event - the ServiceInstancesChangedEvent

toString

String toString()

A human-readable description of the implementation

Overrides:

toString in class Object

Returns:

The description.