Introducing the SMS Service
for Lutris EAS 4
Andy John & Klaus Krull, Lutris Technologies
The Lutris EAS SMS Service is a hot deployable platform service that
adds Short Message Service (SMS) capabilities to Lutris EAS. The SMS Service
adds the following capabilities to Lutris EAS:
- Dynamically add SMS capabilities to a running instance of Lutris EAS
- Send SMS messages from within applications or services, such as the
Lutris EAS Scheduler Service.
- Support for third-party SMS service providers
- "Send" messages to the log file for testing purposes.
- Send Lutris EAS log messages to SMS enabled devices.
Lutris SMS
Service Overview
The SMS Service distribution contains three key components:
- the SMS Service itself,
- the SMSSampleClient example application, and
- a Lutris EAS logging pipeline.
The SMS Service gives Lutris EAS the ability to send messages via SMS
(mt-sms) through 3rd party SMS service providers. The service contains
default phone numbers, so clients may either use the SMS service to send
messages directly to a known user or to the configured default recipient.
The latter case could be used, for example, by a system administrator
who wants all such messages to go to her cell phone. Simply by changing
the default number, someone else gets the messages without having to change
the sending applications.
The SMS Service uses a plug-in architecture to support multiple SMS service
providers and currently includes two plug-ins: one for use with NovelSoft
(http://www.novelsoft.ch/),
and a "no-op" plug-in (default) that writes messages to the Lutris EAS
log file (good for testing).
click for larger image.
The SMSSampleClient is an example Web application that can be used to
manually send messages. It is provided for testing and as example code
for developers who wish to use the SMS service.
The optional logging pipeline forwards selected logging messages to the
SMS service (using the default SMS recipient). The log level (debug, warning,
emergency etc...) and/or the log channel name may be specified. The default
log level is DEBUG9 and the default channel is "SMS". SMS messages have
a limited length, so if the log message is too long it is split up and
sent as multiple messages. SMS messages may arrive out of order, so the
logger prepends a message # to keep things straight.
Each of the 3 pieces may be deployed independently using the deploy tool,
the Lutris Management Console (LMC), or by copying to the deploy directory.
To install and use the SMS Service: (more detailed information
is available in the doc/install.txt file)
- Deploy the SMS Service (
<sms_root>\services\SMSService.jar ).
- Deploy the SMS sample client (
<sms_root>\examples\SMSSampleClient\SMSSampleClient.war ).
- Use the SMS sample client to send messages
- View results (by default) in the Lutris EAS log file (
<eas_root>\logs\ems.log )
- Optionally deploy the logging pipeline (
<sms_root>\logging\SMSLogPipeline.jar ).
This sends selected log messages through the SMS service, which can
also be tested from the SMS sample client.
The Lutris EAS SMS service performs no actions on its own - it provides
methods for applications to call. the SMS sample client is provided as
a simple test case in addition to providing sample code.
Testing Using the SMSSampleClient
You can use the SMS sample client to send messages. This lets you test
the SMS service, or use it to send live messages. It's mission in life
is testing and being sample code to show developers how to connect to
and use the SMS service.
By default, the no-op plug-in is used, which writes messages to the Lutris
EAS log file without actually sending them via SMS. It is meant for debugging
and development use: create and test an application using it and then
switch to a real SMS service provider without making any source code changes.
To view the results in the Lutris EAS log file:
- UNIX: "tail -f" on the <eas_root>\logs\ems.log file (before
sending the message).
- Windows: open the <eas_root>\logs\ ems.log file in an
editor (after sending the message).
- Lutris Management Console: from the menu, select
Server|Display
Log|localhost:1099.
Sending SMS Messages
SMS messages can be easily sent from applications and services using
the following steps:
- Look up the SMS service via JNDI:
SMSService service = (SMSService) new InitialContext().lookup("ems:/Services/SMSService/manager");
- Send the message:
SMSStatus stat = service.send("<recipient phone number>",
"<messsage to send>");
- Respond appropriately to the returned status information.
More robust sample code with error checking can be found within the sendSMS()
method in the <sms_root>\examples\SMSSampleClient\com\lutris\service\smsService\sampleClient\presentation\SendServlet.java
file.
Using an SMS Service Provider
The easiest way to send live SMS messages is to create an account with
NovelSoft :
lutris-eas4/lutris-sms-service/doc/www.novelsoft.ch).
An account can be opened for $20.00 that provides 200 messages, $0.10 for
each additional message.
Once an account has been created with NovelSoft, the SMS Service needs
to be configured to use the NovelSoft plug. In this technology preview,
this is done by editing the enhydra-service.xml file inside
of the SMSService.jar file:
- Extract the
enhydra-service.xml file from the <sms_root>\services\SMSService.jar
file.
- Search for the following lines inside the
enhydra-service.xml
file:
<!-- USE THIS PLUGIN FOR TESTING -->
<property name="pluginClass" type="java.lang.String" value="com.lutris.service.smsService.noop.NoopPlugin"/>
<!-- USE THIS PLUGIN TO SEND VIA WWW.NOVELSOFT.CH
(CREATE AN ACCOUNT FIRST)
<property name="pluginClass" type="java.lang.String"
value="com.lutris.service.smsService.novelsoft.HttpSend"/>
<property name="username" type="java.lang.String" value="USERNAME"/>
<property name="password" type="java.lang.String" value="PASSWORD"/>
-->
- Comment-out the no-op plug-in, and un-comment-out the NovelSoft plugin.
- Change USERNAME and PASSWORD to appropriate values for the just created
account.
- Change the 'defaultSender' and 'defaultRecipient' properties to a
phone # with SMS support. Resulting XML should look like the following
(with user specific settings changed):
<!-- REQUIRED KEYS -->
<property name="defaultSender" type="java.lang.String" value="senderPhoneNumber"/>
<property name="defaultRecipient" type="java.lang.String" value="recipientPhoneNumber"/>
<property name="defaultMessage" type="java.lang.String" value="SMS
Test Message"/>
<!-- USE THIS PLUGIN FOR TESTING
<property name="pluginClass" type="java.lang.String" value="com.lutris.service.smsService.noop.NoopPlugin"/>--
>
<!-- USE THIS PLUGIN TO SEND VIA WWW.NOVELSOFT.CH (CREATE AN ACCOUNT
FIRST) -->
<property name="pluginClass" type="java.lang.String"
value="com.lutris.service.smsService.novelsoft.HttpSend"/>
<property name="username" type="java.lang.String" value="USERNAME"/>
<property name="password" type="java.lang.String" value="PASSWORD"/>
- Add the updated
enhydra-services.xml file to the SMSService.jar
file, ensuring that it is added in the META-INF directory
of the SMSService.jar file.
- Undeploy / redeploy the SMSService from Lutris EAS.
- Use the SMSSampleClient to send a test message.
Creating an SMS Provider Plug-in
New SMS provider plug-in classes can be created and specified within
the SMS Service config file to connect the SMS service to different SMS
providers.
The SMS provide plug-in class must implement the interface com.lutris.service.smsService.SMSPlugin,
whose source code and documentation is provided at <sms_root>\src\com\lutris\service\smsService\SMSPlugin.java .
For this release, the class has to be added to the SMSService.jar
file, and the enhydra-service.xml file needs to be modified
as described above.
Lutris EAS Logging with SMS
The Lutris EAS SMS Service can be tied into the Lutris EAS logging mechanism
for sending arbitrary log messages using SMS. To use this capability,
the included logging pipeline (<sms_root>\logging\SMSLogPipeline.jar )
must be deployed, using one of the deployment options described for deploying
the SMS Service itself. Once deployed, the SMSSampleClient can be used
to test the logging pipeline:
The message will appear in the Lutris EAS log file (<eas_root>\logs\ems.log ). The
pipeline is configured by default to only accept messages at the DEBUG9
log level where the channel name is "SMS", with the sample client being
the only place where this combination occurs. To use the logging pipeline
in applications and services:
- Send log messages to the DEBUG9 log level and/or the SMS channel.
or
- Edit
enhydra-service.xml inside SMSLogPipeline.jar
and change the log level and/or channel name to match existing log message.
Set either the log level or channel name (but not both) to "" to accept
anything. (but be careful with how many SMS messages are sent!)
The logging pipeline always sends the messages to the default recipient.
A system administrator could deploy a second instance of the SMS service
with her cell phone set as the default, and set the logging pipeline to
use that instance, with the log level set to "EMERGENCY", and the channel
name "" (for example).
Using the SMS Service with the Scheduler Service
The SMS Service can also be used in conjunction with the Lutris EAS Scheduler
Service Technology Preview to automatically send messages via SMS
on a defined schedule.
To send messages via SMS from a scheduled task, add a new job to the
Scheduler Service where the task is a JNDI lookup of "ems:/Services/SMSService/manager ",
then either call the method send() or send(messageString) .
The default configuration for the SMS service is to log the messages,
so you should see the scheduler service logging that it is about to fire
off the task, then the SMS service logging the actual message.
Future Enhancements
Potential future enhancements for the SMS Service: (Please provide feedback
on which are most important for you.)
- Provide a UI to change the plug-in class and configure properties
(for example, phone numbers, username and password).
- Ability to receive SMS messages (depends on how service providers
decide to implement this).
- Asych receipt tracking Send(msec): send and wait at most N msec for
a verification that the message made it to the phone. Returns an ID
Object. Have a getStatus(Object) method to let the clients check in
later to see if the SMS finally made it. Note: Most US carriers
do not support this, so until they do it's not worth it. Most US carriers
don't even support specifying a "from" phone number!!!!
- Handle multiple to: phone numbers in a comma separated list.
- Make a new version of the current send that waits at most N msec and
might return an incomplete/unknown status. When N is zero you get always
non-blocking for fire-and-forget uses.
- Have a version of send that takes an array/container of addresses
to send to, for bulk SMSing.
- Add logging - save a copy of the last N messages. Allow for MBean
inspection.
- Provide more pre-defined SMS provider plug-ins.
- Expose an MBean enumeration (popup menu) of plug-in class names. List
all known classes.
- Complete the to/from/message input validation methods. Need to check
on what the standards really are. The max length, for example, depends
on the carrier and varies from 80 - 200 chars. 160 is a good average.
Maybe these methods should be removed, if they provide a false sense
of security. Can always allow the service provider to do validation
at send time.
We are especially interested in these areas for your feedback:
- How you are or would like to use the SMS Service
- Functionality of existing capabilities
- What SMS service provider (if any) are you currently
using? What interfaces/APIs to they expose to let you send messages?
- Favorite items from the 'Future Enhancements' section
- General comments and suggestion
|