xml

Documentation

Overview

Package xml defines types that are specific to handling web service requests and responses as XML. Components implementing this type will be created when you enable the XMLWs facility. For more information on XML web services in Granitic, see https://granitic.io/ref/xml-web-services

Unmarshalling

HTTP request bodies sent to a Granitic application with the XMLWs facility enabled are unmarshalled from XML into a Go struct using Go's built-in XML unmarshalling techniques. See https://golang.org/pkg/encoding/xml/#Unmarshal

Templated or marshalling mode

The data generated by your web service endpoints can be serialised to XML in two ways by setting either:

{
  "XMLWs": {
	"ResponseMode": "MARSHAL"
  }
}

or

{
  "XMLWs": {
	"ResponseMode": "TEMPLATE"
  }
}

in your application configuration file.

In MARSHAL mode the data and errors in your endpoint's Response objects are serialised using Go's built-in XML marshalling techniques. See https://golang.org/pkg/encoding/xml/#Marshal. In TEMPLATE mode each endpoint is associated with the name of a template file which is populated with the data and errors in your response. See https://granitic.io/ref/xml-web-services for more details.

Response wrapping

In MARSHAL mode, any data serialised to XML will first be wrapped with a containing data structure by an instance of GraniticXMLResponseWrapper. This means that all responses share a common top level structure for finding the body of the response or errors if they exist. For more information on this behaviour (and how to override it) see: https://granitic.io/ref/xml-web-services

Error formatting

Any service errors found in a response are formatted by an instance of GraniticXMLErrorFormatter before being serialised to XML. For more information on this behaviour (and how to override it) see: https://granitic.io/ref/xml-web-services

Index

• type Errors
• type GraniticError
• type GraniticXMLErrorFormatter
  • func (ef *GraniticXMLErrorFormatter) FormatErrors(errors *ws.ServiceErrors) interface{}
• type GraniticXMLResponseWrapper
  • func (rw *GraniticXMLResponseWrapper) WrapResponse(body interface{}, errors interface{}) interface{}
• type GraniticXMLWrapper
• type MarshalingWriter
  • func (mw *MarshalingWriter) MarshalAndWrite(data interface{}, w http.ResponseWriter) error
• type TemplatedXMLResponseWriter
  • func (rw *TemplatedXMLResponseWriter) StartComponent() error
  • func (rw *TemplatedXMLResponseWriter) Write(ctx context.Context, state *ws.ProcessState, outcome ws.Outcome) error
  • func (rw *TemplatedXMLResponseWriter) WriteAbnormalStatus(ctx context.Context, state *ws.ProcessState) error
• type Unmarshaller
  • func (um *Unmarshaller) Unmarshall(ctx context.Context, req *http.Request, wsReq *ws.Request) error

Types

type Errors

type Errors struct {
	XMLName xml.Name
	Errors  interface{}
}

Errors is a wrapper to create an errors element in generated XML

type GraniticError

type GraniticError struct {
	XMLName  xml.Name
	Error    string `xml:",chardata"`
	Field    string `xml:"field,attr,omitempty"`
	Code     string `xml:"code,attr,omitempty"`
	Category string `xml:"category,attr,omitempty"`
}

GraniticError is the default XML representation of a service error. See ws.CategorisedError

type GraniticXMLErrorFormatter

type GraniticXMLErrorFormatter struct{}

GraniticXMLErrorFormatter converts service errors into a data structure for consistent serialisation to XML.

func (*GraniticXMLErrorFormatter) FormatErrors

func (ef *GraniticXMLErrorFormatter) FormatErrors(errors *ws.ServiceErrors) interface{}

FormatErrors converts all of the errors present in the supplied objects into a structure suitable for serialisation.

type GraniticXMLResponseWrapper

type GraniticXMLResponseWrapper struct {
}

GraniticXMLResponseWrapper is a component for wrapping response data in a common strcuture before it is serialised.

func (*GraniticXMLResponseWrapper) WrapResponse

func (rw *GraniticXMLResponseWrapper) WrapResponse(body interface{}, errors interface{}) interface{}

WrapResponse wraps the supplied data and errors with an XMLWrapper

type GraniticXMLWrapper

type GraniticXMLWrapper struct {
	XMLName xml.Name
	Errors  interface{}
	Body    interface{} `xml:"body"`
}

GraniticXMLWrapper is a wrapper for web service data and errors giving a consistent structure across all XML endpoints.

type MarshalingWriter

type MarshalingWriter struct {
	// Format generated XML in a human readable form.
	PrettyPrint bool

	// The characters (generally tabs or spaces) to indent child elements in pretty-printed XML.
	IndentString string

	// A prefix for each line of generated XML.
	PrefixString string
}

MarshalingWriter is a component wrapper over Go's xml.Marshalxx functions. Serialises a struct to XML and writes it to the HTTP response output stream.

func (*MarshalingWriter) MarshalAndWrite

func (mw *MarshalingWriter) MarshalAndWrite(data interface{}, w http.ResponseWriter) error

MarshalAndWrite serialises the supplied interface to XML and writes it to the HTTP response output stream.

type TemplatedXMLResponseWriter

type TemplatedXMLResponseWriter struct {
	// Injected by the framework to allow this component to write log messages
	FrameworkLogger logging.Logger

	// A component able to calculate the correct HTTP status code to set for a response.
	StatusDeterminer ws.HTTPStatusCodeDeterminer

	// Component able to generate errors if a problem is encountered during marshalling.
	FrameworkErrors *ws.FrameworkErrorGenerator

	// The common and static set of headers that should be written to all responses.
	DefaultHeaders map[string]string

	// The path (absolute or relative to application working directory) where unpopulated template files can be found.
	TemplateDir string

	// A map from an HTTP status code (e.g. '404') to the name of the template to be used to render that type of response.
	StatusTemplates map[string]string

	// Component able to dynamically generate additional headers to be written to the response.
	HeaderBuilder ws.CommonResponseHeaderBuilder

	//The name of a template to be used if the response has an abnormal (5xx) outcome.
	AbnormalTemplate string

	//The name of the default template to use if the response an error (400 or 409) outcome.
	ErrorTemplate string
	// contains filtered or unexported fields
}

TemplatedXMLResponseWriter serialises the body of a ws.Response to XML using Go templates. See https://golang.org/pkg/text/template/

func (*TemplatedXMLResponseWriter) StartComponent

func (rw *TemplatedXMLResponseWriter) StartComponent() error

StartComponent is called by the IoC container. Verifies that at minimum the AbnormalTemplate and TemplateDir fields are set. Parses all templates found in the TemplateDir

func (*TemplatedXMLResponseWriter) Write

func (rw *TemplatedXMLResponseWriter) Write(ctx context.Context, state *ws.ProcessState, outcome ws.Outcome) error

Write implements ResponseWriter.Write

func (*TemplatedXMLResponseWriter) WriteAbnormalStatus

func (rw *TemplatedXMLResponseWriter) WriteAbnormalStatus(ctx context.Context, state *ws.ProcessState) error

WriteAbnormalStatus implements AbnormalStatusWriter.WriteAbnormalStatus

type Unmarshaller

type Unmarshaller struct {
}

Unmarshaller is a component wrapper over Go's xml.Unmarshal method

func (*Unmarshaller) Unmarshall

func (um *Unmarshaller) Unmarshall(ctx context.Context, req *http.Request, wsReq *ws.Request) error

Unmarshall decodes XML into a Go struct using Go's builtin xml.Unmarshal method.