Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add selector document #381

Merged
merged 1 commit into from
Sep 26, 2023
Merged

Add selector document #381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/en-us/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -589,6 +589,8 @@ Listen for changes of instances under a service.
void subscribe(String serviceName, EventListener listener) throws NacosException;

void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

void subscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;
```

#### Request Parameters
Expand All @@ -597,12 +599,15 @@ void subscribe(String serviceName, List<String> clusters, EventListener listener
| :--- | :--- | --- |
| serviceName | String | service name |
| clusters | List | cluster list |
| selector | NamingSelector | instance selector |
| listener | EventListener | event listener |

#### Response
void

#### Request Example
Listen for changes in the instance list of a service.

```java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3", event -> {
Expand All @@ -613,13 +618,55 @@ naming.subscribe("nacos.test.3", event -> {
});
```

Listen for changes in the instance list in some clusters.
```java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3", Arrays.asList("a","b","c"), event -> {
// ...
});
```

Listen for changes in the list of instances that use a selector,such as listening for instances matching an IP rule.`NamingSelectorFactory` provides selectors that match instances based on IP, cluster, metadata, health, and so on. You can also implement the `NamingSelector` interface as needed.
``` Java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3",
NamingSelectorFactory.newIpSelector("^172\\.18\\.137.*"),
event -> {
// ...
});
```
To obtain information about changed instances, you can cast `Event` to `NamingChangeEvent` or directly use AbstractNamingChangeListener.
``` Java
naming.subscribe("nacos.test.3", new AbstractNamingChangeListener() {
@Override
public void onChange(NamingChangeEvent event) {
// get current instances
List<Instance> curIns = event.getInstances();
if (event.isAdded()) {
// get the new instances
List<Instance> addedIns = event.getAddedInstances();
}
if (event.isRemoved()) {
// get the removed instances
List<Instance> removedIns = event.getRemovedInstances();
}
if (event.isModified()) {
// get the modified instance
List<Instance> modifiedIns = event.getModifiedInstances();
}
}
});
```

### Unlisten Service
#### Description
Cancel listening service.
```java
void unsubscribe(String serviceName, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;
```

#### Request Parameters
Expand All @@ -628,6 +675,7 @@ void unsubscribe(String serviceName, List<String> clusters, EventListener listen
| :--- | :--- | --- |
| serviceName | String | service name |
| clusters | List | cluster list |
| selector | NamingSelector | instance selector |
| listener | EventListener | event listener |

#### Response
Expand All @@ -638,3 +686,4 @@ void
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.unsubscribe("nacos.test.3", event -> {});
```
> To unsubscribe from a selector, you need to pass the `NamingSelector` and `EventListener` that were used to initiate the subscription as parameters.
50 changes: 49 additions & 1 deletion docs/zh-cn/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,8 @@ System.out.println(naming.selectOneHealthyInstance("nacos.test.3"));
void subscribe(String serviceName, EventListener listener) throws NacosException;

void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

void subscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;
```

#### 请求参数
Expand All @@ -491,12 +493,14 @@ void subscribe(String serviceName, List<String> clusters, EventListener listener
| :--- | :--- | --- |
| serviceName | 字符串 | 服务名 |
| clusters | List | 集群列表 |
| selector | NamingSelector | 选择器 |
| listener | EventListener | 回调listener |

#### 返回参数
无

#### 请求示例
监听某个服务下的实例列表变化。
```java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3", event -> {
Expand All @@ -507,13 +511,56 @@ naming.subscribe("nacos.test.3", event -> {
});
```

监听某些集群下的实例列表变化。
```java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3", Arrays.asList("a","b","c"), event -> {
// ...
});
```

监听某个选择器下的实例列表变化，比如监听匹配某个IP规则下的实例。`NamingSelectorFactory`提供了根据IP、集群、元数据、健康情况等条件匹配实例的选择器。用户也可以根据需要实现`NamingSelector`接口。
``` Java
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3",
NamingSelectorFactory.newIpSelector("^172\\.18\\.137.*"),
event -> {
// ...
});
```

如果用户想要获得发生变化的实例信息，可以将`Event`转为`NamingChangeEvent`或者直接使用`AbstractNamingChangeListener`。
``` Java
naming.subscribe("nacos.test.3", new AbstractNamingChangeListener() {
@Override
public void onChange(NamingChangeEvent event) {
// 获取当前实例
List<Instance> curIns = event.getInstances();
if (event.isAdded()) {
// 获取新增的实例
List<Instance> addedIns = event.getAddedInstances();
}
if (event.isRemoved()) {
// 获取移除的实例
List<Instance> removedIns = event.getRemovedInstances();
}
if (event.isModified()) {
// 获取修改的实例
List<Instance> modifiedIns = event.getModifiedInstances();
}
}
});
```

### 取消监听服务
#### 描述
取消监听服务下的实例列表变化。
```java
void unsubscribe(String serviceName, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;
```

#### 请求参数
Expand All @@ -522,6 +569,7 @@ void unsubscribe(String serviceName, List<String> clusters, EventListener listen
| :--- | :--- | --- |
| serviceName | 字符串 | 服务名 |
| clusters | List | 集群列表 |
| selector | NamingSelector | 选择器 |
| listener | EventListener | 回调listener |

#### 返回参数
Expand All @@ -532,5 +580,5 @@ void unsubscribe(String serviceName, List<String> clusters, EventListener listen

NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.unsubscribe("nacos.test.3", event -> {});

```
> 取消某个选择器下的订阅时，要传入发起订阅时使用的`NamingSelector`和`EventListener`。