oracle.panama.mobilealert
Interface MasterAlertService

All Superinterfaces:

ModelObject, XMLObject

public interface MasterAlertService

extends ModelObject

Interface exposes the master alert service features.

There are three major types of Master Alerts:

• Value Based: Master Alert is based on a datafeeder, which will post data events to the notification engine at certain intervals. Notification message will be sent each time data posted by the datafeeder is validated against the user defined triggering conditions.
• Time Based: Notification message will be sent at the user-specified time/time intervals.
• Location Based: Notification message will be sent when the user-specified location condition is met.

Master Alert does not necessarily need to be based on only one of the above. The same Master Alert can be based on one or more. Possible combinations can be listed as follows:

• Purely Time Based: Notification Engine will invoke a service at the specified time/time period. For example, sending the daily appointment schedule at 9:00am. For this specific example, notification engine will invoke the designated service which retrieves the user calendar at 9:00AM every morning.
• Purely Data Based: Notification Engine will invoke a service only when the value condition(s) is/are satisfied. For example, sending the stock quote information when stock price exceeds the specified value. If value-based predicates are involved, you must describe the data content on which this master notification service is built. OracleAS Wireless enables you to define the data content using a data feeder. The data feeder module defines a given content in two forms: input and output parameters. For example, stock quote content can be defined as having a stock ticker as its input parameter and having price, volume, change and change percentage as its output parameters. Data feeder uses the input parameter(s) to uniquely identify output parameters.
• Purely Location Based: Notification Engine will invoke a service when the location condition is satisfied. For example, send a notification message when a specific truck arrives at the customer site.
• Time and Data Based: In this case, notification will be delivered at the specified time if the data condition is met. For example, sending the stock quotes at 9:00 am if ORCL exceeds a user-specified value.
• Time and Location based: Notification will be delivered at the specified time, if the location condition is satisfied at that time. For example, send a notification message to the transportation manager if a specific truck is at the customer site at 9:00 am.
• Data and Location based: Notification will be delivered when both data and location conditions are satisfied. For example, send a notification message when I am not at work and ORCL stock exceeds a user-specified value.
• Time + Data + Location based: Notification will be delivered at the specified time, if value and location conditions are satisfied. For example, send a notification message at 9:00 am, if ORCL stock value exceeds the specified value and if the user is not at the office.

For every event generated, notification engine derives a list of users who are interested in this event. In some cases, notification designer may need to apply some additional logic to manipulate this list. For this, a class file has to be provided that implements the interface MobileAlertSubscriberFilter interface.

 Sample usage:

        MetaLocator m = MetaLocator.getInstance();
        ModelFactory f = m.getModelFactory();
        ModelServices s = m.getModelServices();

        //Locate the data feed that will be used by this notification
        DataFeeder df = s.lookupDataFeeder("StockFeed")

        //Create a master notification with timebase enabled.
        //Note that, new master notification interface is oracle.panama.mobilealert.MasterAlertService
        MasterAlertService mAS = null;
        mAS = f.createMobileMasterAlertService("StockNotification", true, "Stock Master Notification", df);

        //Set the condition relation type to "AND"
        mAS.setConditionRelationType(MasterAlertService.RELATION_AND);

        //Set time based typed to strictly time based
        mAS.setTimeBasedType(true);

        //Enable Location based support
        mAS.enableLocationBaseAlert(true);

        StringBuffer msgTemplate = new StringBuffer("<?xml version = \"1.0\" encoding = \"UTF-8\" standalone=\"yes\" ?>");
        msgTemplate.append("<SimpleResult><SimpleContainer>");
        msgTemplate.append("<SimpleText>Stock alert for [&symbol;] price is [&price;]");
        msgTemplate.append("</SimpleText>");
        msgTemplate.append("</SimpleContainer></SimpleResult>");

        //Provide the default message template
        //that can be used with default notification master service
        mAS.setFormattedXMLTemplate(msgTemplate.toString());

        //add conditions with default valuesto this notifications, i.e. if "price > 10 "

        AlertConditionType cType1 = s.getMobileAlertConditionTypeByName("GT");
        FeedMetaData fmdPrice = df.getOutputParameter("price");
        mAS.addConditionDefinition("PriceMax", fmdPrice, cType1, "23");

        AlertConditionType cType2 = s.getMobileAlertConditionTypeByName("GT");
        FeedMetaData fmdChange = df.getOutputParameter("Change");
        mAS.addConditionDefinition("ChangeMax", fmdChange, cType2, "10");

        //Notification object does not use the persistent store/wireless caching
        //Any create/update operation has to be committed with the save
        mAS.save();
 

 Sample for locating master alerts.
    try {
      MasterAlertService mas = new MasterAlertServiceImpl(6476);
      //or
      mas = s.lookupMobileMasterAlertService(6476);
      //or
      mas = s.lookupMobileMasterAlertService("StockNotification");
    } catch (Exception pe) {
      System.out.println(pe.toString());
    }
 

 Sample for adding mapping.
    MasterService service = s.lookupMasterService(245);
    MAlertServiceMapping map = mas.createMapping(service, "STOCKALERT_TRADINGSERVICE");
    AlertChainParamMeta chainParam = map.addChainParameter(mas.getInputParameters()[0], service.getInputArguments().getArgument("TICKER"))
    map.setInvocationType(MAlertServiceMapping.MASS_INVOKE);
    map.save(); //apply changes to the repository
    mas.save(); //perform an actual commit

 

Sample usage example for adding service subscriptions.

        Link link = s.lookupLink(245);
        ServiceAlertSubscription sub = mas.addUserAlertSubscription(user, link);
        sub.setHour(12);
        sub.setMinute(30);
        ................. -> Other sets
        sub.save();

 

See Also:

DataFeeder, MobileAlertSubscriberFilter, FeedMetaData, ModelObject, LBCondition, ServiceAlertSubscription

Field Summary

static java.lang.String	RELATION_AND Relation type AND between triggering conditions
static java.lang.String	RELATION_OR Relation type OR between triggering conditions
static int	TYPEID The typeid of the master alert object
static java.lang.String	TYPENAME The typename of the master alert object

Method Summary

AlertConditionMeta	addConditionDefinition(java.lang.String name, FeedMetaData param, AlertConditionType type, java.lang.String defaultValue) Adds a new condition to this master alert service.
void	addFilteringHookClassName(java.lang.String filteringHookClassName) Adds a filtering hook class name.
ServiceAlertSubscription	addUserAlertSubscription(User user, Link link) Add/Create a new subscription object for this master alert.
MAlertServiceMapping	createMapping(MasterService service, java.lang.String name) Creates a mapping object for this master alert and the given master service.
MAlertServiceMapping	createQNMapping(MasterService masterService, java.lang.String url, boolean sharedContent) Creates a mapping object for this master alert in quick notification mode.
MAlertServiceMapping	createTemplateMapping(MasterService masterService) Creates a mapping object for this master alert and the given master service with the default message template.
void	delete() Deletes the master alert service.
void	enableLocationBaseAlert(boolean enabled) Enables/Disables location base.
void	enableTimeBaseAlert(boolean enabled) Enables/Disables time base.
AlertConditionMeta[]	getConditionDefinitions() Returns the condition meta data.
java.lang.String	getConditionRelationType() Returns the condition relation type.
DataFeeder	getDataFeeder() Returns the data feeder object used by this master alert.
java.lang.String	getDescription() Returns the description of the master alert.
java.lang.String[]	getFilteringHookClassNames() Returns filtering hook class names.
java.lang.String	getFormattedXMLTemplate() Returns the formatted xml template.
long	getId() Returns the Master Alert id.
AlertInputParamMeta[]	getInputParameters() Returns the input parameter meta data.
MAlertServiceMapping	getMapping(MasterService mService) Returns the first mapping object for the given master service.
MAlertServiceMapping[]	getMappings() Returns all mapping objects for this master alert.
java.lang.String	getName() Returns the master alert name.
AlertParameterMeta[]	getParameters() Returns the merged input + output parameters meta data that can be used for mapping alert parameters to service parameters.
ServiceAlertSubscription[]	getSubscriptions(User user, Link link, java.util.Map inputParameters) Returns all user alert subscriptions for any combination of given parameters.
boolean	getTimeBasedType() Returns the time based type.
ServiceAlertSubscription[]	getUserAlertSubscriptions(User user, Link link) Returns all user alert subscriptions for the given user and link.
boolean	isLocationBaseEnabled() Checks if location base is enabled.
boolean	isTimeBaseEnabled() Checks if time base is enabled.
ServiceAlertSubscription	lookupUserAlertSubscription(long subscriptionId) Lookup a subscription object.
void	removeCondition(AlertConditionMeta condition) Removes the condition for the master alert.
void	removeFilteringHookClassName(java.lang.String filteringHookClassName) Removes the filtering hook class name.
void	removeMapping(MAlertServiceMapping mapping) Removes the specified mapping object for this master alert.
void	removeUserAlertSubscription(ServiceAlertSubscription sub) Removes the specified subscription object for this master alert.
void	resumeAllUserAlertSubscriptions(User user, Link link) Resume all user alert subscriptions for the given user and link.
void	resumeUserAlertSubscription(ServiceAlertSubscription sub) Resumes this alert for the given subscription object.
void	save() Commits the changes to the database.
void	setConditionRelationType(java.lang.String conditionType) Sets the condition relation type.
void	setDescription(java.lang.String desc) Sets the description for the Master Alert Service.
void	setFormattedXMLTemplate(java.lang.String messageTemplate) Sets the formatted xml template for this master service.
void	setTimeBasedType(boolean strict) Set/Unset time based type to strictly time-based.
void	suspendAllUserAlertSubscriptions(User user, Link link) Suspends all user alert subscriptions for the given user and link.
void	suspendUserAlertSubscription(ServiceAlertSubscription sub) Suspends this alert for the given subscription object.

Methods inherited from interface oracle.panama.model.ModelObject

getCreatedDate, getLastModifiedDate, getTypeId, getTypeName, isSystem, setName, setSystem, undoAll

Methods inherited from interface oracle.panama.model.XMLObject

setXML, toXML

Field Detail

RELATION_AND

public static final java.lang.String RELATION_AND

Relation type AND between triggering conditions

See Also:

Constant Field Values

RELATION_OR

public static final java.lang.String RELATION_OR

Relation type OR between triggering conditions

See Also:

Constant Field Values

TYPEID

public static final int TYPEID

The typeid of the master alert object

See Also:

Constant Field Values

TYPENAME

public static final java.lang.String TYPENAME

The typename of the master alert object

See Also:

Constant Field Values

Method Detail

addConditionDefinition

public AlertConditionMeta addConditionDefinition(java.lang.String name,
                                                 FeedMetaData param,
                                                 AlertConditionType type,
                                                 java.lang.String defaultValue)
                                          throws PanamaException

Adds a new condition to this master alert service.

Parameters:

name - Name of the condition

param - FeedMetaData object for the parameter

type - AlertConditionType the alert condition type

defaultValue - String containing the default value

Returns:

Created condition definition object.

Throws:

PanamaException - the exception thrown when addition failed

addFilteringHookClassName

public void addFilteringHookClassName(java.lang.String filteringHookClassName)
                               throws PanamaException

Adds a filtering hook class name. This class should be in the classpath at runtime, and it has to implement the interface MobileAlertSubscriberFilter.

Parameters:

filteringHookClassName - the class name for the hook.

Throws:

PanamaException - exception thrown when addition failed

See Also:

MobileAlertSubscriberFilter

addUserAlertSubscription

public ServiceAlertSubscription addUserAlertSubscription(User user,
                                                         Link link)
                                                  throws PanamaException

Add/Create a new subscription object for this master alert.
The returned ServiceAlertSubscription object can be used to fill in subscription details.

Parameters:

user - User object

link - Link object

Throws:

PanamaException - the exception when this operation fails

See Also:

ServiceAlertSubscription

createMapping

public MAlertServiceMapping createMapping(MasterService service,
                                          java.lang.String name)
                                   throws PanamaException

Creates a mapping object for this master alert and the given master service.
The returned MAlertServiceMapping can be used to fill in the details for this mapping.

Parameters:

service - MasterService object that this mapping is created for

name - String name for this mapping object

Returns:

Created mapping object

Throws:

PanamaException - the exception if the MAlertServiceMapping can not be created.

See Also:

MAlertServiceMapping

createQNMapping

public MAlertServiceMapping createQNMapping(MasterService masterService,
                                            java.lang.String url,
                                            boolean sharedContent)
                                     throws PanamaException

Creates a mapping object for this master alert in quick notification mode.
This method creates the mapping with default information such as mapping all parameters, etc. This call will perform all necessary operations such as: filling in the master service URL argument (with a built-in URL pointing to a seeded jsp) and creating the parameter mapping.

Parameters:

masterService - MasterService object that this mapping is created for

url - The url that this master service is going to invoke, for template based mapping pass null.

sharedContent - Should the master service be invoked in mass invocation mode

Returns:

Created mapping object

Throws:

PanamaException - the exception if the MAlertServiceMapping can not be created.

createTemplateMapping

public MAlertServiceMapping createTemplateMapping(MasterService masterService)
                                           throws PanamaException

Creates a mapping object for this master alert and the given master service with the default message template.
This call will perform all necessary operations such as: filling in the master service URL argument (with a built-in URL pointing to a seeded jsp) and creating the parameter mapping.

Parameters:

masterService - MasterService object that this mapping is created for

Returns:

Created mapping object

Throws:

PanamaException - the exception if the MAlertServiceMapping can not be created.

delete

public void delete()

Deletes the master alert service.
This method call has to be followed by a save() call for committing the delete.

Specified by:

delete in interface ModelObject

enableLocationBaseAlert

public void enableLocationBaseAlert(boolean enabled)
                             throws PanamaException

Enables/Disables location base.

Parameters:

enabled - set to true to enable, false to disable

Throws:

PanamaException - Exception when enabling failed

enableTimeBaseAlert

public void enableTimeBaseAlert(boolean enabled)
                         throws PanamaException

Enables/Disables time base.

Parameters:

enabled - set to true to enable, false to disable

Throws:

PanamaException - Exception when enabling failed

getConditionDefinitions

public AlertConditionMeta[] getConditionDefinitions()
                                             throws PanamaException

Returns the condition meta data.

Returns:

Array of condition meta data

Throws:

PanamaException - the exception thrown when method fails

getConditionRelationType

public java.lang.String getConditionRelationType()
                                          throws PanamaException

Returns the condition relation type.

Returns:

Condition type for this master alert.

Throws:

PanamaException - exception thrown when setting condition type fail

getDataFeeder

public DataFeeder getDataFeeder()

Returns the data feeder object used by this master alert.

Returns:

Data feeder object. Returns null if this master alert service is not value based.

getDescription

public java.lang.String getDescription()

Returns the description of the master alert.

Returns:

Description associated with the master alert

getFilteringHookClassNames

public java.lang.String[] getFilteringHookClassNames()
                                              throws PanamaException

Returns filtering hook class names.

Returns:

String[] array of filtering hook class names

Throws:

PanamaException - the exception when this operation fails

getFormattedXMLTemplate

public java.lang.String getFormattedXMLTemplate()
                                         throws PanamaException

Returns the formatted xml template.

Returns:

Formatted xml template against this master service

Throws:

PanamaException - the exception when this operation fails

getId

public long getId()

Returns the Master Alert id.

Specified by:

getId in interface ModelObject

Returns:

Id of the master alert

getInputParameters

public AlertInputParamMeta[] getInputParameters()
                                         throws PanamaException

Returns the input parameter meta data.

Returns:

Array of input param meta data. Returns an empty error if this master alert service is not value based and/or there is no input parameter.

Throws:

PanamaException - the exception when this operation fails

getMapping

public MAlertServiceMapping getMapping(MasterService mService)

Returns the first mapping object for the given master service.

Parameters:

mService - MasterService object that needs to be queried

Returns:

MAlertServiceMapping Mapping object

getMappings

public MAlertServiceMapping[] getMappings()

Returns all mapping objects for this master alert.

Returns:

Array of all available mapping objects.

getName

public java.lang.String getName()

Returns the master alert name.

Specified by:

getName in interface ModelObject

Returns:

Name of the master alert service

getParameters

public AlertParameterMeta[] getParameters()
                                   throws PanamaException

Returns the merged input + output parameters meta data that can be used for mapping alert parameters to service parameters.

Returns:

Array of parameter meta data

Throws:

PanamaException - the exception thrown when method fails

getSubscriptions

public ServiceAlertSubscription[] getSubscriptions(User user,
                                                   Link link,
                                                   java.util.Map inputParameters)
                                            throws PanamaException

Returns all user alert subscriptions for any combination of given parameters.

 Sample usage:
   MasterAlertService mAS = s.lookupMobileMasterAlertService("TestMasterAlertService");
   Link link = s.lookupLink(4006);
   User user = s.lookupUser("orcladmin");
   ServiceAlertSubscription[] tmpList = null;

   // returns all subscriptions for this master notification
   tmpList = mAS.getSubscriptions(null, null, null);

   // returns all subscriptions of orcladmin for this master notification
   tmpList = mAS.getSubscriptions(user, null, null);

   // returns all subscriptions of orcladmin for the given link for this master notification
   tmpList = mAS.getSubscriptions(user, link, null);

   Map inputParams = new HashMap();
   inputParams.put("ticker", "ORCL");
   // returns all subscriptions of orcladmin for the given link for ticker input parameter value: ORCL
   tmpList = mAS.getSubscriptions(user, link, inputParams);
 

Parameters:

link - the Link object, passing null returns subscriptions for all links

user - the User object, passing null returns subscriptions for all users

inputParameters - name value pair for input parameters, passing null returns subscriptions for all input parameters

Returns:

Array of subscription objects

Throws:

PanamaException - the exception when this operation fails

getTimeBasedType

public boolean getTimeBasedType()
                         throws PanamaException

Returns the time based type.

Returns:

Time based type (true for strictly time based)

Throws:

PanamaException - exception thrown when getting time based type fail

getUserAlertSubscriptions

public ServiceAlertSubscription[] getUserAlertSubscriptions(User user,
                                                            Link link)
                                                     throws PanamaException

Returns all user alert subscriptions for the given user and link.

Parameters:

user - User object

link - Link object

Returns:

Array of subscription objects

Throws:

PanamaException - the exception when this operation fails

isLocationBaseEnabled

public boolean isLocationBaseEnabled()

Checks if location base is enabled.

Returns:

true if location base is enabled

isTimeBaseEnabled

public boolean isTimeBaseEnabled()

Checks if time base is enabled.

Returns:

true if time base is enabled

lookupUserAlertSubscription

public ServiceAlertSubscription lookupUserAlertSubscription(long subscriptionId)
                                                     throws PanamaException

Lookup a subscription object.

Parameters:

subscriptionId - the id of the subscription

Returns:

Subscription object

Throws:

PanamaException - the exception if the ServiceAlertSubscription can not be found.

removeCondition

public void removeCondition(AlertConditionMeta condition)
                     throws PanamaException

Removes the condition for the master alert.

Parameters:

condition - AlertConditionMeta condition object to remove

Throws:

PanamaException - exception thrown when remove condition failed

removeFilteringHookClassName

public void removeFilteringHookClassName(java.lang.String filteringHookClassName)
                                  throws PanamaException

Removes the filtering hook class name.

Parameters:

filteringHookClassName - the filtering hook class name to remove.

Throws:

PanamaException - exception thrown when remove failed

removeMapping

public void removeMapping(MAlertServiceMapping mapping)
                   throws PanamaException

Removes the specified mapping object for this master alert.
This method call has to be followed by a save() call for committing the removal.

Parameters:

mapping - The mapping that needs to be removed

Throws:

PanamaException - the exception if the MAlertServiceMapping can not be removed.

removeUserAlertSubscription

public void removeUserAlertSubscription(ServiceAlertSubscription sub)
                                 throws PanamaException

Removes the specified subscription object for this master alert.
This method commits immediately! This commit is independent from MasterAlertService.save() and will not affect any other master alert transaction.

Parameters:

sub - the ServiceAlertSubscription object

Throws:

PanamaException - the exception when this operation fails

resumeAllUserAlertSubscriptions

public void resumeAllUserAlertSubscriptions(User user,
                                            Link link)
                                     throws PanamaException

Resume all user alert subscriptions for the given user and link.
This method commits immediately! This commit is independent from MasterAlertService.save() and will not affect any other master alert transaction.

Parameters:

user - the User object

link - the Link object

Throws:

PanamaException

resumeUserAlertSubscription

public void resumeUserAlertSubscription(ServiceAlertSubscription sub)
                                 throws PanamaException

Resumes this alert for the given subscription object.
This method commits immediately! This commit is independent from MasterAlertService.save() and will not affect any other master alert transaction.

Parameters:

sub - the ServiceAlertSubscription object

Throws:

PanamaException - the exception when this operation fails

save

public void save()
          throws PanamaException

Commits the changes to the database.
Any create/update operation must be committed with this method. This method also performs a commit for the following objects used in this master alert service:
MAlertServiceMapping, AlertChainParamMeta, AlertInputParamMeta, AlertConditionMeta.

Note that alert objects does not use the wireless caching/persistence framework.

Throws:

PanamaException - the exception when commit failed

setConditionRelationType

public void setConditionRelationType(java.lang.String conditionType)
                              throws PanamaException

Sets the condition relation type.
Notifications can be defined to contain more than one condition, i.e. price is greater than 20 and/or change is less than 10%.
For multiple conditions, it is possible to specify the relation type between these conditions. Relation can be either AND or OR. In this release, mix of relations is not supported.

Parameters:

conditionType - condition type for this master alert. RELATION_AND and RELATION_OR are defined in this interface to specify valid condition types.

Throws:

PanamaException - exception thrown when setting condition type fail

setDescription

public void setDescription(java.lang.String desc)

Sets the description for the Master Alert Service.
Note that this description will be used as the notification message subject.

Parameters:

desc - Description

setFormattedXMLTemplate

public void setFormattedXMLTemplate(java.lang.String messageTemplate)
                             throws PanamaException

Sets the formatted xml template for this master service.
Provided message template should be a valid Mobile XML or XHTML document.
If this master notification service is based on a data feeder, any data feeder input/output parameter can be used in the template using the notation of &<parameter name>;, which is similar to the XML entity notation.
Sample Message Template:

 <?xml version = "1.0" encoding = "UTF-8" standalone="yes" ?>
 <SimpleResult>
   <SimpleContainer>
     <SimpleText>
       <SimpleTitle>OracleAS Wireless</SimpleTitle>
       <SimpleTextItem>Sample Notification: price: &price; and change: &change; for stock: &sym;</SimpleTextItem>
     </SimpleText>
   </SimpleContainer>
 </SimpleResult>
 

Parameters:

messageTemplate - the String contaning the formatted xml

Throws:

PanamaException - Exception thrown when the specified template is not a valid mobile xml or xhtml document and or any other error occurs

setTimeBasedType

public void setTimeBasedType(boolean strict)
                      throws PanamaException

Set/Unset time based type to strictly time-based.
Time-based notifications can be used in conjunction with value based predicates. For this case, notification messages can be sent when: either both time-based and data-based predicates are met, or at least one of them is met.
Strictly time based notifications are sent only if data predicates are met at the user-specified time.

Parameters:

strict - time based type (true for strictly time based)

Throws:

PanamaException - exception thrown when setting time based type fail

suspendAllUserAlertSubscriptions

public void suspendAllUserAlertSubscriptions(User user,
                                             Link link)
                                      throws PanamaException

Suspends all user alert subscriptions for the given user and link.
This method commits immediately! This commit is independent from MasterAlertService.save() and will not affect any other master alert transaction.

Parameters:

user - the User object

link - the Link object

Throws:

PanamaException

suspendUserAlertSubscription

public void suspendUserAlertSubscription(ServiceAlertSubscription sub)
                                  throws PanamaException

Suspends this alert for the given subscription object.
This method commits immediately! This commit is independent from MasterAlertService.save() and will not affect any other master alert transaction.

Parameters:

sub - the ServiceAlertSubscription object

Throws:

PanamaException - the exception when this operation fails