doc.go

   1 //
   2 // Copyright © 2011-2017 Guy M. Allard
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the "License");
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /*
  18         Package stompngo implements a STOMP 1.1+ compatible client library.
  19         For more STOMP information, see the specification at:
  20         http://stomp.github.com/.
  21
  22
  23         Preparation
  24
  25         Network Connect:
  26
  27         You are responsible for first establishing a network connection.
  28
  29         This network connection will be used when you create a stompngo.Connection to
  30         interact with the STOMP broker.
  31
  32                 h := "localhost"
  33                 p := "61613"
  34                 n, err := net.Dial(stompngo.NetProtoTCP, net.JoinHostPort(h, p))
  35                 if err != nil {
  36                         // Do something sane ...
  37                 }
  38
  39
  40         Shutdown
  41
  42         Network Disconnect:
  43
  44         When processing is complete, you MUST close the network
  45         connection.  If you fail to do this, you will leak goroutines!
  46
  47                 err = n.Close() // Could be defered above, think about it!
  48                 if err != nil {
  49                         // Do something sane ...
  50                 }
  51
  52
  53         STOMP Frames
  54
  55         The STOMP specification defines these physical frames that can be sent from a client to a STOMP broker:
  56                 CONNECT         connect to a STOMP broker, any version.
  57                 STOMP           connect to a STOMP broker, specification version 1.1+ only.
  58                 DISCONNECT      disconnect from a STOMP broker.
  59                 SEND            Send a message to a named queue or topic.
  60                 SUBSCRIBE       Prepare to read messages from a named queue or topic.
  61                 UNSUBSCRIBE     Complete reading messages from a named queue or topic.
  62                 ACK             Acknowledge that a message has been received and processed.
  63                 NACK            Deny that a message has been received and processed, specification version 1.1+ only.
  64                 BEGIN           Begin a transaction.
  65                 COMMIT          Commit a transaction.
  66                 ABORT           Abort a transaction.
  67
  68         The STOMP specification defines these physical frames that a client can receive from a STOMP broker:
  69                 CONNECTED       Broker response upon connection success.
  70                 ERROR           Broker emitted upon any error at any time during an active STOMP connection.
  71                 MESSAGE         A STOMP message frame, possibly with headers and a data payload.
  72                 RECEIPT         A receipt from the broker for a previous frame sent by the client.
  73
  74
  75         Subscribe and MessageData Channels
  76
  77         The Subscribe method returns a channel from which you receive MessageData values.
  78
  79         The channel returned has different characteristics depending on the Stomp Version, and the Headers you pass to Subscribe.
  80
  81         For details on Subscribe requirements and behavior, see: https://github.com/gmallard/stompngo/wiki/subscribe-and-messagedata
  82
  83
  84         RECEIPTs
  85
  86         Receipts are never received on a subscription unique MessageData channel.
  87
  88         They are always queued to the shared connection level
  89         stompgo.Connection.MessageData channel.
  90
  91         The reason for this behavior is because RECEIPT frames do not contain a subscription Header
  92         (per the STOMP specifications).  See the:
  93
  94         https://github.com/gmallard/stompngo_examples
  95
  96         package for several examples.
  97
  98 */
  99 package stompngo