This chapter explains how to use the Oracle Communications Services Gatekeeper WAP Push Extended Web Service interface to add WAP Push support to applications.
The WAP Push Extended Web Services interface sends messages which are rendered as WAP Push messages by the addressee's terminal. The content of the message is coded as a PAP message. It also provides an asynchronous notification mechanism for delivery status.
The payload of a WAP Push message must adhere to the following specifications:
WAP Service Indication Specification, as specified in Service Indication Version 31-July-2001, Wireless Application Protocol WAP-167-ServiceInd-20010731-a.
WAP Service Loading Specification, as specified in Service Loading Version 31-Jul-2001, Wireless Application Protocol WAP-168-ServiceLoad-20010731-a.
WAP Cache Operation Specification, as specified in Cache Operation Version 31-Jul-2001, Wireless Application Protocol WAP-175-CacheOp-20010731-a.
See the Open Mobile Alliance websitewebsite for links to the specifications:
http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html
The payload is sent as a SOAP attachment.
See "Sending Custom Message Content for Split and Submit Messaging Requests" for instructions on how to split messages into multiple individually-addressed requests
The PushMessage interface and service use the namespaces:
http://www.bea.com/wlcp/wlng/wsdl/ews/push_message/interface
http://www.bea.com/wlcp/wlng/wsdl/ews/push_message/service
The PushMessageNotification interface and service use the namespaces:
http://www.bea.com/wlcp/wlng/wsdl/ews/push_message/notification/interface
http://www.bea.com/wlcp/wlng/wsdl/ews/push_message/notification/service
The data types are defined in the namespace:
http://www.bea.com/wlcp/wlng/schema/ews/push_message
In addition, WAP Push Extended Web Service uses definitions common for all Extended Web Services interfaces:
The datatypes are defined in the namespace:
http://www.bea.com/wlcp/wlng/schema/ews/common
The faults are defined in the namespace:
targetNamespace="http://www.bea.com/wlcp/wlng/wsdl/ews/common/faults"
The endpoint for the PushMessage interface is: http://
host
:
port
/ews/push_message/PushMessage
Where host and port are the host name and port of the system on which Services Gatekeeper is installed.
Figure 33-1 shows the general message sequence for sending a WAP Push message from an application that uses WAP Push Extended Web Service to the network. In this message sequence the application also receives a notification from the network indicating the delivery status of the WAP Push message, that is that the message has been read The interaction between the network and Services Gatekeeper is illustrated in a protocol-agnostic manner. The exact operations and sequences depend on which network protocol is being used.
Note:
Zero or moreresultNotificationmesages
are sent to the application, depending on parameters provided in the initial SendPushMessage
request.Figure 33-1 Sequence Diagram of WAP Push Extended Web Services
The following data structures are used in the WAP Push Extended Web Service.
Defines the response that Services Gatekeeper returns from a sendPushMessage operation.
Table 33-1 PushResponse Structure
Element Name | Element type | Optional | Description |
---|---|---|---|
result |
push_message_xsd:ResponseResult |
No |
The ResponseResult allows the server to specify a code for the outcome of sending the push message. See "ResponseResult structure" |
pushId |
xsd:string |
No |
The push ID provided in the request. |
senderAddress |
xsd:string |
Yes |
Contains the address to which the message was originally sent, for example the URL to the network node. |
senderName |
xsd:string |
Yes |
The descriptive name of the server. |
replyTime |
xsd:dateTime |
Yes |
The date and time associated with the creation of the response. |
additionalProperties |
ews_common_xsd:AdditionalProperty |
Yes |
Additional properties.The supported properties are: pap.stage, pap.note, pap.time |
Defines the result element in the PushResponse structure, which is used in the response returned from a sendPushMessage operation.
Table 33-2 ResponseResult Structure
Element Name | Element type | Optional | Description |
---|---|---|---|
code |
xsd:string |
No |
A code representing the outcome when sending the push message. Generated by the network node. Possible status codes are listed in this section. |
description |
xsd:string |
No |
Textual description. |
Table 33-3 Outcome Status Codes
Status code | Description |
---|---|
1000 |
OK. |
1001 |
Accepted for processing. |
2000 |
Bad request. |
2001 |
Forbidden. |
2002 |
Address error. |
2003 |
Address not found. |
2004 |
Push ID not found. |
2005 |
Capabilities mismatch. |
2006 |
Required capabilities not supported. |
2007 |
Duplicate push ID. |
2008 |
Cancellation not possible. |
3000 |
Internal server error. |
3001 |
Not implemented. |
3002 |
Version not supported. |
3003 |
Not possible. |
3004 |
Capability matching not possible. |
3005 |
Multiple addresses not supported. |
3006 |
Transformation failure. |
3007 |
Specified delivery method not possible. |
3008 |
Capabilities not available. |
3009 |
Required network not available. |
3010 |
Required bearer not available. |
3011 |
Replacement not supported. |
4000 |
Service failure. |
4001 |
Service unavailable. |
Defines the values for the replacePushId parameter in the sendPushMessage operation. This parameter is used to replace an existing message based on a given push ID. This parameter is ignored if it is set to NULL.
Table 33-4 ReplaceMethod Enumeration
Enumeration value | Description |
---|---|
all |
Indicates that this push message must be treated as a new push submission for all recipients, whether or not a previously submitted push message with pushId equal to the replacePushId in this push message can be found. |
pending-only |
Indicates that this push message should be treated as a new push submission only for those recipients who have a pending push message that is possible to cancel. In this case, if no push message with pushId equal to the replacePushId in this push message can be found, the server responds with status code PUSH_ID_NOT_FOUND in the responseResult. Status code CANCELLATION_NOT_POSSIBLE may be returned in the responseResult if no message can be cancelled. Status code CANCELLATION_NOT_POSSIBLE may also be returned in a subsequent resultNotification to indicate a non-cancellable message for an individual recipient. |
Defines the values for the messageState parameter in a resultMessageNotification.
Table 33-5 MessageState Enumeration
Enumeration value | Description |
---|---|
rejected |
Message was not accepted by the network. |
pending |
Message is being processed. |
delivered |
Message successfully delivered to the network. |
undeliverable |
The message could not be delivered. |
expired |
The message reached the maximum allowed age or could not be delivered by the time specified when the message was sent. Some network elements allows for defining policies on maximum age of messages. |
aborted |
The end-user terminal aborted the message. |
timeout |
The delivery process timed out. |
cancelled |
The message was cancelled. |
unknown |
The state of the message is unknown. |
The following describes the interfaces and operations that are available in the WAP Push Extended Web Service.
Operations to send, or to manipulate previously sent, WAP Push messages.
Sends a WAP Push message. The message Content Entity (the payload) is provided as a SOAP attachment in MIME format. The Content Entity is a MIME body part containing the content to be sent to the wireless device. The content type is not defined, and can be any type as long as it can be described by MIME. The Content Entity is included only in the push submission and is not included in any other operation request or response.
Input message: sendPushMessage
Table 33-6 Input Message: sendPushMessage
Part name | Part type | Optional | Description |
---|---|---|---|
pushId |
xsd:string |
N |
Provided by the application. Serves as a message ID. The application is responsible for its uniqueness, for example, by using an address within its control (for example a URL) combined with an identifier for the push message as the value for pushId. Supported types are PLMN and USER. For example: "www.wapforum.org/123" or "123@wapforum.org" |
destinationAddresses |
xsd:string [1..unbounded] |
N |
An array of end-user terminal addresses. The addresses should be formatted according to the Push Proxy Gateway Service Specification (WAP-249-PPGService-20010713-a). Example addresses:
|
resultNotificationEndpoint |
xsd:anyURI |
Y |
Specifies the URL the application uses to return result notifications. The presence of this parameter indicates that a notification is requested. If the application does not want a notification, this parameter must be set to NULL. |
replacePushId |
xsd:string |
Y |
The pushId of the still pending message to replace. The presence of this parameter indicates that the client is requesting that this message replace one previously submitted, but still pending push message. The following rules apply:
|
replaceMethod |
push_message_xsd:ReplaceMethod |
N |
Defines how to replace a previously sent message. Used in conjunction with the replacePushId parameter described above. Ignored if replacePushId is NULL. |
deliverBeforeTimestamp |
xsd:dateTime |
Y |
Defines the date and time by which the content must be delivered to the end-user terminal. The message is not delivered to the end-user terminal after this time and date. If the network node does not support this parameter, the message is rejected. |
deliverAfterTimestamp |
xsd:dateTime |
Y |
Specifies the date and time after which the content should be delivered to the wireless device. The message is delivered to the end-user terminal after this time and date. If the network node does not support this parameter, the message is be rejected. |
sourceReference |
xsd:string |
Y |
A textual name of the content provider. |
progressNotesRequested |
xsd:boolean |
Y |
This parameter informs the network node if the client wants to receive progress notes. TRUE means that progress notes are requested. Progress notes are delivered using the PushMessageNotification interface. If not set, progress notes are not sent. |
serviceCode |
xsd:string |
N |
Used for charging purposes. |
requesterID |
xsd:string |
N |
The application ID as given by the operator. |
additionalProperties |
ews_common_xsd:AdditionalProperty [0...unbounded] |
Y |
Additional properties, defined as name/value pairs, can be sent using this parameter. The supported properties are: pap.priority, pap.delivery-method, pap.network, pap.network-required, pap.bearer, pap.bearer-required. |
Output message: sendPushMessageResponse
Table 33-7 Output Message: sendPushMessageResponse
Part name | Part type | Optional | Description |
---|---|---|---|
result |
push_message_xsd:PushResponse |
N |
The response that Services Gatekeeper returns for sendPushMessage operation |
Referenced faults
Table 33-8 Exceptions and Error Codes
Exception | Error code | Reason/Action |
---|---|---|
SVC0001 |
WNG-000001 |
Internal problem in Services Gatekeeper. Contact your Services Gatekeeper administrator. |
SVC0001 |
WNG-000002 |
Internal problem in Services Gatekeeper. Contact Services Gatekeeper administrator. |
SVC0001 |
PUSHMSG-000002 |
Failed to create push message. |
SVC0001 |
PUSHMSG-000003 |
Unable to retrieve configuration. |
SVC0001 |
PUSHMSG-000001 |
Failed to submit push message to PPG. |
SVC0001 |
PLG-000004 |
General plug-in routing error |
Operations resultNotificationMessage and resultNotificationMessageResponse.
Input message: resultNotificationMessage
Table 33-9 Input Message: resultNotificationMessage
Part name | Part type | Optional | Description |
---|---|---|---|
pushId |
xsd:string |
N |
Defined by the application in the corresponding sendPushMessage operation. Used to match the notification to the message. |
address |
xsd:string |
N |
The address of the end-user terminal. |
messageState |
push_message_xsd:MessageState |
N |
State of the message. |
code |
xsd:string |
N |
Final status of the message. |
description |
xsd:string |
Y |
Textual description of the notification. Supplied by the network. May or may not be present, depending on the network node used. |
senderAddress |
xsd:string |
Y |
Address of the network node. May or may not be present, depending on the network node used. |
senderName |
xsd:string |
Y |
Name of the network node. May or may not be present, depending on the network node used. |
receivedTime |
xsd:dateTime |
Y |
Time and date when the message was received at the network node. |
eventTime |
xsd:dateTime |
Y |
Time and date when the message reached the end-user terminal. |
additionalProperties |
ews_common_xsd:AdditionalProperty |
Y |
Additional properties can be sent using this parameter in the form of name/value pairs. The supported properties are:
Which properties are sent, if any, is dependent on the network node. |
Output message: resultNotificationMessageResponse
Table 33-10 Output Message: resultNotificationMessageResponse
Part name | Part type | Optional | Description |
---|---|---|---|
N/A |
N/A |
N/A |
N/A |
Referenced faults
The document/literal WSDL representation of the PushMessage interface can be retrieved from the Web services endpoint.
The document/literal WSDL representation of the PushMessageNotification interface can be downloaded from
http://
host:
port/ews/push_message/wsdls/ews_common_types.xsd
http://
host:
port/ews/push_message/wsdls/ews_push_message_notification_interface.wsdl
http://
host:
port/ews/push_message/wsdls/ews_push_message_notification_service.wsdl
http://
host:
port/ews/push_message/wsdls/ews_push_message_types.xsd
Where host and port are the host name and port of the system on which Services Gatekeeper is installed.
Example 33-1 Example Send WAP Push Message
// Add handlers for MIME types needed for WAP MIME-types MailcapCommandMap mc = (MailcapCommandMap) CommandMap.getDefaultCommandMap(); mc.addMailcap("text/vnd.wap.si;;x-java-content-handler=com.sun.mail.handlers.text_xml"); CommandMap.setDefaultCommandMap(mc); // Create a MIME-message where with the actual content of the WAP Push message. InternetHeaders headers = new InternetHeaders(); headers.addHeader("Content-type", "text/plain; charset=UTF-8"); headers.addHeader("Content-Id", "mytext"); byte[] bytes = "Test message".getBytes(); MimeBodyPart mimeMessage = new MimeBodyPart(headers, bytes); // Create PushMessage with only the manadatory parameters // SendPushMessage is provided in the stubs generated from the WSDL. SendPushMessage sendPushMessage = new SendPushMessage(); String [] destinationAddresses = {"wappush=461/type=user@ppg.o.se"}; sendPushMessage.setDestinationAddresses(destinationAddresses); // Create ”unique” pushId, using a combination of timestamp and domain. sendPushMessage.setPushId(System.currentTimeMillis() + "@wlng.bea.com"); // ReplaceMethod is provided by the stubs generated from the WSDL. sendPushMessage.setReplaceMethod(ReplaceMethod.pendingOnly); // Defined by the operator/service provider contractual agreement sendPushMessage.setServiceCode(”Service Code xxx”); // Defined by the operator/service provider contractual agreement sendPushMessage.setRequesterID(”Requester ID xxx”); // Endpoint to send notifications to. Implemented on the application side. String notificationEndpoint = "http://localhost:80/services/PushMessageNotification"; sendPushMessage.setResultNotificationEndpoint(new URI(notificationEndpoint)); // Send the WAP Push message PushMessageService pushMessageService = null; // Define the endpoint of the WAP Push Web service String endpoint = "http://localhost:8001/ews/push_message/PushMessage?WSDL"; try { // Instantiate an representation of the Web service from the generated stubs. pushMessageService = new PushMessageService_Impl(endpoint); } catch (ServiceException e) { e.printStackTrace(); throw e; } PushMessage pushMessage = null; try { // Get the Web service interface to operate on. pushMessage = pushMessageService.getPushMessage(); } catch (ServiceException e) { e.printStackTrace(); throw e; } SendPushMessageResponse sendPushMessageResponse = null; try { // Send the WAP Push message. sendPushMessageResponse = pushMessage.sendPushMessage(sendPushMessage); } catch (RemoteException e) { e.printStackTrace(); throw e; } catch (PolicyException e) { e.printStackTrace(); throw e; } catch (com.bea.wlcp.wlng.schema.ews.common.ServiceException e) { e.printStackTrace(); throw e; } // Assign the pushId provided in the in the response to a local variable. String pushId = sendPushMessageResponse.getPushId();