10g (9.0.4)
Part Number B10948-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle Application Server Wireless Developer's Guide 10g (9.0.4) Part Number B10948-01 |
|
This chapter describes Messaging Application architecture, and explains how to use these Applications to create and deploy mobile applications. Each section of this document presents a different topic. These sections include:
Messaging services are a key component that enhance your mobile applications by supporting sending and receiving messages among mobile users. OracleAS Wireless Messaging services provide a highly scalable mechanism to deliver messages to all mobile devices. Messages are delivered to mobile devices using native device protocols, for example through SMS to a mobile phone, as an email to a 2-way pager, as an audio message to regular telephone, as an Instant Messaging (IM) message to an IM client or as a fax to a fax machine.
Messaging services in OracleAS Wireless also offer a Web Service Interface (specified using WSDL) that uses SOAP over HTTP. The SOAP service enables applications to invoke remote object methods over HTTP protocol. This enables applications to invoke Messaging services from anywhere on the Internet, using any programming model. OracleAS Wireless Messaging services enable applications to specify both the message and the recipient(s) of the message. The application communicates to the Messaging service in OracleAS Wireless using SOAP and HTTP. OracleAS Wireless receives the message and delivers it to mobile devices using appropriate protocols such as SMS, Email, Voice, and others.
Messaging Services in OracleAS Wireless are scalable, and can handle large volumes of messages to many devices. The Messaging Service is based on extensible architecture and design; it can support a variety of devices and push protocols. Push protocols are handled by the XMS messaging API. The Messaging subsystem supports a driver-based architecture; the drivers are components in the wireless messaging system that handle all device-specific or communication protocol-specific routines.
OracleAS Wireless provide intelligent messaging with functionality for:
Messages that are authored generically in XHTML or OracleAS Wireless XML are automatically adapted for devices by OracleAS Wireless. The power of adaptation allows a message to be written once and automatically optimized for receiving device capabilities. For example, multi-media content can be optimized for a device by using image conversion allowing images to be altered from full-color to black and white.
OracleAS Wireless supports Multi-Media Messaging (MMS) for rich mobile messages including graphics, video and audio. MMS messages can be authored natively in SMIL, XHTML or OracleAS Wireless XML.
The Messaging subsystem (based on the device address and transport type such as SMS, MMS, IM, Voice, Email), dispatches a message to the appropriate transport protocol driver. The driver interface delivers the message to a device in the native device protocol. The Messaging subsystem can support multiple drivers in a single instance.
Message drivers in OracleAS Wireless are plugable modules that implement device-specific or communication protocol-specific handling routines. OracleAS Wireless includes pre-built drivers that support communication protocols such as SMS (SMPP and UCP), MMS, IM, Voice, Email and Fax.
OracleAS Wireless includes a special driver implementation that enables your wireless instance to act as a client to another OracleAS Wireless installation or any service that respects the Web Service Interface defined by OracleAS Wireless. This special driver uses the SOAP interface (as the XMS APIs) to send messages. By default, this driver is configured to act as an XMS Client to an OracleAS Wireless instance hosted, on the Internet, by Oracle. Instance administrators can change this default setting to point to any server that respects the XMS WSDL interface defined by OracleAS Wireless. As a result, any OracleAS Wireless installation is capable of sending SMS, MMS, Email, Voice, Fax messages out-of-the-box without configuration.
There is a quota preconfigured. If you need to raise the quota after exceeding the pre-allotted limit, see your Oracle administrator.
The XMS component includes MMS Center (MMSC) functionality out-of-the-box, supporting the MM1 message notification protocol. If the recipient device has an MMS browser, a notification message is sent to the browser, and the message is retrieved using HTTP. The content is stored and served out by OracleAS Wireless, the only external component needed is a regular SMSC for transmitting the notification message. Coupled with the fact that OracleAS Wireless can send SMS out-of-the-box using a hosted server, the product can send MMS out-of-the-box without configuration.
The notification framework includes flexible message templates, security to prevent message spoofing, support for message prioritization, and more flexibility in handling volume notifications.
The OracleAS Wireless Messaging Service is deployed as a web service using SOAP with HTTP as the transport layer. WSDL (Web Services Definition Language) is a standard XML interface that defines a Web Service application. With clearly defined WSDL, developers can build applications in any programming language (such as Java and VB) that can communicate with the OracleAS Wireless messaging interface over the Internet. Developers can use any WSDL toolkit to quickly implement a one-way (Push) application and send messages to mobile devices using any OracleAS Wireless instance on the Internet.
Parallel to the Web Service interface, OracleAS Wireless also supports a simple Java API (the XMS API) for building one-way message (Push) applications. The XMS API uses SOAP over HTTP to communicate with the OracleAS Wireless server instance, however the XMS API abstracts any protocol-specific (SOAP) implementation details from the application's Java code. XMS is the preferred API for application developers who need a clear and simple interface to deliver messages.
The XMS API supports a uniform interface for the delivery of messages to any kind of device (such as SMS, MMS, IM, Voice, Email and Fax). The API allows applications to specify multiple recipients for a single message using only one delivery request.
Furthermore, message destination addresses can have devices using different communications channels; for example, a single message delivery request application can send messages to Email as well as fax machines. Applications can make one delivery request and send the messages to a list of users with SMS or MMS devices, Email or IM clients and Voice devices.
OracleAS Wireless supports different types of contents for delivery. A message can consist of only text characters, or can be as complex as a multipart message. Message types are identified based on the MIME, hence delivering documents such as Microsoft Word or Adobe PDF is possible if the target device supports the message MIME type. OracleAS Wireless provides two variants of the XMS API: the XMSSimpleSender API supports text-only messages, while the XMSSender advanced XMS API supports messages of any MIME type.
The following is an abridged overview of the XMS API functionality; for a complete overview see the XMS JavaDoc.
oracle.panama.messaging.xms.XMSSimpleSender
XMSSimpleSender corresponds to the PushLite API from earlier OracleAS Wireless releases. It is a simple API that works on String parameters only. It is lightweight and very easy to use.
public String[] sendMsg(String[] recipients, String message)
Sends out a text message (without subject) to multiple recipients of multiple transport types. Encoding and content of the message depends on the content of the message and the receiving device. This method provides the easiest way to send out text messages. Other overloaded send() methods can be used to set subject, reply to, content type encoding (MIME type) and associated key parameters.
recipients--an array of recipients addresses. A sender's address consists of either an OracleAS Wireless user name or a transport type and address, separated by a colon (:).
Example 1: Email:myemail@company.com
Example 2: SMS:16505551234
Example 3: username
Valid transport types are defined in:
oracle.panama.messaging.common.TransportType
recipients--recipients' addresses (such as: email address, phone number or user name)
Format of address:
<address string ><:transport type > [;<address string>:<transport type >]* <address string> = <email address>|<phone number> |< subscriber ID > |< user address > <user address> = < brand name > ~ < user name > <phone number> = < country code > - < area code > - < local phone number >
One line per recipient. A recipient may have multiple failover addresses and each address must have at least one transport type. Use a colon(:) to separate address and transport types. Use a comma(,) to separate transport types within the same address. Use a semicolon(;) to separate addresses.
Example 1: SMS:1-650-5551234,Voice:1-650-5551234;Fax:1-408-3456789
Example 2: Email:myemail@foo.com;Voice:mary,Email:mary,Fax:mary;Email:bob
[transport] is one of the types defined in oracle.panama.messaging.common.TransportType
message--body of the message. The message text can be either plain or rich text (XHTML or OracleAS Wireless XML). XMS examines the content of the message to detect whether rich text is used. Rich text will be transformed to the appropriate markup for the target device.
public String[] getStatus(String[] messageIDs)
Gets the current status of a set of message IDs.
Returns: an array of text status strings.
oracle.panama.messaging.xms.XMSSender
XMSSender corresponds to the Push API from earlier OracleAS Wireless releases. It is an API that allows users to send out more complex (multipart) messages.
public WorkOrder[] sendMsg(Packet pkt)
Sends out a message packet.
pkt--The message packet to be delivered. Packet class will be discussed below.
Returns: a set of WorkOrders will be returned after the XMS server accepts the request. One WorkOrder will be returned for each instance of a recipient's address.
public Status getStatus(WorkOrder workOrder)
Gets the current status of a work order. A work order has one address and the message ID of that address.
public Status[] getStatus(WorkOrder[] workOrders)
Gets the current status of a set of work orders.
oracle.panama.messaging.push.Packet
Packet class represents a generic message in the real world (For example: email). It may have a subject, a body or a set of message bodies (multipart). The same message may be delivered to multiple recipients of multiple transport types (delivery types). For example: the same message can be delivered to 2 Email recipients, 3 SMS recipients and 4 fax machines in the same packet.
Every transport type may have a sender, an alternate reply to address and a group of recipients. The packet could have a set of optional delivery instructions, such as priority or registered.
To accomplish this, first construct an empty Packet instance. Then set message, message info, sender, reply to and recipients of the packet. See the sample code below for more details.
The XMS API provides methods to set the properties of a message and dispatch it to a OracleAS Wireless instance. For a detailed description of the API interfaces, see the OracleAS Wireless XMS Javadoc (oracle.panama.messaging.xms). To send a push message, you must provide the following:
The simplest way to use the XMS API is to send text-only messages. When used in this manner, the XMS API behaves like the Push API from earlier OracleAS Wireless releases, with one important difference: when sending messages to devices that cannot display plain text (such as WAP Push), the input text is embedded in the correct markup for the chosen device.
XMS accepts rich text (that is, text marked-up in OracleAS Wireless XML or XHTML markup languages supported by OracleAS Wireless). The content of the input message is converted to fit the target device chosen. This includes both the structure and layout of the document itself, as well as any embedded images or sound files. In addition, XMS also processes URLs to be appropriate for the target device. Specifically, if the target device cannot display HTTP hyperlinks, the message is rewritten to use the Reverse Async (RevAsync) format instead, which allows the end user to invoke links by using a request-reply messaging exchange.
In addition to transcoding the input markup, XMS also converts images and audio as appropriate. For images, the conversion includes changing the image format, as well as resizing and resampling the image if necessary for the target device. If a single image is sent through a channel that supports handset provisioning (such as SMS) it will be sent as an installable operator logo. Similarly, if a single audio clip is sent, it is converted to a ringtone in the format appropriate to the target device.
By providing transparent support for Reverse Async, XMS allows other applications (such as the Notification framework) to send rich content that a user can interact with (so-called actionable notifications). These are notifications that contain the output of a OracleAS Wireless service; the user can interact with the service by replying to the message. Actionable notifications can be thought of as RevAsync sessions that are started by the server rather than by the user.
XMS accepts regular OracleAS Wireless XML markup, as well as the mapping of the markup language elements (depending on the target device of the message). A rich target device such as an MMS browser receives all multimedia elements, and will also use any timing information present in the markup to control the duration of multimedia content. Images can be supplied in JPEG, GIF or BMP format; if the target device does not support the image format at hand, the image will be converted to another format suitable for the target device. XMS also supports the available attribute of the OracleAS Wireless XML SimpleImage tag; this means an image can be stored in multiple formats and the best format of those available will be chosen if possible. This is in fact the recommended approach, since automatic conversion both introduces some computational overhead and can lead to undesirable conversion artifacts in the final image. By pre-generating multiple versions of a given image, one can create simpler versions of the image for devices that support low-resolution images of limited colordepth.
In addition to plain and rich text, XMS can send any arbitrary content. In this case, no transcoding is performed, and it is up to the client programmer to format and package the message correctly.
An explicit MIME-type should be specified in this case, which means the XMSSender API is the correct API to use for this class of messages.
Transport API is a rich set of APIs that can be used for both sending and receiving.
Transport API is the client side messaging interface. This section details the Transport API, explaining the major constructs and functionality available to customize the Transport System.
XMS API is built over Transport API. XMS API handles sending only. In terms of sending, transport API does not provide message transformation. However, Transport API provides some extra features which XMS API does not have, such as status tracking, hints and fine-tuned message routing.
When a message delivery request is submitted, the transport system performs analysis of the recipients and routes the message to the appropriate protocol drivers for delivery.
To receive messages, an application must register listening end points and a message callback listener to the transport system. An end point is in the form of an address, such as a phone number. It identifies (to the transport system) how messages should be dispatched. When a message is received for a targeted address, it is dispatched to the listener associated with an end point with a matching address.
The key interface is oracle.panama.messaging.transport.Messenger. An instance of this interface will be returned through the Get method of oracle.panama.messaging.transport.MessengerController which in turn can be obtained through the TransportLocator class. This gives you access to the rest of the package to build your messaging applications. See the Javadoc for a complete reference of the APIs.
A single message can be delivered to multiple recipients of different communication protocols. For example, one can send a meeting reminder to a few people using SMS, and some other people to their email addresses. Before routing messages to drivers, the transport analyzes and groups recipients by their delivery category. Typically, the transport system starts its internal processing by analyzing all destinations and groups them accordingly.
To send a message, the transport system must locate a proper driver to do so. The process of finding a proper driver is called message routing. The transport system at a particular time may have many messaging servers and protocol drivers configured. Different driver instances may handle different categories of messages.
For example, a driver may be able to send SMS messages only. Another one may be able to send email and fax messages only. Therefore, the transport system must use a driver with SMS capability to send SMS messages, a driver with email capability to send email messages. Sometimes, there may be more than one driver that can handle the same category of messages. For example, there could be more than two SMS drivers. One communicates with ATT's SMSC, the other with Cingular's SMSC. The transport system must use ATT's SMS driver to send SMS messages to ATT's devices, and use Cingular's SMS driver to send SMS messages to Cingular's devices.
All these decisions are made by the transport based on two sets of information. The first set is the sending criteria specified by the application (such as delivery type, speed, cost and encoding). Of these, the delivery type is required and can be specified in the class destination. The other information is provided by the set of available drivers. The properties of the drivers are configured by the administrator, such as driver speed, driver cost, encoding and delivery category.
As mentioned earlier, routing finds the best-matching driver. Some properties must match, for example, the delivery category; some of them just find the closest match, for example, cost and speed.
The transport uses the following information to do the routing:
Attribute encoding is not used in routing.
The transport will route a message to a driver with best match:
If (speed_requested >= 0 and cost_requested >= 0), the minimum (driver_speed -speed_requested)**2 + (driver_cost - cost_requested)**2
or
if cost_requested < 0 the minimum abs(driver_speed - speed_requested)
or
if speed_requested < 0, the minimum abs(driver_cost - cost_requested)
If more than one driver meet the above criteria, the transport chooses randomly one of them.
Applications can provide hints that help speed up routing and destination analysis. For example, if you specify Email as the delivery category of all recipients, the transport will not have to look into each of the recipients to determine what they are.
In principal, the required parameter to deliver a message (the Messenger.send() methods) is Destination and Message. All others (SenderInfo, MessageInfo and DeviceInfo) are optional. When they are specified, they will be interpreted as hints that describe properties common to all recipients. For example, if DeviceInfo is specified and the getDeliveryType() of this DeviceInfo instance returns DeliveryType.EMAIL.getName() then the transport will take it as a hint that all recipients are email addresses and no destination analysis will be performed.
Before OracleAS Wireless, messaging devices could not respond to Push messages initiated from a server. For example, the notification messages sent by the OracleAS Wireless instance were considered in their final result once they were received on a user's device; there was no more interaction. The inability to respond to such messages limited the information and options provided to device users through Push messaging.
Integrating XMS and Async exposes an API that enables content providers to create Push messages which can be acted on for messaging channels such as: SMS, Email and Instant Messaging. Figure 10-2, "Actionable Messages" the relevant components and their relationship.
XMS Client is a component which calls the XMS API to deliver messages and content. There are several requirements on the kind of document it can generate in order to make a Push message actionable:
The role of XMS for actionable messages is to determine if a document being sent must be in persistent state. One example is to push a document with an embedded URL to an SMS device. Since the device does not have a browser to process the URL link, the state must be cached in the server. The XML achieves this by calling the underlying component, RevAsync. The document is subsequently transformed to the device result and sent out.
RevAsync is a newly created entity under the XMS component. Its main function is to receive an OracleAS Wireless-supported markup document as input and analyze the document to locate all the elements and attributes which need to be cached. The cached objects are persisted into the database and are used by Async to reconstruct the session state once the device user replies.
To enable an actionable message, the content provided to XMS must be in a OracleAS Wireless-supported markup document. For this release, only OracleAS Wireless XML is supported.
There are two ways to trigger an actionable message:
Receiving an OracleAS Wireless XML input, XMS traverses the document for any element that could trigger further user interaction. A typical example is the SimpleMenu element which presents a hyperlink for a device user to select. A persistent state and its corresponding transaction ID are generated once such a situation is detected. RevAsync adds an extra instruction line to the result message indicating the format and the transaction ID to be used for user reply. The ID must be part of the reply parameters if the user decides to respond. This way, Async is able to restore the session state by the transaction ID once it receives an actionable message reply.
To retrieve the persisted user state, Async uses the following methods to differentiate between the user reply of an actionable message and the typical Async requests:
<AM short name> <transaction ID> <parameters>
For example, a user may receive the following message for stock notifications:
To respond, type 'am 2 <link selector>' [orcl] L 15.25 B 15.20 A 15.30 O 15.10 1 News 2 Detail Quote
A user would reply to this message with the content am 2 2 to get the Detail Quote option. Since am is the site-wide unique short name, Async will interpret the parameter right after the short name as the transaction ID and use it to retrieve all the persisted state.
To enable actionable messages, follow these steps:
As discussed earlier, the document can be either generated as the output of a notification service, or a document being pushed out by an XMS client. The document should contain action elements (such as SimpleMenu or SimpleForm, on which device users can act). A sample document is shown below.
<SimpleResult> <SimpleContainer> <SimpleText> <SimpleTextItem>Approve/Disapprove John Doe's expense report #1234</SimpleTextItem> <SimpleTextItem>Upgrade 256 MB memory on desktop pc - $30<SimpleBreak/></SimpleTextItem> </SimpleText> <SimpleMenu name="" title=""> <SimpleMenuItem target="omp://expensereply?answer=approved&reportNo=1234">Approve</SimpleMenuItem> <SimpleMenuItem target="omp://expensereply?answer=disapproved&reportNo=1234">Disapprove</SimpleMenuItem> </SimpleMenu> </SimpleContainer> </SimpleResult>
omp://expensereply identifies the service to be invoked once such an action item is triggered on a user reply message.
Application Links addressed in the pushed document must be created with the OMP value set. For the example above, the OMP value should is omp://expensereply
At least one access point must be created for each supported delivery channel. The access point can be set as actionable-message-dedicated if it is only reserved as the entry point of the user reply of actionable message. Or, it can also be an access point, which allows messages from both Async requests and replies of an actionable message. The from address of the push message is set to the access point configured so it can be routed to the Async entry point when a user replies. If there are multiple access points set for the same channels, the one with a dedicated flag set has precedence.
Below are the supported configuration parameters for Actionable Messages. See OracleAS Wireless Administrator's Guide for detailed configuration steps.
OracleAS Wireless presents a framework and a runtime environment for developing wireless and voice applications accessed through a browser-based device, such as a device with a WAP or XHTML browser, or through messaging-protocol-based devices such as mobile phones with SMS. Async is the Wireless component that enables the messaging protocol-based devices to access these wireless applications.
Conventionally, the entry point into an application server is through the HTTP protocol. This limits applications built on an application server to only clients with Web capability. This server restriction is a problem for mobile market users, because the vast majority of mobile users does not have, or are not enabled, with Web access. These users, however, are almost certain to have some kind of message capabilities (such as e-mail or SMS). Consequently, developers are faced with the dilemma of building applications specifically for users depending on their capability, or ignoring them because the application server cannot deal with the mobile market.
OracleAS Wireless solves this dilemma for developers without them having to do anything at all. With the introduction of Async, mobile applications cannot only be accessed through the usual HTTP protocol, but through any other messaging protocol (such as e-mail or SMS) as well. Rather than worry about writing an application to fit a certain protocol, developers can instead focus on building their application logic. OracleAS Wireless establishes the proper connection and performs session management, and the interpretation of user requests. A mobile application is invoked the same way regardless of which protocol handles the incoming requests, offering complete transparency to application developers to allow access to their services.
One of the most obvious challenges is supporting multiple protocols. It is not desirable to build the same functionality to work with e-mail, then SMS, then some other protocols. OracleAS Wireless offers access to the same application regardless of the protocol used by clients. Hence the immediate challenge is to be able to support multiple protocols uniformly.
In contrast to the HTTP protocol, (commonly referred to as the synchronous protocol) messaging protocols such as SMS or e-mail are asynchronous. It is asynchronous because unlike HTTP, they are not based on a "request and response" model. A single atomic operation is typically one way. For example, when you use a Web browser, you enter a URL and make the request, then you wait for the result to come back. In messaging protocols (such as SMS) sending a message itself completes one operation. Most applications respond to user requests so HTTP is usually adequate. To enable the same application be accessed through asynchronous protocols presents a challenge on how such behavior can be mimicked with protocols such as SMS or e-mail.
Another big challenge is that most applications are session based; multiple requests and responses are typically required to complete a task. Applications are able to maintain sessions in the Web world because the client, a Web browser, has built in capabilities such as cookies to facilitate session semantics. This is not the case for an e-mail or SMS client. They do not have any such ability built in to support conversational applications.
A Web browser offers a User Interface for navigating through applications (examples include clicking on a hyperlink and traversing through a menu or a series of steps to complete certain functionality). Clients that work with other protocols such as SMS or e-mail typically do not have similar navigation power. The challenge here is to offer similar navigating capability to such clients so that applications can be independent of the protocols.
In the Web world, applications are typically assigned a URL. The URL is how the application can be identified and requested. Clients for messaging are typically plain text devices; although there is no convention on how to name an application, consistency across protocols is needed.
Async combines functionality of a HTTP server and portions of a Web browser to provide its functionality.
This challenge is a relatively easy one. Built on top of the OracleAS Wireless transport system, support for multiple transport protocols is achieved by the nature of the transport system itself. Async registers as an application to the transport system to send and receive messages. It further registers one or more addresses for each of the protocols it is serving in order to interact with users on those protocols. For example, it can register async@yourcomany.com for e-mail and 1234567 for SMS. Then async@yourcompany.com and 1234567 become the URIs for their respective protocols similar to http://yourcompany.com in the Web world.
Async itself does not consider the incoming protocols; it is designed to send and receive messages by the means that it is registered to use. The payload (content) of the messages are what Async interprets and acts upon.
Async builds logic similar to an HTTP listener to present synchronous semantics over asynchronous protocols. It achieves this by acting as a client to the application that the device requested. Async makes a request to the application on behalf of the user, waits and processes the response from the application, then formats the response and presents it back to the users. To users, it appears as if it is the response from an earlier request.
Upon receiving requests from a user, Async creates a session for the user to enable conversational applications to function. Unlike in HTTP, where session information is kept by the browser (or cookie), all session states are kept in the backend by Async.
Async transforms elements such as forms or menus, and presents a navigation command for end users. When elements such as forms are returned by an application, Async retains the format of the form in the backend, and determines what action to take when the form is submitted with all of the other necessary information. When this user (using the set of Async-specified commands) completes and submits the command, Async makes a request (based on the current user information stored in Async) and processes the result again on behalf of the user. This is akin to hyperlinks stored in the backend when a user clicks on the face of the link.
Just as in assigning a URL to an application in the Web world, using Async requires that a short name be assigned to an application so that it can be Async-enabled. For example, assume the stock quote application has been assigned the path: /finance/quote and can be accessed as http://mycompany.com/finance/stock. Through the Content Manager, one or more short names can be assigned to the application (for example, st.). Now any messages received by Async that begin with st signals a request for the stock quote application. A user can send st orcl (orcl is the stock ticker symbol for Oracle Corporation) to an Async access point to which Async is configured to listen, such as async@mycompany.com for e-mail or 1234567 for SMS, and get back the stock quote for Oracle Corporation.
Optionally, service access points can be created to identify an Async application. Through Content Manager, you can also associate an e-mail access point (stock@mycompany.com) and an SMS access point (123FINANCE) to the stock quote application. Once this is done, sending just orcl as an email to stock@mycompany.com or as SMS message to 123FINANCE results in receiving the stock quote of Oracle Corporation.
Async differentiates the user issuing a request into two categories: guest or registered. Upon receipt of a user request by Async, the source address of the request message is used to reverse-lookup an OracleAS Wireless user for authentication. A user object can be located if a user has a device address registered under his or her profile. This address is the same as the source address of the request message. The located user object is then bound to a newly authenticated session created by the request. Otherwise, a guest user object is bound to the session. Any applications which are authorized to the user are accessible to requests issued from the device.
Only those applications belonging to the guest group are accessible to a guest user. Accessing a non-guest application triggers a returned form challenging the user for name and password. A valid OracleAS Wireless username/password supplied by the user enables the previous session to be upgraded to an authenticated one with the user object identified by the name to be bound. Alternately, a guest user can log in explicitly through a login command,!L (followed by a user name and password) to avoid being challenged.
As discussed earlier, messaging clients typically only present plain text and do not offer conversational navigation capabilities. Async transforms and formats responses from applications to a certain presentation to enable such capabilities. Async includes a set of presentation formats and navigational commands similar to what a Web browser has done for the Web world. Hence when a user invokes applications using Async, he or she sees the response in the format transformed by Async. Further interactions with Async would have to comply with the format expected by Async.
This section discusses the commands that users can issue to Async. Issuing a command is simply sending a message with the correct format. The command text can be put into a subject line or message body.
These commands invoke an application, perform menu selection and fill parameters. There are no reserved command symbols for the application invocation and form commands. Certain commands, such as form command and menu item selection, can be invoked only when there is a current form/menu state maintained in the user's session. More details on form/menu state will be discussed later in this chapter.
A list of site and application configuration parameters enable the system administrator or application developer to customize Async site- and application- level behavior through the Oracle Enterprise Manager (OEM) console and the OracleAS Wireless Tools. For more information, see Section 5.3.5.4 in Chapter 5, "Developing Services".
Through the Wireless Customization Portal, users create their own aliases as the short names to invoke Async applications. A user short name can be an alias that points to an application, or it could be an alias representing a sequence of Async short names.
For example, a user may define an alias (s) to represent the string, stk, which is the short name for a stock application. When the user issues an Async message with content, s orcl, to invoke the stock application, they receive a stock quote for Oracle Corporation (orcl is the stock ticker symbol for Oracle Corporation). A string (tw), can be created as the alias for a string value, traffic ny;weather ny, so two applications, traffic and weather, can be invoked by inputting two characters.
All Async-enabled applications should be assigned short names to enable end user access. The short name should uniquely identify an application on the entire site. To invoke an application, a message is sent to a site access point, such as info@oraclemobile.com, to which the Async Listener is configured to listen. The command line has the format:
<Svc Short Name> <parm1> <parm2> . . .
In the following example, a message is sent to the site access point: info@oraclemobile.com, to invoke a stock quote application with the short name, st. The application requires a stock symbol as its parameter (for this example, it is ORCL).
Each application may have application access points associated with it. For example, an Email address, stock@oraclemobile.com, can be used to identify a stock application. Since the application has been identified in the destination address of the request message, there is no need to specify the application short name in the command line. Only the application parameters, such as the stock symbol, are required in the command line.
All of the system commands (for example, help) can still be issued to the application-associated access point. The Async Listener interprets them in the same way they are sent to the site access point.
Features are presented similar to the HTTP model. An application invocation may trigger the return of a message with the menu. Each menu item is prefixed with a number. Users are able to make selections by issuing another message whose content contains the menu item number. This extends the application capability and enables improved user interaction. A yellow pages application having a short name of yp expects two user parameters: category and area. Users invoke applications by providing the values, for example, burger and home (a landmark for the user). The application searches for all the hamburger restaurants in the home area. A returned message from the application result contains a name list of burger restaurants. The user then issues another message to get detailed information on selected restaurants.
A form is the result of a application invocation requesting user input. The ideal user interaction for Async is when the user enters the input parameters on the command line instead of having to fill in the form, which requires more message round trips.
Figure 10-6, "Form Capability" demonstrates the possible interaction of a phone book application. The phonedit command, which enables users to search and edit the phone number for a particular user, expects a name as its parameter. (For the following example, jdoe is this parameter) The information of jdoe is returned with a menu, enabling the device user to edit the phone number or remove the user. There are two options for editing the phone number:
Or
A form may present fields, which allow users to make either single or multiple selections, similar to the check box or pull-down menu construct for HTML. To simplify selection for the device user, each selection option is prefixed with a number. The user fills in those fields by responding with the number prefix for the items he or she chooses. The field which allows multiple selections is presented with a input marker, [..]. This differentiates this field from a single selection field, which is represented by the single selection marker, []. The values for the user responses should be surrounded with quotation mark if multiple selections are made.
The following figure demonstrates the Select Form fields: Gender, a single selection field and Sports, a multiple selection field.
Menu navigation is possible since a session is maintained for each user. The term current menu identifies the latest menu that a user received from Async. The state of the current menu is kept in the user session on Async.
A user's menu selection always applies to the current menu. If a menu has not yet been received for the user, then Async attempts to locate an application whose short name is the same as the number provided by the user. An error is returned when no such application is found.
An application invocation through short name or access point automatically cancels the menu state created by the previous application invocation. As illustrated in Figure 10-8, a menu returns as a response to invoking the phonedit application. A message for requesting the stk service is subsequently issued. It clears the menu state created by the invocation of the phonedit application. An attempt to make a menu selection triggers an error message from Async.
A current form state is created in the user session whenever the user receives a form message. Form parameter values can be supplied by subsequent user requests to fill the parameter requested from the previous form message. If the user decides not to fill the form but instead to invoke another application, then the Escape command can be issued to cancel the current form state. Once the form state is clear, any form parameter values issued by the user are considered invalid. An error message should be returned in response to a form parameter value without a current form state. Alternatively, a user can issue a command prefix with a short name as a shortcut to clear the form state followed by the invocation of the service identified by the short name.
Figure 10-9, "Current Form State" illustrates a form state example. The device user invokes the phonedit application without providing any parameters. A form message is returned to the user expecting the user to fill in the search name. If the device user decides to invoke another application (for example stk), the first step is to clear the form state so that Async will not treat the command stk as the name value expected from the phonedit application. Then, a new stk command can be issued. These two steps are combined into one message by separating the two commands with the default command separator (;).
The short name, stk, when issued with the command prefix, such as a period ( . ), clears out the form state with fewer keystrokes.
Multiple commands can be issued from one message. They can be issued from the same line, each command separated by the configurable command separator (default [;]). Or, commands can be on different lines. The first blank line or stop command (!s) encountered marks the end of the command sequence. No command interpretation will be done on text after the mark.
Async applications can require multiple parameters. The default parameter separator is a blank space. If a parameter value contains space within it, then it can be enclosed by double quotes to represent a single parameter value. The parameter separator is configurable at the application level.
Figure 10-11 illustrates an application that provides directions. This application expects both the from and to (destination) addresses. The from address is provided with double quotes to enclose the whole value. The to is supplied as a landmark, home, from the user profile. The second message sent from the user is to request traffic information application. The application is configured to use a comma (,) as the parameter delimiter; users provide the parameter values with (,) to separate them.
Async applications are developed in the same manner as browser-based applications. An application provider receives user parameters from the device through HTTP protocol, and responds with the result in OracleAS Wireless XML or XHTML/XForms format. The requirement on the Async client is low; only the ability to send and receive text messages is needed. Because of this, Async does not support all tags. For details on those Async-specific interpretations of the supported tags, and the ways to author documents for this channel, see Chapter 8, "Authoring Mobile Browser and Voice Applications". See also: Chapter 3, "OracleAS Wireless Developer Kit".
Developers may, at times, need to acquire the device information of a service request for accounting or logging purposes. This information can be located through the HTTP header (if the service is created based on an HTTP adapter). The two relevant user device headers are:
The XMS component includes the MMS Center (MMSC) functionality out-of-the-box, supporting the MM1 message notification protocol. If the recipient device has an MMS browser, a notification message is sent to the browser, and the message is retrieved using HTTP. The content is stored and served out by OracleAS Wireless. To support MMS, the only external component needed is a regular SMSC for transmitting the notification message.
When the MMS browser receives the notification message, it contacts the XMSC using HTTP, as per the MM1 spec. The message is served out in encoded MMS format.
XMSC also supports MO (Mobile Originated) messages to another phone. In that case, the message will be stored in the XMSC and a notification message is sent to the target device as above.
XMSC also supports message storage and notification for other messaging channels. For example, if a user has a device that only has MMS capability. If a message is sent that contains multimedia content, XMS will send a text-only SMS message containing a URL, which the user can input into a regular Web browser in order to view the message.
In order to use the XMSC functionality, complete the following steps.
Go to System > Wireless Server > Site Administration > HTTP, HTTPS Configuration.
Under the URL Section, add the host name and port.
Go to System > Wireless Server > Site Administration, and expand Component Configuration. Click XMS Configuration.
Under the XMS Center Section, mark the Enable XMSC checkbox.
For Mobile Terminated (MT) messages (messages sent to a device), the above configuration is sufficient. As XMSC is a full MMSC, it also supports MO (Mobile Originated) messages, that is, messages sent from one phone to another using OracleAS Wireless as the intermediary. In this case the phone must be configured as follows:
The MMS browser must be configured to use the OracleAS Wireless instance as the outgoing message server. The exact steps to follow depend on the specific phone. The following are the steps to follow for the Sony Ericsson T68i:
http://<hostname>:<port>/xms/mm1
When the recipient is specified as a user name, the XMS runtime will determine what device and channel to use, depending on the user's available devices, as well as the user's current contact rules.
If the user has a number of different devices, the XMS runtime will select the best device and channel to use. The channel chosen will depend upon the user preference order as well as the content of the message. For example, imagine a user that has a cell phone with both SMS and MMS messaging capability. If a plain text message is sent to the user, the SMS channel will be chosen, as it is sufficient for that message, and since sending messages over SMS is usually cheaper and faster than through MMS. On the other hand, if the message has multimedia content, XMS will try to send the message through MMS.
In OracleAS Wireless, each user can have a Presence setting, which specifies the user's location and associated contact rule.The contact rule states the user's preferred delivery channel at that point in time. For more information about Contact Rules, see Chapter 15, "Enabling User Customization".
If a user has set a contact rule, that rule will be given preference over the automatic channel selection outlined above. Additionally, a contact rule may specify blackout periods where the user does not wish to receive messages. If the blackout period is set in the contact rule, XMS will delay delivery of the message until after the blackout period.
The Transport Layer is the foundation of the OracleAS Wireless messaging system. It contains the Transport API, Transport Server and Driver API. This section discusses the pre-built transport drivers, how to develop new drivers and how to extend the Transport Server.
The current Transport API is compatible with previous releases (new features created in this release are not, of course, available if you are using previous versions); the current, enhanced Driver API is incompatible with previous releases. However, all the pre-built drivers for previous releases are enhanced accordingly in this release. Previous releases of the pre-built driver cannot be used with this release of the Transport Server; only use current pre-built drivers. In addition to interface enhancements, the pre-built drivers include many new features.
Your own custom-built drivers from previous releases can be upgraded to work with the current Transport Server, provided the driver implements the new driver interface. The driver logic is not significantly changed; the change are confined mainly to the interface.
This driver provides the ability to send and receive MMS messages to and from a Nokia MMSC (Multimedia Messaging Service Center). It requires the Nokia MMS Java Library v1.1. The driver opens two TCP connections to the MMSC, one connection for sending and the other for receiving messages.
This driver requires the Nokia MMS Java Library v1.1 (MMSLibrary.jar) that is available from Forum Nokia (http://www.forum.nokia.com). You must add this library to the CLASSPATH in $ORACLE_HOME/opmn/conf/opmn.xml (UNIX) or $ORACLE_HOME\opmn\conf\opmn.xml (Windows).
oracle.panama.messaging.transport.driver.mms.NokiaMMSDriver
mms.nokia.account.id--The Nokia Account ID or Phone Number. This is required.
mms.nokia.mmsc.url--The Nokia MMSC URL. This is required.
mms.nokia.debug--Enable logging extra debug information to a file. Options: true (debug enabled), false OR leave blank (debug disabled).
mms.nokia.log.filename--Log filename for extra debug information. The default filename is NokiaMMSDriver.log.
mms.nokia.receive.host--The logical local hostname or IP address. If not present, it is derived from the local host.
mms.nokia.receive.port--Port for receiving MMS messages from MMSC. The default is 7000.
mms.nokia.receive.mode.async--Set Asynchronous Mode for receiving MMS messages from MMSC. Options: true (enable), false OR leave blank (disable). For further information about asynchronous mode, see the documentation that came with the Nokia MMS Java Library v1.1.
This driver provides the ability to send and receive MMS messages to and from a CMG MMSC (Multimedia Messaging Service Center). The driver uses the CMG MMSC API for VAS v1.01.
This driver requires the CMG MMSC API for VAS v1.01 (mmscapi.jar and mmscapi.war) available from CMG (http://www.cmgwds.com). You must add the mmscapi.jar library to the CLASSPATH in
$ORACLE_HOME/opmn/conf/opmn.xml (UNIX) or
$ORACLE_HOME\opmn\conf\opmn.xml (Windows).
oracle.panama.messaging.transport.driver.mms.CMGMMSDriver
mms.cmg.account.id
The CMG MMSC Account ID or Phone Number. This is required.
mms.cmg.account.password
The CMG MMSC Account Password. This is required.
mms.cmg.config.file
The path to the core configuration file for the CMG MMSC API. This is required. For details regarding the contents of this file, see the User Manual that is packaged with the CMG MMSC API distribution. We have included a sample configuration file ($ORACLE_HOME\wireless\messaging\drivers\cmg\CMGMMSDriver.cfg) with this driver.
mms.cmg.debug
Enable logging extra debug information to file. Options: true (debug enabled), false OR leave blank (debug disabled).
mms.cmg.billing.category
MMSC Billing Category (optional). This value is used to send custom billing category information to the MMSC. For details and examples of the billing category, see the User Manual that is packaged with the CMG MMSC API distribution.
mms.cmg.billing.price
MMSC Billing Price Value (optional). This value is used to send custom billing price information to the MMSC. For details and examples of the billing price, refer to the User Manual that is packaged with the CMG MMSC API distribution.
To configure the driver to receive MMS messages, you must perform these additional steps:
mmscapi.war file into a cmgmmsc.ear file as follows:
mmscapi.war into this directory and rename this file cmgmmsc.war. This creates the final directory structure:
cmgmmsc.ear.
cmgmmsc.ear to $ORACLE_HOME\wireless\j2ee\applications\
<web-app application="cmgmmsc" name="cmgmmsc" root="/cmgmmsc" load-on-startup="true"/>
<application name="cmgmmsc" path="../applications/cmgmmsc.ear" auto-start="true" />
cmgmmsc.ear file.
<servlet-mapping>
<servlet-name> HttpReceive </servlet-name> <url-pattern> /HR </url-pattern>
</servlet-mapping>
.jar)
This driver provides the ability to send MMS messages to a MMSC (Multimedia Messaging Service Center) using the MM7 protocol based on the specification of 3GPP TS 23.140 V5.3.0.
oracle.panama.messaging.transport.driver.mms.MM7Driver
mms.mm7.url--The URL to access the MMSC/MM7. This is required.
mms.vaspid--(Optional) Identifier of this application (VASP) for the MMSC.
mms.vasid--(Optional) Identifier of the originating application. Example: News.
mms.local.hostname--The logical local hostname or IP address. If not present, it is derived from the local host.
mms.local.port--The local listening port. The default value is 80.
mms.default.encoding--The default MM7/HTTP encoding format. The default encoding is UTF-8.
debug--Enable logging extra debug information to a file. Options: true (debug enabled), false OR leave blank (debug disabled).
CIMD (Computer Interface to Message Distribution) is an SMS protocol specified by Nokia. The OracleAS Wireless Server product includes a pre-built implementation of the CIMD driver that is capable of both sending and receiving messages. The driver opens one TCP/IP connection to the SMSC, for sending and receiving messages. This driver can handle sending of text and binary messages (such as vCard, vCalendar.). The driver can receive only text messages.
oracle.panama.messaging.transport.driver.sms.CIMDDriver
The following parameters must be specified while creating the Driver:
This is the account ID for the SMSC. Generally, it is the short number assigned by the operator. This is required.
sms.cimd.system.userid and sms.cimd.system.password
Along with the short number, the operator provides a User ID and password for you to login to the SMSC. These are required.
sms.server.host and sms.server.port
This information is used by the driver to open a TCP/IP connection to the SMSC.
sms.message.maxchunks
This is the maximum number of chunks allowed for any single message. Chunks after this number are ignored. The default is -1. A negative value means there is no limitation.
sms.message.chunksize
This is the maximum size for each chunk, in bytes. The default is 140.
sms.server.default.encoding
Specify the encoding scheme for text messages. The default is IA-5.
sms.window.size
Specify the window size. If windowing is not supported then set window size = 1.
sms.send.alive.packet.interval
The time interval (in milliseconds) after which alive packet should be sent. Negative value means no alive packets will be sent. This parameter is required to keep the connection to the SMSC alive, because normally the user will be logged out automatically from the SMSC after a specified time interval. Specify a value which is less than that interval.
This driver provides the ability to send and retrieve SMS and MMS messages to and from the Via Vodafone Services Platform (VVSP). In order to use this driver, you must register it as an application with Vodafone Mobile Office. For details on how to register an application and obtain the necessary credentials to run this driver, contact Vodafone Mobile Office at http://www.mobileoffice.vodafone.com.
oracle.panama.messaging.transport.driver.vvsp.VVSPDriver
vvsp.sms.address--Comma-separated list of the SMS network IDs (MSISDN or short code).
For example: 8205, 8206
vvsp.sms.country--Corresponding comma-separated list of 2-letter country codes that the SMS network IDs above are registered for with the VVSP. ISO 3166-1-alpha-2 code element conventions apply.
For example: uk, de.
vvsp.sms.url--The URL to the VVSP SMS gateway. The default value is https://vvsp.vodafone.net/gns/sms.
vvsp.sms.id--The SMS Application Instance ID registered with VVSP.
vvsp.sms.password--The SMS Application Instance Password.
vvsp.sms.onetimepassword--The SMS one-time password for password renewal. Use this field only if you are in the testing phase with VVSP, and want to use a fixed OTP. For example, 69696969.
vvsp.mms.address--Comma-separated list of the MMS network IDs (MSISDN or short code).
For example: 8005, 8006
vvsp.mms.country--Corresponding comma-separated list of 2-letter country codes that the MMS network IDs above are registered for with the VVSP. ISO 3166-1-alpha-2 code element conventions apply.
For example: uk, de.
vvsp.mms.url--The URL to the VVSP MMS gateway. The default value is https://vvsp.vodafone.net/gns/mms.
vvsp.mms.id--The MMS Application Instance ID registered with the VVSP.
vvsp.mms.password--The MMS Application Instance Password.
vvsp.mms.onetimepassword--The MMS one-time password for password renewal. Use this field only if you are in the testing phase with VVSP, and want to use a fixed OTP. For example, 69696969.
vvsp.admin.url--The URL to the VVSP Administration gateway. The default value is https://vvsp.vodafone.net/gns/admin.
vvsp.admin.log--The log file to store new passwords issued by the Administration gateway. The default value is VVSPAdmin.log.
vvsp.admin.url--The URL to the VVSP Administration gateway.
vvsp.local.hostname--The logical local hostname/IP to bind to, for receiving notifications from the VVSP. If not present, it is derived from the local host. The complete URL used to receive notifications will be http://vvsp.local.hostname:vvsp.local.port/.
vvsp.local.port--The local listening port. The default value is 80.
vvsp.ssl.trustStore--The path to the SSL trustStore file (in jks format). If left blank, the built-in VVSP-provided certificate file is automatically loaded. In most cases, you will not need to modify this parameter.
vvsp.ssl.trustPassword--The pass phrase of the trustStore file. Leave blank if none (default).
vvsp.ssl.keyStore--The complete path to the SSL keyStore file (in pkcs12 format). You must provide this path if you have an SSL class 3 client certificate from VVSP.
vvsp.ssl.keyPassword--The pass phrase of the keyStore file. Leave blank if none.
vvsp.default.encoding--The default HTTP encoding format. The default value is UTF-8.
vvsp.sms.maxchunks--The maximum chunks for an SMS message if it exceeds the maximum SMS length. (Note that the per chunk maximum length is 160 chars for text SMS, and 140 chars for binary SMS.). Enter -1 for unlimited chunks. The default value is -1.
vvsp.retrieve.flush.freq--Frequency (in seconds) of periodic polling to retrieve and flush any unretrieved messages waiting at the VVSP due to missed or lost notifications. Enter 0 to disable polling. The default value is 600 seconds.
vvsp.debug--Enable logging extra debug information. Options: true (debug enabled), false OR leave blank (debug disabled).
If you do not have an SSL class 3 client certificate from the VVSP, your application instance password will be periodically expired by the platform. When the password expires, the VVSP will send an SMS containing a one-time password (OTP) to the registered application operator's handset. The application operator must enter this OTP so that the VVSPDriver can complete the password renewal procedure and receive the new application instance password from the VVSP. A utility has been provided to allow the operator to enter the OTP. It can be found on OTN at http://otn.oracle.com/tech/wireless/integration/. You can download and install it on your OracleAS Wireless instance using the instructions provided. Once installed on your instance, the utility can be accessed at http://<instance_hostname>:<instance_port>/vvsp/vvspdriverotp.jsp.
After the operator enters the OTP using this utility, the VVSPDriver renews the password and continues normal operation.
If the operator is unable to enter the OTP within a short time (approximately 4 minutes), the VVSP considers that OTP stale, and the driver reinitiates the password renewal process; the VVSP sends a new and valid OTP to the operator's handset. The operator is then expected to enter this new OTP using the provided utility.
|
Note:
The VVSPDriver cannot automatically update the new application instance password in the driver instance configuration in OracleAS Wireless Tools. As a result, the new password is lost when the messaging server is restarted. Thus, to ensure normal operation, the VVSPDriver instance configuration must be updated before you restart the OracleAS Wireless instance (or just the messaging server process). The new password along with the corresponding application instance ID is available on the utility you use to enter the OTP, and is also logged to the You must get an SSL Class 3 certificate from the VVSP so that you do not have to perform the manual steps involved in periodic password renewal. For more information, refer to the VVSP Gateway Overview Guide available from the Via Vodafone Developer Site at http://www.via.vodafone.com. |
Oracle Corporation recommends that you get SSL class 3 certificates from VVSP so that you are not required to do periodic password renewal. For more information, refer to the guides available fromVodafone Mobile Office at http://www.mobileoffice.vodafone.com.
WCTP (Wireless Communication Transfer Protocol) is specifically aimed at creating a simple means of passing alphanumeric and binary messages between wire line systems and mobile devices. HTTP 1.1 is the recommended transport protocol for WCTP. The built-in driver acts as an Enterprise Host and connects to the WCTP Gateway to send and receive messages. The driver can handle sending and receiving of text messages. The driver implements an HTTP listener to listen to incoming messages. The driver also supports status reporting for the sent messages.
oracle.panama.messaging.transport.driver.sms.WCTPDriver
The following parameters must be specified while creating the Driver:
send-host, send-port and send-page
This is the host, port and page of the WCTP Gateway.
receive-host, receive-port and receive-page
This is the host, port and page at which the HTTP server implemented by the WCTP driver, listens for incoming messages.
receive-proxy-host and receive-proxy-port
This information is required if there is a proxy server. It is required while parsing the WCTP XML messages. These are optional.
maxchunks
This is the maximum number of chunks allowed for any single message. Chunks after this number are ignored. The default is -1. A negative value means there is no limitation.
chunksize
This is the maximum size for each chunk in bytes. The default is 160.
notify-when-queued
Specify true if notification is required when the message has been queued.
notify-when-delivered
Specify true if notification is required when the message has been delivered.
notify-when-read
Specify true if notification is required when the message has been read.
multi-recipient-message-support
Specify true if multiple recipients are sent in a single message. Otherwise a separate message will be sent for each of the recipients in the list.
The data communication driver enables OracleAS Wireless to send and receive SMS messages through a Nokia phone. The driver code is capable of sending text and binary messages. Receiving is enabled only for text messages (the driver has been tested for 5110) when connected to a PC through a data cable.
Follow the procedure below to set up the data communication driver in the Windows platform.
Before you start the setup make sure you have the following:
The setup procedure is divided into three categories:
The details on each of the above categories are below.
Download Javacomm20-win32.zip from the location http://java.sun.com/products/javacomm/
Follow all the steps given in the file PlatformSpecific.html (which you will get after unzipping the file Javacomm20-win32.zip).
Try running a sample, which is included in the zip file to confirm that the configuration is complete, and working fine.
(This step is required only if the Nokia phone used for the data communication doesn't have in-built modem.)
Before installing Nokia data suite, go to control-panel -> ports. Note the ports present in your system.
Class Name
oracle.panama.messaging.transport.driver.datacommunication.DataCommunicationDriv er
This is the port, which the driver will use to communicate with the phone connected through the cable. Type the name of the port is used to connect the phone to pc using the data cable. In case your phone doesn't have an in-built mode, you will have to type here name of the virtual port, which got created when you installed Data suite. (such as: COM3)
sms.datacommunication.phone-no
This is the phone number of the cell phone, which is connected using the data cable to the computer on which the messaging server is running (for example: 1-650-576-8055).
sms.message.maxchunks
This is the maximum number of message chunks to be sent, if the message size is greater than the chunk size. By default all the chunks will be sent.
sms.message.chunksize
Maximum size of a chunk. Default is 150.
Before you run the messaging server, make sure you have included the path of comm.jar to the CLASSPATH in the file opmn.xml.
PAP (Push Access Protocol) is a protocol to access a WAP Push gateway. OracleAS Wireless includes a pre-built implementation of the PAP driver as a driver that is capable of sending WAP pushes.
This driver can handle these content types:
ContentTypes.WAP_PUSH--All supported content types by the WAP push gateway.
ContentTypes.URL (only if the content type of the related resource is one of the above)--The driver accepts all content types and posts the message to the push gateway.
If the WAP push gateway does not understand the messages posted by the PAP driver, the PAP driver will throw a non-fatal exception to indicate the failure.
oracle.panama.messaging.transport.driver.wap.PAPDriver
pap.ppg.url
The URL of the WAP push gateway. This is required.
pap.notifyto.url
The URL to which notifications can be sent by the WAP push gateway. This is optional.
pap.listento.notify
Value is set to true of false. This flag indicates if this driver listens for notifications.
pap.source.reference
The source reference of this driver to the WAP push gateway.
pap.ppg.hostname
The logical hostname of the PPG gateway; used as the PPG's carrier identification. If not present, it is derived from the PPG URL.
pap.local.hostname
The logical local hostname or IP address. If not present, it is derived from the local notification URL if any, or the local machine.
The default content encoding format; if not set, UTF-8 is used.
The PAP version supported by the PPG, must be either 1.0 or 2.0.
The Instant Messaging driver provides unidirectional as well as bidirectional access to end-users for accessing OracleAS Wireless applications through real-time instant messaging (IM). The IM driver uses Jabber, an open, XML-based instant messaging platform, which also integrates with proprietary IM networks such as Yahoo, MSN, AOL and ICQ. This driver allows end-users to receive alert notifications and interactively use applications through their IM client of choice.
Jabber is an open, XML-based protocol for Instant Messaging and presence. Jabber-based software is deployed on thousands of servers across the Internet and is used by over a million people worldwide. Jabber consists of a client-server architecture, which resembles the ubiquitous e-mail network. Jabber servers are completely decentralized, allowing anyone to set up their own server. Messaging is achieved as in the email network, where recipients are addressed by a username and a hostname (for example: username@hostname). In the Jabber network, users are identified by a Jabber ID, which consists of a username and the hostname of the particular Jabber server to which the user connects. An end-user of Jabber connects to a Jabber server using a Jabber client in order to send instant messages to other Jabber users. This, however, is not the only way to achieve instant messaging. Jabber has an extensible and modular architecture. It integrates with proprietary IM networks such as Yahoo, MSN, AOL and ICQ using transport gateways that can connect to these networks. This allows Jabber users to communicate with those on Yahoo, MSN, AOL or ICQ.
In order to use the IM driver in OracleAS Wireless, you must access a Jabber server and a Jabber account for the OracleAS Wireless instance (using the ID that the IM driver will log in to Jabber with, to send to and receive messages from end-users). In addition, the IM driver includes configuration parameters that enable the OracleAS Wireless instance to communicate with users on Yahoo, MSN, AOL or ICQ IM networks. This requires that you additionally have accounts on these proprietary IM networks to which you are connecting using OracleAS Wireless, and thus, allow end-users of those particular networks to communicate with OracleAS Wireless.
The following figure depicts a scenario in which an OracleAS Wireless instance is connected to Jabber and MSN (through Jabber's MSN transport gateway). This enables end-users on MSN and Alice to communicate with the OracleAS Wireless instance using MSN Messenger.
The Instant Messaging driver uses the JabberBeans Java library to connect to a Jabber Instant Messaging Server. It requires the following third-party software:
| Name | Instructions | Version(s) |
|---|---|---|
|
JabberBeans |
OracleAS Wireless includes a copy of JabberBeans (version 0.9.1). If you wish to upgrade to a newer version of JabberBeans, follow these instructions:
Download and copy the latest |
0.9.1 |
|
Jabber Server (jabberd) |
Optional. To download and install your own Jabber server, follow the Jabber server's installation guide on http://www.jabber.org. |
1.4.2 |
|
Yahoo TransportGateway |
Optional. Follow the transport installation guide. Refer to http://yahoo-transport.jabberstudio.org. |
2.0.0 |
|
MSN Transport Gateway |
Optional. Follow the transport installation guide. Refer to http://msn-transport.jabberstudio.org. |
1.1.0 or greater |
|
AOL & ICQ Transport Gateway |
Optional. Follow the transport installation guide. Refer to http://aim-transport.jabberstudio.org. |
0.9.25 |
|
Note: You do not need to install your own Jabber server if you have access to an existing Jabber server. For a list of public Jabber servers, see http://www.jabberview.com. |
Use the OracleAS Wireless Tools to configure the messaging server with the instant messaging driver.
To add/enable the instant messaging driver:
im.server.host, im.server.port, im.server.username, im.server.password
To support users of proprietary, IM networks (for example: Yahoo, MSN, AOL or ICQ), add the parameters for each network as follows (Though you must add these parameters, entering values for these is optional when you configure the Driver Instance.):
im.yahoo.enable, im.yahoo.username, im.yahoo.password
im.msn.enable, im.msn.username, im.msn.password
im.aol.enable, im.aol.username, im.aol.password
im.icq.enable, im.icq.username, im.icq.password
output: im.debug
im.retry.limit, im.retry.interval
To configure the instant messaging driver instance:
The IM driver can be used in conjunction with the Async Server to provide access to async-enabled applications on OracleAS Wireless through Instant Messaging. To enable, configure access points in the Async Server.
To configure the Async Server:
<Jabber ID> is the ID used by your IM driver (for example, oracleagent@localhost). In other words, the entire address will take the form: <im.server.username>@<im.server.host>).
<network-name> is yahoo, msn, aim, or icq. For example, if you have configured the IM driver for MSN, you must add an access point with the address msn|<im.msn.username>, where <im.msn.username> is the value of the parameter you configured in the IM driver instance. Likewise, if you have configured the IM driver for AOL IM (AIM), add an access point with the address aim|<im.aol.username>.
This completes the Async Server configuration. To invoke an Async-enabled Application:
Example: You have configured the MSN transport in the IM driver, using msnimdemo@oracle.com as the value of im.msn.username. Now, launch your MSN Messenger client, login as yourself (with your own MSN account) and add the MSN IM Agent msnimdemo@oracle.com to your contact list.
Example: Invoke the hello application by sending a message with the text hello to the IM Agent. The agent will return a simple Hello World response:
Example: Invoke the Short Messaging application by typing sm. You will receive a menu of options such as 0 Menu, 1 [] Type. Enter 1 to select Type. A list of types to choose from is returned. Type 3 to select Voice. You can enter other fields such as Recipients, Subject and Body in a similar manner, and finally send the message.
In order to send instant messages using the XMS service, you have two API options, namely XMSSimpleSender and XMSSender:
To address recipients, prepend the IM: tag to the IM address. In other words, use the following format:
IM:<address>
where <address> is the IM address of the recipient.
<address> further takes the form:
<network-name>|<userid>,
where <network-name> is the name of the IM network. For example: jabber, yahoo, msn, aim, icq.
<userid> is the ID of user on that network
Here are some examples:
To address recipients, use the address format specified above without the IM: tag (example shown below). Create the addresses as instances of the class IMAddressData, and use the IM transport type. Apart from this, use the XMS client as you would normally. Refer to the XMS examples in Section 10.6.1.10, "XMS Driver".
To create an instance of IMAddressData, you may use one of two constructors:
IMAddressData(String address)
IMAddressData("msn|foo@msn.com") IMAddressData("aim|foo")
IMAddressData(String userid, String network)
where userid is <userid>
network is <network-name>
For example:
IMAddressData("foo@msn.com", "msn") IMAddressData("foo", "aim") IMAddressData("foo@jabber.org", "jabber")
Here is some sample XMS client code to show IM addressing using both the constructors:
// IM recipients AddressData imRecipients[] = new AddressData[4]; /* using the first constructor */ // specify a regular Jabber user imRecipients[0] = new IMAddressData("jabber|foo@jabber.org"); // specify a Yahoo user (by prepending the "yahoo|" tag) imRecipients[1] = new IMAddressData("yahoo|foo"); /* using the second constructor */ // specify an MSN user imRecipients[2] = new IMAddressData("foo@msn.com", "msn"); // specify an AOL IM user imRecipients[3] = new IMAddressData("foo", "aim"); // Packet object Packet pkt = new Packet(); AddressData imSender = new IMAddressData("jabber|oracle@jabber.org"); pkt.setFrom(TransportType.IM, imSender); pkt.addRecipients(TransportType.IM, imRecipients);
To test the IM driver on your local machine, you must perform a few more additional steps, specifically, installing a Jabber server and a Jabber client.
To install Jabber Server on Windows:
[notice] (-internal): initializing server. If you see this message, you have successfully started the Jabber server.
To install Jabber Server on UNIX:
Solaris 2.6: http://jabberd.jabberstudio.org/downloads/jabber-1.4.2a-sparc-solaris-2.6.tar.gz
Solaris 7: http://jabberd.jabberstudio.org/downloads/jabber-1.4.2a-sparc-solaris-7.tar.gz
# mkdir jabber # cd jabber # gtar xzvf jabber-1.4.2a-sparc-solaris-<ver>.tar.gz
[notice] (-internal): initializing server. If you see this message, you have successfully started the Jabber server.
To install Jabber Client on Windows:
http://www.jabber.org/user/clientlist.php. Oracle Corporation recommends Rival (http://rival.chote.net/) for first-time Jabber users.
To install Jabber Client on UNIX:
http://www.jabber.org/user/clientlist.php?Platform=Linux. Not all clients may compile on UNIX; try at your own risk. There are pre-compiled UNIX binaries of Gabber (a popular Linux Jabber client) at: http://prdownloads.sourceforge.net/gabber/gabber0.8.7_solaris.tar.gz.
To send a test message to OracleAS Wireless:
To quick-configure the IM driver for AOL Instant Messenger:
You must have two AOL screennames (accounts), one for yourself (referred to here as <my_screenname>), and one for the IM driver (referred to here as <imdriver_screenname>). If you do not already have two screennames, create them at http://www.aim.com.
im.server.host = myjabber.net (or any Jabber host that has an AOL IM (AIM) transport) im.server.username = <imdriver_screenname> im.server.password = <password of imdriver_screenname> (or whatever you want) im.aol.enable = true im.aol.username = <imdriver_screenname> im.aol.password = <password of imdriver_screenname>
host = www-proxy.us.oracle.com, port = 80, protocol = HTTP).
This driver uses a hosted XMS service and by default uses the demonstration service hosted by Oracle Corporation. This driver acts as an XMS client to an OracleAS Wireless server hosted on the Internet, and can be configured to point to any service that supports the OracleAS Wireless XMS Web Service. The XMS driver uses a special protocol, SOAP over HTTP (the OracleAS Wireless XMS Web Service). The Oracle-hosted XMS server does not require any account for access. The XMS uses SOAP over HTTP. For trial purposes, you may use the hosted demonstration OracleAS Wireless instance and use "" (a pair of double quotes) as username and "" as password. This grants you limited usage for sending messages. The URL for it is: http://messenger.oracle.com/xms/webservices.
oracle.panama.messaging.transport.driver.push.PushDriver
messaginggatewayURL
URL to the Hosted XMS Web Service. This parameter is required. For example: http://messenger.oracle.com/xms/webservices
username
Name to use to authenticate against the XMS Service. XMS Web Services can determine whether username and password are required. If username is not required by XMS Web Services, leave blank (empty string). Bad username or password is returned from XMS Web Services if the user name does not exist, or if the password of that username is incorrect.
Example: messaginguser
password
Password of the user specified in the username field, used to authenticate against the XMS Service. XMS Web Services can determine whether username and password are required. If username and password are not required, leave password blank (empty string). Bad username or password is returned from XMS Web Services if either the user name does not exist, or if the password of that user name is not correct.
Example: 8Uh42g
The XMS driver can handle all content types. The hosted XMS Web Services determine how to handle them. The driver runs on an HTTP connection; no explicit HTTP proxy setting is needed because the XMS driver inherits the proxy settings of OracleAS Wireless.
This driver sends only. It supports as many transport types as the Hosted XMS Service; the actual types supported are dependent on which Hosted (OracleAS Wireless Instance) service is running. The OracleAS Wireless Service supports an API that describes the exact transports supported by an Instance.
The email driver supports SMTP in delivering messages, and either IMAP or POP3 in receiving messages. This driver can handle sending and receiving messages. Both IMAP or POP3 protocols are supported for receiving messages.
oracle.panama.messaging.transport.driver.email.EmailDriver
server.incoming.protocol
This is the value for the e-mail receiving protocol. The possible values are IMAP and POP3. Required only if email receiving is supported on the driver instance.
server.incoming.host
The host name of the incoming mail server. Required only if email receiving is supported on the driver instance.
server.incoming.receivefolder
The name of the folder the driver is polling messages from. The default value is INBOX.
server.incoming.usernames
The list of user names of the mail accounts the driver instance is polling from. Each name must be separated by a comma, for example, foo,bar. Required only if email receiving is supported on the driver instance.
server.incoming.passwords
The list of passwords corresponding to the user names above. Each password is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. Required only if email receiving is supported on the driver instance.
Example: foopwd,barpwd
server.incoming.emails
The email addresses corresponding to the user names above. Each email address is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. Required only if email receiving is supported on the driver instance.
Example: foo@oracle.com,bar@oracle.com
server.incoming.checkmailfreq
The frequency with which to retrieve messages from the mail server. The unit is in seconds and the default value is 5 seconds.
server.incoming.deletefreq
The frequency to permanently remove deleted messages. The unit is in seconds and the default value is 300 seconds. A negative value indicates the messages should not be expunged. For the POP3 protocol, the message is expunged after it is processed.
server.incoming.autodelete
This value indicates if the driver should mark the messages deleted after they have been processed. The value can be true or false and the default value is false. For the POP3 protocol, the messages are always deleted right after they are processed.
server.outgoing.host
The name of the SMTP server. Mandatory only if email sending is required.
Example: smtp05.oracle.com
default.outgoing.from.address
The default FROM address (if one is not provided in the outgoing message).
The email driver supports SMTP in delivering messages, and either IMAP4 or POP3 in receiving messages. This driver can handle sending and receiving messages. Both IMAP4 or POP3 protocols are supported for receiving messages.
The voice driver supports the Out Bound Call protocol supported by VoiceGenie. Currently, it has been tested only to work with a Voice gateway. This driver handles sending messages only. Although the driver can only send messages, it must be configured to have both sending and receiving capabilities for the driver to work.
This driver can handle:
text/plain
ContentTypes.MOBILE_XML_URL
ContentTypes.MOBILE_XML_URL_REMOTE
ContentTypes.MOBILE_XML
ContentTypes.URL (only if the content type of the URL resource is one of above)
For other content types, the driver will throw a non-fatal driver exception.
oracle.panama.messaging.transport.driver.voice.Voice
GenieDriver
voicegenie.outbound.servlet.uri
URL for the VoiceGenie Outbound Call Servlet. This is required with no default value. Here is a sample:
http://rossini.us.oracle.com/servlet/com.voicegenie.outboundcallservlet.Outb oundCallServlet
The driver uses the site level proxy configuration in accessing this URL.
voicegenie.outbound.servlet.username
Username for the VoiceGenie Outbound Call.
voicegenie.outbound.servlet.password
Password for the VoiceGenie Outbound Call.
voicegenie.outbound.servlet.dnis
The phone number to be set as the caller. This is optional. The default value is 12345678.
voicegenie.urlservice.path
Servicepath to the prebuilt VoiceGenie service. This driver depends on an OracleAS Wireless service based on the HTTP adapter. By default the OracleAS Wireless installation has an HTTP Adapter service named VoiceGenieURLService to support this voice driver. This is a required parameter. There is no default value and one must look at a particular OracleAS Wireless installation to obtain a value for it. Here is an sample:
foo.oracle.com:9000/ptg/rm?PAservicepath=/VoiceGenieURLService&PAsubmit=
Submit
voicegenie.driver.receive.host and voicegenie.driver.receive.port
These are the IP host and port for the HTTP adapter to get sending content in Mobile XML format. The port should be used by this driver only. These are required.
UCP (Universal Communication Protocol) is one of the most popular GSM SMS protocols. OracleAS Wireless includes a pre-built implementation of the UCP driver as a driver that is capable of both sending and receiving.
The UCP driver implements EMI/UCP 4.0. It supports both listening mode and non-listening mode. In the non-listening mode, the driver opens one connection to the SMSC. This connection is shared in sending and receiving. UCP driver works with most SMSC in the non-listening mode. In the listening mode, the driver listens to a port. The SMSC opens a connection to the driver to deliver received messages from devices to the driver. The driver opens a HTTP connection on demand to deliver a message to the SMSC for sending to the target device. The HTTP connection is reused if possible.
This driver can handle:
text/plain
ContentTypes.RING_TONE
ContentTypes.GRAPHICS
ContentTypes.WAP_SETTINGS
ContentTypes.WAP_PUSH
ContentTypes.VCARD
ContentTypes.EMAIL_SETTING
ContentTypes.VCALENDAR
ContentTypes.MM1_NOTIFICATION
ContentTypes.EMS
ContentTypes.ENCODED_SMS
ContentTypes.URL (only if the content type of the related resource is one of above)
For other content types, the driver will throw a non-fatal driver exception.
oracle.panama.messaging.transport.driver.sms.UCPDriver
sms.account.id
This is the account ID for the SMSSC. Generally, it should be the assigned short number by the operator. This is required.
sms.account.password
This is a password assigned by the operator. It is used to open a session to the SMSC with UCP command 60.
sms.ucptype
Specifies which command to use in sending a message. The possible values are 01 and 51. The default value is 51, which means UCP command 51 is used to send a message.
sms.server.host and sms.server.port
SMSC server information the driver uses to open a TCP/IP connection.
sms.server.default.encoding
The default encoding of the text message. The default value is IA5.
sms.local.port
The local port the driver should use to make the outgoing connection, applicable to the non-listening mode driver.
sms.local.address
The logical hostname or IP address where the driver runs, applicable to the non-listening mode driver.
sms.window.size
The windowing size, applicable to the non-listening mode driver only.
sms.receiver.listener.port
If the driver is in listening mode, this port is used by the SMSC to initialize the TCP/IP connection to pass received messages to the driver. If the sms.server.url is specified, this one will be used. Otherwise, it will be ignored.
sms.server.url
This is the URL for the driver to access the SMSC to send messages through an HTTP connection. If specified, sms.server.host and sms.server.port will be ignored. If it is not specified, then sms.server.host and sms.server.port are required.
sms.bulk.sending
Determines whether to use command 02 to do bulk sending (if it is possible). The default value is true.
sms.message.maxchunks
This is the maximum chunks for any single message allowed. Chunks after this number are ignored. The default is -1, which means no limit.
sms.message.chunksize
This is the maximum size for each chunk in byte. The default is 160.
sms.alert.interval
The interval (in seconds) at which command 31 is invoked. If it is set to a negative value, command 31 will not be invoked. This command is mainly used as a signal to the SMSC to keep the connection alive when the driver is in non-listening mode.
SMPP (Short Message Peer-to-Peer) is one of the most popular GSM SMS protocols. OracleAS Wireless includes a pre-built implementation of the SMPP driver as a driver that is capable of both sending and receiving. The driver opens one TCP connection to the SMSC as a transmitter for sending if the sending feature is enabled, another connection to the SMSC as a receiver for receiving if the receiving feature is enabled. Hence two connections (initiated by the driver) are needed for all communication between the driver and the SMSC if both sending and receiving features are enabled. This driver implements SMPP 3.4. It supports only SMSC which supports SMPP 3.4.
This driver can handle:
text/plain
ContentTypes.RING_TONE
ContentTypes.GRAPHICS
ContentTypes.WAP_SETTINGS
ContentTypes.WAP_PUSH
ContentTypes.VCARD
ContentTypes.EMAIL_SETTING
ContentTypes.VCALENDAR
ContentTypes.MM1_NOTIFICATION
ContentTypes.EMS
ContentTypes.ENCODED_SMS
ContentTypes.URL (only if the content type of the related resource is one of above)
For other content types, the driver will throw a non-fatal driver exception.
oracle.panama.messaging.transport.driver.sms.SMPPDriver
sms.account.id
This is the account ID for the SMSSC. Generally, it should be the assigned short number by the operator. This is required.
sms.server.host
SMSC server information the driver uses to open a TCP/IP connection
sms.smpp.transmitter.system.id
sms.smpp.transmitter.system.type
sms.smpp.transmitter.system.password
sms.server.transmitter.port
These attributes depend on your SMSC. Along with the short number assigned to you, the operator may also give you a system ID, type, password and port for you to log in to the SMSC as transmitter (that is, to send SMS).
sms.smpp.receiver.system.id
sms.smpp.receiver.system.type
sms.smpp.receiver.system.password
sms.server.receiver.port
These attributes depend on your SMSC. The operator may also give you a system ID, type, password and port for you to log in to the SMSC as receiver (that is, to receive SMS).
sms.server.default.encoding
The default encoding of the text message. The default value is IA5.
sms.local-sending.port
The local port the driver should use to make the outgoing sending connection.
sms.local-receiving.port
The local port the driver should use to make the outgoing receiving connection.
sms.local.address
The logical hostname or IP address where the driver runs.
sms.server.source.ton
The TON of the from-address (account id).
sms.server.source.npi
The NPI of the from-address (account id).
sms.server.destination.ton
The TON of the destination address.
sms.server.destination.npi
The NPI of the destination address.
sms.window.size
The windowing size. The default value is 1.
sms.bulk.sending
Whether to use command submit_multi to do bulk sending (if it is possible). The default value is true.
sms.payload.sending
Whether to use message_payload field for sending when short_message field is operational. The default value is false.
sms.message.maxchunks
The maximum chunks a long message can be split into. Chunks after this number are ignored. A negative value means there is no limitation. The default is -1.
sms.message.chunksize
The maximum size for each chunk in bytes. The default is 160.
sms.enquire-link.interval
The interval in seconds that the enquire link is called. This feature is disabled if the interval is less than 0. The default value is -1.
sms.throttling.delay
The delay in seconds that sending re-starts after a throttling error is received from SMSC. This feature is disabled if the delay is less than 0. The default value is 15.
sms.extra.error-code
The list of comma-separated error codes that can be sent by the SMSC that require re-sending of the messages.(for example: 0x45, 0x50). By default if any error code is received as status, the message is discarded.
sms.bind.retry.delay
The delay in seconds, after which the driver will wait for an enquiry link response before trying to rebind with the SMSC. This feature is disabled if the value of this parameter or sms.enquire-link.interval is less than 0. The default value of this parameter is -1.
sms.registered.delivery.mark
The driver may set the registered-delivery flag when sending a message to the SMSC based on the requirement of the application. However, the SMSC may not support all valid flags. In this case, this mark can be used to disable certain flag bits so that the sending request is not rejected by the SMSC.
This driver supports Fax messages and supports the RightFax (by Captaris) FAX protocol. The driver depends on the RightFax software package and the availability of a RightFax Fax server to deliver fax messages. This driver is capable of only sending messages.
This driver can handle any content type. It recognizes the following MIME types:
text/plain
application/msword
application/msexcel
application/msppt
application/postscript
application/octet-stream
In the case of the ContentTypes.URL, the driver retrieves the content from the specified URL. The content and MIME type returned by this operation become content and MIME type sent to the fax server.
oracle.panama.messaging.transport.driver.fax.RightFAXDriver
server.url
URL to the RightFax server. This is required.
server.account
Account name to the RightFax server. This is required.
All the default attributes below are optional. They are used to customize the cover sheet only.
server.coverpage
The cover page to be used by this driver. If not specified, then the default cover page of the fax gateway will be used.
default.sender.name
The default sender name to be shown on the cover page.
default.sender.corporation
The default sender corporation to be shown on the cover page.
default.sender.fax
The default sender's fax number to be shown on the cover page.
default.sender.phone
The default sender's phone number to be shown on the cover page.
default.sender.address
The default sender's address to be shown on the cover page.
default.sender.notes
The default sender's notes to be shown on the cover page.
server.coverpage
The RightFAX driver requires a coverpage setting to render the coverpage. The coverpage is under a coverpage directory of the RightFAX server. This parameter should be set to the filename of the coverpage you want. If this parameter is not set, the default coverpage of the fax server is used.
The driver interfaces are intended for the implementation of drivers for particular protocols. As explained above, drivers can be plugged into the transport system rather easily, extending network protocol support to the base product. A driver is expected to be a very thin layer and handles only the protocol-specific details. It is not designed to handle life cycle, load balancing or scalability issues. The transport system handles these issues.
The transport system initializes and destroys driver instances by respectively calling the init() and destroy() methods as specified in the Interface Driver. The transport system also handles load balancing and concurrence. A driver should just focus on interpreting the semantics of a particular protocol, leaving all others to the transport system.
A driver can be capable of only sending, or receiving, or both. To implement the sending semantics, a driver only implements the send() methods as specified in the interface Driver. Receiving is a bit more complex in that the action to receive is driven by the transport. To implement receiving, a driver fills in the logic to receive in the receive() method specified by the Driver interface. The transport will continuously invoke the receive() method throughout the life cycle of the driver instance.
Drivers should be designed to be instance thread safe, or their usage must be clearly conveyed to system administrators so that proper configurations can be set to not thread the driver instance.
The key classes and interfaces required for developing the SMS driver interface to work with OracleAS Wireless are listed below.
The class TransportLocator defines interfaces that provide initial access to both the messaging interface and the driver interface. Two key methods defined for this class are:
getDriverController() returns an instance for the use of the driver interface
getMessagingController() returns a Controller instance for the use of the messaging interface
This is the main interface for developing drivers for a particular protocol. You develop a driver by implementing the Driver interface. Your component is a qualified OracleAS Wireless driver if it implements this interface.
These methods control the life cycle of the driver instance. The initialization properties passed to the init method are those specified through the OracleAS Wireless Tools configuration framework.
The init() method returns an initialization status, which can be one of:
Driver.FAILED, Driver.SEND, Driver.RECEIVE Driver.SEND_RECEIVE.
Ensure that the status returned is consistent with those configured through OracleAS Wireless Tools. If different, then the value of the status returned here and that configured through the webtool will be used.
Drivers implement this method to perform whatever is appropriate for their particular protocols to send out messages. The content to be delivered is stored in the Message object passed onto the send() method, while the address parameter specifies one or more recipients to deliver the message to.
Further, the driver is expected to return a unique ID for each message, or identifies one for each of the recipients. These IDs are used by the transport to query the status of the delivery when necessary.
|
Note:
All classes mentioned below assume that you are using the |
The driver must return a null message ID to make the transport retry. Exceptions thrown out of the send method are caught, and logged as sending statuses. If the send () method throws any exception, the transport will not retry. If the send () method throws an exception of the type DriverException, the exception code is checked. If the code of the exception is marked fatal, the sending capability of this driver instance is revoked.
Before a driver throws a non-fatal DriverException, the driver will try to recover. For example, if a TCP/IP connection is dropped, the driver tries to reconnect it without throwing an exception. If the driver does throw a non-fatal exception without trying to recover, the transport will keep sending messages, which will fail since the error is not recovered. This will decrease performance of the system, especially when the load is heavy.
Drivers implement this method to perform whatever is appropriate for their particular protocols to receive messages and/or status reports.
As mentioned above, the transport drives the operation. Normally the driver is expected to return from this method once a message is received. Controlled is yielded back to the transport regularly so that the transport can evaluate the next best step.
The receive() method is called continuously by the transport. Hence it is preferable the receive() method blocks if it does not receive any messages. However it should not block indefinitely otherwise it will be considered a runaway operation and the thread that calls the receive will be terminated. The elapsed time for runaway threads can be configured by setting Maximum Execution Time per Request under runtime configuration (default is 60 second). When a message is received, it should call the onMessage method of the Message Listener to submit the message (or, the onStatus callback on the Status Listener if the message was a status report). The method can throw an exception of type DriverException and mark it as fatal to request that the transport stop calling the receive () method. The reason for this design is to simplify the logic and thread control of the driver.
The transport calls this method in an attempt to retrieve delivery status for a particular message when necessary.
With some protocols, an active poll to the external service must be performed to check the status of messages previously sent. These methods are called by the Transport to determine whether a getStatus() must be issued to retrieve status, or the driver would pass status back to Transport without such call (typically the driver calls onStatus() inside receive() ).
Provides an entry point into other driver-related utilities and interfaces such as Message Listener. You can get an instance of the DriverController by calling the getDriverController() method of the Locator.
These methods return the Transport callback instances for the receiving messages or status. You typically call the onMessage() or onStatus() methods within your implementation of the receive() method in the Driver interface to pass on messages and status to the Transport system respectively.
If your implementation must process GSM smart message delivery (such as OTA WAP provisioning, ring-tone, graphics), you will find this interface useful. OracleAS Wireless includes a default implementation of this interface, which can be located by getting the value for the property wireless.messaging.gsmsms.encoder.class. The default implementation handles OTA WAP provisioning, ringtone, and graphics for Nokia and Ericsson handsets.
If you would want to extend the base capability, you can do so by developing your own implementation by extending this interface. Once done, you should configure the transport property wireless.messaging.gsmsms.encoder.class to include the value of the class of your implementation.
This is the only method needed for the interface. The parameters indicate the type (ringtone, graphics), model (Nokia, Ericsson) and all the attributes relevant to the requested type.
You process the information and return encoded messages in a form of GSMSmartMsg, which is the fragments for the message and some specific smart message information.
It might happen that either the type, model or other item are not supported by your implementation. In this case, you have two choices:
In this case, the pre-built SMS drivers (such as UCP driver, SMPP driver) will fall back to the default implementation of the GSMSmartMsgEncoder to see if it can handle the situation. This depends on whether a driver is developed with the correct semantics. If you are focused on extending the capabilities of the GSMSmartMsgEncoder, follow this convention to allow maximum utilization of your development.
You obtain instances of these interfaces by calling the appropriate methods in the DriverController interface.
They are typically used within your implementation of the receive() method in the Driver interface to inform the availability of messages or status to the Transport system.
The message class is used to capture the content to be delivered or received. It is comprehensive, and has an expressive power similar to email. It supports multi-part messages and allows mime types to be associated with the content.
However, how to deal with the particular parts or MIME types is left for the implementation of the drivers.
You will find the header of the message a good place to pass information from your application to the driver if such information is not passed to the driver through the driver interface.
This class is not a class only for drivers. It specifies a few content types (MIME types) in addition to the standard MIME types. As driver implementers, you might encounter these MIME types. How to deal with these MIME types is left to the individual driver, but it is critical that you are aware of them.
While adding a driver to the OracleAS Wireless using OracleAS Wireless Tools, a set of properties must be specified, as listed in the table below.
When installing a driver, custom properties can be specified for the driver to function. For example, for an email driver to work, it might need to have a property for the imap hostname. The driver can be coded to expect a property of, say, name imap.hostname. When adding a driver through OracleAS Wireless Tools, one can specify any number of property names. When creating the driver instances, the specific values of such a property can be provided. For example, out of the same driver code, one can install two email driver instances, each provided with imap hostnames to two distinct IMAP servers.
These custom properties are passed into the driver instance when init() is called. In addition to the set of custom properties, some OracleAS Wireless site-level properties are also passed implicitly, they are:
wireless.log.directory
wireless.firewall.http.use.proxy
wireless.firewall.http.proxy.host
wireless.firewall.http.proxy.port
wireless.firewall.http.non.proxy.hosts
wireless.firewall.ftp.use.proxy
wireless.firewall.ftp.proxy.host
wireless.firewall.ftp.proxy.port
wireless.firewall.authentication.set
wireless.firewall.authentication.username
wireless.firewall.authentication.password
// Copyright (c) 2001 Oracle Corporation. All rights reserved. package oracle.panama.messaging.transport.driver.sample; /** * A SimpleDriver class. * <P> * @author Oracle Corporation */ import Java.util.Properties; import Java.net.ServerSocket; import Java.net.Socket; import Java.io.BufferedReader; import Java.io.PrintStream; import Java.io.InputStreamReader; import Java.io.IOException; import Java.io.PrintWriter; import Java.io.FileOutputStream; import Java.text.SimpleDateFormat; import oracle.panama.messaging.transport.*; import oracle.panama.messaging.common.*; import oracle.panama.model.DeliveryType; import oracle.panama.util.MessageCatalog; import oracle.panama.core.admin.L; /** * A Simple driver * * @author ashah, jxiang */ public class SimpleDriver implements Driver { private String mCompanyName; private String mDeliveryType; private String mVersion; private PrintWriter log = null; /** * Initialize the driver. * * @param properties the driver's properties. * @return the initialization status. */ public int init(Properties properties) { // get the locator instance and various listeners TransportLocator locator = TransportLocator.getInstance(); DriverController manager = locator.getDriverController(); mMessageListener = manager.getMessageListener(); mStatusListener = manager.getStatusListener(); // read pr operties mCompanyName = properties.getProperty("company-name"); // delivery type is needed. Use SMS mDeliveryType = DeliveryType.SMS.getName(); mVersion = "1.0"; int status = Driver.FAILED; try { String logName = properties.getProperty("logfile"); if (logName == null) logName = new String("SimpleDriver.log"); log = new PrintWriter(new FileOutputStream(logName, true ) ); } catch(Exception e) { e.printStackTrace(); return status; } log ("initialized: " + new Java.util.Date()); mPort = Integer.parseInt(properties.getProperty("port")); mDelay = 20000; // 20 seconds mMessage = new Message(); mSemaphore = new Object(); status = Driver.SEND_RECEIVE; // TODO - verify the return code mStatus = new Status(); log ("init complete"); return status; } /** * Destroy the driver. */ public void destroy() { try { log ("destroy"); mServerSocket.close(); mReader.close(); mWriter.close(); log ("destroy comp lete"); } catch (Exception e) { } } /** * Get the accepted attributes of the driver. * * @return the accepted attributes of the driver. */ public Parameter[] getParameters() { Parameter[] parameters = new Parameter[3]; parameters[0] = new Parameter("company-name", "a company name", true, null); parameters[1] = new Parameter("logfile", "the log file name", false, "SimpleDriver.log"); parameters[2] = new Parameter("port", "the listening port of the driver", true, null); return parameters; } /** * Get the version of the driver. * * @return the version of the driver. */ public String getVersion() { return mVersion; } /** * Get additional information of the listener. * * @return the information of the listener. */ public String getInfo() { return "Simple Driver"; } /** * Send a message to a single address with this driver. * * @param address the address to send to. * @param encoding the encoding of the device. * @param tracking the tracking level. * @param expiration the expiration time. * @param reliability the reliability level. * @param priority the priority level. * @param fromAddr the from-address. * @param replyToAddr the reply-to-address. * @param mid a unique message id can be used to generate return message id. * @param message the message to send. * @return a unique message id, null if failed. */ public String send(String dtype, String address, int mode, String encoding, int tracking, int expiration, int reliability, int priority, String fromAddr, String replyToAddr, String mid, Message message) { log ("send: " + address + " => " + message.getContent()); String id = null; try { id = mid + ':' + address; mWriter.println(id); mWriter.println(message.getContent()); mWriter.flush(); } catch (Exception e) { // no t synchronized, it works for this toy. mWriter = null; mReader = null; id = null; } log ("sent id: " + id ); return id; } /** * Send a message to a list of addresses with this driver. * * @param addresses the addresses to send to. * @param encoding the encoding of the device. * @param tracking the tracking level. * @param expiration the expiration time. * @param reliability the reliability level. * @param priority the priority level. * @param fromAddr the from-address. * @param replyToAddr the reply-to-address. * @param mid a unique message id can be used to generate return message id. * @param message the message to send. * @return a list of unique message ids, null if failed. */ public String[] send(String dtype, String[] addresses, int[] modes, String encoding, int tracking, int expiration, int reliability, int priority, String fromAddr, String replyToAddr, String mid, Message message) { String[] ids = null; log ("send: mult iple => " + message.getContent()); try { int count = addresses.length; ids = new String[count]; String id = mid + ':' + addresses[0]; ids[0] = id; mWriter.print(id); for (int i=1; i<count; i++) { id = mid + ':' + addresses[i]; ids[i] = id; mWriter.print(',' + id); } mWriter.println(); mWriter.println(message.getContent()); mWriter.flush(); } catch (Exception e) { // no t synchronized, it works for this toy. mWriter = null; mReader = null; ids = null; } log ("sent multiple"); return ids; } /** * Send a message to a list of addresses with this driver. * * @param dtypes the delivery types for all destinations * @param addresses the addresses to send to. * @param modes the delivery modes * @param encoding the encoding of the device. * @param tracking the tracking level. * @param expiration the expiration time. * @param reliability the reliability level. * @param priority the priority level. * @param fromAddr the from-address. * @param replyToAddr the reply-to-address. * @param mid a unique message id can be used to generate return message id. * @param message the message to send. * @return a list of unique message ids, null if failed. */ public String[] send(String[] dtypes, String[] addresses, int[] modes, String encoding, int tracking, int expiration, int reliability, int priority, String fromAddr,String replyToAddr, String mid, Message message) throws DriverException { String[] ids = null; int count = addresses.length; log (" send: " + count + " recipients : " + message.getContent()); ids = new String[count]; for (int i=0; i<count; i++) { ids[i] = send(dtypes[i], addresses[i], modes[i], encoding, tracking, expiration, reliability, priority, fromAddr, replyToAddr, mid, message); } return ids; } /** * Get the sending status of a message. The * status got by this call should be reported * the transport system via the driver listener * onStatus callback. * * @param mid the id of the message. */ public void getStatus(String mid) { } /** * Get the sending statuses of a list of messages. * The statuses got by this call should be reported * the transport system via the driver listener * onStatus callback. * * @param mids the ids of these messages. */ public void getStatus(String[] mids) { } /** * Check if query is required to get the notification. * * @return true if required, false otherwise. */ public boolean queryNotifying() { return false; } /** * Check if query is required to track the * sending status. * * @return true if required, false otherwise. */ public boolean queryTracking() { return false; } /** * Receive a message/status. If any message/status * is received, the driver should use the onMessage/ * onStatus callbacks of the driver listener (got * via the controller) to report it to the transport * system. This method should do something if the * initization status has the RECEIVE ability. */ public void receive() { log ("receive started"); synchronized (mSemaphore) { try { if (mServerSocket == null) { try { mServerSocket = new ServerSocket(mPort); mServerSocket.setSoTimeout(mDelay); } catch (IOException ioe) { mServerSocket = null; mSocket = null; throw ioe; } } if (mSocket == null) { try { mSocket = mServerSocket.accept(); mSocket.setSoTimeout(mDelay); } catch (IOException ioe) { mSocket = null; throw ioe; } } if (mReader == null) { mReader = new BufferedReader( new InputStreamReader(mSocket.getInputStream())); mWriter = new PrintStream(mSocket.getOutputStream()); } String buf = mReader.readLine(); log ("receive read: " + buf); if (buf.charAt(0) == '*') { String address = buf.substring(1); mMessage.setContent(mReader.readLine()); DeviceInfo info = new DeviceInfo(); info.setDeliveryType(mDeliveryType); info.setEncoding("7b"); String from = "FROM-ME-TODO"; mMessageListener.onMessage(from, info, address, mMessage); log ("message sent to message listener"); } else { mStatus.setContent("received"); mStatusListener.onStatus(buf.substring(1), mStatus); log ("status sent to status listener"); } } catch (IOException ioe) { mReader = null; mWriter = null; } } } /** * write to message log * * @param message string */ void log(String message) { if( log != null ) { synchronized( log ) { String currentTime = new SimpleDateFormat( "yyyy-MM-dd HH:mm:ss").format( new Java.util.Date() ); log.println(currentTime + " " + message); log.flush(); } } } private Socket mSocket; private Object mSemaphore; private ServerSocket mServerSocket; private MessageListener mMessageListener; private StatusListener mStatusListener; private BufferedReader mReader; private PrintStream mWriter; private Message mMessage; private Status mStatus; private int mDelay; private int mPort; }
Since the OracleAS Wireless 9.0.2x driver interface is not compatible with the 9.0.4 driver interface, 9.0.2x drivers must be upgraded to work with the 9.0.4 Transport Server (9.0.4 drivers must be downgraded to work with the 9.0.2x Transport Server.). The included pre-built drivers have been upgraded and work with the current release. Only customer-developed, 9.0.2x drivers are affected. This section shows you how to upgrade your 9.0.2x drivers.
The main differences between the 9.0.2x driver interface and 9.0.4 driver interface are:
getParameter() was added
send() methods are changed
getParameter() method
This method lists the attributes the driver accepts. It can be called to get the accepted attributes information dynamically.
send() methods
These methods are enhanced to pass more parameters from the Transport to the driver; none of the original parameters have been removed, making it very easy to upgrade the 9.0.2x drivers. The newly-added parameters are useful, but they are not required. The newly added parameters include priority, message ID (mid), and expiration. The priority is the priority level of the message. Its possible values are defined in MessageInfo as constants. The message ID is a unique message ID that can be used as a seed by the driver to generate unique return message IDs. Generally, the driver can use this message ID (appended with the destination address) as the return message ID. The expiration is the time in seconds when the message will expire. If the value is less than or equal to zero (0), the message will not expire. See the Java doc of the new driver interface more information on the newly added parameters.
To upgrade your 9.0.2x driver, you just must:
getParameter() method.
send() methods to use the latest signatures.
Applications can install hooks that are invoked during message sending and receiving depending on the type of hook. All hooks are optional. Typically the hooks are passed all of the information the application specifies and can do what ever is appropriate. Hooks are useful in providing routing information, and perform other custom logic in some cases.
There are two main categories of hooks:
No default hook is provided for the product.
oracle.panama.messaging.transport.DriverFinder). The expected semantics of this hook is to fill in the driver name for a delivery request.
oracle.panama.messaging.transport.CarrierFinder). This hook is a named hook that can be configured through OracleAS Wireless Tools. The expected semantics of this hook is to locate a carrier for a given device address. The carrier information is then used by the DriverFinder or the transport system to perform routing. It is generally called once per message. There can be only one hook of this kind.
oracle.panama.messaging.transport.SmartMsgEncoder). This hook is used to encode GSM and/or CDMA smart messages. In 9.0.2.x releases, this hook is called GSMSmartMsgEncoder. It supports GSM smart message encoding only. This interface is extended in this release to support both GSM and CDMA smart messages; however, the semantics are unchanged. If a hook can not encode a message, it should return null to indicate this fact so that other encoders will be invoked until a proper encoder is found. The previously-shipped encoder will be upgraded to the new interface. To upgrade your implementation from 9.0.2.x to this release, change the class definition from implements oracle.panama.messaging.transport.GSMSmartMsgEncoder to extends oracle.panama.messaging.transport.SmartMsgEncoder, and change the method name encodeSmartMsg to encodeGSMSmartMsg.
oracle.panama.messaging.transport.FailOverHook). This hook is for future use.
oracle.panama.messaging.transport.GeneralHook). This hook is called before sending any message.
oracle.panama.messaging.transport.GeneralHook). This hook is called after sending any message.
oracle.panama.messaging.transport.GeneralHook). This hook is called before passing any received message to the listener.
oracle.panama.messaging.transport.GeneralHook). This hook is called after passing any received message to the listener.
SMS phones are one of the major devices Async is targeted to serve. Within the SMS segment, a popular billing model is Premium SMS. It is similar to the 900 model of voice phone translated into SMS. SMS phones send a message (with all the service-required information) to a short number (termed as Large Account). The message is routed to the content provider, which has their system set up to listen to the SMS message sent to the number. The user request is processed and the result is sent back to the device. The end-user is charged a service premium rate on top of the typical SMS transport rate for the request message issued from the mobile device. The premium varies depending on the types of service to be invoked. The request charge is reflected on the subscriber's existing SMS phone bill. At the end of the billing cycle, the premium will be split between the Carrier (Premium SMS operator), and the content provider. Figure 10-14, "Premium SMS Process" illustrates the process.
To access a Premium SMS service, a mobile user sends a message to a Large Account (Async address in OracleAS Wireless terminology) with a keyword (Async short name in OracleAS Wireless terminology) to identify the service. A predefined service premium (associated with the Large Account) is charged to the mobile subscriber when the request message is sent from the device to the network of the Premium SMS operator. The content provider invokes the corresponding service identified by the service keyword once it receives the message. The service result is sent back to the mobile subscriber through another SMS message.
Reverse Charge SMS is a billing model which charges the service premium to the mobile subscriber on the Result SMS message. The service premium of the request depends on which service a mobile user accesses. Each service has a tariff class associated with it. Once the Service Provider generates the service result, it also supplies the Reverse Charge SMS operator with the required information so the operator is able to record the billing transaction correctly.
To properly support the Premium SMS and Reverse Charge model on OracleAS Wireless, the following new features have been added:
_MESSAGE_ROUTE_, is included with a standard installation. The administrator is able to edit the Preset Definition to add, modify or remove fields to custom fit their own requirements. This gives users added flexibility to define result message attributes.
To make an OracleAS Wireless service Premium SMS-enabled, follow the steps below. For a more detailed step-by-step walk-through, see OracleAS Wireless Administrator's Guide.
_MESSAGE_ROUTE_ Preset Definition so that each portal is able to customize the message headers to be sent to the SMS driver as the billing information for the result message. For instance, the description of ROUTE_COST_LEVEL can be changed from Cost level to Tariff class. Those meta fields can also be added or deleted.
By default, the values of the two fields, ROUTE_CHANNEL and ROUTE_REV_CHANNEL, are set to From and ReplyTo fields of the result message. This allows the information to be passed to the Premium SMS operator without requiring a custom-built driver. If the administrator needs to change the mapping, he should modify the two attributes, wireless.async.routeinfo.to and wireless.async.routeinfo.replyto.
|
 Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|