[ Web Proxy ]
URL:
Viewing: https://ignite.apache.org/docs/latest/binary-client-protocol/binary-client-protocol [Back]  [Original]

Binary Client Protocol | Ignite Documentation
menu icon [menu icon]
Apache Ignite logo [Apache Ignite logo]
2.18.0 Ignite 3
  • Documentation Overview
  • Quick Start Guidesleft-nav-arrow.svg [left-nav-arrow.svg]
  • Java
  • .NET/C#
  • C++
  • Python
  • Node.JS
  • SQL
  • PHP
  • REST API
  • Installationleft-nav-arrow.svg [left-nav-arrow.svg]
  • Installing Using ZIP Archive
  • Installing Using Docker
  • Installing DEB or RPM package
  • Kubernetesleft-nav-arrow.svg [left-nav-arrow.svg]
  • Amazon EKS
  • Azure Kubernetes Service
  • Google Kubernetes Engine
  • VMWare
  • Version Upgrade
  • Setting Upleft-nav-arrow.svg [left-nav-arrow.svg]
  • Understanding Configuration
  • Setting Up
  • Configuring Logging
  • Resources Injection
  • Starting and Stopping Nodes
  • Clusteringleft-nav-arrow.svg [left-nav-arrow.svg]
  • Overview
  • TCP/IP Discovery
  • ZooKeeper Discovery
  • Discovery in the Cloud
  • Network Configuration
  • Connecting Client Nodes
  • Baseline Topology
  • Running Client Nodes Behind NAT
  • Thin Clientsleft-nav-arrow.svg [left-nav-arrow.svg]
  • Thin Clients Overview
  • Java Thin Client
  • .NET Thin Client
  • C++ Thin Client
  • Python Thin Client
  • PHP Thin Client
  • Node.js Thin Client
  • Binary Client Protocolleft-nav-arrow.svg [left-nav-arrow.svg]
  • Binary Client Protocol
  • Data Format
  • Key-Value Queries
  • SQL and Scan Queries
  • Binary Types Metadata
  • Cache Configuration
  • Data Modelingleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Data Partitioning
  • Affinity Colocation
  • Binary Marshaller
  • Configuring Memoryleft-nav-arrow.svg [left-nav-arrow.svg]
  • Memory Architecture
  • Configuring Data Regions
  • Eviction Policies
  • Replacement Policies
  • Configuring Persistenceleft-nav-arrow.svg [left-nav-arrow.svg]
  • Ignite Persistence
  • External Storage
  • Swapping
  • Implementing Custom Cache Store
  • Configuring Snapshot Directory
  • Disk Compression
  • Tuning Persistence
  • Change Data Capture
  • Cluster Snapshots
  • Configuring Cachesleft-nav-arrow.svg [left-nav-arrow.svg]
  • Cache Configuration
  • Configuring Partition Backups
  • Partition Loss Policy
  • Atomicity Modes
  • Expiry Policy
  • On-Heap Caching
  • Cache Groups
  • Near Caches
  • Data Rebalancing
  • Data Streaming
  • Using Key-Value APIleft-nav-arrow.svg [left-nav-arrow.svg]
  • Basic Cache Operations
  • Working with Binary Objects
  • Using Cache Queries
  • Read Repair
  • Performing Transactions
  • Working with SQLleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Understanding Schemas
  • Defining Indexes
  • Using SQL API
  • Distributed Joins
  • Custom SQL Functions
  • JDBC Driver
  • JDBC Client Driver
  • ODBC Driverleft-nav-arrow.svg [left-nav-arrow.svg]
  • ODBC Driver
  • Connection String and DSN
  • Querying and Modifying Data
  • Specification
  • Data Types
  • Error Codes
  • SQL Statistics
  • Calcite-based SQL Engine
  • SQL Referenceleft-nav-arrow.svg [left-nav-arrow.svg]
  • SQL Conformance
  • Data Definition Language (DDL)
  • Data Manipulation Language (DML)
  • Transaction-aware Queries
  • Operational Commands
  • Aggregate functions
  • Numeric Functions
  • String Functions
  • Data and Time Functions
  • System Functions
  • Data Types
  • Optimizer Hints
  • Distributed Computingleft-nav-arrow.svg [left-nav-arrow.svg]
  • Distributed Computing API
  • Cluster Groups
  • Executor Service
  • MapReduce API
  • Load Balancing
  • Fault Tolerance
  • Job Scheduling
  • Colocating Computations with Data
  • Code Deploymentleft-nav-arrow.svg [left-nav-arrow.svg]
  • Deploying User Code
  • Peer Class Loading
  • Machine Learningleft-nav-arrow.svg [left-nav-arrow.svg]
  • Machine Learning
  • Partition Based Dataset
  • Updating Trained Models
  • Binary Classificationleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Linear SVM (Support Vector Machine)
  • Decision Trees
  • Multilayer Perceptron
  • Logistic Regression
  • k-NN Classification
  • ANN (Approximate Nearest Neighbor)
  • Naive Bayes
  • Regressionleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Linear Regression
  • Decision Trees Regression
  • k-NN Regression
  • Clusteringleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • K-Means Clustering
  • Gaussian mixture (GMM)
  • Preprocessing
  • Model Selectionleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Evaluator
  • Split the dataset on test and train datasets
  • Hyper-parameter tuning
  • Pipeline API
  • Multiclass Classification
  • Ensemble Methodsleft-nav-arrow.svg [left-nav-arrow.svg]
  • Stacking
  • Bagging
  • Random Forest
  • Gradient Boosting
  • Recommendation Systems
  • Importing Modelleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Import Model from XGBoost
  • Import Model from Apache Spark
  • Using Continuous Queries
  • Using Ignite Services
  • Using Ignite Messaging
  • Distributed Data Structuresleft-nav-arrow.svg [left-nav-arrow.svg]
  • Queue and Set
  • Atomic Types
  • CountDownLatch
  • Semaphore
  • ID Generator
  • Distributed Locks
  • Session Context
  • REST API
  • .NET Specificleft-nav-arrow.svg [left-nav-arrow.svg]
  • Configuration Options
  • Deployment Options
  • Standalone Nodes
  • Asynchronous APIs
  • Logging
  • LINQ
  • Java Services Execution
  • .NET Platform Cache
  • Plugins
  • Serialization
  • Cross-Platform Support
  • Platform Interoperability
  • Remote Assembly Loading
  • Troubleshooting
  • Integrationsleft-nav-arrow.svg [left-nav-arrow.svg]
  • ASP.NET Output Caching
  • ASP.NET Session State Caching
  • Entity Framework 2nd Level Cache
  • C++ Specificleft-nav-arrow.svg [left-nav-arrow.svg]
  • Serialization
  • Platform Interoperability
  • Objects Lifetime
  • Monitoringleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Cluster ID and Tag
  • Cluster States
  • Metrics Systemleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Configuring Metrics
  • Metrics
  • Custom Metrics
  • System Views
  • Performance Statistics
  • Tracing
  • Working with Eventsleft-nav-arrow.svg [left-nav-arrow.svg]
  • Enabling and Listenting to Events
  • Events
  • Toolsleft-nav-arrow.svg [left-nav-arrow.svg]
  • Control Script
  • GridGain Control Center
  • Platform V Grid Center
  • SQLLine
  • Tableau
  • Informatica
  • Pentaho
  • Index Reader
  • Securityleft-nav-arrow.svg [left-nav-arrow.svg]
  • Security Model
  • Authentication
  • SSL/TLS
  • Transparent Data Encryptionleft-nav-arrow.svg [left-nav-arrow.svg]
  • Introduction
  • Master key rotation
  • Cache encryption key rotation
  • Sandbox
  • Extensions and Integrationsleft-nav-arrow.svg [left-nav-arrow.svg]
  • Springleft-nav-arrow.svg [left-nav-arrow.svg]
  • Spring Boot
  • Spring Data
  • Spring Caching
  • Spring Transactions
  • Ignite for Sparkleft-nav-arrow.svg [left-nav-arrow.svg]
  • Overview
  • IgniteContext and IgniteRDD
  • Ignite DataFrame
  • Installation
  • Test Ignite with Spark-shell
  • Troubleshooting
  • MyBatis L2 Cache
  • Streamingleft-nav-arrow.svg [left-nav-arrow.svg]
  • Kafka Streamer
  • Camel Streamer
  • Flink Streamer
  • Flume Sink
  • JMS Streamer
  • MQTT Streamer
  • RocketMQ Streamer
  • Storm Streamer
  • ZeroMQ Streamer
  • Twitter Streamer
  • Cassandra Integrationleft-nav-arrow.svg [left-nav-arrow.svg]
  • Overview
  • Configuration
  • Usage Examples
  • DDL Generator
  • Change Data Captureleft-nav-arrow.svg [left-nav-arrow.svg]
  • Overview
  • Ignite to Ignite Replication
  • Ignite to Kafka Replication
  • Ignite to PostgreSQL Replication
  • PHP PDO
  • Performance Statistics
  • ZooKeeper IP Finder
  • Plugins
  • Performance and Troubleshootingleft-nav-arrow.svg [left-nav-arrow.svg]
  • General Performance Tips
  • Memory and JVM Tuning
  • Persistence Tuning
  • SQL Tuning
  • Thread Pools Tuning
  • Troubleshooting and Debugging
  • Handling Exceptions
  • Benchmarking With Yardstick
  • Edit

    Binary Client Protocol

    Overview

    Ignite binary client protocol enables user applications to communicate with an existing Ignite cluster without starting a full-fledged Ignite node. An application can connect to the cluster through a raw TCP socket. Once the connection is established, the application can communicate with the Ignite cluster and perform cache operations using the established format.

    To communicate with the Ignite cluster, a client must obey the data format and communication details explained below.

    Data Format

    Byte Ordering

    Ignite binary client protocol has little-endian byte ordering.

    Data Objects

    User data, such as cache keys and values, are represented in the Ignite Binary Object format. A data object can be a standard (predefined) type or a complex object. For the complete list of data types supported, see the Data Format section.

    Message Format

    All messages- requests and responses, including handshake, start with an int type message length (excluding these first 4 bytes) followed by the payload (message body).

    Handshake

    The binary client protocol requires a connection handshake to ensure that client and server versions are compatible. The following tables show the structure of handshake message request and response. Refer to the Example section on how to send and receive a handshake request and response respectively.

    Request Type Description

    int

    Length of handshake payload

    byte

    Handshake code, always 1.

    short

    Version major.

    short

    Version minor.

    short

    Version patch.

    byte

    Client code, always 2.

    String

    Username

    String

    Password

    Response Type (success) Description

    int

    Success message length, 1.

    byte

    Success flag, 1.

    Response Type (failure) Description

    int

    Error message length.

    byte

    Success flag, 0.

    short

    Server version major.

    short

    Server version minor.

    short

    Server version patch.

    String

    Error message.

    Standard Message Header

    Client operation messages are composed of a header and operation-specific data. Each operation has its own data request and response format, with a common header.

    The following tables and examples show the request and response structure of a client operation message header:

    Request Type Description

    int

    Length of payload.

    short

    Operation code

    long

    Request id, generated by client and returned as-is in response

    Request header
    private static void writeRequestHeader(int reqLength, short opCode, long reqId, DataOutputStream out) throws IOException {
      // Message length
      writeIntLittleEndian(10 + reqLength, out);
    
      // Op code
      writeShortLittleEndian(opCode, out);
    
      // Request id
      writeLongLittleEndian(reqId, out);
    }
    Response Type Description

    int

    Length of response message.

    long

    Request id (see above)

    int

    Status code (0 for success, otherwise error code)

    String

    Error message (present only when status is not 0)

    Response header
    private static void readResponseHeader(DataInputStream in) throws IOException {
      // Response length
      final int len = readIntLittleEndian(in);
    
      // Request id
      long resReqId = readLongLittleEndian(in);
    
      // Success code
      int statusCode = readIntLittleEndian(in);
    }

    Connectivity

    TCP Socket

    Client applications should connect to server nodes with a TCP socket. By default, the connector is enabled on port 10800. You can configure the port number and other server-side connection parameters in the clientConnectorConfiguration property of IgniteConfiguration of your cluster, as shown below:

    <bean id="ignite.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
        <!-- Thin client connection configuration. -->
        <property name="clientConnectorConfiguration">
            <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
                <property name="host" value="127.0.0.1"/>
                <property name="port" value="10900"/>
                <property name="portRange" value="30"/>
            </bean>
        </property>
    
        <!-- Other Ignite Configurations. -->
    
    </bean>
    IgniteConfiguration cfg = new IgniteConfiguration();
    
    ClientConnectorConfiguration ccfg = new ClientConnectorConfiguration();
    ccfg.setHost("127.0.0.1");
    ccfg.setPort(10900);
    ccfg.setPortRange(30);
    
    // Set client connection configuration in IgniteConfiguration
    cfg.setClientConnectorConfiguration(ccfg);
    
    // Start Ignite node
    Ignition.start(cfg);

    Connection Handshake

    Besides socket connection, the thin client protocol requires a connection handshake to ensure that client and server versions are compatible. Note that handshake must be the first message after the connection is established.

    For the handshake message request and response structure, see the Handshake section above.

    Example

    Socket and Handshake Connection
    Socket socket = new Socket();
    socket.connect(new InetSocketAddress("127.0.0.1", 10800));
    
    String username = "yourUsername";
    
    String password = "yourPassword";
    
    DataOutputStream out = new DataOutputStream(socket.getOutputStream());
    
    // Message length
    writeIntLittleEndian(18 + username.length() + password.length(), out);
    
    // Handshake operation
    writeByteLittleEndian(1, out);
    
    // Protocol version 1.0.0
    writeShortLittleEndian(1, out);
    writeShortLittleEndian(1, out);
    writeShortLittleEndian(0, out);
    
    // Client code: thin client
    writeByteLittleEndian(2, out);
    
    // username
    writeString(username, out);
    
    // password
    writeString(password, out);
    
    // send request
    out.flush();
    
    // Receive handshake response
    DataInputStream in = new DataInputStream(socket.getInputStream());
    int length = readIntLittleEndian(in);
    int successFlag = readByteLittleEndian(in);
    
    // Since Ignite binary protocol uses little-endian byte order,
    // we need to implement big-endian to little-endian
    // conversion methods for write and read.
    
    // Write int in little-endian byte order
    private static void writeIntLittleEndian(int v, DataOutputStream out) throws IOException {
      out.write((v >>> 0) & 0xFF);
      out.write((v >>> 8) & 0xFF);
      out.write((v >>> 16) & 0xFF);
      out.write((v >>> 24) & 0xFF);
    }
    
    // Write short in little-endian byte order
    private static final void writeShortLittleEndian(int v, DataOutputStream out) throws IOException {
      out.write((v >>> 0) & 0xFF);
      out.write((v >>> 8) & 0xFF);
    }
    
    // Write byte in little-endian byte order
    private static void writeByteLittleEndian(int v, DataOutputStream out) throws IOException {
      out.writeByte(v);
    }
    
    // Read int in little-endian byte order
    private static int readIntLittleEndian(DataInputStream in) throws IOException {
      int ch1 = in.read();
      int ch2 = in.read();
      int ch3 = in.read();
      int ch4 = in.read();
      if ((ch1 | ch2 | ch3 | ch4) < 0)
        throw new EOFException();
      return ((ch4 << 24) + (ch3 << 16) + (ch2 << 8) + (ch1 << 0));
    }
    
    
    // Read byte in little-endian byte order
    private static byte readByteLittleEndian(DataInputStream in) throws IOException {
      return in.readByte();
    }
    
    // Other write and read methods

    Client Operations

    Upon successful handshake, a client can start performing various cache operations:


    Web Proxy Viewer  |  New URL  |  Original Page