10 Creating Messaging Applications

10.2.1.1.1 Send

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: E-mail:mye-mail@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: e-mail address, phone number or user name)

The address format is shown in Example 10-1

<address string ><:transport type > [;<address string>:<transport type >]* 
<address string> = <e-mail 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: E-mail:mye-mail@foo.com;Voice:mary,E-mail:mary,Fax:mary;E-mail: 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.

10.2.1.1.2 getStatus

public String[] getStatus(String[] messageIDs)

Gets the current status of a set of message IDs.

Returns: an array of text status strings.

10.2.1.2.1 Send

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.

10.2.1.2.2 getStatus

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: e-mail). 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 E-mail 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:

• OracleAS Wireless server on which the Push Web Service is running. Include the username and password, and the HTTP proxy required to access the remote OracleAS Wireless Web Service (unless the application will be running in an OracleAS Wireless VM).

• Actual message to be sent and the content (MIME) type of the message.

10.2.3.1.1 XMS Client

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 document must be in OracleAS Wireless-supported content markup format. For this release, only OracleAS Wireless XML is supported for actionable messages.

• The URL link used in the document could be in HTTP or OMP protocol. The OMP is a virtual URL to identify a service in an OracleAS Wireless instance. The benefit of using OMP URL is that it uniquely identifies a service created in OracleAS Wireless. Thus, any change of a service OID does not affect the user program.

10.2.3.1.2 XMS

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.

10.2.3.1.3 RevAsync

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.

10.2.3.5.1 Requirements

This tutorial requires a full installation (10g) of OracleAS Wireless installation.

10.2.3.5.2 Assumptions

The tutorial assumes that you have the knowledge to send out documents by calling the XMS API. There is no discussion on how to write such programs. The main focus here is to demonstrate how to associate an original document with the service being invoked on user reply.

10.2.3.5.3 Pre-requisites

Because this tutorial shows how to create a simple Async application and test it with Jabber IM clients, a Jabber client and an account on a Jabber server should be prepared before starting configuration.

In this tutorial, the product (Rival), is the Jabber client, and netmindz.net is the Jabber server for user accounts; you can use your own favorite client or server. The site http://jabber.org provides a comprehensive list of popular Jabber clients and public servers. To download the freeware and set up an account:

1. Point your browser to http://rival.chote.net/

2. Download the software.

3. Run the EXE file, and follow the instructions to install the software. Be sure to set the proxy value (if required in your environment). Once installed, the first screen you see should look like the following screen:

Figure 10-3 Actionable Message Tutorial Opening Screen

Description of "Figure 10-3 Actionable Message Tutorial Opening Screen"

4. Click the text (Click to Login) in the middle of the screen to log in. The Rival Messenger Login screen appears.

Figure 10-4 Actionable Message Login

Description of "Figure 10-4 Actionable Message Login"

5. Click the text, Rival Signup / Registration, to register for a new account.

6. Check New Account.

7. Enter netmindz.net (or the name of your favorite server) as the Jabber Server value.

8. Enter UserName. In this tutorial, we create a user called asynctester. You should assign a name other than this, if you also use netmindz.net as your server.

9. Enter a Password.

10. Click Proceed to create a new account. A new account is created, and you can chat with your Jabber buddy.

Next, you will accomplish Async Configuration.

10.2.3.5.4 Tutorial Steps

This tutorial is accomplished in four parts:

• Configuring the Messaging driver

• Adding Async access points

• Creating the service to be invoked for user reply

• Testing

10.2.3.5.5 Configuring the Messaging Driver

Async uses the transport layer to provide access to wireless networks. Async supports various channels; in this example Instant Messaging is the transport for this tutorial.

You will first configure the IM driver to be able to communicate with a Jabber client. You will configure the system parameters in different components, depending on the installation you are working on (standalone or integrated). For standalone mode, configure it through OracleAS Wireless Webtool. Enterprise Manager is the tool to use for integrated installation. This tutorial is based on the standalone instance. Here are the steps:

1. Log in to OracleAS Wireless Webtool (at a URL such as http://<hostname>:7777/webtool).

2. Enter the user account (orcladmin with the password manager, or whatever password has been set).

3. Click the link, Site Administration, in the Wireless Server section. The Administration page for site configuration appears.

4. Under the General Configuration section, click HTTP, HTTPS Configuration.

5. Provide the proxy settings if the instance resides within an intranet, and is required to use a proxy server to direct traffic to the Internet. Set required values.

6. Click the + sign in front of Component Configuration to expand the configuration settings for server components.

7. Select the Drivers link under the Messaging component. The driver page appears, listing supported drivers for the instance.

8. Select PushDriver and click Edit. The property settings for the PushDriver are displayed.

Because you are creating your own IM driver instance, remove the IM delivery capability from the PushDriver; all the IM traffic will go though the IM driver instance.

9. Under the Delivery Category section, deselect the IM entry and click OK. You are returned to the Driver list screen.

10. Click System (or the Wireless link from Enterprise Manager) to go to the Process Configuration Page.

11. Click Add Process; the Create New Process page appears.

12. Select Messaging Server as the Process Type, assign a name (for example, messaging_server_tutorial and click Continue.

13. Set the value (IMTutorialDriverInst) as the Driver Instance Name.

14. Select IMDriver for the Driver Name and click Go.

15. Assign 1 to both Sending and Receiving Threads.

16. Assign netmindz.net as the value for im.server.host.

17. To avoid user name conflicts for the tutorial, choose a name for im.server.username, which is specific to each tester (for example, <last_name><birthday>). In this walk-through, we will use the name am0101; you should configure using a different name.

18. Assign a password and click Finish. A new Messaging Server named messaging_server_tutorial is created with an IM driver.

19. Click Start to start the process. Only one active IM driver should be running in order to have two-way IM work properly.

20. Bring up your IM client window and add the newly created account (am0101 in this example), to the contact list. For Rival Jabber client, you do this by clicking the + sign to the left of the screen.

Once the account is added as a contact, you will see the contact (am0101), marked as online in your IM client. If this is not the case, it may be due to the following:

• The contact name being entered into your IM client is not correct.

• The IM Server is not up. This can be verified by viewing the log file. To do so, click System, and then View Log File at the bottom of the screen.

Messaging Configuration is complete.

10.2.3.5.6 Adding Async Access Point

To configure the Async access point, log in to the Webtool (or Enterprise Manager).

1. Click Site Administration and then click the + sign in front of Component Configuration to expand the configurable items.

2. Click Access Point under Async Listener.

3. Add the IM account you created earlier as an Async access point.

4. Click Add Access Point to enter the account information.

5. Assign TutorialActionableMessage as the Name value.

6. Select IM as the Delivery Type. The format for the address is <network>|<User ID>. Since the account you created is for the Jabber protocol, the network value should be Jabber. The User ID format for Jabber is <User Name>@<Server>. Hence, the value of the Address field should be jabber|am0101@netmindz.net. Note: Your address should be different from this one, and be consistent with the address configured for your Messaging Driver.

7. Check Dedicated for Async Message Reply.

8. Uncheck Allowed to Access All Applications and click OK. The new entry appears on the Access Point list.

This completes System Configuration; next is application creation.

10.2.3.5.7 Creating Async-enabled Applications

This phase includes two steps: application creation and content publishing. You will create a Hello application to exercise some important Async parameters. First login to Webtool and click Services tab on top. This leads you to the page shown below.

1. Log in to the Webtool.

2. Click Add Folder, and create a folder named Async Tutorial.

3. Click the Async Tutorial link to navigate to the folder.

4. Click Create Application.

5. Click Create.

6. Assign TutorialExpense as the Name value.

7. Assign a URL value /mcs/async/modules/revask/ExpenseReply.jsp. ExpenseReply.jsp is a simple JSP file, which outputs a Wireless XML document, listed below.

<?xml version = "1.0" encoding = "ISO-8859-1"?>
<%@ page contentType="text/vnd.oracle.OracleAS Wireless XML; charset=ISO-8859-1" %>
<%
   String answer = request.getParameter("answer");
   String reportNo = request.getParameter("reportNo");
%>
<SimpleResult>
   <SimpleContainer>
      <SimpleText>
         <SimpleTextItem>Expense Report, #<SimpleStrong><%=reportNo%></SimpleStrong>, has been <%=answer%>.</SimpleTextItem>
      </SimpleText>
   </SimpleContainer>
</SimpleResult>

The JSP file is included in the product, in the directory ORACLE_HOME/wireless/j2ee/applications/mcs/async-web/modules/revask. The listing above is for your reference.

8. Click Finish to create the application.

   Now you will publish the application.

9. Click the Content tab to go to Content Manager.

10. Create a folder named Async Tutorial.

11. Navigate to the newly created folder.

12. Click Add Application Link.

13. Click Master Link.

14. Click Async Tutorial.

15. Select TutorialExpense Application and click Next.

16. Assign TutorialExpense to the Name field.

17. Assign omp://tutorialexpensereply to the OMP URL field. This is the identification of the Application Link, which should be referenced by the MenuItem of the document being published.

18. Click Finish.

    Next, you will make the application accessible to public by associating it with the Guest group.

19. Click the Access Control Content tab.

20. Select the Guest group and click Assign Application.

21. Click Async Tutorial under the Available Applications group.

22. Select TutorialExpense and click Add to Group. TutorialExpense appears in the Group Accessible Applications section.

23. Click Finish.

Since we also want to restrict the service to be accessible to the access point just configured, we should create an application category to associate this two.

24. Click Categorize Content.

25. To create a new category, click Create.

26. Assign Tutorial Expense as the Name.

27. Click Add to bind an access point.

28. Select access point TutorialActionableMessage and click Add; associating the access point with the application category. The access point is associated with the category.

29. Click Finish to complete the category creation. Now you will bind the application category with an application link.

30. Click the Publish Content tab on top left.

31. Click the Async Tutorial folder.

32. Select the Tutorial Expense Application link, and click Categorize to bind the link to a category.

33. Select Tutorial Expense Category and click Move to make the association.

34. Click Apply to complete the action.

10.2.3.5.8 Test Run

Now you will test the application you created. Open a browser and go to http://<host_name>:7777/mcs/async/modules/revask/RequestPushInfo.jsp with <host_name> being the name of the installed OracleAS Wireless host.

1. Assign jabber|<jabber_account> as the device address value where <jabber_account> is the Jabber account you use as the client device (for example: asynctester@netmindz.net). Important: Be sure to add Jabber as the IM transport in front of the account name (making the full address jabber|asynctester@netmindz.net).

2. Select IM as the Delivery Type.

3. Select XML Document.

4. Paste the document below into the document input box:

   Example 10-5 Test Run Sample

   <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>
            <SimpleMenuItem target="omp://tutorialexpensereply?answer=approved&amp;reportNo=1234">Approve</SimpleMenuItem>
            <SimpleMenuItem target="omp://tutorialexpensereply?answer=disapproved&amp;reportNo=1234">Disapprove</SimpleMenuItem>
         </SimpleMenu>
      </SimpleContainer>
   </SimpleResult>
   
   

As you see, the MenuItem uses the OMP URL to point to the service to be invoked on user reply. The value is the same as the OMP value you defined for the newly created Application Link (You can also use HTTP protocol if you prefer). In this case the format should be like this:

http://<host_name>:7777/ptg/rm?answer=approved&amp;reportNo=1234&amp;PAompurl=omp%3A%2F%2Ftutorialexpensereply

If you do not want to go through the OracleAS Wireless service for request authorization (that is, the service provider will do the request authorization), you can skip the application/link creation steps, and provide the URL format like the one shown here:

http://<host_name>:7777/mcs/async/modules/revask/ExpenseReply.jsp&amp;answer=approved&amp;reportNo=1234

There is no value in above URL to indicate the service to invoke. The invocation goes through a public proxy service seeded in OracleAS Wireless installation.

5. Click Push Message to send out the document. A text message is displayed indicating a message has been sent, and a message will be received by your IM client.

6. To reply to the message, follow the instruction on the first line of the message. For the example above, it requires the format 3 [params] where 3 is transaction ID, and params may have the values of 1 (approve) or 2 (disapprove).

7. Reply with the value 3 1 to approve the expense report.

Service is sent back to confirm the approval of the expense report. This step completes the walkthrough of the actionable message example.

10.6.1.1.1 Required Third-Party Software

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

10.6.1.1.2 Class Name

oracle.panama.messaging.transport.driver.mms.NokiaMMSDriver

10.6.1.1.3 Configuration

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.

10.6.1.2.1 Required Third-Party Software

This driver requires the CMG MMSC API for VAS v1.1.1 (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 (in UNIX) or ORACLE_HOME\opmn\conf\opmn.xml (in Windows).

10.6.1.2.2 Class Name

oracle.panama.messaging.transport.driver.mms.CMGMMSDriver

10.6.1.2.3 Configuration

• mms.cmg.account.id—The MSISDN of the VAS application, or the short identification number as registered with the CMG MMSC. This is required.

• mms.cmg.account.alias—The application alias configured in the CMG U-power web interface. This is required.

• mms.cmg.account.password—The password to authenticate the VAS application as registered with the CMG MMSC. 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, refer to the User Manual that is packaged with the CMG MMSC API distribution. A sample configuration file is included: (ORACLE_HOME\wireless\messaging\drivers\cmg\CMGMMSDriver.cfg) with this driver.

• mms.cmg.debug—Enable logging extra debug information to the 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, refer to 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.

10.6.1.2.4 Additional Configuration

To configure the driver to receive MMS messages, you must perform these steps:

1. Package the mmscapi.war file into a cmgmmsc.ear file as follows:

   1. Unzip ORACLE_HOME\wireless\messaging\drivers\cmg\cmgmmsc.ear.zip into an empty directory. This creates the following directory structure: \META-INF\application.xml, \META-INF\MANIFEST.MF

   2. Copy mmscapi.war into this directory and rename this file to cmgmmsc.war. This creates the final directory structure: \META-INF\application.xml, \META-INF\MANIFEST.MF, \cmgmmsc.war

   3. Zip this directory structure and rename the zip file to cmgmmsc.ear.

   4. Copy cmgmmsc.ear to ORACLE_HOME\wireless\j2ee\applications\

2. In ORACLE_HOME\wireless\j2ee\config\wireless-web-site.xml, add: <web-app application="cmgmmsc" name="cmgmmsc" root=/"cmgmmsc" load-on-startup="true"/>

3. In ORACLE_HOME\wireless\j2ee\config\wireless-server.xml, add: <application name="cmgmmsc" path="../applications/cmgmmsc.ear" auto-start="true" />

4. Start the OracleAS Wireless instance, which will auto-deploy the cmgmmsc.ear file.

5. After the auto-deploying is complete, in ORACLE_HOME\wireless\j2ee\applications\cmgmmsc\cmgmmsc\WEB-INF\web.xml:

   • Edit the trace directory and filename.

   • Add the following section: <servlet-mapping> <servlet-name> HttpReceive </servlet-name> <url-pattern> /HR </url-pattern></servlet-mapping>

6. Back up (rename the file's extension to anything except .jar) ORACLE_HOME\wireless\lib\log4j-core.jar and ORACLE_HOME\wireless\lib\log4j.jar. Copy ORACLE_HOME\wireless\j2ee\applications\cmgmmsc\cmgmmsc\WEB-INF\lib\log4j-1.2.5.jar to ORACLE_HOME\wireless\lib\log4j-core.jar.

7. Restart the OracleAS Wireless instance.

   The servlet HttpReceive runs within the OracleAS Wireless instance, and requires RMI to communicate with the CMGMMSDriver. Further details are provided in the User Manual that is packaged with the CMG MMSC API distribution.

10.6.1.3.1 Class Name

oracle.panama.messaging.transport.driver.mms.MM7Driver

10.6.1.3.2 Configuration

mms.mm7.url—The URL to access the MMSC/MM7. This is required.

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

mms.http.user—(Optional) Username for HTTP authentication.

mms.vaspid—(Optional) Password for HTTP authentication.

mms.vaspid—(Optional) Identifier of this application (VASP) for the MMSC.

mms.vasid—(Optional) Identifier of the originating application. Example: News.

10.6.1.4.1 Class Name

oracle.panama.messaging.transport.driver.sms.CIMDDriver

10.6.1.4.2 Configuration

The following parameters must be specified while creating the Driver:

• sms.account.id

  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.

10.6.1.5.1 Class Name

oracle.panama.messaging.transport.driver.vvsp.VVSPDriver 

10.6.1.5.2 Configuration

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/ (this is an example; not meant to be an actual link).

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

10.6.1.5.3 Additional Configuration—Password Renewal

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://www.oracle.com/technology/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.

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 from Vodafone Mobile Office at http://www.mobileoffice.vodafone.com.

10.6.1.6.1 Class Name

oracle.panama.messaging.transport.driver.sms.WCTPDriver

10.6.1.6.2 Configuration

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.

• network-connection-test-interval-minutes

  Time interval (in minutes) between successive handshake signals sent to the Gateway in order to keep the connection alive. A negative value means that the feature is disabled. Default value is -1.

• callback-connection-test-interval-minutes

  Time interval (in minutes) to wait for status callback, before sending "Return to Service" message to the Gateway.Negative value means that the feature is disabled. Default value is -1.

• connection-retry-count

  Number of times to retry connecting to the Gateway if there is a connection failure. Negative value means there is no limit to the number of tries. The default value is -1.

• maximum-multiple-recipients

  Maximum number of recipients in a multi-recipient message. Negative value means there is no limitation. The default value is -1.

10.6.1.7.1 Setup Details

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:

• Java communication package—can be downloaded from Sun Microsystem's web site.

• Nokia cell phone (the driver has been tested for 5100 and 6100 series of phone).

• Data cable for the Nokia phone (the cable 9-pin RS-232C serial cable DAU-9P is required for 5100/6100 series of phone)

• Data suite installation CD (if the phone does not have a built-in modem).

The setup procedure is divided into three categories:

• Installing Java communication package.

• Installing Data suite.(This step is required only if your phone does not have a built-in modem, such as the Nokia 5110).

• Configuring OracleAS Wireless messaging server.

The details on each of the above categories are listed below.

• Installing Java communication package

  Download Javacomm20-win32.zip.

  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.

  
  

  Note: In case the sample programs are not listing the serial ports, try copying the file Javax.comm.properties in the directory <Java_HOME>\jre\lib. Where <Java_HOME> is the place where jdk is installed and the Java installed at <Java_HOME>\bin\Java is the one, which will be used to run the OracleAS Wireless components.

  
  

• Installing Data suite

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

  1. Connect your Nokia cell phone using the appropriate data cable to any of the PC's COM ports.

  2. Install Nokia data suite (typical installation).

  3. After the software is installed successfully, reboot the machine.

  4. Go to control-panel -> ports; an extra port will be listed. For example if the ports listed before installation were COM1 and COM2 then after installation the ports may get listed as COM1, COM2 and COM3. In this case, COM3 is the virtual port, which the data suite has configured for data transfer between the phone and the pc.

10.6.1.7.2 Driver Configuration

Class Name

oracle.panama.messaging.transport.driver.datacommunication.DataCommunicationDriver

10.6.1.7.3 Configuration

·

• sms.datacommunication.port

  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.

10.6.1.7.4 Compatible Devices

Table 10-4 lists devices tested to work with this driver. It is not meant to be an exclusive list of all devices that will work, simply a list of devices tested thus far.

10.6.1.8.1 Class Name

oracle.panama.messaging.transport.driver.wap.PAPDriver

10.6.1.8.2 Configuration

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

• pap.default.encoding

  The default content encoding format; if not set, UTF-8 is used.

• pap.version

  The PAP version supported by the PPG, must be either 1.0 or 2.0.

10.6.1.9.1 About Jabber

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 e-mail 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.

10.6.1.9.2 Third-party Jabber Software

The Instant Messaging driver uses the JabberBeans Java library to connect to a Jabber Instant Messaging Server. It requires third-party software listed in Table 10-5.

10.6.1.9.3 Configuring the Messaging Server with the Instant Messaging Driver

Use the OracleAS Wireless Tools to configure the messaging server with the instant messaging driver.

To add/enable the instant messaging driver:

1. Click the Administration tab.

2. Expand the Messaging Server section under Special Configuration for Wireless Site. Click Messaging Server Drivers. The Messaging Server Drivers screen appears.

3. In the Configuration section, click Messaging Server Drivers. The Messaging Server Drivers screen appears.

4. If you do not see an entry for IMDriver, go to Step 5. If you see an entry for IMDriver, enable the driver as follows:

   1. Select the IMDriver entry and click Edit. This will open the IMDriver Properties screen.

   2. Check the Enabled box and click Apply.

   3. Go to the next section Configuring the Driver Instance.

5. Click Add Driver. The Add Driver screen appears. Enter only the values noted here; other values are not required.

   1. In the Driver Name field, enter IMDriver.

   2. Select IM from Delivery Category.

   3. From the Speed Level drop-down list, select 8.

   4. From the Cost Level drop-down list, select 1.

   5. From the Capability drop-down list, select BOTH (or only SEND or RECEIVE, if you want unidirectional messaging).

   6. Enter 1 in the Number of Message Queues field.

   7. Check the Enabled box.

   8. In the Driver Class Name field, enter oracle.panama.messaging.transport.driver.instantmessaging.InstantMessagingDriver

   9. Click Add Another Row to add a row for each of the following parameters:

      • For the Jabber server: 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.):

      • For Yahoo: im.yahoo.enable, im.yahoo.username, im.yahoo.password

      • For MSN: im.msn.enable, im.msn.username, im.msn.password

      • For AOL: im.aol.enable, im.aol.username, im.aol.password

      • For ICQ: im.icq.enable, im.icq.username, im.icq.password

      • To print verbose debug output: im.debug

      • To adjust retry parameters which are used when the driver is disconnected from the Jabber server: im.retry.limit, im.retry.interval

        
        

        Note: Detailed explanations of these parameters are provided in the Table below.

        
        

   10. Click OK to create the driver.

10.6.1.9.4 Configuring the Driver Instance

To configure the instant messaging driver instance:

1. Click the Wireless Server tab. The Server screen appears.

2. Click messagingserver1 in the process table. The messagingserver1 process screen appears.

3. Click Add Driver Instance. The Add Driver Instance screen appears.

4. Complete the Add Driver Instance screen as follows:

   1. Enter IMDriver Instance in the Driver Instance Name field.

   2. From the Driver Name drop-down list, select IMDriver.

   3. Click Go.

   4. In the Number of Sending Threads field, enter 2.

   5. In the Number of Receiving Threads field, enter 1.

   6. In the Driver Specific Parameter fields, enter values as listed in Table 10-6.

   Table 10-6 Values for Driver Specific Parameters

   For This Parameter Name...	Enter this Value
   Parameters for Jabber IM	Enter these values for Jabber IM.
   im.server.host	localhost (Replace this value with the hostname of your Jabber server. For multiple servers, use a comma-separated list. If only one hostname is specified, it will be used for all accounts. Example: my1.host.com, my2.host.com.). If the Jabber server is outside your firewall, the IM driver will connect to it using the site-wide HTTP proxy settings configured in your OracleAS Wireless instance.
   im.server.port	5222(default Jabber port. For multiple servers, provide a corresponding comma-separated list of ports. Example: 5222, 5222.)
   im.server.username	oracleagent (Replace this value with the Jabber username of the OracleAS Wireless instance). The IM Driver will connect to Jabber with this username. A Jabber ID is of the form username@hostname, and this parameter only requires the username part. For multiple accounts, enter a comma-separated list of Jabber usernames to login as. If you have multiple servers listed above, there must be an equal number of usernames (one username per server). If you have only one server listed above, all usernames listed here will use that server. Example: oracleagent1, oracleagent2). If an account does not exist on the Jabber server, the IM driver will attempt to register it as a new account.
   im.server.password	test (Replace this value with a corresponding comma-separated list of passwords for each username listed above.)
   Optional Parameters for Yahoo IM	Enter these values only if you want to connect to Yahoo's IM network
   im.yahoo.enable	Set im.yahoo.enable to true to enable the Yahoo transport. To disable using Yahoo, leave this field blank, and ignore the username and password fields. If you have multiple accounts specified above, provide a corresponding comma-separated list of values.
   im.yahoo.username	Enter a comma-separated list of Yahoo account IDs (requires that you already have these IDs registered on Yahoo), for each user account above (leave entries blank for accounts without Yahoo). Entering valid Yahoo account information enables Yahoo users to access OracleAS Wireless applications through Yahoo Messenger.
   im.yahoo.password	Enter corresponding comma-separated list of Yahoo account passwords.
   Optional Parameters for MSN IM	Enter these values only if you want to connect to MSN's IM network
   im.msn.enable	Set im.msn.enable to true to enable the MSN transport. To disable using MSN, leave this field blank, and ignore the username and password fields. If you have multiple accounts specified above, provide a corresponding comma-separated list of values.
   im.msn.username	Enter comma-separated list of MSN account IDs (requires that you already have these IDs registered on MSN), for each user account above (leave entries blank for accounts without MSN). Entering valid MSN account information allows MSN users to access OracleAS Wireless applications through MSN Messenger.
   im.msn.password	Enter corresponding comma-separated list of MSN account passwords.
   Optional Parameters for AOL IM	Enter these values only if you want to connect to AOL's IM network.
   im.aol.enable	Set im.aol.enable to true to enable the AOL IM (AIM) transport. To disable using AOL, simply leave this field blank, and ignore the username and password fields. If you have multiple accounts specified above, provide a corresponding comma-separated list of values.
   im.aol.username	Enter comma-separated list of AOL account IDs (requires that you already have these IDs registered on AOL), for each user account above (leave entries blank for accounts without AOL). Entering valid AOL account information enables AOL users to access OracleAS Wireless applications through AOL Instant Messenger.
   im.aol.password	Enter corresponding comma-separated list of AOL account passwords.
   Optional Parameters for ICQ	Enter these values only if you want to connect to ICQ's IM network
   im.icq.enable	Set im.icq.enable to true to enable the ICQ transport. To disable using ICQ, leave this field blank, and ignore the username and password fields. If you have multiple accounts specified above, provide a corresponding comma-separated list of values.
   im.icq.username	Enter comma-separated list of ICQ account IDs (requires that you already have these IDs registered on ICQ), for each user account above (leave entries blank for accounts without ICQ). Entering valid ICQ account information enables ICQ users to access OracleAS Wireless applications through ICQ Instant Messenger.
   im.icq.password	Enter corresponding comma-separated list of ICQ account passwords.
   Additional Parameters	Enter these values for additional configuration
   im.debug	Set this value to true to enable verbose debug output. This triggers the driver to output additional notification messages, which also requires that you have the Notify log level enabled in your system logging configuration for the OracleAS Wireless instance.
   im.retry.limit	20 (Number of times the driver should attempt to reconnect when disconnected from a Jabber server. (the default limit is 20.)
   im.retry.interval	20 Time interval, in seconds, between reconnect attempts. (the default interval is 20 seconds.)

   
   

5. Click OK to create the driver instance.

   
   

   Note: You must restart the messaging server each time you change the driver-specific attributes.

   
   

10.6.1.9.5 Using the IM Driver with the Async Server

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:

1. Click the Wireless Server tab.

2. Click the Administration tab.

3. Expand the Async Server section under Special Configuration for Wireless Site. Click Access Points. The Access Points screen appears.

4. Click Add Access Point.

5. Enter IM entry point in the Name field.

6. Select IM from Delivery Type.

7. In the Address field, enter jabber|<Jabber ID> where <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>).

8. Check the Allowed to Access All Services box.

9. Click OK to add the access point.

10. If you have configured the IM driver for other IM networks such as Yahoo or MSN, you must specifically add an access point for each such network. The address must be of the form <network-name>|<userid>, where <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:

• Depending on which IM systems (such as Jabber, Yahoo, MSN, AOL and ICQ) you have configured the IM driver for, you must add the corresponding user to your IM client's roster or contact list. We refer to this user as the IM Agent.

  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.

• Send an instant message to the IM Agent with help as the body of the message. After you send this message, you receive an instant message with the list of applications you can invoke.

  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:

  
  

  Note: The above example assumed that the hello application is async-enabled.

  
  

• For applications that require user input, chat with the agent and enter the necessary values.

  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.

10.6.1.9.6 Using the XMS Service

In order to send instant messages using the XMS service, you have two API options, namely XMSSimpleSender and XMSSender:

• Using XMSSimpleSender:

  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

Some examples are listed in Table 10-7.

• Using XMSSender

  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)

where address has the XMSSimpleSender Address format <address> as shown above.

For example:

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

Example 10-6 shows a 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);

10.6.1.9.7 Standalone test of the IM Driver

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:

1. Download JabberD from http://jabberd.jabberstudio.org/downloads/JabberD-1.4.2.exe

2. Open the file to start the installation process. Proceed in the installation with the default values and finish the installation.

3. Start the Jabber server from Windows Start > Programs > JabberD > JabberD This opens a DOS Command Prompt window, and you will see log output that says [notice] (-internal): initializing server. If you see this message, you have successfully started the Jabber server.

To install Jabber Server on UNIX:

1. Download the Jabber server:

   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

2. Extract the tar file.

   # mkdir jabber
   # cd jabber
   # gtar xzvf jabber-1.4.2a-sparc-solaris-<ver>.tar.gz
   
   

3. Execute jabberd:

   # jabberd/jabberd
    
   

4. This starts the Jabber server and begins printing log messages such as: [notice] (-internal): initializing server. If you see this message, you have successfully started the Jabber server.

To install Jabber Client on Windows:

1. Download and install a Jabber client of your choice from http://www.jabber.org/user/clientlist.php. Oracle Corporation recommends Rival (http://rival.chote.net/) for first-time Jabber users.

2. After installation, configure your client to connect to the Jabber server on localhost. Create a new Jabber account for yourself. Now add to your contact list the Jabber ID of the OracleAS Wireless instance that you configured in the IM driver. For example, if you use the pre-configured default settings in the IM driver, you would add the ID oracleagent@localhost to your contact list.

To install Jabber Client on UNIX:

1. Download, compile and install a Jabber client of your choice from 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.

2. Once you have a client up and running, follow Step 2 from the Windows section above.

To send a test message to OracleAS Wireless:

1. From your Jabber client, double-click on the contact you just added (oracleagent@localhost) to send an instant message.

2. Type help in the body, and send the message. If your IM driver and Async access point are configured correctly, you will receive an instant response from OracleAS Wireless listing the async applications you can invoke.

10.6.1.9.8 Quick-configuring the IM Driver for AOL Instant Messenger

To quick-configure the IM driver for AOL Instant Messenger:

1. Create AOL screen names.

   You must have two AOL screen names (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 screen names, create them at http://www.aim.com.

   
   

   Note: The AOL web site limits the number of accounts you can create for a given e-mail address or IP address. If you receive an error while trying to create an account, use an alternate e-mail address, or a different machine.

   
   

2. Configure IM Driver and Async Access Point.

   1. Add an IMDriver Instance in the messagingserver1 process. Enter the following values:

      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>
      
      

   2. Add an IM access point from Wireless Tools > Site Administration > Component Configuration > Access Point:

      • Enter IM entry for Name.

      • Select IM for Delivery Type.

      • Enter aim|<imdriver_screenname> for Address.

      • Check Allowed to Access All Applications.

      • Restart the messagingserver1 process.

3. Install AOL Instant Messenger (AIM).

   1. Download and install AIM from http://aim.aol.com/aimnew/NS/congratsd2.adp.

   2. Launch AIM and click Setup. Click Connection to configure HTTP proxy settings (host = www-proxy.us.oracle.com, port = 80, protocol = HTTP).

   3. Sign on to AIM with your screen name <my_screenname>.

   4. Add <imdriver_screenname> to your buddy list and start chatting.

10.6.1.10.1 Class Name

oracle.panama.messaging.transport.driver.push.PushDriver

10.6.1.10.2 Configuration

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

10.6.1.11.1 Class Name

oracle.panama.messaging.transport.driver.e-mail.e-mailDriver

10.6.1.11.2 Configuration

• server.incoming.protocol

  This is the value for the e-mail receiving protocol. The possible values are IMAP and POP3. Required only if e-mail receiving is supported on the driver instance.

• server.incoming.host

  The host name of the incoming mail server. Required only if e-mail 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 e-mail 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 e-mail receiving is supported on the driver instance.

  Example: foopwd,barpwd

• server.incoming.e-mails

  The e-mail addresses corresponding to the user names above. Each e-mail 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 e-mail 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.retry.limit

  This value specifies the number of times to retry connecting to the incoming mail server, if the connection is lost due to some reason. The default value is -1 which means no limit to the number of tries.

• 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 e-mail sending is required.

  Example: smtp05.oracle.com

• server.outgoing.username

  The username used for SMTP authentication. Required only if SMTP authentication is supported by the SMTP server.

• server.outgoing.password

  The password used for SMTP authentication. Required only if SMTP authentication is supported by the SMTP server.

• default.outgoing.from.address

  The default FROM address (if one is not provided in the outgoing message).

The e-mail 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.

10.6.1.12.1 Class Name

oracle.panama.messaging.transport.driver.voice.Voice GenieDriver

10.6.1.12.2 Configuration

• 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.OutboundCallServlet
  
  

  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.

  
  

  Note: This driver opens a port (as specified in voicegenie.driver.receive.port) and listens to HTTP traffic. It uses voicegenie.driver.receive.host and voicegeneie.driver.receive.port to compose a URL for OracleAS Wireless HTTP adapter to contact the driver. This is required if you want to send a message that contains OracleAS Wireless XML. Ensure that you provide the correct hostname and unique port number in order for the driver to function.

  
  

10.6.1.14.1 Class Name

oracle.panama.messaging.transport.driver.sms.UCPDriver

10.6.1.14.2 Configuration

• 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. If the account ID is a Multiple User Large Account (MULA), then you are required to open a session.

• 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. For multibyte languages (such as Chinese), the attribute must be set to UCS-2. The attribute sms.message.chunksize should be set accordingly (that is, the chunksize should be no more than 160 if the encoding is IA5; no more than 70 if the encoding is UCS-2).

• 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. The default size is 1. This parameter usually applies to MULAs. Contact the SMSC administrator if you want to set it to a number other than 1.

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

  
  

  Note: If you have a direct TCP connection to the SMSC, the driver uses Command 60 to start a session with the SMSC. This allows the driver and the SMSC to communicate with one socket connection for sending, receiving and status. In this case sms.server.url is not used. If the connection you have to an SMSC is HTTP-based, then you must provide the value for sms.server.url; this is the URL the driver instance uses to send messages. Also sms.receiver.listener.port must be provided so that the driver instance opens binds to this port for incoming messages. In the HTTP connection case, sms.server.host and sms.server.port are not used. sms.message.chunksize controls the size of each message in case the message total size is bigger than one SMS message. sms.message.maxchunks controls the maximum number of chunks allowed for each message. Those beyond that will be discarded.

  
  

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

10.6.1.15.1 Class Name

oracle.panama.messaging.transport.driver.sms.SMPPDriver

10.6.1.15.2 SMPP DRIVER--Configuration

• 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. For multibyte languages (such as Chinese), the attribute must be set to UCS-2. The attribute sms.message.chunksize should be set accordingly (that is, the chunksize should be no more than 160 if the encoding is IA5; no more than 70 if the encoding is UCS-2).

• 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, applicable to the non-listening mode driver only. The default size is 1. This parameter usually applies to MULAs. Contact the SMSC administrator if you want to set it to a number other than 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.

• sms.wireless.network

  The type of network used to send SMS. The valid values for this field are GSM or CDMA. The default value is GSM.

• sms.priority.allowed

  Designates the highest priority allowed for a message. The valid values for this field are from 0 to 3. The default value is 0.

10.6.1.16.1 Class Name

oracle.panama.messaging.transport.driver.fax.RightFAXDriver

10.6.1.16.2 Configuration

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

10.6.2.2.1 The init() and destroy() methods

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.

10.6.2.2.2 The send() method

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.

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.

• If the exception is not marked fatal, the driver will still be used to send other messages.

• If the exception is not of the type DriverException, the driver will be used to send other messages as well.

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.

10.6.2.2.3 The receive() method

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.

10.6.2.2.4 The getStatus() method

The transport calls this method in an attempt to retrieve delivery status for a particular message when necessary.

10.6.2.2.5 The queryTracking() and queryNotifying() methods

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() ).

10.6.2.3.1 The getMessageListener() and getStatusListener() methods

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.

10.6.2.4.1 The encode() method

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:

• Throw a Transport exception when you know how to handle it and are sure that user data are corrupted or improper. In this case, the smart messaging process (not the physical Java process) terminates.

• Do not throw an exception, just return null when you do not know how to handle it.

In this case, the prebuilt 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.

10.6.4.1.1 OracleAS Wireless Messaging System

• FailOverHook--(interface oracle.panama.messaging.transport.FailOverHook). This hook is for future use.