Skip to content

SDB Mid Tier Routing Services

Jump to bottom
Bharath Ramaprasad edited this page Jul 24, 2019 · 13 revisions

Steps to install & access Mid Tier Routing services via Docker

  1. Install Docker if not already installed on the target machine using instructions at : https://docs.docker.com/install/

  2. Make sure docker is running by issuing a docker -v at the terminal

  3. Login to docker using your dockerhub creds by issuing a docker login at the terminal

SDB Mid-Tier Routing (MTR) Docker image

The Mid-Tier routing (MTR) docker image can be built using the instructions in the README file.

What is contained in the MTR docker image

A tomcat container serving the following :

  1. REST APIs for retrieving swim lane details and shard info details given a sharding key.
  2. REST APIs for retrieving and administering the swim lane detail mappings on the swim lane cache.

Running SDB Mid-Tier Routing services in a Docker Container

To pull & run SDB Mid-Tier routing docker image use the docker run command as follows
docker run --name <container name> \
 -p <host port>:8080 
 -e CATALOG_USERNAME='<username>' \
 -e CATALOG_PASSWD='<password>' \
 -e CATALOG_URL='<jdbc:oracle:thin:@hostname:port:sid>' \ 
 -e CATALOG_SVC_NAME='<catalog-service-name> (default : '')' \
 -e SWIM_LANE_CACHE_HOST='<cache host> (default : '')' \
 -e SWIM_LANE_CACHE_PORT='<cache port> (default : '')' \
 -e SWIM_LANE_CACHE_TYPE='<local | redis>' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest

 Parameters:

 --name:                   The name of the container (default: auto generated)
 -p:                       The port mapping of the host port to the container port. One port is exposed: 8080
 -e CATALOG_USERNAME:      Catalog user's username
 -e CATALOG_PASSWD:        Catalog user's password 
 -e CATALOG_URL:           JDBC Connect String to the catalog database 
 -e CATALOG_SVC_NAME:      Service name of the catalog  
 -e SWIM_LANE_CACHE_HOST:  The swim lane cache hostname that MTR should use
 -e SWIM_LANE_CACHE_PORT:  The swim lane cache port that MTR should use                          
 -e SWIM_LANE_CACHE_TYPE:  Swim lane cache type. Value can either be local or redis. 
                           local refers to an in-built cache within the container. 
                           REDIS refers to an external REDIS server instance.

Once the MTR docker container has been started, you can make REST API calls to Mid-Tier routing services.

  • Local in-memory cache mode

In this mode, the cache is local and in-memory. So if the container goes down the swim lane details are lost. So the swim lane mappings needs to be established again.

This mode is recommended if the number of shards or the swim lane mappings aren't too large.

Local mode example :

docker run --rm --name oracle-sdb-mtr-latest \
-p 8080:8080 \
-e CATALOG_USERNAME='app_schema' \ 
-e CATALOG_PASSWD='app_schema' \
-e CATALOG_URL='jdbc:oracle:thin:@localhost:1521:composite' \
-e CATALOG_SVC_NAME='' \ 
-e SWIM_LANE_CACHE_HOST='' \
-e SWIM_LANE_CACHE_PORT='' \
-e SWIM_LANE_CACHE_TYPE='local' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest
  • External REDIS cache mode

In this mode, the user is responsible here to start the REDIS instance and pass in the necessary parameters for the sdb mid-tier routing docker container. As the cache is external and running in its own container, even if the sdb-mtr container goes down, the swim lane mappings are not lost.

This mode is recommended if the number of shards or the swim lane mappings are large and you need or already using a distributed cache like REDIS.

REDIS mode example :

docker run --rm --name oracle-sdb-mtr-latest \
-p 8080:8080 \
-e CATALOG_USERNAME='app_schema' \ 
-e CATALOG_PASSWD='app_schema' \
-e CATALOG_URL='jdbc:oracle:thin:@localhost:1521:composite' \
-e CATALOG_SVC_NAME='' \ 
-e SWIM_LANE_CACHE_HOST='192.168.0.2' \
-e SWIM_LANE_CACHE_PORT='6379' \
-e SWIM_LANE_CACHE_TYPE='redis' \
 oraclesharding/oracle-sdb-mid-tier-routing-services:latest

SDB Mid-Tier Routing services REST API documentation

1. Retrieve swim lane details for a shard key REST API

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#72e8c15f-4267-a03c-f5f4-a00722478cc8

CURL for API

curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/shardDetails/swimLane" \
     --header "Content-Type: application/vnd.oracle.sdb.mtr.sk.datatype.mixed.swimlane.v1+json" \
     --data "[
         {
           \"shardKeyType\":\"number\",
           \"shardKeyValue\":\"2000\",
           \"isSuperShardKey\": false
         },
         {
           \"shardKeyType\":\"varchar2\",
           \"shardKeyValue\":\"small\",
           \"isSuperShardKey\": true
         }
        ]"

Description : Given a shard key and optionally a super shard key, this API will retrieve any pre-associated/pre-defined swimlane details corresponding to the sharding keys on success. On failure expect 4XX or 5XX HTTP error codes.

This API supports all datatypes that are supported by JDBC for sharded database. Refer the following link for all supported data types : https://docs.oracle.com/en/database/oracle/oracle-database/12.2/jjdbc/database-sharding.html#GUID-4B151856-8B27-470C-B7DA-016FCBF97638 .

There are three aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header :

Content type header

application/vnd.oracle.sdb.mtr.sk.datatype.mixed.swimlane.v1+json

  1. Fields of the request body :

    shardKeyType → needs to be one of the supported jdbc types. shardKeyValue → value of the shardKey. isSuperShardKey → boolean for denoting whether this is a super shard key or not.

Sharding key example

 {
   "shardKeyType":"number",
   "shardKeyValue":"1000",
   "isSuperShardKey": false
 }
  1. Order of the sharding keys

The order of the sharding keys is important and needs to correspond for example how a composite sharding key is defined in the sharded database table.

Order of shard keys example

[
  {
    "shardKeyType":"number",
    "shardKeyValue":"1000",
    "isSuperShardKey": false
  },
  {
    "shardKeyType":"varchar2",
    "shardKeyValue":"small",
    "isSuperShardKey": true
  }
]

2. Retrieve shard details for a shard key REST API

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#83897420-eb34-b29a-7aed-bf72bd6be396

CURL for API

 curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/shardDetails" \
      --header "Content-Type: application/vnd.oracle.sdb.mtr.sk.datatype.mixed.v1+json" \
      --data "[
                {
                  \"shardKeyType\":\"number\",
                  \"shardKeyValue\":\"1000\",
                  \"isSuperShardKey\": false
                },
                {
                  \"shardKeyType\":\"varchar2\",
                  \"shardKeyValue\":\"small\",
                  \"isSuperShardKey\": true
                }
              ]"

There are three aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header :

Content type header

application/vnd.oracle.sdb.mtr.sk.datatype.mixed.v1+json

  1. Fields of the request body :

    shardKeyType → needs to be one of the types mentioned above. shardKeyValue → value of the shardKey. isSuperShardKey → boolean for denoting whether this is a super shard key or not.

Sharding key example

 {
   "shardKeyType":"number",
   "shardKeyValue":"1000",
   "isSuperShardKey": false
 }
  1. Order of the sharding keys

The order of the sharding keys is important and needs to correspond for example how a composite sharding key is defined in the sharded database table.

Order of shard keys example

[
  {
    "shardKeyType":"number",
    "shardKeyValue":"1000",
    "isSuperShardKey": false
  },
  {
    "shardKeyType":"varchar2",
    "shardKeyValue":"small",
    "isSuperShardKey": true
  }
]

Note : If there are multiple shard names returned, then there is a replication setup for a shard, wherein one is the primary and the other a standby in the case of a active / passive setup (Example : Dataguard) or both can be the masters in a active-active setup (Example : Goldengate).

3. Associate shard name with a swim lane REST API

Note : The onus of associating a shard name with a swim lane is on the application administrator / owner / privileged user. The swim lane naming and the details of the swim lane such as swimLane URL, must be added by the application admin, as using just the shard name as swim lane name may not be meaningful in the application domain.

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#6456ac2d-fc6a-53ae-dade-6b60e7663b37

CURL for API

 curl --location --request POST "http://localhost:8080/sdb-mid-tier-routing-services/swimLane" \
      --header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
      --data "{
                 \"shardName\":\"mpositec\",
                 \"swimLaneName\":\"small-swimlane-1\",
                 \"swimLaneURL\": \"http://localhost:10000/api/invoice/\"
              }"

Description : Given a shardName retrieved from the Retrieve shard details for a shard key REST API, its corresponding swim lane name (user defined specific to the application) and swim lane url (user defined specific to the application), the REST API responds with a 200 OK for a successful association. On failure expect 4XX or 5XX HTTP error codes to indicate failure in association.

There are two aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header :

Content type header

application/vnd.oracle.sdb.mtr.swimlane.v1+json

  1. Fields of the request body :

    shardName → a valid shardName retrieved from the Retrieve shard details for a shard key REST API. 
swimLaneName → corresponding swim lane name (user defined specific to the application).
swimLaneURL → swim lane url (user defined specific to the application) which may be an FQDN or IP for 
              example an application load balancer or a gateway or a data API endpoint or an web / app
              server address amongst others.

Swim lane association request body example

 {
    "shardName":"mpositec",
    "swimLaneName":"small-swimlane-1",
    "swimLaneURL": "http://localhost:10000/api/invoice/"
 }

4. Retrieve swim lane details REST API

Note : This API will return a non-empty, successful response only when there is a mapping already established between shardName(s) and the swim lane whose details are to be retrieved. To establish a mapping / association please refer to Associate shard name with a swim lane REST API.

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#91be24a7-dc57-f35e-1828-b437d72b883a

CURL for API

 curl --location --request GET "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
      --header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json"

Description : Retrieve the swim lane details given a swim lane name in the path parameter. On failure expect 4XX or 5XX HTTP error codes to indicate failure in retrieval.

There are two aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header

Content type header

application/vnd.oracle.sdb.mtr.swimlane.v1+json
  1. Path Parameter : The path parameter swimLaneName must be substituted with a valid swimLaneName.

Path parameter

 http://localhost:8080/sdb-mid-tier-routing-services/swimLane/{swimLaneName}

5. Update the swimLane association REST API

Note : The onus of updating the association of a shard name and its swim lane details is on the application administrator / owner / privileged user. The swim lane naming and the details of the swim lane such as swimLane URL, must be added by the application admin, as using just the shard name as swim lane name may not be meaningful in the application domain.

API reference : https://documenter.getpostman.com/view/754319/RznJmG4U#272857b8-c68f-d249-4d21-1e9da12bf8cc

CURL for API

   curl --location --request PUT "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
        --header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
        --data "{
                   \"shardName\":\"mpositec\",
                   \"swimLaneName\":\"small-swimlane-1\",
                   \"swimLaneURL\": \"http://localhost:10000/api/invoice/\"
                }"

Description : Given a valid and already associated shardName retrieved from the Retrieve shard details for a shard key REST API, its corresponding swim lane name (user defined specific to the application) and swim lane url (user defined specific to the application), the REST API responds with a 200 OK for a successful association. On failure expect 4XX or 5XX HTTP error codes to indicate failure in association.

There are two aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header.

Content type header

application/vnd.oracle.sdb.mtr.swimlane.v1+json

  1. Fields of the request body :

     shardName → a valid shardName retrieved from the Retrieve shard details for a shard key REST API.
 swimLaneName → corresponding swim lane name (user defined specific to the application).
 swimLaneURL →  swim lane url (user defined specific to the application) which may be an FQDN or IP for 
                example an application load balancer or a gateway or a data API endpoint or an web / app
                server address amongst others.

Swim lane association request body example

 {
    "shardName":"mpositec",
    "swimLaneName":"small-swimlane-1",
    "swimLaneURL": "http://localhost:10000/api/invoice/"
 }

6. Delete swimLane association REST API

Note : This API will return a successful response 200 OK only when there is a mapping already established between shardName(s) and the swim lane whose details are to be deleted exists. To establish a mapping / association please refer to Associate shard name with a swim lane REST API. To retrieve a swim lane to be deleted please refer to Retrieve swim lane details REST API

API Reference : https://documenter.getpostman.com/view/754319/RznJmG4U#65fbe3fa-fc0e-96dd-c328-b55482187fe3

CURL for API

 curl --location --request DELETE "http://localhost:8080/sdb-mid-tier-routing-services/swimLane/mpositec" \
      --header "Content-Type: application/vnd.oracle.sdb.mtr.swimlane.v1+json" \
      --data ""

Description : Delete the swim lane mapping given a swim lane name in the path parameter. Expect 200 OK on successful deletion. On failure expect 4XX or 5XX HTTP error codes to indicate failure in deletion.

There are two aspects to this REST API :

  1. Content Type : The client invoking this REST API must include the following content type in its header

Content type header

application/vnd.oracle.sdb.mtr.swimlane.v1+json
  1. Path Parameter : The path parameter swimLaneName must be substituted with a valid swimLaneName.

Path parameter

 http://localhost:8080/sdb-mid-tier-routing-services/swimLane/{swimLaneName}

Complete API Collection

https://documenter.getpostman.com/view/754319/RznJmG4U

Clone this wiki locally