Notifications


Table of Contents

1. Introduction
2. Notifyables
2.1. Dates
2.2. Contact information
3. SMS Senders and Handlers
4. Mobile number validation
5. Clustering
5.1. Notifications
5.2. Sending SMS

The MMBase 'notifications' component provides basic functionality to implement a notification mechanism using MMBase objects. That means that you can make any object 'notifyable' by linking a 'notifyables' object to it. Website visitors can then subscribe to those notifyables and receive notifications if something happens with the notifyable. In practice this is for example used to send Short Message Service text message a certain time before the commence of certain TV program.

So besides the MMBase code to model 'notifications' this component also contains the interfaces to send (and receive) SMS messages. An implemention is provided to communicate with 'CM-Telecom'.

This component provides only one builder ('notifyables') and one relation type ('notifications'). It does not define what objects are related to users nor what object types can be related to a notifyable.

The only thing that is required is that those two unspecified object types contain certain functions to request some information.


The object about which notifications are to be sent, must be linked to an object of type 'notifyable' using the role 'related', and it must provide a function 'dates', which provides a list of dates at which a notification must be sent. This function must accept parameters 'since' and 'until', to limit the list. This can e.g. be done like so in the builder XML under concern:

      ....
    </field>

  </fieldlist>
  <functionlist>
    <function key="dates">
      <class>nl.teleacnot.mmbase.functions.ProgrammeDates</class>
    </function>
  </functionlist>

</builder>

Where the mentioned class can look like so:

      package nl.teleacnot.mmbase.functions;
import org.mmbase.bridge.*;
import org.mmbase.storage.search.*;
import org.mmbase.bridge.util.Queries;
import org.mmbase.util.DynamicDate;
import java.util.*;

/**
 * Function wich determines for a certain t_programme node the dates for wich notifications must be
 * issued.
 *
 * @author Michiel Meeuwissen
 * @version $Id: notifications.xml,v 1.4 2007/12/07 13:35:13 michiel Exp $
 **/
public class ProgrammeDates  {

    protected Node node;
    protected Date since;
    protected Date until;
    {
        try {
            since = DynamicDate.getInstance("yesterday");
            until = DynamicDate.getInstance("today + 100 year");
        } catch (org.mmbase.util.dateparser.ParseException pe) {
            // could not happen
        }
    }

    public void setNode(Node n) {
        node = n;
    }

    public void setSince(Date s) {
        since = s;
    }

    public void setUntil(Date u) {
        until = u;
    }

    public List<Date> dates() {
        List<Date> result = new ArrayList<Date>();
        Cloud cloud = node.getCloud();
        NodeManager eps = cloud.getNodeManager("t_episode");
        NodeManager trans = cloud.getNodeManager("t_transmission");
        NodeQuery nq = Queries.createRelatedNodesQuery(node, eps, "posrel", "destination");
        RelationStep rstep = nq.addRelationStep(trans);
        nq.setNodeStep(rstep.getNext());
        Queries.addConstraint(nq, Queries.createConstraint(nq, "begin", Queries.OPERATOR_BETWEEN, since, until, false));

        NodeIterator i = trans.getList(nq).nodeIterator();
        while (i.hasNext()) {
            Node transmission = i.nextNode();
            result.add(transmission.getDateValue("begin"));
        }
        return result;

    }

}

One SMS Sender can be configured using the property 'class' in <config dir>utils/sms_sender.xml. So there can be only one.

The file is watched, if you change it a new Sender wil be instantiated. This one instance is obtained by calling org.mmbase.sms.Sender.getInstance().

The sender may offer the possibility to collect messages and send them in bulk. Use the method 'offer' is this allowed, mmbase-crontab can be used to periodically call 'trigger', to send pending messages.

For receival of SMS, multiple 'Handlers' can be configured though. Those are implementions of org.mmbase.sms.Handler.

<?xml version="1.0"?>
<!DOCTYPE util PUBLIC "-//MMBase//DTD util config 1.0//EN" "http://www.mmbase.org/dtd/util_1_0.dtd">
<util>
  <properties>
    <property name="nl.teleacnot.mmbase.sms.Handler" type="map">
      <entry>
        <key>prefix</key>
        <value>TELEAC </value>
      </entry>
    </property>
  </properties>
</util>
      

An SMS handler can decide to not handle the message, and leave it to the next one.

The SMS Handlers are called by the class org.mmbase.sms.Receiver. The receiver is offered received messages with it's method 'offer', which is called by the implemention code for actual retreival. E.g. in the case of CMTelecom this is a very simple JSP in /mmbase/notifications/cmtelecom. Which can be actively called by their system. Other implementations may work differntly.

This component does not itself provide the functionality to fill in the phone number of users. It should however be done, and the SMS-functionality present in this component can be used to implement the 'validation' protocol which should normally be present.

An example you can find in nl.teleacnot.example package. (A Processor for a phone number field and a Handler).

This application is aware of the fact that MMBase may be 'clustered'.


This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: documentation@mmbase.org