README.adoc

= Chatterbox

A collection of sample JCA connectors.

== Projects

The following connectors are available:

- IMAP
- Twitter
- XMPP
- Slack

These connectors demonstrate inbound and outbound connectivity, using strongly typed method parameters and an API based
on JAX-RS +@Path+ / +@PathParam+ annotations.

== Annotations

Each connector has an API module that defines a number of annotations. The annotations are defined in pairs, such as
+@Body+ and +@BodyParam+. The method parameter (+@Body+ in this example) optionally allows a regular expression to be
specified as the annotation value. This regular expression should match for the method to be called. The matching +Param+
annotation can be specified on a parameter for the value to be passed into the method. The parameter can optionally
reference a group in the regular expression on the matching method annotation.

Consider the following example:

[source,java,numbered]
----
    @MessageDriven
    public class InboxReader implements MailListener {

        private static final Logger LOGGER = Logger.getLogger(InboxReader.class.getName());

        @Subject("Order {orderId: \\d+}")
        public void logMessage(@FromParam final String from, @SubjectParam final String subject, @BodyParam final String message
            @SubjectParam("orderId") final Integer orderId) {
            // TODO: logic goes here
        }

    }
----

This method will be called for any incoming e-mail where the subject is in the format "Order XXX" where XXX is numerical
and the orderId parameter is set to the part of the subject that matches the order ID. A +Param+ annotation without a
value set, such as +@SubjectParam+ will receive the full value as opposed to the matching regex group.

== Project structure

Each connector consists of an API, implementation, RAR module and a sample WAR file demonstrating simple cases of using
the connector.

In TomEE, the API module should be copied to the +lib/+ directory, the RAR module deployed under +apps/+ and the sample
WAR deployed in +webapps/+.

The WAR module for each project can be executed using the Maven tomee:run plugin. To use this, add the necessary config
settings to ~/.openejb/system.properties (see tables for each connector below) and run `mvn tomee:run` in the WAR module
directory.

== IMAP connector

The IMAP connector will poll the inbox folder for a specified IMAP account every 10 seconds, and invoke matching methods on MDBs that
implement the +MailListener+ interface.

The following annotations are available:

|===
| Method Annotation | Parameter Annotation | Description
| @From
| @FromParam
| Matches the sender of the email. Where a value is specified, on the +@FormParam+ annotation, the value of the parameter will be the portion of the sender's address matching the regex group
| @Subject
| @SubjectParam
| Matches the subject of the email. Where a value is specified, on the +@SubjectParam+ annotation, the value of the parameter will be the portion of the subject matching the regex group
| @Body
| @BodyParam
| Matches the message body of the email. Where a value is specified, on the +@BodyParam+ annotation, the value of the parameter will be the portion of the message body matching the regex group
|===

This connector has the following configuration options:

|===
| Property name | Default | Description
| Host
| No default
| The IMAP host to connect to
| Port
| 993
| The IMAP port
| Username
| No default
| The username to fetch mail for
| Password
| No default
| The password for the user account
|===

== Twitter connector

The Twitter connector opens a long running stream to the specified user's tweets, and invokes MDBs implementing the +TwitterUpdates+
interface. New tweets where the status and/or screen name of the Tweeter match the annotations on the MDB method will cause the
method to be invoked.

The following annotations are available:

|===
| Method Annotation | Parameter Annotation | Description
| @Tweet
| @TweetParam
| Matches the full tweet. Where a value is specified, on the +@TweetParam+ annotation, the value of the parameter will be the portion of the tweet matching the regex group.
| @User
| @UserParam
| Matches the screen name of the user tweeting. Where a value is specified, on the +@UserParam+ annotation, the value of the parameter will be the portion of the user's screen name matching the regex group
|===

This connector has the following configuration options:

|===
| Property name |  Description
| ConsumerKey
| The OAuth Consumer key
| ConsumerSecret
| The OAuth Consumer secret
| AccessToken
| The OAuth Access token
| AccessTokenSecret
| The OAuth Access token secret
|===

These credentials can be obtained by creating a new application on the Twitter Developers site, and authorizing the
application for your Twitter account.

== XMPP connector

The XMPP connector is a bidirectional connector. MDBs can be invoked on messages being sent to the account signed into
the connector. ConnectionFactory and Connection classes can be used in managed components to send messages to other
users.

The following annotations are available:

|===
| Method Annotation | Parameter Annotation | Description
| @Sender
| @SenderParam
| Matches the sender of the message. Where a value is specified, on the +@SenderParam+ annotation, the value of the parameter will be the portion of the sender's address matching the regex group
| @MessageText
| @MessageTextParam
| Matches the text of the message. Where a value is specified, on the +@MessageTextParam+ annotation, the value of the parameter will be the portion of the message matching the regex group
|===

This connector has the following configuration options:

|===
| Property name | Default | Description
| Host
| No default
| The XMPP host to connect to
| Port
| 5222
| The XMPP port
| Username
| No default
| The username to fetch mail for
| Password
| No default
| The password for the user account
| Service name
| No default
| The XMPP service to connect to
|===