CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-alibaba-nacos--nacos-client

Nacos client library for dynamic service discovery and configuration management in cloud native applications and microservices platforms

—

Pending
Overview
Eval results
Files

service-discovery.mddocs/

Service Discovery and Registration

Service registration, discovery, and health monitoring with support for weighted load balancing, cluster management, and real-time instance updates. Includes batch operations and event-driven programming model.

Capabilities

Service Registration

Register and deregister service instances with comprehensive metadata support.

public interface NamingService {
    // Register instance with service name, IP, and port
    void registerInstance(String serviceName, String ip, int port) throws NacosException;
    
    // Register instance with group specification
    void registerInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
    
    // Register instance object with full configuration
    void registerInstance(String serviceName, Instance instance) throws NacosException;
    
    // Register instance with group and instance object
    void registerInstance(String serviceName, String groupName, Instance instance) throws NacosException;
    
    // Batch register multiple instances
    void batchRegisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
    
    // Deregister instance by IP and port
    void deregisterInstance(String serviceName, String ip, int port) throws NacosException;
    
    // Deregister instance with group specification
    void deregisterInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
    
    // Deregister instance object
    void deregisterInstance(String serviceName, Instance instance) throws NacosException;
    
    // Deregister instance with group and instance object
    void deregisterInstance(String serviceName, String groupName, Instance instance) throws NacosException;
    
    // Batch deregister multiple instances
    void batchDeregisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
}

Usage Examples

import com.alibaba.nacos.api.naming.NamingService;
import com.alibaba.nacos.api.naming.NamingFactory;
import com.alibaba.nacos.api.naming.pojo.Instance;

// Create naming service
Properties props = new Properties();
props.setProperty("serverAddr", "localhost:8848");
NamingService namingService = NamingFactory.createNamingService(props);

// Simple registration
namingService.registerInstance("user-service", "192.168.1.100", 8080);

// Register with metadata
Instance instance = new Instance();
instance.setIp("192.168.1.100");
instance.setPort(8080);
instance.setWeight(2.0);
instance.setClusterName("beijing");
instance.setHealthy(true);
instance.setEnabled(true);
instance.setEphemeral(true);

// Add custom metadata
Map<String, String> metadata = new HashMap<>();
metadata.put("version", "1.0.0");
metadata.put("region", "us-west");
instance.setMetadata(metadata);

namingService.registerInstance("user-service", "PROD_GROUP", instance);

// Batch registration
List<Instance> instances = Arrays.asList(instance1, instance2, instance3);
namingService.batchRegisterInstance("user-service", "PROD_GROUP", instances);

// Batch deregistration
namingService.batchDeregisterInstance("user-service", "PROD_GROUP", instances);

Service Discovery

Discover service instances with filtering and selection capabilities.

public interface NamingService {
    // Get all instances of a service
    List<Instance> getAllInstances(String serviceName) throws NacosException;
    
    // Get all instances with group specification
    List<Instance> getAllInstances(String serviceName, String groupName) throws NacosException;
    
    // Get healthy or unhealthy instances
    List<Instance> getAllInstances(String serviceName, boolean healthy) throws NacosException;
    
    // Get instances from specific clusters
    List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;
    
    // Get all instances with full options
    List<Instance> getAllInstances(String serviceName, String groupName, List<String> clusters, boolean subscribe) throws NacosException;
    
    // Select healthy instances only
    List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
    
    // Select instances with group and health filter
    List<Instance> selectInstances(String serviceName, String groupName, boolean healthy) throws NacosException;
    
    // Select instances with cluster filter
    List<Instance> selectInstances(String serviceName, String groupName, List<String> clusters, boolean healthy) throws NacosException;
    
    // Select one healthy instance (load balancing)
    Instance selectOneHealthyInstance(String serviceName) throws NacosException;
    
    // Select one healthy instance with group
    Instance selectOneHealthyInstance(String serviceName, String groupName) throws NacosException;
    
    // Select one healthy instance from specific clusters
    Instance selectOneHealthyInstance(String serviceName, String groupName, List<String> clusters) throws NacosException;
}

Usage Examples

// Get all instances
List<Instance> allInstances = namingService.getAllInstances("user-service");

// Get healthy instances only
List<Instance> healthyInstances = namingService.selectInstances("user-service", true);

// Get instances from specific clusters
List<String> clusters = Arrays.asList("beijing", "shanghai");
List<Instance> clusterInstances = namingService.getAllInstances("user-service", clusters);

// Load balancing - select one healthy instance
Instance instance = namingService.selectOneHealthyInstance("user-service");
if (instance != null) {
    String serviceUrl = "http://" + instance.getIp() + ":" + instance.getPort();
    // Make HTTP call to service
}

// Advanced filtering with group and clusters
List<Instance> prodInstances = namingService.selectInstances(
    "user-service", 
    "PROD_GROUP", 
    Arrays.asList("us-west", "us-east"),
    true  // healthy only
);

Service Event Subscription

Real-time notifications of service instance changes through event listeners.

public interface NamingService {
    // Subscribe to service instance changes
    void subscribe(String serviceName, EventListener listener) throws NacosException;
    
    // Subscribe with group specification
    void subscribe(String serviceName, String groupName, EventListener listener) throws NacosException;
    
    // Subscribe with cluster filter
    void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
    
    // Subscribe with full options
    void subscribe(String serviceName, String groupName, List<String> clusters, EventListener listener) throws NacosException;
    
    // Unsubscribe from service changes
    void unsubscribe(String serviceName, EventListener listener) throws NacosException;
    
    // Unsubscribe with group
    void unsubscribe(String serviceName, String groupName, EventListener listener) throws NacosException;
    
    // Unsubscribe with clusters
    void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
    
    // Unsubscribe with full options
    void unsubscribe(String serviceName, String groupName, List<String> clusters, EventListener listener) throws NacosException;
}

// Event listener interface
public interface EventListener {
    void onEvent(Event event);
}

// Naming event containing service changes
public class NamingEvent extends Event {
    private String serviceName;
    private String groupName;
    private String clusters;
    private List<Instance> instances;
    
    public String getServiceName();
    public String getGroupName();
    public String getClusters();
    public List<Instance> getInstances();
}

Usage Examples

import com.alibaba.nacos.api.naming.listener.EventListener;
import com.alibaba.nacos.api.naming.listener.NamingEvent;

// Create event listener
EventListener listener = new EventListener() {
    @Override
    public void onEvent(Event event) {
        if (event instanceof NamingEvent) {
            NamingEvent namingEvent = (NamingEvent) event;
            System.out.println("Service changed: " + namingEvent.getServiceName());
            
            List<Instance> instances = namingEvent.getInstances();
            System.out.println("Current instances: " + instances.size());
            
            // Update local service registry
            updateLocalRegistry(namingEvent.getServiceName(), instances);
        }
    }
};

// Subscribe to service changes
namingService.subscribe("user-service", listener);

// Subscribe with cluster filter
namingService.subscribe("user-service", "PROD_GROUP", 
                       Arrays.asList("beijing", "shanghai"), listener);

Fuzzy Watching

Pattern-based service watching for monitoring multiple services with wildcards.

public interface NamingService {
    // Start fuzzy watching with group pattern only
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
    
    // Start fuzzy watching with both service and group patterns
    void fuzzyWatch(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
    
    // Start fuzzy watching and return matching service keys
    Future<ListView<String>> fuzzyWatchWithServiceKeys(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
    
    // Cancel fuzzy watching
    void cancelFuzzyWatch(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
}

// Fuzzy watch event watcher interface
public interface FuzzyWatchEventWatcher {
    // Handle set of naming events
    void onEvent(Set<NamingEvent> events);
}

Usage Examples

import com.alibaba.nacos.api.naming.listener.FuzzyWatchEventWatcher;

// Watch all microservices with pattern
FuzzyWatchEventWatcher watcher = new FuzzyWatchEventWatcher() {
    @Override
    public void onEvent(Set<NamingEvent> events) {
        for (NamingEvent event : events) {
            System.out.println("Service changed: " + event.getServiceName());
            updateServiceRegistry(event.getServiceName(), event.getInstances());
        }
    }
};

// Watch all services ending with "-service" in DEFAULT_GROUP
namingService.fuzzyWatch("*-service", "DEFAULT_GROUP", watcher);

// Watch all services in production group (group pattern only)
namingService.fuzzyWatch("PROD_GROUP", watcher);

// Watch all services in groups matching pattern
namingService.fuzzyWatch("*", "PROD_*", watcher);

Service Management

Service listing and metadata management operations.

public interface NamingService {
    // Get paginated list of services
    ListView<String> getServicesOfServer(int pageNo, int pageSize) throws NacosException;
    
    // Get services with group filter
    ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName) throws NacosException;
    
    // Get services with selector
    ListView<String> getServicesOfServer(int pageNo, int pageSize, AbstractSelector selector) throws NacosException;
    
    // Get services with full options
    ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName, AbstractSelector selector) throws NacosException;
    
    // Get all subscribed services of current client
    List<ServiceInfo> getSubscribeServices() throws NacosException;
    
    // Get server status
    String getServerStatus();
    
    // Shutdown service
    void shutDown() throws NacosException;
}

Types

Service Instance Model

public class Instance {
    private String instanceId;
    private String ip;
    private int port;
    private double weight;
    private boolean healthy;
    private boolean enabled;
    private boolean ephemeral;
    private String clusterName;
    private String serviceName;
    private Map<String, String> metadata;
    
    // Constructors
    public Instance();
    
    // Core properties
    public String getInstanceId();
    public void setInstanceId(String instanceId);
    
    public String getIp();
    public void setIp(String ip);
    
    public int getPort();
    public void setPort(int port);
    
    // Load balancing weight
    public double getWeight();
    public void setWeight(double weight);
    
    // Health and availability
    public boolean isHealthy();
    public void setHealthy(boolean healthy);
    
    public boolean isEnabled();
    public void setEnabled(boolean enabled);
    
    // Persistence mode
    public boolean isEphemeral();
    public void setEphemeral(boolean ephemeral);
    
    // Cluster assignment
    public String getClusterName();
    public void setClusterName(String clusterName);
    
    // Service association
    public String getServiceName();
    public void setServiceName(String serviceName);
    
    // Custom attributes
    public Map<String, String> getMetadata();
    public void setMetadata(Map<String, String> metadata);
    
    // Utility methods
    public String toInetAddr();
    public boolean containsMetadata(String key, String value);
}

Service Information

public class ServiceInfo {
    private String name;
    private String groupName;
    private String clusters;
    private List<Instance> hosts;
    private long cacheMillis;
    private long lastRefTime;
    private String checksum;
    private boolean allIPs;
    private boolean reachProtectionThreshold;
    
    // Service identification
    public String getName();
    public void setName(String name);
    
    public String getGroupName();
    public void setGroupName(String groupName);
    
    // Cluster information
    public String getClusters();
    public void setClusters(String clusters);
    
    // Instance list
    public List<Instance> getHosts();
    public void setHosts(List<Instance> hosts);
    
    // Caching and refresh
    public long getCacheMillis();
    public void setCacheMillis(long cacheMillis);
    
    public long getLastRefTime();
    public void setLastRefTime(long lastRefTime);
    
    // Validation and protection
    public String getChecksum();
    public boolean isReachProtectionThreshold();
    
    // Utility methods
    public String getKey();
    public String getKeyEncoded();
    public boolean validate();
}

Service and Cluster Models

public class Service {
    private String name;
    private String groupName;
    private String appName;
    private float protectThreshold;
    private Map<String, String> metadata;
    
    public String getName();
    public void setName(String name);
    
    public String getGroupName();
    public void setGroupName(String groupName);
    
    public String getAppName();
    public void setAppName(String appName);
    
    public float getProtectThreshold();
    public void setProtectThreshold(float protectThreshold);
    
    public Map<String, String> getMetadata();
    public void setMetadata(Map<String, String> metadata);
}

public class Cluster {
    private String name;
    private AbstractHealthChecker healthChecker;
    private int defaultPort;
    private int defaultCheckPort;
    private boolean useIPPort4Check;
    private Map<String, String> metadata;
    
    public String getName();
    public void setName(String name);
    
    public AbstractHealthChecker getHealthChecker();
    public void setHealthChecker(AbstractHealthChecker healthChecker);
    
    public int getDefaultPort();
    public void setDefaultPort(int defaultPort);
    
    public Map<String, String> getMetadata();
    public void setMetadata(Map<String, String> metadata);
}

Pagination and Selection

public class ListView<T> {
    private int count;
    private List<T> data;
    
    public int getCount();
    public void setCount(int count);
    
    public List<T> getData();
    public void setData(List<T> data);
}

// Abstract selector for filtering
public abstract class AbstractSelector {
    private String type;
    
    public String getType();
    public void setType(String type);
    
    public abstract String toJsonString();
}

// Expression-based selector
public class ExpressionSelector extends AbstractSelector {
    private String expression;
    
    public String getExpression();
    public void setExpression(String expression);
    
    @Override
    public String toJsonString();
}

Naming Utilities

public class NamingUtils {
    public static final String NAMING_INSTANCE_ID_SPLITTER = "#";
    public static final String DEFAULT_GROUP = "DEFAULT_GROUP";
    
    // Service name parsing
    public static String getServiceName(String serviceNameWithGroup);
    public static String getGroupName(String serviceNameWithGroup);
    public static String getGroupedName(String serviceName, String groupName);
    
    // Instance utilities
    public static String getInstanceId(Instance instance);
    
    // Validation
    public static void checkServiceName(String serviceName);
    public static void checkInstanceIsLegal(Instance instance);
}

Install with Tessl CLI

npx tessl i tessl/maven-com-alibaba-nacos--nacos-client

docs

configuration.md

distributed-locking.md

factory-utilities.md

index.md

service-discovery.md

tile.json