or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ai-mcp.mdconfiguration.mdcore-api.mdexceptions.mdindex.mdnaming.mdremote.md
tile.json

tessl/maven-com-alibaba-nacos--nacos-api

Nacos API package providing interfaces and common classes for dynamic service discovery, configuration management, and service management in cloud native applications and microservices

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.alibaba.nacos/nacos-api@3.0.x

To install, run

npx @tessl/cli install tessl/maven-com-alibaba-nacos--nacos-api@3.0.0

index.mddocs/

Nacos API

Nacos API is a comprehensive Java library that provides interfaces and common classes for dynamic service discovery, configuration management, and service management in cloud native applications and microservices. This package serves as the foundational layer for interacting with Nacos services through well-defined interfaces.

Package Information

  • Package Name: nacos-api
  • Package Type: maven
  • Group ID: com.alibaba.nacos
  • Language: Java
  • Version: 3.0.2
  • License: Apache-2.0
  • Installation:
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-api</artifactId>
    <version>3.0.2</version>
</dependency>

For Gradle:

implementation 'com.alibaba.nacos:nacos-api:3.0.2'

Core Imports

import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.naming.NamingService;
import com.alibaba.nacos.api.lock.LockService;
import com.alibaba.nacos.api.exception.NacosException;

Basic Usage

import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.naming.NamingService;
import com.alibaba.nacos.api.naming.pojo.Instance;
import java.util.Properties;

// Initialize Nacos services
Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
properties.setProperty(PropertyKeyConst.NAMESPACE, "public");

// Configuration management
ConfigService configService = NacosFactory.createConfigService(properties);
String config = configService.getConfig("myapp.properties", "DEFAULT_GROUP", 3000);
boolean published = configService.publishConfig("myapp.properties", "DEFAULT_GROUP", "key=value");

// Service discovery and registration
NamingService namingService = NacosFactory.createNamingService(properties);
namingService.registerInstance("my-service", "127.0.0.1", 8080);
List<Instance> instances = namingService.getAllInstances("my-service");

// Distributed locking
LockService lockService = NacosFactory.createLockService(properties);
LockInstance lock = new LockInstance();
lock.setLockName("my-distributed-lock");
boolean acquired = lockService.lock(lock);

Architecture

The Nacos API is built around several key architectural components:

  • Factory Pattern: NacosFactory provides centralized creation of all service instances
  • Service Interfaces: Clean separation between ConfigService, NamingService, and LockService
  • Event-Driven Model: Comprehensive listener system for configuration changes and service discovery events
  • Remote Communication: Built-in gRPC and HTTP support for client-server communication
  • Health Checking: Pluggable health check mechanisms (HTTP, TCP, MySQL)
  • Multi-tenancy: Namespace support for resource isolation
  • Exception Handling: Structured exception hierarchy with specific error codes

Capabilities

Core API and Factories

Central factory classes and property constants for creating and configuring Nacos services. Essential for initializing any Nacos functionality.

class NacosFactory {
    static ConfigService createConfigService(Properties properties) throws NacosException;
    static ConfigService createConfigService(String serverAddr) throws NacosException;
    static NamingService createNamingService(String serverAddr) throws NacosException;
    static NamingService createNamingService(Properties properties) throws NacosException;
    static LockService createLockService(Properties properties) throws NacosException;
}

class PropertyKeyConst {
    static final String SERVER_ADDR = "serverAddr";
    static final String NAMESPACE = "namespace";
    static final String USERNAME = "username";
    static final String PASSWORD = "password";
    static final String ACCESS_KEY = "accessKey";
    static final String SECRET_KEY = "secretKey";
    static final String CONTEXT_PATH = "contextPath";
    static final String CLUSTER_NAME = "clusterName";
}

Core API and Factory Classes

Configuration Management

Dynamic configuration management with real-time updates, listeners, and fuzzy watching capabilities. Perfect for application settings, feature flags, and environment-specific configurations.

interface ConfigService {
    String getConfig(String dataId, String group, long timeoutMs) throws NacosException;
    String getConfigAndSignListener(String dataId, String group, long timeoutMs, Listener listener) throws NacosException;
    boolean publishConfig(String dataId, String group, String content) throws NacosException;
    boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;
    boolean removeConfig(String dataId, String group) throws NacosException;
    void addListener(String dataId, String group, Listener listener) throws NacosException;
    void removeListener(String dataId, String group, Listener listener);
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher watcher) throws NacosException;
    void shutDown() throws NacosException;
}

interface Listener {
    Executor getExecutor();
    void receiveConfigInfo(String configInfo);
}

Configuration Management

Service Discovery and Naming

Service registration, discovery, and health monitoring with event-driven updates. Essential for microservices architectures and load balancing.

interface NamingService {
    void registerInstance(String serviceName, String ip, int port) throws NacosException;
    void registerInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
    void registerInstance(String serviceName, Instance instance) throws NacosException;
    void deregisterInstance(String serviceName, String ip, int port) throws NacosException;
    List<Instance> getAllInstances(String serviceName) throws NacosException;
    List<Instance> getAllInstances(String serviceName, String groupName) throws NacosException;
    List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
    Instance selectOneHealthyInstance(String serviceName) throws NacosException;
    void subscribe(String serviceName, EventListener listener) throws NacosException;
    void unsubscribe(String serviceName, EventListener listener) throws NacosException;
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
    void shutDown() throws NacosException;
}

class Instance {
    String instanceId;
    String ip;
    int port;
    double weight;
    boolean healthy;
    boolean enabled;
    boolean ephemeral;
    String clusterName;
    String serviceName;
    Map<String, String> metadata;
}

Service Discovery and Naming

Remote Communication

Low-level remote communication infrastructure including gRPC support, request/response handling, and connection management.

abstract class Request implements Payload {
    void putHeader(String key, String value);
    void putAllHeader(Map<String, String> headers);
    String getHeader(String key);
    String getRequestId();
    void setRequestId(String requestId);
}

abstract class Response implements Payload {
    boolean isSuccess();
    int getResultCode();
    void setResultCode(int resultCode);
    int getErrorCode();
    void setErrorCode(int errorCode);
    String getMessage();
    void setMessage(String message);
}

interface RequestCallBack<T extends Response> {
    void onResponse(T response);
    void onException(Throwable e);
}

Remote Communication

AI and Model Context Protocol (MCP) Integration

Advanced AI integration capabilities including Model Context Protocol (MCP) server management, tool specifications, and service discovery integration for AI agents.

class McpTool {
    String name;
    String description;
    Map<String, Object> inputSchema;
    
    String getName();
    void setName(String name);
    String getDescription();
    void setDescription(String description);
    Map<String, Object> getInputSchema();
    void setInputSchema(Map<String, Object> inputSchema);
}

class McpServiceRef {
    String namespaceId;
    String groupName;
    String serviceName;
    
    String getNamespaceId();
    void setNamespaceId(String namespaceId);
    String getGroupName();
    void setGroupName(String groupName);
    String getServiceName();
    void setServiceName(String serviceName);
}

class AiConstants.Mcp {
    static final String MCP_DEFAULT_NAMESPACE = "public";
    static final String MCP_PROTOCOL_STDIO = "stdio";
    static final String MCP_PROTOCOL_SSE = "mcp-sse";
    static final String MCP_PROTOCOL_HTTP = "http";
    static final String MCP_PROTOCOL_DUBBO = "dubbo";
}

AI and Model Context Protocol Integration

Exception Handling

Comprehensive exception hierarchy with specific error codes and handling patterns for robust error management.

class NacosException extends Exception {
    NacosException();
    NacosException(int errCode, String errMsg);
    NacosException(int errCode, Throwable throwable);
    NacosException(int errCode, String errMsg, Throwable throwable);
    
    int getErrCode();
    String getErrMsg();
    void setErrCode(int errCode);
    void setErrMsg(String errMsg);
    
    // Client error codes
    static final int CLIENT_INVALID_PARAM = -400;
    static final int CLIENT_DISCONNECT = -401;
    static final int CLIENT_OVER_THRESHOLD = -503;
    
    // Server error codes
    static final int INVALID_PARAM = 400;
    static final int NO_RIGHT = 403;
    static final int NOT_FOUND = 404;
    static final int CONFLICT = 409;
    static final int SERVER_ERROR = 500;
    static final int BAD_GATEWAY = 502;
    static final int OVER_THRESHOLD = 503;
}

Exception Handling

Common Constants

class Constants {
    static final String CLIENT_VERSION = "3.0.0";
    static final String DEFAULT_GROUP = "DEFAULT_GROUP";
    static final String DEFAULT_CLUSTER_NAME = "DEFAULT";
    static final String DEFAULT_NAMESPACE_ID = "public";
    static final long DEFAULT_HEART_BEAT_TIMEOUT = 15000;
    static final long DEFAULT_HEART_BEAT_INTERVAL = 5000;
    static final int POLLING_INTERVAL_TIME = 15;
    static final int CONFIG_LONG_POLL_TIMEOUT = 30000;
    static final int MAX_RETRY = 3;
}

enum ConfigType {
    UNSET, TEXT, JSON, XML, YAML, HTML, PROPERTIES;
}

enum PropertyChangeType {
    ADDED, MODIFIED, DELETED;
}

Utility Classes

class StringUtils {
    static boolean isEmpty(String str);
    static boolean isNotEmpty(String str);
    static boolean isBlank(String str);
    static boolean isNotBlank(String str);
}

class NamingUtils {
    static boolean isNumber(String str);
    static String getGroupedName(String serviceName, String groupName);
    static String[] getGroupAndServiceName(String serviceName);
}