[TDR Generic Table][Java SDK] Insert a Record

1. Interface Description

Insert new data into a specified table.

When data with the same Key already exists in the table, the data insertion will fail.

2. Version Requirements

This interface is provided in all versions without special requirements.

3. Preparations

Refer to Preparation document to complete the preparation before using this interface and create the following TDR Generic table.

Get the following information after the preparation. These details will be used by the SDK:

1. Directory server address list
2. App ID
3. App access password
4. Game zone ID
5. Table name

4. Example Code

Basic execution process of example code:

1. Create a client;
2. Create a request;
3. Send a request;
4. Process the response;
5. Destroy the client.

4.1 Example Code for Synchronous Call

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. Prepare the environment information
        // 1.1. Directory server address list
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. App ID
        int appId = 1;
        // 1.3. App access password
        String appPassword = "****************";
        // 1.4. Game zone ID
        int zoneId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, zoneId, appPassword, dirList);
        try {
            // 3. Construct a request to insert data
            // 3.1. Get the request object. In order to improve the SDK's performance, the Request object is reused
            Request request = client.acquireRequest();
            // 3.2. Set the request type and target table name
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of each data field. It should be noted that the Key and Value fields are set in different ways.
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            record.setValueByte("typeid", (byte) 1);
            record.setValueByte("Data", (byte) 1);
            record.setValueString("uname", "test");

            // 4. Send a request and get the result
            Response response = client.poll(request);

            // 5. Process the response
            if (response.getResult() == 0) {
                // Data insert successful
                // TODO: add the code to process the result of data insert successful here
            } else {
                // Data insert failure
                // TODO: add the code to process the result of data insert failure here
            }
        } finally {
            // 6. Destroy the client object
            ClientFactory.destroyClient(client);
        }
    }

}

4.2 Example Code for Asynchronous Call

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. Prepare the environment information
        // 1.1. Directory server address list
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. App ID
        int appId = 1;
        // 1.3. App access password
        String appPassword = "****************";
        // 1.4. Game zone ID
        int zoneId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, zoneId, appPassword, dirList);
        try {
            // 3. Construct a request to insert data
            // 3.1. Get the request object. In order to improve the SDK's performance, the Request object is reused
            Request request = client.acquireRequest();
            // 3.2. Set the request type and target table name
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of each data field. It should be noted that the Key and Value fields are set in different ways.
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            record.setValueByte("typeid", (byte) 1);
            record.setValueByte("Data", (byte) 1);
            record.setValueString("uname", "test");

            CountDownLatch latch = new CountDownLatch(1);

            // 4. Send the request asynchronously and specify the processor that returns the response. The post method will return the result immediately
            client.post(request, new Future() {

                @Override
                public void onResponse(Response response) {
                    // 5. Process the response
                    if (response.getResult() == 0) {
                        // Data insert successful
                        // TODO: add the code to process the result of data insert successful here
                    } else {
                        // Data insert failure
                        // TODO: add the code to process the result of data insert failure here
                    }
                }

            });

            latch.await();
        } finally {
            // 6. Destroy the client object
            ClientFactory.destroyClient(client);
        }
    }

}

5. Method Description in Request Object

Note: If there is an unlisted data request method, it means that this method is not needed in the scenario of inserting data, and misuse may cause an error.

5.1. Method Description in Data Object

The scene of inserting data mainly uses the setXXX interface of the data object to set the field values of new data.

Note: TcaplusDB supports unsigned integer type fields, but Java statements do not support unsigned integers. Therefore, when the field value exceeds the value range of the corresponding type in Java (it appears as a negative number in Java), the app needs to convert the negative number to a positive number. Note: If there is an unlisted data object method, it means that this method is not needed in the scenario of inserting data, and misuse may cause an error.

6. Method Description in Response Object

Note: If there is an unlisted response object method, it means that this method is not needed in the scenario of inserting data, and misuse may cause an error.

7. FAQ

For details, see Meaning and Handling of Error Codes.

8. Other Reference Documents

[TDR Generic Table][C++ SDK] Interface Description for Inserting a Record.

[TDR Generic Table][Go SDK] Interface Description for Inserting a Record.

[TDR Generic Table] [MySQL Protocol Compatibility Interface] Interface Description for Replacing a Record.