oracle.panama.messaging.push
Class PushLite

java.lang.Object
oracle.panama.messaging.push.PushClientBase
oracle.panama.messaging.push.PushLite

public class PushLite

extends PushClientBase

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
It requires:
PushException class in the same package
No other classes in the same package are needed.
No special serializers are needed.

Sending messages to a HTTPS PushServer
PushAPI supports both Oracle SSL and SUN's JSSE. No code change is needed. The classpath is different in these two cases however.
Use Oracle SSL: Oracle SSL uses native code to get high performance.
1. Make sure jssl-1_2.jar and javax-ssl-1_2.jar are inside classpath and NONE of JSSE jars is in classpath.
2a. On Windows system, make sure njssl9.dll is in path.
2b. On Solaris system, make sure libnjssl9.so is in library path.

Use SUN's JSSE
JSSE is a pure Java implementation of SSL, which could be downloaded from SUN. (Not included in this release.)
Add jsse.jar, jcert.jar and jnet.jar into classpath. Make sure jssl-1_2.jar and javax-ssl-1_2.jar are NOT in classpath.

Following example sends out message to 2 recipients:
1. Mike of Oracle via SMS, Voice or Email. If fails, send a SMS or Voice message to phone number 1-650-5551234
2. Email good-guy@company.com, if fails, send SMS or Voice msg to alice of brandA. If still fails, send bob of brandB a voice message.

   String to[] = new String[2];
   to[0] = "SMS:oracle-mike,Voice:oracle-mike,Email:oracle-mike;SMS:1-650-5551234,Voice:1-650-5551234";
   // Has the second recipient?
   to[1] = new String("Email:good-guy@company.com;SMS:brandA~alice,Voice:BrandA~alice;Voice:brandB~bob");

   String senders[] = new String[1];
   senders[0] = "brandC~jerry.lee";

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

   PushLite ml = new PushLite(gatewayURL,"user","password");
   // proxy server to reach internet (optional)
   ml.setProxy("proxy.company.com",80);

   // get supported delivery types by the gateway
   String supportedTransports[] = ml.getSupportedTransports();
   if(supportedTransports != null)
   {
        System.out.println("**** Supported transports ****");
        for(int i=0;i<supportedTransports.length;i++)
        System.out.println(supportedTransports[i]);

   }
   else
        System.out.println("can't get supported transports");


   String wo[] = null;

   try
   {
     wo = ml.sendMsg( senders, null, to, associatedKeys, "message subject",
                   "hello world! (msg body)" ,"text/plain");
   }
   catch(PushException e)
   {
     e.printStackTrace();
   }

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

     if(wo.length > 0)
     {
                  String status = ml.getStatus(wo[0]);
                    if(status != null)
                {
                System.out.println("[" + status + "]");
                }
     }
     else
     {
        System.out.println("no msg id returned");
     }

   }
   else
   {
        System.out.println("Send failed. No work order returned");
   }
  

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

java.lang.String	getStatus(java.lang.String messageID) Deprecated. Use XMSSimpleSender#getStatus instead
java.lang.String[]	getStatus(java.lang.String[] messageIDs) Deprecated. Use XMSSimpleSender#getStatus instead
java.lang.String[]	send(java.lang.String[] senders, java.lang.String[] recipients, java.lang.String message) Deprecated. Please use sendMsg()
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 contentType) Deprecated. Please use sendMsg() instead
java.lang.String[]	sendMsg(java.lang.String[] senders, java.lang.String[] recipients, java.lang.String message) This method is based on send() with supports of failover capability and username capability.
java.lang.String[]	sendMsg(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 contentType) Deprecated. Use XMSSimpleSender#sendMsg instead

Methods inherited from class oracle.panama.messaging.push.PushClientBase

getServerVersion, getSupportedTransports, getVersion, removeStatusListener, setProxy, setProxy, setStatusListener, setStatusListener

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://messenger.oracle.com/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

getStatus

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

Deprecated. Use XMSSimpleSender#getStatus instead

Get current status of one message ID If failover addresses have been defined for a recipient, this method returns the most up-to-date status of that recipient.
For example: a recipient has failover addresses in following order: 1-222-333333 (SMS), 1-333-444444 (Fax), 1-444-5551234 (voice) and foo@bar.com (Email). Suppose first two attempts fail and msg gets delivered to 3rd address. Status may be like this:
"1, Message has been delivered successfully., Email,foo@bar.com"

Returns:

a status string in following format:
status-ID, status-description [, transport-type, address]
status <0: failed to deliver the message
status =0: pending
status >0: sent to message center of device.
status-description: Text description of status
transport-type: transport type used to in the attempt
address: address used in the attempt
For example: "1, Message has been delivered successfully., Email, foo@bar.com"

Throws:

PushException

getStatus

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

Deprecated. Use XMSSimpleSender#getStatus instead

Get current status of a set of message IDs. If failover addresses have been defined for a recipient, this method returns the most up-to-date status of that recipient.
For example: a recipient has failover addresses in following order: 1-222-333333 (SMS), 1-333-444444 (Fax), 1-444-5551234 (voice) and foo@bar.com (Email). Suppose first two attempts fail and msg gets delivered to 3rd address. Status may be like this:
"1, Message has been delivered successfully., Email,foo@bar.com"

Returns:

a status string array. Each line is in following format:
status-ID, status-description [, transport-type, address]
status <0: failed to deliver the message
status =0: pending
status >0: sent to message center of device.
status-description: Text description of status
transport-type: transport type used to in the attempt
address: address used in the attempt
For example: "1, Message has been delivered successfully., Email, foo@bar.com"

Throws:

PushException

send

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

Deprecated. Please use sendMsg()

Send out a text message to multiple physical addresses. Message's content type 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 (MIME type) and associated keys parameters. This method doesn't support failover or user. sendMsg() supports those features.

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:1-650-5551234" 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, SMS: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,Email: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.

Throws:

PushException

See Also:

Note: The formats of address in send() are quite different from address formats in sendMsg(), because sendMsg() supports failover and user features.


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 contentType)
                        throws PushException

Deprecated. Please use sendMsg() instead

Send out a text message to multiple physical addresses. This method doesn't support failover or user. sendMsg() supports those features.

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:1-650-5551234" [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,SMS: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,Email:mary@company.com"
"SMS:1-123-45678"
"Email:bob@company.com"
Note: The formats of address in send() are quite different from address formats in sendMsg(), because sendMsg() supports failover and user features.

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

contentType - 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.

Throws:

PushException

See Also:

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

sendMsg

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

This method is based on send() with supports of failover capability and username capability.
User name capability means that the sender can specify a username (instead of physical address of a recipient) and preferred delivery types to send out a message. Sender and reply to addresses can be existing users too.
For example: send an email to user 'michael' from user 'richard'. That user name must be registered and the specified device must be available in that user's profile.
Failover means that each recipient may have an "address chain". Each node of the chain has one transport type, followed by 1 address. The same address (i.e a user name, an email address, a phone number or a WAP push subscriber ID) can be used for different transport type/s. PushServer will try every transport type and address combination of that node, from the head of the chain until (1) message has been delivered to an address by a transport type of that address or (2) all addresses and their transport types have been tried.
If a physical address (i.e. phone number, email address or WAP push subscriber ID) is given, it will be used directly. If a username is given, PushServer will find physical addresses from user's profile.
Device failover example: Send a message to Michael's cell phone # 1-234-1234567 via SMS or voice, if all fail, send a voice message to his work number 1-222-3456789. If fails, send an email to his manager's email address paul@company.com
User failover example: contact Michael via SMS, Voice or email. If can't get him, Send a voice or email message to his manager, Paul.
Same address failover:
Failover could happen within same user or same physical device from a transport types (delivery types) to another different transport type in the transport type order specified.
For example: send a SMS to phone number 1-234-5551234, if failed, try voice.
It could happen to a user too. For example: send a voice msg to Sam's work phone, if failed, try his cell phone and pager.
Failover to another address:
If all transport types (delivery types) of an address have been tried and failed and another address is specified as its failover address, the second address is used in further attempts.
A user may fail to another user or a physical address. A physical address may fail to anther physical address or a user.
The maximum number of failover devices is limited to 4. A failover device means a physical address (user name will be converted to physical address by the server) and a transport type combination. If more failover address or transport types have been specified than maximum failover devices, only the first maximum devices are considered. Rest will not be used.

Parameters:

senders - an array of senders' addresses. A sender's address has an address, transport type(s), and they are separated by colon sign(:). <sender's address>[:transports] [transport] is a type string defined in oracle.panama.messaging.common.TransportType One sender per transport type. Latest sender of the same transport type will override earlier senders with same transport type in the array.
If there is no transport types for a user address (i.e. brand~user), the default devices defined in user will be used. Example 1: Use myemail@company.com as sender's from email address: "Email:myemail@company.com" Example 2: Use 1-650-5551234 as from address for SMS and voice: "SMS:1-650-5551234,Voice:1-650-5551234" Example 3: Use default devices in user Larry's profile as sender's from addresses. Suppose he is in 'oracle' brand: "oracle~larry"

recipients - recipients' addresses (i.e. email address, phone number or user name) Format of address:
<tranport type >:<:address string >+ [;<transport type >:<address string >+]*
<address string> = <email address>|<phone number> |< subscriber ID > |< user address > <user address> = < brand name > ~ < user name > <phone number> = < country code > - < area code > - < local phone number >
One line per recipient. A recipient may have multiple failover addresses and each address must have at least one transport type. Use colon(:) to separate transport types and address. Use comma(,) to separate transport types within the same address. Use semicolon to separate addresses.
Example 1: SMS:1-650-5551234,Voice:1-650-5551234;Fax:1-408-3456789
Example 2: Email:myemail@foo.com;Voice:oracle/mary,Email:oracle/mary,Fax:oracle/mary;Email:oracle/bob [transport] is a type defined in oracle.panama.messaging.common.TransportType
Note: The formats of address in send() are quite different from address formats in sendMsg(), because sendMsg() supports failover and user features.

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.

Throws:

PushException

See Also:

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

sendMsg

public java.lang.String[] sendMsg(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 contentType)
                           throws PushException

Deprecated. Use XMSSimpleSender#sendMsg instead

This method is based on send() with supports of failover capability and username capability.
User name capability means that the sender can specify a username (instead of physical address of a recipient) and preferred delivery types to send out a message. Sender and reply to addresses can be existing users too.
For example: send an email to user 'michael' from user 'richard'. That user name must be registered and the specified device must be available in that user's profile.
Failover means that each recipient may have an "address chain". Each node of the chain has one address (i.e. a user name, an email address, a phone number or a WAP push subscriber ID) and a list of preferred transport types of that address. PushServer will try every address and every transport type of that address from the head of the chain until (1) message has been delivered to an address by a transport type of that address or (2) all addresses and their transport types have been tried.
If a physical address (i.e. phone number, email address or WAP push subscriber ID) is given, it will be used directly. If a username is given, PushServer will find physical addresses from user's profile.
Device failover example: Send a message to Michael's cell phone # 1-234-1234567 via SMS or voice, if all fail, send a voice message to his work number 1-222-3456789. If fails, send an email to his manager's email address paul@company.com
User failover example: contact Michael via SMS, Voice or email. If can't get him, Send a voice or email message to his manager, Paul.
Same address failover:
Failover could happen within same user or same physical device from a transport types (delivery types) to another different transport type in the transport type order specified.
For example: send a SMS to phone number 1-234-5551234, if failed, try voice.
It could happen to a user too. For example: send a voice msg to Sam's work phone, if failed, try his cell phone and pager.
Failover to another address:
If all transport types (delivery types) of an address have been tried and failed and another address is specified as its failover address, the second address is used in further attempts.
A user may fail to another user or a physical address. A physical address may fail to anther physical address or a user.
The maximum number of failover devices is limited to 4. A failover device means a physical address (user name will be converted to physical address by the server) and a transport type combination. If more failover address or transport types have been specified than maximum failover devices, only the first maximum devices are considered. Rest will not be used.

Parameters:

senders - an array of senders' addresses. A sender's address has an address, transport type(s), and they are separated by colon sign(:). <sender's address>[:transports] [transport] is a type string defined in oracle.panama.messaging.common.TransportType One sender per transport type. Latest sender of the same transport type will override earlier senders with same transport type in the array.
If there is no transport types for a user address (i.e. brand~user), the default devices defined in user will be used. Example 1: Use myemail@company.com as sender's from email address: "Email:myemail@company.com" Example 2: Use 1-650-5551234 as from address for SMS and voice: "SMS:1-650-5551234,Voice:1-650-5551234" Example 3: Use default devices in user Larry's profile as sender's from addresses. Suppose he is in 'oracle' brand: "oracle~larry"

replyTOs - an array of reply to addresses or phone numbers (optional). Use null if no reply to address. The format is exactly the same as senders' address described above.

recipients - recipients' addresses (i.e. email address, phone number or user name) Format of address:
<tranport type >:<:address string >+ [;<transport type >:<address string >+]*
<address string> = <email address>|<phone number> |< subscriber ID > |< user address > <user address> = < brand name > ~ < user name > <phone number> = < country code > - < area code > - < local phone number >
One line per recipient. A recipient may have multiple failover addresses and each address must have at least one transport type. Use colon(:) to separate transport types and address. Use comma(,) to separate transport types within the same address. Use semicolon to separate addresses.
Example 1: SMS:1-650-5551234,Voice:1-650-5551234;Fax:1-408-3456789
Example 2: Email:myemail@foo.com;Voice:oracle/mary,Email:oracle/mary,Fax:oracle/mary;Email:oracle/bob [transport] is a type defined in oracle.panama.messaging.common.TransportType
Note: The formats of address in send() are quite different from address formats in sendMsg(), because sendMsg() supports failover and user features.

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

contentType - 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.

Throws:

PushException

See Also:

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