[TDR Generic Table][Java SDK] Query Local Index

1. Interface Description

Get multiple pieces of data from the specified table according to part Key field values.

Note: Before getting data by part Key field values, create an index with the corresponding key value as the Key, otherwise an error will be reported that the index cannot be found.

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 password
        String appPassword = "****************";
        // 1.4. Table group ID
        int tableGroupId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. Construct a request to read data according to the value of partial Key fields
            // 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_GET_BY_PARTKEY_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of partial Key fields The complete Key in this sample consists of three fields, but only one of them needs to be specified during the query.
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            // 3.4. Add the Value field to be read
            request.addFieldName("typeid");
            request.addFieldName("Data");
            request.addFieldName("uname");
            // 3.5. If it is set, only the number data starting from offset in the result list will be returned. If it is not set, all the data that meets the conditions will be returned
            int offset = 0;
            int number = 100;
            request.setPartkeyGetParam(offset, number);

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

            // 5. Process the result
            if (response.getResult() == 0) {
                // Data reading successful
                Record result;
                while ((result = response.fetchRecord()) != null) {
                    // TODO: add the code to process the result of data reading successful here
                }
            } else {
                // Data reading failure
                // TODO: add the code to process the result of data reading 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 password
        String appPassword = "****************";
        // 1.4. Table group ID
        int tableGroupId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. Construct a request to read data according to the value of partial Key fields
            // 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_GET_BY_PARTKEY_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of partial Key fields The complete Key in this sample consists of three fields, but only one of them needs to be specified during the query.
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            // 3.4. Add the Value field to be read
            request.addFieldName("typeid");
            request.addFieldName("Data");
            request.addFieldName("uname");
            // 3.5. If it is set, only the number data starting from offset in the result list will be returned. If it is not set, all the data that meets the conditions will be returned
            int offset = 0;
            int number = 100;
            request.setPartkeyGetParam(offset, number);

            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 getting success
                        // TODO: add the subsequent processing code of successful data getting here
                    } else {
                        // Data getting failure
                        // TODO: add the subsequent processing code of failed data getting here
                    }
                }

            });

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

}

5. Method Description in Request Object

Note: If there is an unlisted Request object method, it means that the method is invalid in the scenario of getting data according to part Key field values.

5.1. Method Description in Request Data Object

Note: If there is an unlisted Record object method, it means that the method is invalid in the scenario of getting data according to part Key field values.

6. Method Description in Response Object

Note: If there is an unlisted Response object method, it means that the method is invalid in the scenario of getting data according to part Key field values.

6.1. Method Description in Response Data Object

Note: If there is an unlisted Record object method, it means that the method is invalid in the scenario of getting data according to part Key field values.

7. FAQ

For details, see Meaning and Handling of Error Codes.

8. Other Reference Documents

[[TDR Generic Table][C++ SDK] Interface Description for Querying Local Index](../../01C++_SDK/02Interface_Documents/06[Generic_Table]Query_Local_Index.md

[TDR Generic Table] [Go SDK] Interface Description for Querying Local Index.

[TDR Generic Table] [MySQL Protocol Compatibility Interface] Interface Description for Querying Local Index.