https://github.com/axway/ace-golang-sdk
ECDGS-14676
https://github.com/axway/ace-golang-sdk
Last synced: 6 months ago
JSON representation
ECDGS-14676
- Host: GitHub
- URL: https://github.com/axway/ace-golang-sdk
- Owner: Axway
- License: other
- Created: 2019-01-28T09:36:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-08-16T20:11:03.000Z (almost 7 years ago)
- Last Synced: 2024-06-20T02:06:10.185Z (about 2 years ago)
- Language: Go
- Size: 95.7 KB
- Stars: 2
- Watchers: 9
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Description
ACE SDK allows developers to implement microservices that can be used as executable step in a choreography.
# Service Implemenation and Using the SDK
## Implement the callback method
### The callback method signature
Implement the callback method that will process the received message. Below is the signature of the method
```
func businessMessageProcessor(executionContext linker.ExecutionContext) error
```
### Execution Context
Get the Open Tracing Span Context
```
ctx := executionContext.GetSpanContext();
```
Get the Business Message list
```
businessMsgs := executionContext.GetBusinessMessages();
```
Get the Message Producer Function
```
msgProducer := executionContext.GetMsgProducer();
```
Get a String Config Value
```
stringParamNameValue := executionContext.GetStringConfigValue("stringParamName");
```
Get an Int Config Value
```
intParamNameValue := executionContext.GetIntConfigValue("intParamName");
```
Get a Boolean Config Value
```
boolParamNameValue := executionContext.GetBooleanConfigValue("boolParamName");
```
### Input processing
The businessMsgs is an array of type messaging.BusinessMessage. Each identify a business message and holds the payload and the metadata associated with the payload.
#### Processing payload
The payload can be retrieived using the interface method GetPayload() on businessMsg object.
The payload [type messaging.Payload] can be actual payload (use messaging.Payload.GetBody() to retrieve the content) or a reference to a location (use messaging.Payload.GetLocationReference() to identify if the payload body is location reference)
#### Processing metadata
The metadata can be retrieved using the interface method GetMetaData() on businessMsg object which returns map of string key/value pairs identifying the metadata associated with the payload.
### Output processing
The output of the processing can be responded by generating new message(s). To create a new message construct business message and setup metadata. The new message can then be produced using clientRelay parameter.
#### Creating new ACE business message
- Construct the metadata
Constructing the metadata is done by setting up a map of string key/value pairs
- Contruct the payload
Create the payload with content as demonstrated below. The newContent in the example below is a byte array holding the raw content
```
newPayload := messaging.Payload{Body: newContent}
```
OR
Create the payload with location reference as demonstrated below. The newContent in the example below is a byte array holding the the location reference.
```
newPayload := messaging.Payload{Body: newContent, LocationReference: true}
```
- Construct the ACE business message
Create new business message object as demonstrated below. The "newMetadata" and "newPayload" in the example below identifies the metadata and payload for the new business message
```
newBusinessMsg := messaging.BusinessMessage{ MetaData: newMetadata, Payload: &newPayload}
```
#### Producing message
To produce messages use the Send method on msgProducer parameter as demostrated below
```
msgProducer.Send(&newBusinessMsg)
```
## Add trace for service execution (Optional)
ACE SDK has instrumentation for OpenTracing(https://opentracing.io/specification/) built-in and provides ability to allow the business service to inject the tracing spans.
To start a span as child of span managed by ACE, use StartSpanFromContext method from opentracing package. Using the created span the business service can log details as demonstrated below.
```
span, ctxWithSpan := opentracing.StartSpanFromContext(ctx, "business-service")
span.LogFields(opentractingLog.String("event", "processed message"))
span.Finish()
```
## Add log lines (Optional)
ACE SDK sets up a log object that can be used by the service to add additional logging to the console. Using the provided logger will write the lines consistent with the ACE SDK.
A call to the log method and level will include a message and additional fields provided with zap logger calls. The SDK provides field names that may be used.
```
import "github.com/Axway/ace-golang-sdk/util/logging"
var log = logging.Logger()
log.Debug("Business service config",
zap.String(logging.LogFieldServiceName, cfg.ServiceName),
zap.String(logging.LogFieldServiceVersion, cfg.ServiceVersion),
zap.String(logging.LogFieldServiceType, cfg.ServiceType),
zap.String(logging.LogFieldServiceDesc, cfg.ServiceDescription),
)
```
## Handling errors in the service execution
ACE SDK had three error types defined.
SendingError - Can be returned from calling send method on the MsgProducer.
```
error := msgProducer.Send(&newBusinessMsg)
```
ProcessingError - Returned by the BusinessMessageProcessor.
```
return linker.NewProcessingError(fmt.Errorf("processing error)"))
```
SystemError - Returned by the BusinessMessageProcessor to clientRelay.
```
return linker.NewSystemError(fmt.Errorf("system error)"))
```
## Register the service callback method with ACE
ACE business service must register the service info and callback method for making it usable as a step to build choreographies
The service registration needs following details
- Service Name
- Service Version
- Service Type
- NATIVE
- AGGREGATION
- Service Description
- Callback method
The business service may also define config parameters to be used when using the service in a choreography. These
parameters need to be added prior to registering the callback method
```
# String Parmeters (name, default value, isRequired)
AddStringConfigParam("parameterName", "defaultValue", true)
# Integer Parmeters (name, default value, isRequired)
AddIntConfigParam("parameterName", 123, false)
# Boolean Parmeters (name, default value)
AddBooleanConfigParam("parameterName", false)
```
Below is an example of Registering the service info & callback method and then starting the ACE processing
```
aceAgent, err := linker.Register(serviceName, serviceVersion, serviceDescription, serviceType, businessMessageProcessor)
aceAgent.Start()
```
The provided template reads the serviceName, serviceVersion and serviceDescription from following environment variables respectively, but its the implemenation choice on how to setup these details.
- SERVICE_NAME
- SERVICE_VERSION
- SERVICE_DESCRIPTION