Jabber endpoint
The Jabber endpoint is used when you would like to have code invoked when an instant message is received by Martini.
Properties
General configuration
Property | Default | Description |
---|---|---|
Name | (required) | The name of the endpoint. |
Service | (required) | The service to execute when the endpoint is triggered. |
Run As | Anonymous |
The user to run the service in behalf of. This is logged to Tracker. |
Document Type | <Name of endpoint type> | The document type to be used when adding documents to Tracker as this endpoint is triggered. |
Auto Start | true |
Whether or not to automatically start the endpoint upon package startup. |
Log To Tracker | false |
Flag determining whether executions should be logged to Tracker. |
Replicated | true |
If this endpoint is configured on a Martini instance that's running in a cluster, replicated will determine whether to run the endpoint on all instances, or only the elected leader node in the cluster. When this is checked, all instances will run the endpoint. When it's unchecked, only the leader node will run the endpoint. |
Jabber-specific configuration
Name | Default | Description |
---|---|---|
Username | (required) | Jabber client username. |
Password | (required) | Jabber client password. |
Host | (required) | Jabber server host. |
Port | 5222 |
Jabber server port. |
Service Name | (required) | The service name of the XMPP service (i.e., the XMPP domain). |
Reply with Service Response | false |
If set to true , this will automatically reply with the returned value of your service (limited to java.lang.String and groovy.lang.GString ). |
Use Object Converter on Service Response | false |
If set to true , this will allow the endpoint to reply with an object marshalled by an object converter. |
Advanced configuration
For advanced cases, there are more properties available:
Name | Default | Description |
---|---|---|
Security Mode | Default |
Sets the TLS security mode used when making the connection. |
Ping Interval (s) | 20 |
Pings the server periodically. This setting will ensure the connection will not be dropped. |
Connection Timeout (ms) | 50000 |
How long the socket will wait until a TCP connection is established in milliseconds. |
Packet Reply Timeout (ms) | 10000 |
Set the stanza (packet) reply timeout in milliseconds. If no reply to a request was received within the timeout period, an exception will be thrown. |
Resource Name | jabber/{endpoint_name} |
Set the resource to use. If resource is null, then the server will automatically create a resource for the client. |
Keystore Path | Sets the path to the KeyStore file. The key store file contains the certificates that may be used to authenticate the client to the server, in the event the server requests or requires it. | |
Keystore Type | Sets the KeyStore type. | |
PKCS11 Library | Sets the PKCS11 library file location, needed when the KeyStore type is PKCS11. | |
Enable Compression | false |
Sets if the connection is going to use stream compression. Stream compression will be requested after TLS was established (if TLS was enabled) and only if the server offered stream compression. With stream compression, network traffic can be reduced up to 90%. |
Allow Empty Username | false |
Allow null or an empty string as username. Some SASL mechanisms (e.g. SASL External) may also signal the username (as "authorization identity"), in which case Smack should not throw an IllegalArgumentException when the username is not set. |
Allow Reconnection | true |
Enables the automatic reconnection process. |
Send Presence | false |
Determines whether an initial available presence will be sent to the server. By default, an available presence will be sent to the server indicating that this presence is not online and available to receive messages. If you want to log in without being 'noticed' then pass a false value. |
Service
When the endpoint is triggered, the following variables are exposed to the configured service:
General parameters
Name | Type | Description |
---|---|---|
$trackerId |
java.lang.String |
The Tracker document internal ID. If the endpoint was configured to not track, this value will be null . |
$tracker |
io.toro.martini.tracker.Tracker |
The Tracker object. If the endpoint was configured to not track, this value will be null . |
martiniPackage |
MartiniPackage |
The Martini package that contains the endpoint. |
parameters |
java.util.Map |
A map containing all the endpoint specific parameters. |
properties |
java.util.Map |
A map containing containing all the properties associated with the endpoint. |
Jabber-specific parameters
Name | Type | Description |
---|---|---|
message |
io.toro.martini.jabber.Message |
The message object. |
content |
java.lang.String |
The default body of the message, or null if the body has not been set. The body is the main message content. |
error |
io.toro.martini.jabber.XMPPError |
The error associated with this packet, or null if there are no errors. |
chat |
io.toro.martini.jabber.Chat |
Jabber chat client which can be used to send messages & perform other operations. |
to |
java.lang.String |
The stanza (packet) is being sent "to", or null if the value is not set. The XMPP protocol often makes the "to" attribute optional, so it does not always need to be set. |
from |
java.lang.String |
The stanza (packet) is being sent "from" or null if the value is not set. The XMPP protocol often makes the "from" attribute optional, so it does not always need to be set. |
subject |
java.lang.String |
The subject of the message, or null if the subject has not been set. The subject is a short description of the message's contents. |
language |
java.lang.String |
The language, or null if one has not been set. |
threadId |
java.lang.String |
The thread ID of the message, which is a unique identifier for a sequence of "chat" messages. If no thread ID is set, null will be returned. |
Name | Type | Description |
---|---|---|
message |
Message |
The message object. |
content |
java.lang.String |
The default body of the message, or null if the body has not been set. The body is the main message content. |
error |
XMPPError |
The error associated with this packet, or null if there are no errors. |
chat |
Chat |
Jabber chat client which can be used to send messages & perform other operations. |
to |
java.lang.String |
The stanza (packet) is being sent "to", or null if the value is not set. The XMPP protocol often makes the "to" attribute optional, so it does not always need to be set. |
from |
java.lang.String |
The stanza (packet) is being sent "from" or null if the value is not set. The XMPP protocol often makes the "from" attribute optional, so it does not always need to be set. |
subject |
java.lang.String |
The subject of the message, or null if the subject has not been set. The subject is a short description of the message's contents. |
language |
java.lang.String |
The language, or null if one has not been set. |
threadId |
java.lang.String |
The thread ID of the message, which is a unique identifier for a sequence of "chat" messages. If no thread ID is set, null will be returned. |
Example
Gloop as service
Consider the following endpoint configuration, for Atlassian's Hipchat:
It uses a Gloop service called GuessingGame
, which asks the user what number it currently "thinks" of. The service
responds with hints as to whether the actual number is higher or lower than the current guess. See it in action:
Groovy as service
Consider the following Groovy stub:
1 2 3 4 5 6 7 |
|
By querying the properties from the injected Message
, we can add conditions that direct the behavior of the replies,
such as inviting the user for a guessing game. The returned String
value in this method is sent back to the user as
a chat reply.
Similar to the Gloop example, we can configure the endpoint into the following:
... the only difference being, this time we use our GuessingGame
code as the endpoint service.
Want more examples?
The distribution ships with a Martini package called examples
, which
contains services demonstrating more use cases.