Documentation
¶
Overview ¶
Package amqp encodes and decodes AMQP 1.0 messages and data types as Go types.
It follows the standard 'encoding' libraries pattern. The mapping between AMQP and Go types is described in the documentation of the Marshal and Unmarshal functions.
Package 'electron' is a full AMQP 1.0 client/server toolkit using this package.
AMQP 1.0 is an open standard for inter-operable message exchange, see <http://www.amqp.org/>
Index ¶
- Variables
- func Marshal(v interface{}, buffer []byte) (outbuf []byte, err error)
- func ParseURL(s string) (u *url.URL, err error)
- func PnError(e *C.pn_error_t) error
- func Unmarshal(bytes []byte, v interface{}) (n int, err error)
- func UpdateURL(in *url.URL) (err error)
- type Binary
- type Decoder
- type Encoder
- type Error
- type List
- type Map
- type Message
- type PnErrorCode
- type Symbol
- type UnmarshalError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( InternalError = "amqp:internal-error" NotFound = "amqp:not-found" DecodeError = "amqp:decode-error" ResourceLimitExceeded = "amqp:resource-limit-exceeded" NotAllowed = "amqp:not-allowed" InvalidField = "amqp:invalid-field" NotImplemented = "amqp:not-implemented" ResourceLocked = "amqp:resource-locked" PreconditionFailed = "amqp:precondition-failed" ResourceDeleted = "amqp:resource-deleted" IllegalState = "amqp:illegal-state" FrameSizeTooSmall = "amqp:frame-size-too-small" )
Functions ¶
func Marshal ¶
Marshal encodes a Go value as AMQP data in buffer. If buffer is nil, or is not large enough, a new buffer is created.
Returns the buffer used for encoding with len() adjusted to the actual size of data.
Go types are encoded as follows
+-------------------------------------+--------------------------------------------+
|Go type |AMQP type |
+-------------------------------------+--------------------------------------------+
|bool |bool |
+-------------------------------------+--------------------------------------------+
|int8, int16, int32, int64 (int) |byte, short, int, long (int or long) |
+-------------------------------------+--------------------------------------------+
|uint8, uint16, uint32, uint64 (uint) |ubyte, ushort, uint, ulong (uint or ulong) |
+-------------------------------------+--------------------------------------------+
|float32, float64 |float, double. |
+-------------------------------------+--------------------------------------------+
|string |string |
+-------------------------------------+--------------------------------------------+
|[]byte, Binary |binary |
+-------------------------------------+--------------------------------------------+
|Symbol |symbol |
+-------------------------------------+--------------------------------------------+
|interface{} |the contained type |
+-------------------------------------+--------------------------------------------+
|nil |null |
+-------------------------------------+--------------------------------------------+
|map[K]T |map with K and T converted as above |
+-------------------------------------+--------------------------------------------+
|Map |map, may have mixed types for keys, values |
+-------------------------------------+--------------------------------------------+
|[]T |list with T converted as above |
+-------------------------------------+--------------------------------------------+
|List |list, may have mixed types values |
+-------------------------------------+--------------------------------------------+
The following Go types cannot be marshaled: uintptr, function, interface, channel
TODO ¶
Go types: array, slice, struct, complex64/128.
AMQP types: decimal32/64/128, char, timestamp, uuid, array, multi-section message bodies.
Described types.
func ParseURL ¶
ParseUrl parses an AMQP URL string and returns a net/url.Url.
It is more forgiving than net/url.Parse and allows most of the parts of the URL to be missing, assuming AMQP defaults.
Example ¶
for _, s := range []string{
"amqp://username:password@host:1234/path",
"host:1234",
"host",
"host/path",
"amqps://host",
"/path",
"",
":1234",
// Taken out becasue the go 1.4 URL parser isn't the same as later
//"[::1]",
//"[::1",
// Output would be:
// amqp://[::1]:amqp
// parse amqp://[::1: missing ']' in host
} {
u, err := ParseURL(s)
if err != nil {
fmt.Println(err)
} else {
fmt.Println(u)
}
}
Output: amqp://username:password@host:1234/path amqp://host:1234 amqp://host:amqp amqp://host:amqp/path amqps://host:amqps amqp://localhost:amqp/path amqp://localhost:amqp parse :1234: missing protocol scheme
func PnError ¶
func PnError(e *C.pn_error_t) error
func Unmarshal ¶
Unmarshal decodes AMQP-encoded bytes and stores the result in the value pointed to by v. Types are converted as follows:
+---------------------------+----------------------------------------------------------------------+
|To Go types |From AMQP types |
+===========================+======================================================================+
|bool |bool |
+---------------------------+----------------------------------------------------------------------+
|int, int8, int16, |Equivalent or smaller signed integer type: byte, short, int, long. |
|int32, int64 | |
+---------------------------+----------------------------------------------------------------------+
|uint, uint8, uint16, |Equivalent or smaller unsigned integer type: ubyte, ushort, uint, |
|uint32, uint64 types |ulong |
+---------------------------+----------------------------------------------------------------------+
|float32, float64 |Equivalent or smaller float or double. |
+---------------------------+----------------------------------------------------------------------+
|string, []byte |string, symbol or binary. |
+---------------------------+----------------------------------------------------------------------+
|Symbol |symbol |
+---------------------------+----------------------------------------------------------------------+
|map[K]T |map, provided all keys and values can unmarshal to types K, T |
+---------------------------+----------------------------------------------------------------------+
|Map |map, any AMQP map |
+---------------------------+----------------------------------------------------------------------+
|interface{} |Any AMQP value can be unmarshaled to an interface{} as follows: |
| +------------------------+---------------------------------------------+
| |AMQP Type |Go Type in interface{} |
| +========================+=============================================+
| |bool |bool |
| +------------------------+---------------------------------------------+
| |byte,short,int,long |int8,int16,int32,int64 |
| +------------------------+---------------------------------------------+
| |ubyte,ushort,uint,ulong |uint8,uint16,uint32,uint64 |
| +------------------------+---------------------------------------------+
| |float, double |float32, float64 |
| +------------------------+---------------------------------------------+
| |string |string |
| +------------------------+---------------------------------------------+
| |symbol |Symbol |
| +------------------------+---------------------------------------------+
| |binary |Binary |
| +------------------------+---------------------------------------------+
| |nulll |nil |
| +------------------------+---------------------------------------------+
| |map |Map |
| +------------------------+---------------------------------------------+
| |list |List |
+---------------------------+------------------------+---------------------------------------------+
The following Go types cannot be unmarshaled: uintptr, function, interface, channel.
TODO ¶
Go types: array, struct.
AMQP types: decimal32/64/128, char (round trip), timestamp, uuid, array, multi-section message bodies.
AMQP maps with mixed/unhashable key types need an alternate representation.
Described types.
Types ¶
type Binary ¶
type Binary string
Binary is a string that is encoded as an AMQP binary. It is a string rather than a byte[] because byte[] is not hashable and can't be used as a map key, AMQP frequently uses binary types as map keys. It can convert to and from []byte
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder decodes AMQP values from an io.Reader.
func NewDecoder ¶
NewDecoder returns a new decoder that reads from r.
The decoder has it's own buffer and may read more data than required for the AMQP values requested. Use Buffered to see if there is data left in the buffer.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder encodes AMQP values to an io.Writer
func NewEncoder ¶
New encoder returns a new encoder that writes to w.
type Error ¶
type Error struct{ Name, Description string }
Error is an AMQP error condition. It has a name and a description. It implements the Go error interface so can be returned as an error value.
You can pass amqp.Error to methods that send an error to a remote endpoint, this gives you full control over what the remote endpoint will see.
You can also pass any Go error to such functions, the remote peer will see the equivalent of MakeError(error)
type List ¶
type List []interface{}
List is a generic list that can hold mixed values and can represent any AMQP list.
type Map ¶
type Map map[interface{}]interface{}
Map is a generic map that can have mixed key and value types and so can represent any AMQP map
type Message ¶
type Message interface {
// Durable indicates that any parties taking responsibility
// for the message must durably store the content.
Durable() bool
SetDurable(bool)
// Priority impacts ordering guarantees. Within a
// given ordered context, higher priority messages may jump ahead of
// lower priority messages.
Priority() uint8
SetPriority(uint8)
// TTL or Time To Live, a message it may be dropped after this duration
TTL() time.Duration
SetTTL(time.Duration)
// FirstAcquirer indicates
// that the recipient of the message is the first recipient to acquire
// the message, i.e. there have been no failed delivery attempts to
// other acquirers. Note that this does not mean the message has not
// been delivered to, but not acquired, by other recipients.
FirstAcquirer() bool
SetFirstAcquirer(bool)
// DeliveryCount tracks how many attempts have been made to
// delivery a message.
DeliveryCount() uint32
SetDeliveryCount(uint32)
// MessageId provides a unique identifier for a message.
// it can be an a string, an unsigned long, a uuid or a
// binary value.
MessageId() interface{}
SetMessageId(interface{})
UserId() string
SetUserId(string)
Address() string
SetAddress(string)
Subject() string
SetSubject(string)
ReplyTo() string
SetReplyTo(string)
// CorrelationId is set on correlated request and response messages. It can be
// an a string, an unsigned long, a uuid or a binary value.
CorrelationId() interface{}
SetCorrelationId(interface{})
ContentType() string
SetContentType(string)
ContentEncoding() string
SetContentEncoding(string)
// ExpiryTime indicates an absoulte time when the message may be dropped.
// A Zero time (i.e. t.isZero() == true) indicates a message never expires.
ExpiryTime() time.Time
SetExpiryTime(time.Time)
CreationTime() time.Time
SetCreationTime(time.Time)
GroupId() string
SetGroupId(string)
GroupSequence() int32
SetGroupSequence(int32)
ReplyToGroupId() string
SetReplyToGroupId(string)
// Instructions - AMQP delivery instructions.
Instructions() map[string]interface{}
SetInstructions(v map[string]interface{})
// Annotations - AMQP annotations.
Annotations() map[string]interface{}
SetAnnotations(v map[string]interface{})
// Properties - Application properties.
Properties() map[string]interface{}
SetProperties(v map[string]interface{})
// Inferred indicates how the message content
// is encoded into AMQP sections. If inferred is true then binary and
// list values in the body of the message will be encoded as AMQP DATA
// and AMQP SEQUENCE sections, respectively. If inferred is false,
// then all values in the body of the message will be encoded as AMQP
// VALUE sections regardless of their type.
Inferred() bool
SetInferred(bool)
// Marshal a Go value into the message body. See amqp.Marshal() for details.
Marshal(interface{})
// Unmarshal the message body into the value pointed to by v. See amqp.Unmarshal() for details.
Unmarshal(interface{})
// Body value resulting from the default unmarshalling of message body as interface{}
Body() interface{}
// Encode encodes the message as AMQP data. If buffer is non-nil and is large enough
// the message is encoded into it, otherwise a new buffer is created.
// Returns the buffer containing the message.
Encode(buffer []byte) ([]byte, error)
// Decode data into this message. Overwrites an existing message content.
Decode(buffer []byte) error
// Clear the message contents.
Clear()
// Copy the contents of another message to this one.
Copy(m Message) error
}
Message is the interface to an AMQP message.
func DecodeMessage ¶
func NewMessageWith ¶
func NewMessageWith(value interface{}) Message
NewMessageWith creates a message with value as the body. Equivalent to
m := NewMessage(); m.Marshal(body)
type PnErrorCode ¶
type PnErrorCode int
func (PnErrorCode) String ¶
func (e PnErrorCode) String() string
type UnmarshalError ¶
type UnmarshalError struct {
// The name of the AMQP type.
AMQPType string
// The Go type.
GoType reflect.Type
}
Error returned if AMQP data cannot be unmarshaled as the desired Go type.
func (UnmarshalError) Error ¶
func (e UnmarshalError) Error() string
Source Files