api: mark all request methods as deprecated

We mark all request methods as deprecated because the logic based
on request methods is very difficult to extend. These methods will
be removed in a next major version.

The client code should prefer a request object + Do(). We have updated
the examples for this purpose.

Closes #241

CHANGELOG.md

@@ -20,6 +20,15 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 - Use msgpack/v5 instead of msgpack.v2 (#236)
 - Call/NewCallRequest = Call17/NewCall17Request (#235)
 
+### Deprecated
+
+- All Connection.<Request>, Connection.<Request>Typed and
+  Connection.<Request>Async methods. Instead you should use requests objects +
+  Connection.Do() #241)
+- All ConnectionPool.<Request>, ConnectionPool.<Request>Typed and
+  ConnectionPool.<Request>Async methods. Instead you should use requests
+  objects + Connection.Do() (#241)
+
 ### Removed
 
 - multi subpackage (#240)

README.md

@@ -113,7 +113,9 @@ func main() {
 	if err != nil {
 		fmt.Println("Connection refused:", err)
 	}
-	resp, err := conn.Insert(999, []interface{}{99999, "BB"})
+	resp, err := conn.Do(tarantool.NewInsertRequest(999).
+		Tuple([]interface{}{99999, "BB"}),
+	).Get()
 	if err != nil {
 		fmt.Println("Error", err)
 		fmt.Println("Code", resp.Code)
@@ -138,12 +140,9 @@ starting a session. There are two parameters:
 **Observation 4:** The `err` structure will be `nil` if there is no error,
 otherwise it will have a description which can be retrieved with `err.Error()`.
 
-**Observation 5:** The `Insert` request, like almost all requests, is preceded by
-"`conn.`" which is the name of the object that was returned by `Connect()`.
-There are two parameters:
-
-* a space number (it could just as easily have been a space name), and
-* a tuple.
+**Observation 5:** The `Insert` request, like almost all requests, is preceded
+by the method `Do` of object `conn` which is the object that was returned
+by `Connect()`.
 
 ### Migration to v2
 

connector.go

@@ -8,40 +8,106 @@ type Connector interface {
 	Ping() (resp *Response, err error)
 	ConfiguredTimeout() time.Duration
 
+	// Deprecated: the method will be removed in the next major version,
+	// use a SelectRequest object + Do() instead.
 	Select(space, index interface{}, offset, limit uint32, iterator Iter, key interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an InsertRequest object + Do() instead.
 	Insert(space interface{}, tuple interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a ReplicaRequest object + Do() instead.
 	Replace(space interface{}, tuple interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a DeleteRequest object + Do() instead.
 	Delete(space, index interface{}, key interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a UpdateRequest object + Do() instead.
 	Update(space, index interface{}, key, ops interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a UpsertRequest object + Do() instead.
 	Upsert(space interface{}, tuple, ops interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a CallRequest object + Do() instead.
 	Call(functionName string, args interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call16Request object + Do() instead.
 	Call16(functionName string, args interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call17Request object + Do() instead.
 	Call17(functionName string, args interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an EvalRequest object + Do() instead.
 	Eval(expr string, args interface{}) (resp *Response, err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an ExecuteRequest object + Do() instead.
 	Execute(expr string, args interface{}) (resp *Response, err error)
 
+	// Deprecated: the method will be removed in the next major version,
+	// use a SelectRequest object + Do() instead.
 	GetTyped(space, index interface{}, key interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a SelectRequest object + Do() instead.
 	SelectTyped(space, index interface{}, offset, limit uint32, iterator Iter, key interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an InsertRequest object + Do() instead.
 	InsertTyped(space interface{}, tuple interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a ReplaceRequest object + Do() instead.
 	ReplaceTyped(space interface{}, tuple interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a DeleteRequest object + Do() instead.
 	DeleteTyped(space, index interface{}, key interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a UpdateRequest object + Do() instead.
 	UpdateTyped(space, index interface{}, key, ops interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a CallRequest object + Do() instead.
 	CallTyped(functionName string, args interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call16Request object + Do() instead.
 	Call16Typed(functionName string, args interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call17Request object + Do() instead.
 	Call17Typed(functionName string, args interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an EvalRequest object + Do() instead.
 	EvalTyped(expr string, args interface{}, result interface{}) (err error)
+	// Deprecated: the method will be removed in the next major version,
+	// use an ExecuteRequest object + Do() instead.
 	ExecuteTyped(expr string, args interface{}, result interface{}) (SQLInfo, []ColumnMetaData, error)
 
+	// Deprecated: the method will be removed in the next major version,
+	// use a SelectRequest object + Do() instead.
 	SelectAsync(space, index interface{}, offset, limit uint32, iterator Iter, key interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use an InsertRequest object + Do() instead.
 	InsertAsync(space interface{}, tuple interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a ReplaceRequest object + Do() instead.
 	ReplaceAsync(space interface{}, tuple interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a DeleteRequest object + Do() instead.
 	DeleteAsync(space, index interface{}, key interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a UpdateRequest object + Do() instead.
 	UpdateAsync(space, index interface{}, key, ops interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a UpsertRequest object + Do() instead.
 	UpsertAsync(space interface{}, tuple interface{}, ops interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a CallRequest object + Do() instead.
 	CallAsync(functionName string, args interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call16Request object + Do() instead.
 	Call16Async(functionName string, args interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use a Call17Request object + Do() instead.
 	Call17Async(functionName string, args interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use an EvalRequest object + Do() instead.
 	EvalAsync(expr string, args interface{}) *Future
+	// Deprecated: the method will be removed in the next major version,
+	// use an ExecuteRequest object + Do() instead.
 	ExecuteAsync(expr string, args interface{}) *Future
 
 	NewPrepared(expr string) (*Prepared, error)

datetime/example_test.go

@@ -45,7 +45,9 @@ func Example() {
 	index := "primary"
 
 	// Replace a tuple with datetime.
-	resp, err := conn.Replace(space, []interface{}{dt})
+	resp, err := conn.Do(tarantool.NewReplaceRequest(space).
+		Tuple([]interface{}{dt}),
+	).Get()
 	if err != nil {
 		fmt.Printf("Error in replace is %v", err)
 		return
@@ -58,7 +60,13 @@ func Example() {
 	// Select a tuple with datetime.
 	var offset uint32 = 0
 	var limit uint32 = 1
-	resp, err = conn.Select(space, index, offset, limit, tarantool.IterEq, []interface{}{dt})
+	resp, err = conn.Do(tarantool.NewSelectRequest(space).
+		Index(index).
+		Offset(offset).
+		Limit(limit).
+		Iterator(tarantool.IterEq).
+		Key([]interface{}{dt}),
+	).Get()
 	if err != nil {
 		fmt.Printf("Error in select is %v", err)
 		return
@@ -69,7 +77,10 @@ func Example() {
 	fmt.Printf("Data: %v\n", respDt.ToTime())
 
 	// Delete a tuple with datetime.
-	resp, err = conn.Delete(space, index, []interface{}{dt})
+	resp, err = conn.Do(tarantool.NewDeleteRequest(space).
+		Index(index).
+		Key([]interface{}{dt}),
+	).Get()
 	if err != nil {
 		fmt.Printf("Error in delete is %v", err)
 		return

decimal/example_test.go

@@ -40,7 +40,9 @@ func Example() {
 		log.Fatalf("Failed to prepare test decimal: %s", err)
 	}
 
-	resp, err := client.Replace(spaceNo, []interface{}{number})
+	resp, err := client.Do(tarantool.NewReplaceRequest(spaceNo).
+		Tuple([]interface{}{number}),
+	).Get()
 	if err != nil {
 		log.Fatalf("Decimal replace failed: %s", err)
 	}

example_custom_unpacking_test.go

@@ -93,7 +93,9 @@ func Example_customUnpacking() {
 	indexNo := uint32(0)
 
 	tuple := Tuple2{Cid: 777, Orig: "orig", Members: []Member{{"lol", "", 1}, {"wut", "", 3}}}
-	resp, err := conn.Replace(spaceNo, &tuple) // NOTE: insert a structure itself.
+	// Insert a structure itself.
+	initReq := tarantool.NewReplaceRequest(spaceNo).Tuple(&tuple)
+	resp, err := conn.Do(initReq).Get()
 	if err != nil {
 		log.Fatalf("Failed to insert: %s", err.Error())
 		return
@@ -102,7 +104,12 @@ func Example_customUnpacking() {
 	fmt.Println("Code", resp.Code)
 
 	var tuples1 []Tuple2
-	err = conn.SelectTyped(spaceNo, indexNo, 0, 1, tarantool.IterEq, []interface{}{777}, &tuples1)
+	selectReq := tarantool.NewSelectRequest(spaceNo).
+		Index(indexNo).
+		Limit(1).
+		Iterator(tarantool.IterEq).
+		Key([]interface{}{777})
+	err = conn.Do(selectReq).GetTyped(&tuples1)
 	if err != nil {
 		log.Fatalf("Failed to SelectTyped: %s", err.Error())
 		return
@@ -111,7 +118,7 @@ func Example_customUnpacking() {
 
 	// Same result in a "magic" way.
 	var tuples2 []Tuple3
-	err = conn.SelectTyped(spaceNo, indexNo, 0, 1, tarantool.IterEq, []interface{}{777}, &tuples2)
+	err = conn.Do(selectReq).GetTyped(&tuples2)
 	if err != nil {
 		log.Fatalf("Failed to SelectTyped: %s", err.Error())
 		return
@@ -120,7 +127,8 @@ func Example_customUnpacking() {
 
 	// Call a function "func_name" returning a table of custom tuples.
 	var tuples3 [][]Tuple3
-	err = conn.Call17Typed("func_name", []interface{}{}, &tuples3)
+	callReq := tarantool.NewCallRequest("func_name")
+	err = conn.Do(callReq).GetTyped(&tuples3)
 	if err != nil {
 		log.Fatalf("Failed to CallTyped: %s", err.Error())
 		return