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

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

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:

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, Extended Web Services WAP Push 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"

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 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 5-1 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 Services Gatekeeper returns from a sendPushMessage operation.

Table 5-1 PushResponse structure

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.

Table 5-2 ResponseResult structure

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 this section.
description	xsd:string	N	Textual description.

Element Name

Element type

Optional

Description

code

xsd:string

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

Textual description.

Table 5-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.

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.

Table 5-4 ReplaceMethod enumeration

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.

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.

Table 5-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.

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

Table 5-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: 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

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

Interface: PushMessageNotification

Operations resultNotificationMessage and resultNotificationMessageResponse.

Operation: resultNotificationMessage

Input message: resultNotificationMessage

Table 5-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: 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

Table 5-10 Output message: resultNotificationMessageResponse

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

Referenced faults

Table 5-11 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 Services Gatekeeper deployment.

Sample Send WAP Push Message

Example 5-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();