# Application Development Guide

# 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 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

## 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();