oracle.panama.messaging.push
Class PushLite

java.lang.Object
  |
  +--oracle.panama.messaging.push.PushLite

public class PushLite

extends java.lang.Object

Light weight push messaging client, which sends out messages and queries status of delivery to recipients.
Push Server may be configured in two ways:
1. Public Push gateway: Push gateway provides messaging services to Internet/intranet users. The communication between Push client and Push gateway is powered by SOAP technology. Push client must have the URL of Push gateway. It must provide a valid username/password combination to get services, if the gateway asks so.
For example: PushLite myPushClient = new PushLite("http://messenger.oracle.com/push/webservices", "user","passwd");
2. Private Local Push Server: Push client and Push server are running on the same machine. Push client calls Push server class through java methods call directly without using SOAP or RPC. No SOAP gateway or authentication is needed for local installation. Push Server provides services to that Push client only. When constructing Push client for local Push server, pass 'null' as Push gateway URL in the constructor. Access to Push Server is granted to local Push client automatically. It's a good idea to provide a user name for logging and reporting purpose, though it's not required.
For example: PushLite myPushClient = new PushLite(null, "user",null);
Only classes/types defined in JDK have been used. No self-defined Java types. Push.java provides richer functionalities than PushLite.
It only supports
text messaging, no binary data is allowed
all email recipients are sent as "To" mode. "CC" and "Bcc" are not supported.
Multipart message is NOT supported
No failover
It requires:
PushException class in the same package
No other classes in the same package are needed.
No special serializers are needed.

Following example sends out message to 2 email recipients and 1 SMS phone.

     // 2 email and 1 SMS recipients
  String recipients[] = new String[2];
  recipients[0] = new String(TransportType.EMAIL + ":" +"john@company.com,mary@company.com");
  recipients[1] = new String(TransportType.SMS + ":" +"1-333-5551234");

  // one email sender and one SMS sender
  String senders[] = new String[2];
  senders[0] = TransportType.EMAIL + ":" + "sender@company.com";
  senders[1] = TransportType.SMS + ":" + "1-222-1234567";

  String messageString = "Hello World!";   // message body

  String gatewayURL = "http://messenger.oracle.com/push/webservices";

  // create a PushLite client instance
  PushLite pushLite = null;
  try{
    pushLite = new PushLite(gatewayURL,"user name","password");
  }
  catch(PushException e)
  { e.printStackTrace();   }

  String wo[] = null;
  try
  {
    wo = pushLite.send( senders, recipients, messageString);

  }
  catch(PushException e)
  {
    System.out.println("**** PushException caught ");
    e.printStackTrace();
  }

  if(wo != null)
  {
    for(int i=0;i< wo.length;i++)
      System.out.println(wo[i]);
  }

  String status [] = null;
  try{
    pushLite.getStatus(wo);
  } catch(PushException e) { e.printStackTrace(); }

  if(status != null)
  {
    for(int i=0;i< status.length;i++)
      System.out.println("[" + status + "]");
  }
  

See Also:

Push

Constructor Summary

PushLite(java.lang.String messagingGatewayURL, java.lang.String username, java.lang.String password)
Construct a new push lite instance, which is a push client to an OracleMobile SOAP Push gateway or Push server locally.

Method Summary

Type	Method
java.lang.String	getStatus(java.lang.String messageID) Get current status of one message ID
java.lang.String[]	getStatus(java.lang.String[] messageIDs) Get current status of a set of message IDs.
java.lang.String[]	getSupportedTransports() Get names of available transports from Push server.
java.lang.String	getVersion() Get version of Push API.
java.lang.String[]	send(java.lang.String[] senders, java.lang.String[] recipients, java.lang.String message) Send out a text message.
java.lang.String[]	send(java.lang.String[] senders, java.lang.String[] replyTOs, java.lang.String[] recipients, java.lang.String[] associatedKeys, java.lang.String subject, java.lang.String message, java.lang.String encoding) Send out a message.
void	setProxy(java.lang.String host, int port) If Push client machine is inside firewall and Push Server is outside firewall, user may need to tell Push client his/her HTTP proxy settings.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PushLite

public PushLite(java.lang.String messagingGatewayURL,
                java.lang.String username,
                java.lang.String password)
         throws PushException

Construct a new push lite instance, which is a push client to an OracleMobile SOAP Push gateway or Push server locally.

Parameters:

messagingGatewayURL - Complete URL of OracleMobile Push messaging gateway(SOAP). For example: http://gateway.oraclemobile.com:9000/push/webservices
null for local installation.

username - username of OracleMobile messaging gateway(SOAP). null if no username is needed.

password - password of OracleMobile messaging gateway(SOAP). null if no password is needed.

Method Detail

setProxy

public void setProxy(java.lang.String host,
                     int port)

If Push client machine is inside firewall and Push Server is outside firewall, user may need to tell Push client his/her HTTP proxy settings.
DO NOT set proxy if:
- Push server is on Internet and Push client machine connects to internet directly
- they both on the same intranet
- local installation

Parameters:

host - host name of proxy For example: proxy.company.com

port - port number of the proxy. For example: 80

send

public java.lang.String[] send(java.lang.String[] senders,
                               java.lang.String[] recipients,
                               java.lang.String message)
                        throws PushException

Send out a text message. Encoding of the message is "text/plain". This method provides the easiest way to send out text messages. Use overloaded send() method to set subject, reply to, content type encoding (MIME type) and associated keys parameters.

Parameters:

senders - an array of senders' addresses. A sender's address has a transport type, an address and they are separated by colon sign(:). One sender per transport type. Latest sender of the same transport type will override earlier senders of same transport type in the array. Example 1: "Email:myemail@company.com" Example 2: "SMS:16505551234" transportType a type defined in oracle.panama.messaging.common.TransportType

recipients - recipients' addresses (i.e. email address or phone number) Format of recipient addresses: [transport]:[recipient address 1],[recipient address 2] ... Example: SMS:1-650-5551234,1-408-3456789 transportType a type defined in oracle.panama.messaging.common.TransportType
Recipeints of the same transport may be separated into multiple lines, But, these lines may not be separated by recipients of other transport type lines. An exception will be thrown out if it has been detected.
Example 1 -- OK:
"Email:john@company.com,mary@company.com"
"Email:bob@company.com"
"SMS:1-123-45678"
Example 2 -- ERROR: second email recipients line (bob@company.com) is cut off by SMS recipients
"Email:john@company.com,mary@company.com"
"SMS:1-123-45678"
"Email:bob@company.com"

message - body of message

Returns:

a set of message IDs will be returned after Push server accepts the request. One message ID for each instance of recipient's address. The order of message IDs is the same as the order of addresses in recipient's array.

See Also:

send(String[], String[], String[], String[], String, String, String)

send

public java.lang.String[] send(java.lang.String[] senders,
                               java.lang.String[] replyTOs,
                               java.lang.String[] recipients,
                               java.lang.String[] associatedKeys,
                               java.lang.String subject,
                               java.lang.String message,
                               java.lang.String encoding)
                        throws PushException

Send out a message.

Parameters:

senders - an array of senders' addresses. A sender's address has a transport type, an address and they are separated by colon sign(:). [transport]:[sender's address] One sender per transport type. Latest sender of the same transport type will override earlier senders with same transport type in the array. Example 1: "Email:myemail@company.com" Example 2: "SMS:1-650-5551234" [transport] is a type string defined in oracle.panama.messaging.common.TransportType

replyTOs - an array of reply to addresses or phone numbers (optional). Use null if no reply to address. [transport]:[reply to address] One reply to per transport type. Latest reply to of the same transport type will override earlier reply to of same transport type in the array. Example 1: "Email:myemail@company.com" Example 2: "SMS:16505551234" [transport] is a type defined in oracle.panama.messaging.common.TransportType

recipients - recipients' addresses (i.e. email address or phone number) Format of recipient addresses: [transport]:[recipient address 1],[recipient address 2] ... Example: SMS:1-650-5551234,1-408-3456789 [transport] is a type defined in oracle.panama.messaging.common.TransportType
Recipeints of the same transport may be separated into multiple lines. But, these lines may not be separated by recipients of other transport type lines. An exception will be thrown out if it has been detected.
Example 1 -- OK:
"Email:john@company.com,mary@company.com"
"Email:bob@company.com"
"SMS:1-123-45678"
Example 2 -- ERROR: second email recipients line is cut off by SMS recipients
"Email:john@company.com,mary@company.com"
"SMS:1-123-45678"
"Email:bob@company.com"

associatedKeys - an array of text strings may be used by client application to do message tracking. one key per recipient. The length of the each key could be up to 64 bytes. The orders of the keys are the same as the orders of recipients. This field is optional, if no associated key is used, use null.

subject - subject of message (optional)

message - body of message

encoding - MIME type with optional charset encoding of message. For example: "text/plain", "text/plain; charset=us-ascii" and "text/html"

Returns:

a set of message IDs will be returned after Push server accepts the request. One message ID for each instance of recipient's address. The order of message IDs is the same as the order of addresses in recipient's array.

See Also:

send(String[] , String[] , String )

getSupportedTransports

public java.lang.String[] getSupportedTransports()
                                          throws PushException

Get names of available transports from Push server. Use this method to get what kinds of transports the Push server supports. For example: if the return values are: "SMS","email". You may only send SMS and email messages through this gateway.

getStatus

public java.lang.String getStatus(java.lang.String messageID)
                           throws PushException

Get current status of one message ID

Returns:

a status string like this: "Message has been delivered successfully."

getStatus

public java.lang.String[] getStatus(java.lang.String[] messageIDs)
                             throws PushException

Get current status of a set of message IDs.

getVersion

public java.lang.String getVersion()

Get version of Push API.