Application Development Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Extended Web Services WAP Push

The Extended Web Services WAP Push Web Service allows for the sending of 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:

See http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html for links to the specifications.

The payload is sent as a SOAP attachment.

 

Namespaces

The PushMessage interface and service use the namespaces:

The PushMessageNotification interface and service use the namespaces:

The data types are defined in the namespace:

In addition, Extended Web Services WAP Push uses definitions common for all Extended Web Services interfaces:

 

Endpoint

The endpoint for the PushMessage interface is: http://<host:port>/ews/push_message/PushMessage

Where host and port depend on the Oracle Communications Services Gatekeeper deployment.

 

Sequence Diagram

The following diagram shows the general message sequence for sending a WAP Push message from an Extended Web Services WAP Push application 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 Oracle Communications 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 more resultNotificationmesages are sent to the application, depending on parameters provided in the initial SendPushMessage request.
Figure 6-1 Sequence diagram Extended Web Services WAP Push

Sequence diagram Extended Web Services WAP Push

 

XML Schema data type definition

The following data structures are used in the Extended Web Services WAP Push Web Service.

PushResponse structure

Defines the response that the Oracle Communications Services Gatekeeper returns from a sendPushMessage operation.

Element Name
Element type
Optional
Description
result
push_message_xsd:ResponseResult
N
The ResponseResult allows the server to specify a code for the outcome of sending the push message. See ResponseResult structure
pushId
xsd:string
N
The push ID provided in the request.
senderAddress
xsd:string
Y
Contains the address to which the message was originally sent, for example the URL to the network node.
senderName
xsd:string
Y
The descriptive name of the server.
replyTime
xsd:dateTime
Y
The date and time associated with the creation of the response.
additionalProperties
ews_common_xsd:AdditionalProperty
Y
Additional properties.The supported properties are: pap.stage, pap.note, pap.time

ResponseResult structure

Defines the result element in the PushResponse structure, which is used in the response returned from a sendPushMessage operation.

Element Name
Element type
Optional
Description
code
xsd:string
N
A code representing the outcome when sending the push message. Generated by the network node.
Possible status codes are listed in Table 6-1.
description
xsd:string
N
Textual description.

Table 6-1 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.

ReplaceMethod enumeration

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.

Enumeration value
Description
all
Indicates that this push message MUST be treated as a new push submission for all recipients, no matter if a previously submitted push message with pushId equal to the replacePushId in this push message can be found or not.
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.

MessageState enumeration

Defines the values for the messageState parameter in a resultMessageNotification.

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.

Note: 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.

 

Web Service interface description

The following describes the interfaces and operations that are available in the Extended Web Services WAP Push Web Service.

Interface: PushMessage

Operations to send, or to manipulate previously sent, WAP Push messages.

Operation: sendPushMessage

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

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:
  • WAPPUSH=+155519990730
    TYPE=PLMN@ppg.carrier.com
  • WAPPUSH=john.doe%40wapforum.org
    TYPE=USER@ppg.carrier.com
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:
  • Setting the replacePushId parameter to NULL indicates that it is a new message. It does not replace any previously submitted message.
  • The initial pending (pending delivery to the end-user terminal) message is cancelled, if possible, for all recipients of the message. This means that it is possible to replace a message for only a subset of the recipients of the original message.
  • Message replacement will occur only for the recipients for whom the pending message can be cancelled.
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 via 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

Part name
Part type
Optional
Description
result
push_message_xsd:PushResponse
N
The response that Oracle Communications Services Gatekeeper returns for sendPushMessage operation

Referenced faults

Table 6-2 exceptions and error codes
Exception
Error code
Reason/Action
SVC0001
WNG-000001
Internal problem in Oracle Communications Services Gatekeeper.
Contact Oracle Communications Services Gatekeeper administrator.
SVC0001
WNG-000002
Internal problem in Oracle Communications Services Gatekeeper.
Contact Oracle Communications 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

Interface: PushMessageNotification

Operation: resultNotificationMessage

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:
  • pap.priority
  • pap.delivery-method
  • pap.network
  • pap.network-required
  • pap.bearer
  • pap.bearer-required
Which properties are sent, if any, is dependent on the network node.

Output message: resultNotificationMessageResponse

Part name
Part type
Optional
Description
none
     

Referenced faults

Table 6-3 exceptions and error codes
Exception
Error code
Reason/Action
SVC0001
PUSHMSG-000004
Failed to send result notification to the application.

 

WSDLs

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 depending on the Oracle Communications Services Gatekeeper deployment.

 

Sample Send WAP Push Message

Listing 6-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();

  Back to Top       Previous  Next