<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">

Overview

Package

Class

Tree

Deprecated

Index

Help

Oracle Application Server Wireless Java API Reference
B10400-01

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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);
    } 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, 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. The returned MAlertServiceMapping can be used to fill in the details for this mapping.
`MAlertServiceMapping`	`createTemplateMapping(MasterService masterService)` Creates a mapping object for this master alert and the given master service with the default message template. This call will perform all necessary operatins such as: filling in the master service URL argument with the built-in URL that will process this message and creating the parameter mapping.
`void`	`delete()` Deletes the master alert service This method call has to be followed by a `save()` call for committing the delete.
`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 For mapping alert parameters to service parameters, this method can be used to get a merged list
`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. This method call has to be followed by a `save()` call for committing the removal.
`void`	`removeUserAlertSubscription(ServiceAlertSubscription sub)` 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.
`void`	`resumeAllUserAlertSubscriptions(User user, Link link)` 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.
`void`	`resumeUserAlertSubscription(ServiceAlertSubscription sub)` 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.
`void`	`save()` Commits the changes to the database.
`void`	`setConditionRelationType(java.lang.String conditionType)` Set the condition relation type.
`void`	`setDescription(java.lang.String desc)` Sets description for the Master Alert Service Note that this description will be used as the notification message subject if relevant.
`void`	`setFormattedXMLTemplate(java.lang.String simpleResultXml)` Sets the formatted xml template for this master service.
`void`	`setTimeBasedType(boolean strict)` Set/Unset time based type to strictly time-based Time-based notifications can be used in conjunction with value based predicates.
`void`	`suspendAllUserAlertSubscriptions(User user, Link link)` 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.
`void`	`suspendUserAlertSubscription(ServiceAlertSubscription sub)` 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.

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

TYPENAME

public static final java.lang.String TYPENAME

The typename of the master alert object

See Also:: Constant Field Values

TYPEID

public static final int TYPEID

The typeid of the master alert object

See Also:: Constant Field Values

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

Method Detail

getId

public long getId()

Returns the Master Alert id

Specified by:: getId in interface ModelObject

Returns:: long the id of the master alert

getName

public java.lang.String getName()

Returns the master alert name

Specified by:: getName in interface ModelObject

Returns:: String the name of the master alert service

getFormattedXMLTemplate

public java.lang.String getFormattedXMLTemplate()

Returns the formatted xml template

Returns:: String The formatted xml template against this master service

setFormattedXMLTemplate

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

Sets the formatted xml template for this master service. Provided message template should be a valid Mobile XML 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:: simpleResultXml - the String contaning the formatted xml
Throws:: PanamaException - Exception thrown when the specified template is not a valid mobile xml document and or any other error occurs

getFilteringHookClassNames

public java.lang.String[] getFilteringHookClassNames()

Returns filtering hook class names

Returns:: String[] array of filtering hook class names

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
Throws:: PanamaException - exception thrown when addition failed
See Also:: MobileAlertSubscriberFilter

removeFilteringHookClassName

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

Removes the filtering hook class name

Parameters:: filteringHookClassName - the filtering hook class name
Throws:: PanamaException - exception thrown when remove failed

isTimeBaseEnabled

public boolean isTimeBaseEnabled()

Checks if time base is enabled

Returns:: boolean true if time base is enabled

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

isLocationBaseEnabled

public boolean isLocationBaseEnabled()

Checks if location base is enabled

Returns:: boolean true if location base is enabled

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

getInputParameters

public AlertInputParamMeta[] getInputParameters()

Returns the input parameter meta data

Returns:: AlertInputParamMeta[] 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.

getParameters

public AlertParameterMeta[] getParameters()

Returns the merged input + output parameters meta data For mapping alert parameters to service parameters, this method can be used to get a merged list

Returns:: AlertInputParamMeta[] Array of input param meta data

getConditionDefinitions

public AlertConditionMeta[] getConditionDefinitions()

Returns the condition meta data

Returns:: AlertConditionMeta[] Array of condition meta data

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
Throws:: PaanamaException - the exception thrown when addition failed; PanamaException

getDataFeeder

public DataFeeder getDataFeeder()

Returns the data feeder object used by this master alert

Returns:: DataFeeder the data feeder object. Returns null if this master alert service is not value based.

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

setConditionRelationType

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

Set 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

getConditionRelationType

public java.lang.String getConditionRelationType()
                                          throws PanamaException

Returns the condition relation type

Returns:: String condition type for this master alert
Throws:: PanamaException - exception thrown when setting condition type fail

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

getTimeBasedType

public boolean getTimeBasedType()
                         throws PanamaException

Returns the time based type

Returns:: boolean time based type (true for strictly time based)
Throws:: PanamaException - exception thrown when getting time based type fail

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

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

setDescription

public void setDescription(java.lang.String desc)

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

Parameters:: desc - The description

getDescription

public java.lang.String getDescription()

Returns the description of the master alert

Returns:: String The description associated with the master alert

getUserAlertSubscriptions

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

Returns all user alert subscriptions for the given user and link

Parameters:: user - the User object; link - the Link object
Returns:: ServiceAlertSubscription[] Array of subscription objects

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; PanamaException

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; PanamaException

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

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

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

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

lookupUserAlertSubscription

public ServiceAlertSubscription lookupUserAlertSubscription(long subscriptionId)
                                                     throws PanamaException

Lookup a subscription object

Returns:: ServiceAlertSubscription object
Throws:: PanamaException - the exception if the ServiceAlertSubscription can not be found.

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
Returns:: MAlertServiceMapping created mapping object
Throws:: PanamaException - the exception if the MAlertServiceMapping can not be created.
See Also:: MAlertServiceMapping

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.

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

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 operatins such as: filling in the master service URL argument with the built-in URL that will process this message and creating the parameter mapping.

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

getMappings

public MAlertServiceMapping[] getMappings()

Returns all mapping objects for this master alert

Returns:: MAlertServiceMapping[] Array of all available mapping objects.

getMapping

public MAlertServiceMapping getMapping(MasterService mService)

Returns the first mapping object for the given master service

Returns:: MAlertServiceMapping Mapping object