9 Using Calendar Server Notifications

This chapter describes the Oracle Communications Calendar Server notification architecture, how to enable notifications, the different types of notifications, and how to customize notifications.

Overview of Notification Architecture

Calendar Server is capable of generating notifications for any change to the calendar data in the database, or for some preset trigger. Notifications are published as Java Message Service (JMS) messages. Calendar Server also includes a JMS consumer program that consumes the JMS notifications and sends email messages to end users. One type of such end user email notification, reminders, (sometimes called alarms), are set by end-users for themselves, so that they are notified about their upcoming events and todos. Another type of notification is sent by the server when a user, different than the one being notified, makes a change to the calendar database, for example, by modifying an event invitation, granting a calendar permission, and so on.

Calendar Server notification services use a publish/subscribe paradigm. Calendar Server publishes messages, in this case, notifications. Receiving clients (the subscribers) receive only those messages that they are interested in.

Calendar Server utilizes the built-in Java Messaging Service (JMS) in Oracle GlassFish Server to communicate calendar data changes and calendar alarm triggers. Calendar Server bundles a consumer program that "consumes" this information and sends email for certain subset of the notifications as detailed in "Notification Types". For more information, see the JMS website at:

http://java.sun.com/products/jms/

Figure 9-1 shows that the Calendar Server notification service consists of two major components, the Notification Service and Notification Consumer. The Notification Service component is part of the Calendar Server itself, and is the publisher that posts messages of a pre-configured JMS topic managed by the JMS provider. The Notification Consumer component is the subscriber or the message consumer of that JMS topic.

Figure 9-1 Calendar Server Notifications Services Architecture

Description of Figure 9-1 follows
Description of ''Figure 9-1 Calendar Server Notifications Services Architecture''

The Notification Service component provides interfaces for Calendar Server to publish JMS messages to a specific JMS topic (DavNotificationTopic) of the JMS broker. The Notification Service component is part of the main Calendar Server servlet that is deployed in the GlassFish Server web container. The Notification Consumer component listens on the JMS bus for the specific topic (DavNotificationTopic) notification messages, consumes the messages, and sends notification email to recipients, if applicable. The consumer checks the notification type and other instructions provided in the JMS message to determine what action is to be taken. The Notification Consumer component message-driven bean (MDB) runs in the GlassFish Server J2EE container. The consumer MDB is deployed in EMBEDDED mode, and thus is running in the same JVM of the J2EE container.

You can choose to write your own customized Notification Consumer programs. See "Writing a Java Messaging Service Consumer".

About Reminders (Alarms)

Calendar Server sends out email for upcoming events and tasks if the owners of the events and tasks have set an email or SMS reminder. (Convergence users can enable default reminders.) The information is stored along with the event or task in the standard VALARM format as specified in RFC 5545 with action set to EMAIL. The server maintains a queue of these alarms and when the right time arrives, it posts the relevant information to the JMS bus with the notification type set to ALARM. The notification consumer fills in the right alarm template file based on the instructions in the JMS payload and the email is sent. For reminders to work, you only need to set the notification.dav.enablejmsnotif parameter to true, as well as the correct SMTP configuration settings.

Calendar Server supports the Alarm-Agent Property. This property specifies whether a client, server, both client and server, or none, is responsible for processing an alarm when it is triggered. This is in accordance with the Extended VALARM draft. To view the draft, see the IETF website at:

http://tools.ietf.org/html/draft-daboo-valarm-extensions-04

For details on how to set alarms by using the store commands in the WCAP protocol, see the Calendar Server WCAP Developer's Guide.

About Server Email Notifications

Server notifications are used to notify users mostly about changes to their calendars due to actions by other users, including event or task invitations, granting permission to a calendar, and so on. To enable email notifications at a server level, both the notification.dav.enablejmsnotif and notification.dav.enableemailnotif configuration parameters must be set to true. In addition, notification should be enabled on a per account basis. In case of event and task invitations or responses, to include the actual event or task in standard ics format, the notification.dav.enableimipmailnotif needs to be enabled as well (set to true).

Calendar Server supports RFC 6047 and sends iMIP invitations and responses to external users as a consequence. External users reside either on a different Calendar Server deployment administered by a separate group, or on an outside calendaring system, such as Exchange, Google Calendar, and so on. However, this is a separate feature from the notifications that are explained in this chapter. Calendar Server uses the notification.dav.enableimip configuration parameter to control iMIP notifications. Both iMIP and server email notifications use the notification.dav.smtp* configuration parameters to configure the SMTP server to use.

In addition to external users, internal users that have their status set to inactive can also be configured to receive iMIP invitations. The davcore.scheduling.rejectinactiverecipients parameter enables and disables this capability. If this value is set to false, internal users whose status attribute (icsStatus by default) is set to inactive in the LDAP directory receive iMIP invitations just like external users. For users whose status is set to deleted or inactive, no iMIP invitations are sent under any circumstances.

Enabling Calendar Server Notifications

Table 9-1 describes the Calendar Server notifications that are controlled by the configuration parameters.

Table 9-1 Notification Configuration Parameters

Parameter Description

notification.dav.enableemailnotif

Controls server-wide email notification. When this parameter is set to true, Calendar Server sends email notifications for new event, task, calendar creation, and access changes, if end users choose to receive them. End users can choose to receive notifications either by enabling their own account through Convergence or by requesting that an administrator do so by using the davadmin command. These notifications are text emails sent to users for actions that have already been recorded in their calendars. If set to false, server-wide email notification is disabled.

notification.dav.enablejmsnotif

Controls server-wide JMS notification. When set to true, Calendar Server publishes notifications to the JMS bus. This parameter must be set to true for any notification to work.

notification.dav.enableimipmailnotif

Controls server-wide inclusion of actual event/task ical content in email notification. When this parameter is set to true, iCal content is included in the server-wide JMS notification email sent to users on the internal deployment. By default, iCal content is not included in notifications. If this parameter is enabled, email notifications with ics content can be interpreted by iCal aware clients and even used for responding from the email client itself. For this feature to work correctly, notification.dav.enableemailnotif, notification.dav.enablejmsnotif, and notification.dav.enableimipmailnotif must all be enabled.


You can enable or disable these parameters by using Jconsole or the davadmin utility. You do not need to restart the server for a change to these parameters to take effect.

The settings are not cumulative. That is, to receive email notification, not only should notification.dav.enableemailnotif be set to true, so should notification.dav.enablejmsnotif. Similarly, to get ics information in notifications, all three configuration options must be set to true.

Other notification.dav.* configuration parameters control items such as the SMTP server to use and its settings, maximum notification payload, location of notification templates, and so on. The davcore.autocreate.enableemailnotification parameter determines if notification is enabled by default on a newly created account and the davcore.autocreate.emailnotificationaddressattr parameter specifies which LDAP attribute to set as the default notification address when autocreating an account. (The default value is mail.) For more details, see "Calendar Server Configuration Parameters".

Enabling Notifications on an Account

To enable notifications for all accounts:

  1. Use the davadmin command to set the davcore.autocreate.enableemailnotification to true.

    davadmin config modify -o davcore.autocreate.enableemailnotification -v true
    Enter Admin password: password
    
  2. If necessary, change the value of the LDAP attribute corresponding to davcore.autocreate.emailnotificationaddressattr, which is used to set the email notification address during account autocreation. The default value is mail.

Modifying Notifications on an Account

Calendar Server stores the values for the davcore.autocreate.enableemailnotification and davcore.autocreate.emailnotificationaddressattr parameters in the database as properties for each account. These parameters can be modified in two ways:

  • User: Use a WCAP client that is capable of running the set_accountprops.wcap command, specifying a new value for notifemail and notifrecipients.

  • Administrator: Run the davadmin account command.

For more information on davadmin account see "Calendar Server Command-Line Utilities".

For information on the get_accountprops.wcap command, see Calendar Server WCAP Developer's Guide.

Managing Notification Templates

This section describes the Calendar Server notification service in more detail and how to customize notification templates for your deployment.

Topics in this section:

Notification Types

The notification message contains a type field that indicates what action triggered the notification and thus helps the consumer decide how to process it.

Table 9-2 describes the notification types. It also lists the payload data, which is the resource content (for example, iCal data) in byte array format. Attachments are not included.

Table 9-2 Notification Types

Notification Type Description Payload CS7 Consumer Action

ALARM

Alarm

iCal data

Email is sent if ACTION type is EMAIL.

AUTOCREATE

Initial creation of a user's home collection (and its default sub-collections)

None

Email sent if creation happened as a result of a scheduling invitation. Creation due to user login or explicit account creation by using the davadmin command does not trigger an email.

CREATE_CAL_COLLECTION

Creation of a calendar collection

None

None.

CREATE_CAL_RESOURCE

Creation of an entry (event or task) in a calendar collection

iCal data

None.

CREATE_COLLECTION

Creation of a non-calendar collection

None

None.

CREATE_RESOURCE

Creation of an entry in a non-calendar collection

iCal data

None.

DELETE_CAL_COLLECTION

Deletion of a calendar collection

None

None.

DELETE_CAL_RESOURCE

Deletion of an entry (event or task) in a calendar collection

iCal data

None.

DELETE_COLLECTION

Deletion of a non-calendar collection

None

None.

DELETE_RESOURCE

Deletion of an entry in a non-calendar collection

iCal data

None.

EVENT_START

Event start for presence integration

UID, DTSTART, DTEND

Notification email is triggered if presence notification is enabled (davcore.presence.enable=true).

EVENT_END

Event end for presence integration

UID, DTSTART, DTEND

Notification email is triggered if presence notification is enabled (davcore.presence.enable=true).

MODIFY_CAL_RESOURCE

Modification of an entry (event or task) in a calendar collection

iCal data

None.

MODIFY_RESOURCE

Modification of an entry in a non-calendar collection

iCal data

None.

MOVE_CAL_COLLECTION

A calendar collection was moved

None

None.

MOVE_CAL_RESOURCE

An entry in a calendar collection was moved

iCal data

None.

MOVE_COLLECTION

A non-calendar collection was moved

None

None.

MOVE_RESOURCE

An entry in a non-calendar collection was moved

None

None.

SHARE_ACCOUNT

An account was shared

None

An email is sent if additional permission was granted.

SHARE_CAL_COLLECTION

A calendar collection was shared

None

An email is sent if additional permission was granted.

SCHEDULE_ITIP*

Scheduling iTIP message

iCal data

iTIP scheduling: Announces an iTIP scheduling event, task, or a significant change to an event or task to an external attendee.

SCHEDULE_RECEIVE

Scheduling message is received

iCal data

Sends an email notification of the invitation or the response as long as it refers to an event or task in the future. Notifies attendee of new event, task, or a significant change to the event/task.

SCHEDULE_SEND

Scheduling message is sent

iCal data

None.

NONE

Undefined type

iCal data

Not applicable.


SCHEDULE_ITIP* notification type is used by the notification service to directly send iMIP messages to external invitees by using the same template substitution mechanism. No posting is done to the JMS bus.

Templates, Resource Bundle, and Other Configuration Files

This section contains the following topics:

Notification Configuration

You enable or disable notifications and set the values of the SMTP server used by the notification consumer by using the davadmin command or Jconsole. See "Calendar Server Configuration Parameters" for details on each of the configuration properties that you can set for notifications.

Resource Bundles

The value of the user's locale/preferred language attribute (defined by the davcore.ldapattr.preferredlang configuration parameter) in the user's directory entry is used to localize notification email. The attribute is retrieved from LDAP every time a notification is triggered and is then passed along as part of the notification object being published. If the user does not have any preferred locale/language, it defaults to the consumer module's system's default.

Template Files

Notification templates are files that contain pre-formatted notification messages. For example, request.fmt is used for scheduling request notification email message, while sms.fmt contains a short template for alarm SMS messages.

Table 9-3 describes the available notification email templates. In a deployed production environment, by default the templates should be located in the /config/templates sub-directory, for example, /opt/sun/comms/davserver/config/templates/. The location of the templates directory is defined by the notification.dav.configdir configuration parameter.

Table 9-3 Scenarios That Trigger Notifications and Templates Files Used

Message Type Notification Type Template Files From To Description

Alarm

ALARM

alarm.fmt?alarm_todo.fmt

User's scheduling address

Recipients listed in alarm

Email reminder for an upcoming event or todo.

Alarm

ALARM

sms.fmt

User's scheduling address

Recipients listed in alarm

SMS reminder for an upcoming event or todo. The SMS message is a more concise message but is still sent by email.

Auto creation

AUTOCREATE

autocreate.fmt

User's scheduling address.

User's scheduling address

Notifies of auto creation of user's home collection due to the arrival of the very first invitation.

Event Request Notification

SCHEDULE_RECEIVE

request.fmt, request_recur.fmt

Organizer

Notification recipients

Notifies attendee of a new event invitation or significant change to an invitation.

Todo Request Notification

SCHEDULE_RECEIVE

request_todo.fmt, request_recur_todo.fmt

Organizer

Notification recipients

Notifies attendee of a new todo or significant change to a todo.

Event reply Notification

SCHEDULE_RECEIVE

reply_requeststatus.fmt

Attendee

Organizer

Notifies the organizer of the status of an invitation, when the status is of value 3.x and 4.x, which indicates some issues with the scheduling.

Todo Reply Notification

SCHEDULE_RECEIVE

reply_requeststatus_todo.fmt

Attendee

Organizer

Notifies the organizer of the status of a todo, when the status is of value 3.x and 4.x, which indicates some issues with the scheduling.

Event Cancel Notification

SCHEDULE_RECEIVE

cancel.fmt, cancel_recur.fmt, cancel_imip_todo.fmt, cancel_recur_imip_todo.fmt

Organizer

Notification recipients

Notifies of a canceled event (to attendee).

Todo Cancel Notification

SCHEDULE_RECEIVE

cancel_todo.fmt, cancel_recur_todo.fmt

Organizer

Notification recipients

Notifies of a canceled todo (to attendee).

Event Reply Notification

SCHEDULE_RECEIVE

reply.fmt, reply_recur.fmt, reply_imip_todo.fmt, reply_recur_imip_todo.fmt

Attendee

Organizer

Notifies of the following reply scenarios:

  1. Notifies the event organizer that an attendee accepted the invitation;

  2. Notifies the event organizer that an attendee declined the invitation;

  3. Notifies the event organizer that an attendee tentatively accepted the invitation.

Todo Reply Notification

SCHEDULE_RECEIVE

reply_todo.fmt, reply_recur_todo.fmt

Attendee

Organizer

Notifies of the following reply scenarios:

  1. Notifies the todo organizer that an attendee accepted the todo;

  2. Notifies the todo organizer that an attendee declined the todo;

  3. Notifies the todo organizer that an attendee tentatively accepted the todo.

Event Request Notification with iMIP Data

SCHEDULE_RECEIVE

request_imip.fmt, request_recur_imip.fmt, request_imip_todo.fmt, request_recur_imip_todo.fmt

Organizer

Notification recipients

Notifies attendee of a new event or significant change to the event. The notification contains iCal information because the notification.dav.enableimipemailnotif configuration parameter has been set to true.

Event Cancel Notification with iMIP Data

SCHEDULE_RECEIVE

cancel_imip.fmt,cancel_recur_imip.fmt, cancel_imip.fmt, cancel_recur_imip.fmt

Organizer

Notification recipients

Notifies of a canceled event (to attendee). The notification contains iCal information because the notification.dav.enableimipemailnotif configuration parameter has been set to true.

Event Reply Notification with iMIP Data

SCHEDULE_RECEIVE

reply_imip.fmt, reply_recur_imip.fmt, reply_imip.fmt, reply_recur_imip.fmt

Attendee

Organizer

Notifies of the following reply scenarios:

  1. Notifies the event organizer that an attendee accepted the invitation;

  2. Notifies the event organizer that an attendee declined the invitation;

  3. Notifies the event organizer that an attendee tentatively accepted the invitation. The notification contains iCal information because the notification.dav.enableimipemailnotif configuration parameter has been set to true.

iTIP Event Request

SCHEDULE_ITIP

itip_eventrequest.fmt

Organizer

External attendee

iTIP scheduling: Announces an iTIP scheduling event or a significant change to an event to an external attendee.

iTIP Todo Request

SCHEDULE_ITIP

itip_todorequest.fmt

Organizer

External attendee

iTIP scheduling: Announces an iTIP todo or a significant change to a todo to an external attendee.

iTIP Event Cancel

SCHEDULE_ITIP

itip_eventcancel.fmt

Organizer

External attendee

iTIP scheduling: Notifies of a cancellation of an iTIP scheduling event to an external attendee.

iTIP Todo Cancel

SCHEDULE_ITIP

itip_todocancel.fmt

Organizer

External attendee

iTIP scheduling: Notifies of a cancellation of an iTIP todo to an external attendee.

iTIP Event Reply

SCHEDULE_ITIP

itip_eventreply.fmt

External attendee

Organizer

iTIP scheduling: Replies to an iTIP scheduling event.

  1. attendee accepted the invitation;

  2. attendee declined the invitation;

  3. attendee tentatively accepted the invitation.

iTIP Todo Reply

SCHEDULE_ITIP

itip_todoreply.fmt

External attendee

Organizer

iTIP scheduling: Replies to an iTIP todo.

  1. attendee accepted the todo;

  2. attendee declined the todo;

  3. attendee tentatively accepted the todo.

Share calendar account

SHARE_ACCOUNT

share_account.fmt

Sharer's email address

Sharee's email address

Notifies of a calendar account being shared.

Share calendar collection

SHARE_CAL_COLLECTION

share_cal.fmt

Sharer's email address

Sharee's email address

Notifies of a calendar collection being shared.


Notes about notifications and templates:

  • Notification recipients: A recipient list stored in the property, SUN_NOTIFRECIPIENT. By default, it's the scheduling address of the LDAP user on behalf of whom the operation is executed. It can be modified through interfaces provided by WCAP or by using the davadmin command.

  • _recur files: Templates of file names containing "_recur" are used for notifications regarding recurring resources.

  • _imip templates: These templates are used by the iSchedule gateway, and contain x-headers added by the gateway for special processing instructions.

Customizing Templates

Because JavaMail has interfaces to parse an entire string into a MIME message, a notification template file is designed to be a well-formatted email MIME message that contains character sequences denoted by a starting "%{", and an ending "}".

A template contains two types of trinkets:

  • Resource bundle key: A place holder for locale-specific resource, in the format of ${key};

    For example, trinket ${summary} contains a key "summary" that uniquely identifies a locale-specific object in the resource bundle.

  • Value trinket: A place holder for notification field value, in the format of %{trinket};

For a complete list of keys, refer to the email.properties file.

Table 9-4 describes all notification values and trinkets.

Table 9-4 Notification Value Trinkets

Name Description or Note Example

summary

Summary

Not applicable

from

Email from value for this notification

Not applicable

to

Email to value for this notification

Not applicable

organizer

Organizer in ical

Not applicable

attendees

Attendee list in ical

Not applicable

sender

On behalf of sender

Not applicable

recipient

Original recipient

Not applicable

start

Start date/time for this notification

Not applicable

end

End date/time for this notification

Not applicable

location

Location in ical

Not applicable

description

Description in ical

Not applicable

note_recurring

Used in template in recurring resources

Not applicable

partstat

Used in reply

[ACCEPTED, TENTATIVE, DECLINED]

requeststatus

Used in reply_requeststatus templates

As defined in RFC5545

due

Used in todo templates

Not applicable

alarm_summary

Used in alarm templates

Not applicable

cal_owner

Owner of the shared calender. Used in share templates.

Not applicable

displayname

The displayname of a calendar

Not applicable

ical

Used for iMIP messages

Entire ical raw data


The following example shows an event request template, request.fmt, and the resulting notification message constructed from the template.

Event Request Template

Subject: ${event_request_notification} %{summary} 
From: %{from} 
To: %{to} 
MIME-Version: 1.0 
Content-Type: text/plain; charset=utf-8 
Content-Transfer-Encoding: 7BIT 
${summary}: %{summary} 
${organizer}: %{organizer} 
${attendees}: %{attendees} 
${start}: %{start} 
${end}: %{end} 
${location}: %{location} 
${description}: 
%{description}

Resulting Notification Message

Subject: Event Request Notification: test 
From: caluser39@example.com 
To: caluser8@example.com 
MIME-version: 1.0 
Content-type: text/plain; charset=utf-8 
Content-transfer-encoding: 7BIT 
Summary: test 
Organizer: caluser7@example.com 
Attendees: caluser8@example.com 
Start: Tue December 01, 2009 10:30:00 AM PST 
End: Tue December 01, 2009 11:30:00 AM PST 
Location: Loveland conf room, BRM05 
Description: test notes.

The following example shows a customized request.fmt template, and the resulting notification message constructed from the template. In the resource bundle, a new entry should be included as shown in the example (summary_cap=SUMMARY).

Customized request.fmt

Subject: ${event_request_notification} %{summary} 
From: %{from} 
To: %{to} 
MIME-Version: 1.0 
Content-Type: text/plain; charset=utf-8 
Content-Transfer-Encoding: 7BIT 
${summary_cap}: %{summary} 
${organizer}: %{organizer} 
${attendees}: %{attendees} 
${start}: %{start} 
${end}: %{end} 
${location}: %{location} 
${description}: 
%{description}

Resulting Notification Message

Subject: Event Request Notification: test 
From: caluser39@example.com 
To: caluser8@example.com 
MIME-version: 1.0 
Content-type: text/plain; charset=utf-8 
Content-transfer-encoding: 7BIT 
SUMMARY: test 
Organizer: caluser7@example.com 
Attendees: caluser8@example.com 
Start: Tue December 01, 2009 10:30:00 AM PST 
End: Tue December 01, 2009 11:30:00 AM PST 
Location: Loveland conf room, BRM05 
Description: test notes.

The Calendar Notifications module constructs the notification message from the corresponding template. Based on the user's preferred language/locale, the Notification module retrieves the locale-specific template from a runtime templates cache. It then performs more customization with the notification values. If the locale-specific template is not found, the original template is loaded and localized. The localized template is then stored in the cache, and thus should be constructed only once.

You can customize a template as long as it is in valid MIME format. Each resource bundle key is defined in the resource bundles and can be adjusted and added as long as it has a matching entry in the bundle files. All notification value trinkets are predefined in the Java source code, and should not be changed.

Preserving Customized Template Files During Calendar Server Upgrade

Customized notification template files are preserved during a Calendar Server upgrade. Normally, there should be no problem merging customized notification template files during the upgrade. If the upgrade encounters a problem with merging these files, the following message is displayed:

log_msg "There are conflicts in merging $file customization"
log_msg "Please finish the merge by manually resolving the conflicts in $cfgFileNew"

The $file and $cfgFileNew are substituted with actual file names.

Writing a Java Messaging Service Consumer

Calendar Server Notification Services use a publish/subscribe paradigm. The information in this section describes how to create your own consumer program.

All Calendar Server notification messages are posted to a pre-defined JMQ Topic called DavNotificationTopic. Each message consists of the associated iCal data as the message body and some additional information passed in as properties.

Topics in this section:

Notification Message Format

The Notification data posted to the JMS bus is a JMS Message object. The iCal data is sent as a JMS message body, while all other information is sent as message properties.

The properties are as follows:

  • type (notification type): Indicates the type of change that occurred. See "Notification Types" for the types that are currently defined. The following notification types trigger a notification message to be sent from the MDB consumer:

    • ALARM

    • AUTOCREATE

    • SCHEDULE_RECEIVE

    • SCHEDULE_ITIP (email directly from Calendar Server)

    • SHARE_ACCOUNT

    • SHARE_CAL_COLLECTION

  • resourceURI: A string property indicating the URI of the changed resource.

  • fromAddress: A string Property indicating the originator, the scheduling address of the principal URI who made the change.

  • toAddresses: A string Property consisting of a comma separated list of recipient address(es) where the notification is to be delivered. The final list of recipients are further calculated based on the notification type and other conditions at the consumer.

  • locale: A string Property that specifies the locale/preferred language of the owner of the resource or collection on which a notification was triggered.

  • notificationDate: A Long Property with the timestamp when the notification was posted to the JMS bus.

The Notification Message payload is the resource content (that is, iCal data) in byte array format. Attachments are not included.

An instruction field in a notification carries a special instruction on processing of a notification. For example, an instruction of EXCEED_PAYLOAD_LIMIT indicates the iCal data involved in this change exceeds the pre-configured maximum JMS payload size, and thus the consumer needs to fetch the data separately.

Code Sample

The following sample code for a consumer assumes that you know now to implement Message Driven Beans (MDB), and that you are familiar with Calendar Server's notification model and types.

@MessageDriven(mappedName = "jms/DavNotificationTopic", 
activationConfig = { 
@ActivationConfigProperty(propertyName = "subscriptionDurability", propertyValue = "Durable"), 
@ActivationConfigProperty(propertyName = "clientID", propertyValue = "CalDAVNotifConsumerID"), 
@ActivationConfigProperty(propertyName = "subscriptionName", propertyValue = "CalDAVNotifConsumer") 
}) 
public class NotificationConsumer implements MessageListener { 
... 
public void onMessage(Message contents) { 
... 
public void onMessage(Message contents) { 
if (contents instanceof StreamMessage) { 
Notification notif = null; 
// read the JMS message, 
StreamMessage msg = (StreamMessage) contents; 
try { 
msg.reset(); 
byte[] theData = (byte[]) msg.readObject(); 
//first, filter out those types of notification that we want to process. 
NotificationType type = NotificationType.valueOf(msg.getStringProperty("type")); 
switch (type) { 
case ACLCHANGE: 
case CREATE_COLLECTION: 
case CREATE_CAL_COLLECTION: 
case DELETE_COLLECTION: 
case DELETE_CAL_COLLECTION: 
case SCHEDULE_SEND: 
case CREATE_RESOURCE: 
case CREATE_CAL_RESOURCE: 
case DELETE_RESOURCE: 
case DELETE_CAL_RESOURCE: 
case MODIFY_RESOURCE: 
case MODIFY_CAL_RESOURCE: 
return; 
case ALARM: 
case AUTOCREATE: 
case SCHEDULE_RECEIVE: 
default: 
break; 
} 
notif = new Notification(type, 
msg.getStringProperty("resourceURI"), 
msg.getStringProperty("fromAddress"), 
msg.getStringProperty("toAddresses").split(","), 
msg.getStringProperty("locale"), 
new Date(msg.getLongProperty("notificationDate")), 
theData); 
} catch (MessageEOFException meofex) { 
LOGGER.log(Level.WARNING, "Error reading message data object: " 
+ "unexpected end of message stream has been reached. \n", 
meofex); 
} catch (MessageFormatException mfex) { 
LOGGER.warning("Invalid type conversion.\n" + mfex); 
} catch (JMSException jmse) { 
LOGGER.log(Level.WARNING, "Error reading JMS message: " 
+ "JMS provider fails to read the message due to some internal error.\n", 
jmse); 
} 
if(notif != null) { 
try { 
// Get iCal data 
byte[] data = notif.getData(); 
} 
} .........

Managing Calendar Server Java Messaging Server Destinations

This section describes how to manage Java Messaging Server (JMS) destinations in Calendar Server by using the imqcmd command. For a complete list of imqcmd options, see Sun Java System Message Queue 4.1 Administration Guide.

Topics in this section:

Overview of Calendar Server JMS Destinations

The JMS API enables messages to be specified as either PERSISTENT or NON_PERSISTENT. By default, Calendar Server JMS notification messages are delivered in PERSISTENT mode. Thus, you should monitor and purge JMS messages for cases when the destination's accumulated messages are taking up too much of the system's resources. Calendar Server uses the DavNotificationTopic JMS topic.

Using the imqcmd Command with Calendar Server

Use the following tasks to use the JMS imqcmd command to work with JMS destinations:

Listing a JMS Destination's Metrics

To list a JMS destination's metrics:

  1. Change directories to the GlassFish_home/imq/bin directory.

  2. List and display the metrics of the JMS topic used by the Calendar Server, DavNotificationTopic.

    imqcmd list dst -t t -n DavNotificationTopic
    ...
    imqcmd metrics dst -t t -n DavNotificationTopic
    ...
    

Purging All Messages

Occasionally, you might need to purge all messages queued at the DavNotificationTopic physical destination, if the destination's accumulated messages are taking up too much of the system's resources. Purging a physical destination deletes all messages queued at the destination. Consider pausing the destination to temporarily suspend the delivery of messages from producers to the destination previous to the purge operation. Also, take a snapshot of the metrics before and after you run the purge command.

To purge all messages:

imqcmd pause dst -t t -n DavNotificationTopic PRODUCERS
...
imqcmd purge dst -t t -n DavNotificationTopic
...
imqcmd resume dst -t t -n DavNotificationTopic
...

Monitoring Disk Utilization

To monitor a physical destination's disk utilization, use the imqcmd metrics command with the dsk option:

imqcmd metrics dst -t t -n DavNotificationTopic -m dsk -u admin

Accessing Remote Brokers Tip

You can also use the -b host:port option to specify a remote broker host name and port, for example, -b host1.example.com:7676.

Presence Notifications

Calendar Server publishes a JMS message on an event start and end that presence clients, including Oracle Communications Instant Messaging Server, can use to automatically set presence status. The client then displays a status message based on how that client consumes and posts the status. Calendar Server publishes this JMS message through its existing JMS infrastructure, which is also used to publish alarms for database changes.

Configuring Presence Notifications

  1. If you upgraded to Calendar Server 7.0.4.14.0, run the davadmin account upgrade command.

  2. Enable server-wide presence by setting the davcore.presence.enable parameter to true.

    See "Enabling Notifications on an Account" for more information.

  3. Configure the davcore.presence.advancepresencetriggerinterval parameter to set time difference in seconds, between actual event timings and trigger time.