SENV.md

   1 # senv - A stompngo helper (sub) package
   2
   3 The intent of this package is to assist the clients of the
   4 _stompngo_ package when developing and using _stompngo_ client application
   5 code.
   6
   7 This assistance is _primarily_ implemented in the form of environment variables:
   8
   9 * export=STOMP_var=value (Unix systems)
  10 * set STOMP_var=value (Windows systems)
  11
  12 Using these environment variables can help avoid or eliminate 'hard coding'
  13 values in the client code.
  14
  15 Environment variables and related subjects are discussed in the following sections:
  16
  17 * [Supported Environment Variables](#senv)
  18 * [Supported Helper Function](#shf)
  19 * [Example Code Fragments](#ecf)
  20 * [Complete Connect Header Fragment](#cchf)
  21 <br />
  22
  23 ---
  24
  25 ## <a name="sev"></a>Supported Environment Variables
  26
  27 The following table shows currently supported environment variables.
  28
  29 <table border="1" style="width:80%;border: 1px solid black;">
  30 <tr>
  31 <th style="width:20%;border: 1px solid black;padding-left: 10px;" >
  32 Environment Variable Name
  33 </th>
  34 <th style="width:60%border: 1px solid black;padding-left: 10px;" >
  35 Usage
  36 </th>
  37 </tr>
  38
  39 <tr>
  40 <td style="border: 1px solid black;padding-left: 10px;" >
  41 STOMP_DEST
  42 </td>
  43 <td style="border: 1px solid black;padding-left: 10px;" >
  44 A destination to be used by the client.<br />
  45 Default: /queue/sng.sample.stomp.destination
  46 </td>
  47 </tr>
  48
  49 <tr>
  50 <td style="border: 1px solid black;padding-left: 10px;" >
  51 STOMP_HEARTBEATS
  52 </td>
  53 <td style="border: 1px solid black;padding-left: 10px;" >
  54 For protocol 1.1+, the heart-beat value to be used by the client in the CONNECT frame.<br />
  55 Default: 0,0
  56 </td>
  57 </tr>
  58
  59 <tr>
  60 <td style="border: 1px solid black;padding-left: 10px;" >
  61 STOMP_HOST
  62 </td>
  63 <td style="border: 1px solid black;padding-left: 10px;" >
  64 The broker host to connect to.<br />
  65 Default: localhost
  66 </td>
  67 </tr>
  68
  69 <tr>
  70 <td style="border: 1px solid black;padding-left: 10px;" >
  71 STOMP_LOGIN
  72 </td>
  73 <td style="border: 1px solid black;padding-left: 10px;" >
  74 The login to be used by the client in the CONNECT frame.<br />
  75 Default: guest
  76 </td>
  77 </tr>
  78
  79 <tr>
  80 <td style="border: 1px solid black;padding-left: 10px;" >
  81 STOMP_NMSGS
  82 </td>
  83 <td style="border: 1px solid black;padding-left: 10px;" >
  84 A default nummber of messages to receive or send.  Useful for some clients.<br />
  85 Default: 1
  86 </td>
  87 </tr>
  88
  89 <tr>
  90 <td style="border: 1px solid black;padding-left: 10px;" >
  91 STOMP_PASSCODE
  92 </td>
  93 <td style="border: 1px solid black;padding-left: 10px;" >
  94 The passcode to be used by the client in the CONNECT frame.<br />
  95 Default: guest
  96 </td>
  97 </tr>
  98
  99 <tr>
 100 <td style="border: 1px solid black;padding-left: 10px;" >
 101 STOMP_PERSISTENT
 102 </td>
 103 <td style="border: 1px solid black;padding-left: 10px;" >
 104 May control use of the persistent header in SEND frames.<br />
 105 Default: no persistent header to be used.<br />
 106 Example:<br />
 107 STOMP_PERSISTENT=anyvalue
 108 </td>
 109 </tr>
 110
 111 <tr>
 112 <td style="border: 1px solid black;padding-left: 10px;" >
 113 STOMP_PORT
 114 </td>
 115 <td style="border: 1px solid black;padding-left: 10px;" >
 116 The broker port to connect to.<br />
 117 Default: 61613
 118 </td>
 119 </tr>
 120
 121 <tr>
 122 <td style="border: 1px solid black;padding-left: 10px;" >
 123 STOMP_PROTOCOL
 124 </td>
 125 <td style="border: 1px solid black;padding-left: 10px;" >
 126 For protocol 1.1+, the accept-version value to be used by the client in the CONNECT frame.<br />
 127 Default: 1.2<br />
 128 Multiple versions may be used per the STOMP specifications, e.g.:<br />
 129 STOMP_PROTOCOL="1.0,1.1,1.2"
 130 </td>
 131 </tr>
 132
 133 <tr>
 134 <td style="border: 1px solid black;padding-left: 10px;" >
 135 STOMP_SUBCHANCAP
 136 </td>
 137 <td style="border: 1px solid black;padding-left: 10px;" >
 138 Used to possibly override the default capacity of _stompngo_ subscription channels.<br />
 139 Default: 1 (the same as the _stompngo_ default.)
 140 </td>
 141 </tr>
 142
 143 <tr>
 144 <td style="border: 1px solid black;padding-left: 10px;" >
 145 STOMP_VHOST
 146 </td>
 147 <td style="border: 1px solid black;padding-left: 10px;" >
 148 For protocol 1.1+, the host value to be used by the client in the CONNECT frame.<br />
 149 Default: If not specified the default is STOMP_HOST (i.e. localhost).
 150 </td>
 151 </tr>
 152 </table>
 153
 154 <br />
 155
 156 ---
 157
 158 ## <a name="shf"></a>Supported Helper Function
 159
 160 There is currently one helper function also provided by the _senv_ package.
 161
 162 <table border="1" style="width:80%;border: 1px solid black;">
 163 <tr>
 164 <th style="width:20%;border: 1px solid black;padding-left: 10px;" >
 165 Function Name
 166 </th>
 167 <th style="width:60%border: 1px solid black;padding-left: 10px;" >
 168 Usage
 169 </th>
 170 </tr>
 171
 172 <tr>
 173 <td style="border: 1px solid black;padding-left: 10px;" >
 174 HostAndPort()
 175 </td>
 176 <td style="border: 1px solid black;padding-left: 10px;" >
 177 This function returns two values, the STOMP_HOST and STOMP_PORT values.<br />
 178 Example:<br />
 179 h, p := senv.HostAndPort()
 180 </td>
 181 </tr>
 182
 183 </table>
 184
 185 <br />
 186
 187 ---
 188
 189 ## <a name="ecf"></a>Example Code Fragments
 190
 191 Example code fragments follow.
 192
 193 ### STOMP_DEST Code Fragment
 194
 195         sbh := ..... // Subscribe header, type stompngo.Headers
 196         if senv.Dest() != "" {
 197             sbh = sbh.Add("destination", senv.Dest())
 198         }
 199
 200 ### STOMP_HEARTBEATS Code Fragment
 201
 202         ch := ..... // Connect headers, type stompngo.Headers
 203         if senv.Heartbeats() != "" {
 204             ch = ch.Add("heart-beat", senv.Heartbeats())
 205         }
 206
 207 ### STOMP_HOST Code Fragment
 208
 209         ch := ..... // Connect headers, type stompngo.Headers
 210         if senv.Host() != "" {
 211             ch = ch.Add("host", senv.Host())
 212         }
 213
 214 ### STOMP_LOGIN Code Fragment
 215
 216         ch := ..... // Connect headers, type stompngo.Headers
 217         if senv.Login() != "" {
 218             ch = ch.Add("login", senv.Login())
 219         }
 220
 221 ### STOMP_NMSGS Code Fragment
 222
 223     msg_count := senv.Nmsgs() // Default is 1
 224
 225 ### STOMP_PASSCODE Code Fragment
 226
 227         ch := ..... // Connect headers, type stompngo.Headers
 228         if senv.Passcode() != "" {
 229             ch = ch.Add("passcode", senv.Passcode())
 230         }
 231
 232 ### STOMP_PERSISTENT Code Fragment
 233
 234         sh := ..... // Send headers, type stompngo.Headers
 235         if senv.Persistent() != "" {
 236             ch = ch.Add("persistent", "true") // Brokers might need 'true' here
 237         }
 238
 239 ### STOMP_PORT Code Fragment
 240
 241         ch := ..... // Connect headers, type stompngo.Headers
 242         if senv.Port() != "" {
 243             ch = ch.Add("port", senv.Port())
 244         }
 245
 246 ### STOMP_PROTOCOL Code Fragment
 247
 248         ch := ..... // Connect headers, type stompngo.Headers
 249         if senv.Protocol() != "" {
 250             ch = ch.Add("accept-version", senv.Protocol())
 251         }
 252
 253 ### STOMP_VHOST Code Fragment
 254
 255         ch := ..... // Connect headers, type stompngo.Headers
 256         if senv.Vhost() != "" {
 257             ch = ch.Add("host", senv.Vhost())
 258         }
 259 <br />
 260
 261 ---
 262
 263 ## <a name="cchf"></a>Complete Connect Header Fragment
 264
 265 Obtaining a full set of headers to use for a _stompngo.Connect_ might
 266 look like this:
 267
 268         func ConnectHeaders() stompngo.Headers {
 269           h := stompngo.Headers{}
 270           l := senv.Login()
 271           if l != "" {
 272               h = h.Add("login", l)
 273           }
 274           pc := senv.Passcode()
 275           if pc != "" {
 276               h = h.Add("passcode", pc)
 277           }
 278           //
 279           p := senv.Protocol()
 280           if p != stompngo.SPL_10 { // 1.1 and 1.2
 281               h = h.Add("accept-version", p).Add("host", senv.Vhost())
 282           }
 283           //
 284           hb := senv.Heartbeats()
 285           if hb != "" {
 286               h = h.Add("heart-beat", hb)
 287           }
 288           return h
 289         }
 290