From ef3febf7b231b9dfe837a0db99dbbfbba3d6b220 Mon Sep 17 00:00:00 2001
From: Joe Zou <yixian.zou@gmail.com>
Date: Sat, 13 Jun 2020 20:45:19 +0800
Subject: [PATCH] add comment for jsonrpc
---
protocol/invocation.go | 6 +--
protocol/invocation/rpcinvocation.go | 57 +++++++++++++---------------
protocol/jsonrpc/http.go | 10 ++---
protocol/jsonrpc/json.go | 17 ++++++---
protocol/jsonrpc/jsonrpc_exporter.go | 6 +--
protocol/jsonrpc/jsonrpc_invoker.go | 6 +--
protocol/jsonrpc/jsonrpc_protocol.go | 12 +++---
protocol/jsonrpc/server.go | 8 ++--
8 files changed, 61 insertions(+), 61 deletions(-)
diff --git a/protocol/invocation.go b/protocol/invocation.go
index 44bebfd94..ba5949794 100644
--- a/protocol/invocation.go
+++ b/protocol/invocation.go
@@ -29,15 +29,15 @@ type Invocation interface {
ParameterTypes() []reflect.Type
// ParameterValues gets invocation parameter values.
ParameterValues() []reflect.Value
- // Arguments get arguments.
+ // Arguments gets arguments.
Arguments() []interface{}
- // Reply gets request response
+ // Reply gets response of request
Reply() interface{}
// Attachments gets all attachments
Attachments() map[string]string
// AttachmentsByKey gets attachment by key , if nil then return default value
AttachmentsByKey(string, string) string
- // Refer to dubbo 2.7.6. It is different from attachment. It is used in internal process.
+ // Attributes refers to dubbo 2.7.6. It is different from attachment. It is used in internal process.
Attributes() map[string]interface{}
// AttributeByKey gets attribute by key , if nil then return default value
AttributeByKey(string, interface{}) interface{}
diff --git a/protocol/invocation/rpcinvocation.go b/protocol/invocation/rpcinvocation.go
index 68fe7b920..93b563a45 100644
--- a/protocol/invocation/rpcinvocation.go
+++ b/protocol/invocation/rpcinvocation.go
@@ -31,7 +31,7 @@ import (
// ///////////////////////////
// todo: is it necessary to separate fields of consumer(provider) from RPCInvocation
-// RPCInvocation ...
+// RPCInvocation is invocation implement of RPC.
type RPCInvocation struct {
methodName string
parameterTypes []reflect.Type
@@ -46,7 +46,7 @@ type RPCInvocation struct {
lock sync.RWMutex
}
-// NewRPCInvocation ...
+// NewRPCInvocation creates a RPC invocation.
func NewRPCInvocation(methodName string, arguments []interface{}, attachments map[string]string) *RPCInvocation {
return &RPCInvocation{
methodName: methodName,
@@ -56,7 +56,7 @@ func NewRPCInvocation(methodName string, arguments []interface{}, attachments ma
}
}
-// NewRPCInvocationWithOptions ...
+// NewRPCInvocationWithOptions creates a RPC invocation with @opts.
func NewRPCInvocationWithOptions(opts ...option) *RPCInvocation {
invo := &RPCInvocation{}
for _, opt := range opts {
@@ -68,42 +68,42 @@ func NewRPCInvocationWithOptions(opts ...option) *RPCInvocation {
return invo
}
-// MethodName ...
+// MethodName gets RPC invocation method name.
func (r *RPCInvocation) MethodName() string {
return r.methodName
}
-// ParameterTypes ...
+// ParameterTypes gets RPC invocation parameter types.
func (r *RPCInvocation) ParameterTypes() []reflect.Type {
return r.parameterTypes
}
-// ParameterValues ...
+// ParameterValues gets RPC invocation parameter values.
func (r *RPCInvocation) ParameterValues() []reflect.Value {
return r.parameterValues
}
-// Arguments ...
+// Arguments gets RPC arguments.
func (r *RPCInvocation) Arguments() []interface{} {
return r.arguments
}
-// Reply ...
+// Reply gets response of RPC request.
func (r *RPCInvocation) Reply() interface{} {
return r.reply
}
-// SetReply ...
+// SetReply sets response of RPC request.
func (r *RPCInvocation) SetReply(reply interface{}) {
r.reply = reply
}
-// Attachments ...
+// Attachments gets all attachments of RPC.
func (r *RPCInvocation) Attachments() map[string]string {
return r.attachments
}
-// AttachmentsByKey ...
+// AttachmentsByKey gets RPC attachment by key , if nil then return default value.
func (r *RPCInvocation) AttachmentsByKey(key string, defaultValue string) string {
r.lock.RLock()
defer r.lock.RUnlock()
@@ -117,12 +117,12 @@ func (r *RPCInvocation) AttachmentsByKey(key string, defaultValue string) string
return defaultValue
}
-// get attributes
+// Attributes gets all attributes of RPC.
func (r *RPCInvocation) Attributes() map[string]interface{} {
return r.attributes
}
-// get attribute by key. If it is not exist, it will return default value
+// AttributeByKey gets attribute by @key. If it is not exist, it will return default value.
func (r *RPCInvocation) AttributeByKey(key string, defaultValue interface{}) interface{} {
r.lock.RLock()
defer r.lock.RUnlock()
@@ -133,7 +133,7 @@ func (r *RPCInvocation) AttributeByKey(key string, defaultValue interface{}) int
return defaultValue
}
-// SetAttachments ...
+// SetAttachments sets attribute by @key and @value.
func (r *RPCInvocation) SetAttachments(key string, value string) {
r.lock.Lock()
defer r.lock.Unlock()
@@ -143,29 +143,24 @@ func (r *RPCInvocation) SetAttachments(key string, value string) {
r.attachments[key] = value
}
-// SetAttribute. If Attributes is nil, it will be inited.
+// SetAttribute sets attribute by @key and @value.
func (r *RPCInvocation) SetAttribute(key string, value interface{}) {
r.lock.Lock()
defer r.lock.Unlock()
r.attributes[key] = value
}
-// Invoker ...
+// Invoker gets the invoker in current context.
func (r *RPCInvocation) Invoker() protocol.Invoker {
return r.invoker
}
-// SetInvoker ...
-func (r *RPCInvocation) SetInvoker() protocol.Invoker {
- return r.invoker
-}
-
-// CallBack ...
+// CallBack sets RPC callback method.
func (r *RPCInvocation) CallBack() interface{} {
return r.callBack
}
-// SetCallBack ...
+// SetCallBack sets RPC callback method.
func (r *RPCInvocation) SetCallBack(c interface{}) {
r.callBack = c
}
@@ -176,56 +171,56 @@ func (r *RPCInvocation) SetCallBack(c interface{}) {
type option func(invo *RPCInvocation)
-// WithMethodName ...
+// WithMethodName creates option with @methodName.
func WithMethodName(methodName string) option {
return func(invo *RPCInvocation) {
invo.methodName = methodName
}
}
-// WithParameterTypes ...
+// WithParameterTypes creates option with @parameterTypes.
func WithParameterTypes(parameterTypes []reflect.Type) option {
return func(invo *RPCInvocation) {
invo.parameterTypes = parameterTypes
}
}
-// WithParameterValues ...
+// WithParameterValues creates option with @parameterValues
func WithParameterValues(parameterValues []reflect.Value) option {
return func(invo *RPCInvocation) {
invo.parameterValues = parameterValues
}
}
-// WithArguments ...
+// WithArguments creates option with @arguments function.
func WithArguments(arguments []interface{}) option {
return func(invo *RPCInvocation) {
invo.arguments = arguments
}
}
-// WithReply ...
+// WithReply creates option with @reply function.
func WithReply(reply interface{}) option {
return func(invo *RPCInvocation) {
invo.reply = reply
}
}
-// WithCallBack ...
+// WithCallBack creates option with @callback function.
func WithCallBack(callBack interface{}) option {
return func(invo *RPCInvocation) {
invo.callBack = callBack
}
}
-// WithAttachments ...
+// WithAttachments creates option with @attachments.
func WithAttachments(attachments map[string]string) option {
return func(invo *RPCInvocation) {
invo.attachments = attachments
}
}
-// WithInvoker ...
+// WithInvoker creates option with @invoker.
func WithInvoker(invoker protocol.Invoker) option {
return func(invo *RPCInvocation) {
invo.invoker = invoker
diff --git a/protocol/jsonrpc/http.go b/protocol/jsonrpc/http.go
index 70b3abd24..5fca66d99 100644
--- a/protocol/jsonrpc/http.go
+++ b/protocol/jsonrpc/http.go
@@ -63,7 +63,7 @@ type Request struct {
// HTTP Client
// ////////////////////////////////////////////
-// HTTPOptions ...
+// HTTPOptions is a HTTP option include HandshakeTimeout and HTTPTimeout.
type HTTPOptions struct {
HandshakeTimeout time.Duration
HTTPTimeout time.Duration
@@ -74,13 +74,13 @@ var defaultHTTPOptions = HTTPOptions{
HTTPTimeout: 3 * time.Second,
}
-// HTTPClient ...
+// HTTPClient is a HTTP client ,include ID and options.
type HTTPClient struct {
ID int64
options HTTPOptions
}
-// NewHTTPClient ...
+// NewHTTPClient creates a new HTTP client with HTTPOptions.
func NewHTTPClient(opt *HTTPOptions) *HTTPClient {
if opt == nil {
opt = &defaultHTTPOptions
@@ -100,7 +100,7 @@ func NewHTTPClient(opt *HTTPOptions) *HTTPClient {
}
}
-// NewRequest ...
+// NewRequest creates a new HTTP request with @service ,@method and @arguments.
func (c *HTTPClient) NewRequest(service common.URL, method string, args interface{}) *Request {
return &Request{
@@ -114,7 +114,7 @@ func (c *HTTPClient) NewRequest(service common.URL, method string, args interfac
}
}
-// Call ...
+// Call makes a HTTP call with @ctx , @service ,@req and @rsp
func (c *HTTPClient) Call(ctx context.Context, service common.URL, req *Request, rsp interface{}) error {
// header
httpHeader := http.Header{}
diff --git a/protocol/jsonrpc/json.go b/protocol/jsonrpc/json.go
index 3176e1938..389ead9c1 100644
--- a/protocol/jsonrpc/json.go
+++ b/protocol/jsonrpc/json.go
@@ -37,7 +37,7 @@ const (
VERSION = "2.0"
)
-// CodecData ...
+// CodecData is codec data for json RPC.
type CodecData struct {
ID int64
Method string
@@ -64,6 +64,7 @@ type Error struct {
Data interface{} `json:"data,omitempty"`
}
+// Error decodes response error for a string.
func (e *Error) Error() string {
buf, err := json.Marshal(e)
if err != nil {
@@ -114,6 +115,7 @@ func newJsonClientCodec() *jsonClientCodec {
}
}
+// Write codec data as byte.
func (c *jsonClientCodec) Write(d *CodecData) ([]byte, error) {
// If return error: it will be returned as is for this call.
// Allow param to be only Array, Slice, Map or Struct.
@@ -170,6 +172,7 @@ func (c *jsonClientCodec) Write(d *CodecData) ([]byte, error) {
return buf.Bytes(), nil
}
+// Read bytes as structured data
func (c *jsonClientCodec) Read(streamBytes []byte, x interface{}) error {
c.rsp.reset()
@@ -223,6 +226,7 @@ func (r *serverRequest) reset() {
}
}
+// UnmarshalJSON unmarshals JSON for server request.
func (r *serverRequest) UnmarshalJSON(raw []byte) error {
r.reset()
@@ -281,7 +285,7 @@ type serverResponse struct {
Error interface{} `json:"error,omitempty"`
}
-// ServerCodec ...
+// ServerCodec is codec data for request server.
type ServerCodec struct {
req serverRequest
}
@@ -296,7 +300,7 @@ func newServerCodec() *ServerCodec {
return &ServerCodec{}
}
-// ReadHeader ...
+// ReadHeader reads header and unmarshal to server codec
func (c *ServerCodec) ReadHeader(header map[string]string, body []byte) error {
if header["HttpMethod"] != "POST" {
return &Error{Code: -32601, Message: "Method not found"}
@@ -328,7 +332,7 @@ func (c *ServerCodec) ReadHeader(header map[string]string, body []byte) error {
return nil
}
-// ReadBody ...
+// ReadBody reads @x as request body.
func (c *ServerCodec) ReadBody(x interface{}) error {
// If x!=nil and return error e:
// - Write() will be called with e.Error() in r.Error
@@ -339,7 +343,7 @@ func (c *ServerCodec) ReadBody(x interface{}) error {
return nil
}
- // 在这里把请求å‚æ•°json å—符串转æ¢æˆäº†ç›¸åº”çš„struct
+ // the request parameter JSON string is converted to the corresponding struct
params := []byte(*c.req.Params)
if err := json.Unmarshal(*c.req.Params, x); err != nil {
// Note: if c.request.Params is nil it's not an error, it's an optional member.
@@ -362,7 +366,7 @@ func (c *ServerCodec) ReadBody(x interface{}) error {
return nil
}
-// NewError ...
+// NewError creates a error with @code and @message
func NewError(code int, message string) *Error {
return &Error{Code: code, Message: message}
}
@@ -380,6 +384,7 @@ func newError(message string) *Error {
}
}
+// Write responses as byte
func (c *ServerCodec) Write(errMsg string, x interface{}) ([]byte, error) {
// If return error: nothing happens.
// In r.Error will be "" or .Error() of error returned by:
diff --git a/protocol/jsonrpc/jsonrpc_exporter.go b/protocol/jsonrpc/jsonrpc_exporter.go
index c61cf9ada..6f75f6aea 100644
--- a/protocol/jsonrpc/jsonrpc_exporter.go
+++ b/protocol/jsonrpc/jsonrpc_exporter.go
@@ -28,19 +28,19 @@ import (
"github.com/apache/dubbo-go/protocol"
)
-// JsonrpcExporter ...
+// JsonrpcExporter is JSON RPC exporter and extends from base invoker.
type JsonrpcExporter struct {
protocol.BaseExporter
}
-// NewJsonrpcExporter ...
+// NewJsonrpcExporter creates JSON RPC exporter with @key, @invoker and @exporterMap
func NewJsonrpcExporter(key string, invoker protocol.Invoker, exporterMap *sync.Map) *JsonrpcExporter {
return &JsonrpcExporter{
BaseExporter: *protocol.NewBaseExporter(key, invoker, exporterMap),
}
}
-// Unexport ...
+// Unexport exported JSON RPC service.
func (je *JsonrpcExporter) Unexport() {
serviceId := je.GetInvoker().GetUrl().GetParam(constant.BEAN_NAME_KEY, "")
interfaceName := je.GetInvoker().GetUrl().GetParam(constant.INTERFACE_KEY, "")
diff --git a/protocol/jsonrpc/jsonrpc_invoker.go b/protocol/jsonrpc/jsonrpc_invoker.go
index b6e194ce0..d84b98021 100644
--- a/protocol/jsonrpc/jsonrpc_invoker.go
+++ b/protocol/jsonrpc/jsonrpc_invoker.go
@@ -29,13 +29,13 @@ import (
invocation_impl "github.com/apache/dubbo-go/protocol/invocation"
)
-// JsonrpcInvoker ...
+// JsonrpcInvoker is JSON RPC invoker
type JsonrpcInvoker struct {
protocol.BaseInvoker
client *HTTPClient
}
-// NewJsonrpcInvoker ...
+// NewJsonrpcInvoker creates JSON RPC invoker with @url and @client
func NewJsonrpcInvoker(url common.URL, client *HTTPClient) *JsonrpcInvoker {
return &JsonrpcInvoker{
BaseInvoker: *protocol.NewBaseInvoker(url),
@@ -43,7 +43,7 @@ func NewJsonrpcInvoker(url common.URL, client *HTTPClient) *JsonrpcInvoker {
}
}
-// Invoke ...
+// Invoke the JSON RPC invocation and return result.
func (ji *JsonrpcInvoker) Invoke(ctx context.Context, invocation protocol.Invocation) protocol.Result {
var (
diff --git a/protocol/jsonrpc/jsonrpc_protocol.go b/protocol/jsonrpc/jsonrpc_protocol.go
index 64f708652..90a6bf5ef 100644
--- a/protocol/jsonrpc/jsonrpc_protocol.go
+++ b/protocol/jsonrpc/jsonrpc_protocol.go
@@ -44,14 +44,14 @@ func init() {
var jsonrpcProtocol *JsonrpcProtocol
-// JsonrpcProtocol ...
+// JsonrpcProtocol is JSON RPC protocol.
type JsonrpcProtocol struct {
protocol.BaseProtocol
serverMap map[string]*Server
serverLock sync.Mutex
}
-// NewJsonrpcProtocol ...
+// NewJsonrpcProtocol creates JSON RPC protocol
func NewJsonrpcProtocol() *JsonrpcProtocol {
return &JsonrpcProtocol{
BaseProtocol: protocol.NewBaseProtocol(),
@@ -59,7 +59,7 @@ func NewJsonrpcProtocol() *JsonrpcProtocol {
}
}
-// Export ...
+// Export JSON RPC service for remote invocation
func (jp *JsonrpcProtocol) Export(invoker protocol.Invoker) protocol.Exporter {
url := invoker.GetUrl()
serviceKey := strings.TrimPrefix(url.Path, "/")
@@ -74,7 +74,7 @@ func (jp *JsonrpcProtocol) Export(invoker protocol.Invoker) protocol.Exporter {
return exporter
}
-// Refer ...
+// Refer a remote JSON PRC service from registry
func (jp *JsonrpcProtocol) Refer(url common.URL) protocol.Invoker {
//default requestTimeout
var requestTimeout = config.GetConsumerConfig().RequestTimeout
@@ -93,7 +93,7 @@ func (jp *JsonrpcProtocol) Refer(url common.URL) protocol.Invoker {
return invoker
}
-// Destroy ...
+// Destroy will destroy all invoker and exporter, so it only is called once.
func (jp *JsonrpcProtocol) Destroy() {
logger.Infof("jsonrpcProtocol destroy.")
@@ -125,7 +125,7 @@ func (jp *JsonrpcProtocol) openServer(url common.URL) {
}
}
-// GetProtocol ...
+// GetProtocol gets JSON RPC protocol.
func GetProtocol() protocol.Protocol {
if jsonrpcProtocol == nil {
jsonrpcProtocol = NewJsonrpcProtocol()
diff --git a/protocol/jsonrpc/server.go b/protocol/jsonrpc/server.go
index fcea66632..aa458a161 100644
--- a/protocol/jsonrpc/server.go
+++ b/protocol/jsonrpc/server.go
@@ -59,7 +59,7 @@ const (
PathPrefix = byte('/')
)
-// Server ...
+// Server is JSON RPC server wrapper
type Server struct {
done chan struct{}
once sync.Once
@@ -69,7 +69,7 @@ type Server struct {
timeout time.Duration
}
-// NewServer ...
+// NewServer creates new JSON RPC server.
func NewServer() *Server {
return &Server{
done: make(chan struct{}),
@@ -228,7 +228,7 @@ func accept(listener net.Listener, fn func(net.Conn)) error {
}
}
-// Start ...
+// Start JSON RPC server then ready for accept request.
func (s *Server) Start(url common.URL) {
listener, err := net.Listen("tcp", url.Location)
if err != nil {
@@ -255,7 +255,7 @@ func (s *Server) Start(url common.URL) {
}()
}
-// Stop ...
+// Stop JSON RPC server, just can be call once.
func (s *Server) Stop() {
s.once.Do(func() {
close(s.done)
--
GitLab