| = 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 |
| |=== |
| |
| |