cl::yx::YX_Session Class Reference

List of all members.

Public Member Functions

 YX_Session (String username, String password, YX_Connector c) throws YX_IOException
void finalize ()
synchronized boolean sendMsg (String message, String to) throws YX_IOException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Tries to deliver a message and does not consider a timeout. However If more than A_LOT(*) seconds have passed and the message is still undelivered, the message delivery will be aborted and the method will return false. An YX_IOException may occur also, if there are connectivity problems. (*) A_LOT is specified inside the API ( = 5 minutes ).
synchronized boolean sendMsg (String message, String to, int timeout) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Tries to deliver a message before the timeout (in seconds) If more than timeout seconds have passed and the message is still undelivered, a YX_TimeoutException will occur. An YX_IOException may occurr also, if there are connectivity problems.
synchronized boolean sendMsg (String message, String to, int timeout, YX_Notifier n) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Tries to deliver a message before the timeout (in seconds) If more than timeout seconds have passed and the message is still undelivered, a YX_TimeoutException will occur. An YX_IOException may occurr also, if there are connectivity problems. Will report to the notifier a string indicating the state.
synchronized YX_Ticket queueMsg (String message, String to, int timeout) throws YX_TimeoutException, YX_IOException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Send message to lyric. It will be delivered sometime in the future. It will return a ticket which can be used to request information about it later using the requestStatus() method. You can also use the registerNotifier() method, to be informed when the ticket changes.
YX_NotificationServer initNotificationServer (int port) throws YX_IOException
 Tries to start a notification server and will link it to this YX_Session object. Use the YX_NotificationServer object to test for connectivity problems. Use a port > 1024 if you do not have administrative permissions on the machine, and be sure to enable inbound connections for that port in the firewall, if you are using one.
boolean registerNotificationServer (int port) throws YX_NotificationServerNotInitializedException
 internal method. Will try to send NotificationServer information so that server can send reports back here.
String requestStatus (YX_Ticket ticket) throws YX_NotificationServerNotInitializedException
 Request information on a ticket previously returned by queueMsg(). Call this method only if you have called initNotificationServer().
String requestStatus (YX_Ticket ticket, int timeout) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Request information on a ticket previously returned by queueMsg(). If more than timeout seconds have passed, and the device has not answered yet, a YX_TimeoutException will occur.
YX_SMS_Status requestCompleteStatus (YX_Ticket ticket, int timeout) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException
 Request information on a ticket previously returned by queueMsg(). If more than timeout seconds have passed, and the device has not answered yet, a YX_TimeoutException will occur.
boolean registerNotifier (YX_Ticket ticket, YX_Notifier n) throws YX_NotificationServerNotInitializedException
 Register a YX_Notifier object, so that when the ticket changes, the notifier's notify() method will be called. Be sure to call the initNotificationServer() method before and that its return is not null.
String getVersion ()
 Current API Version in a String.

Static Public Member Functions

static synchronized int get_count ()
static synchronized int advance_count ()

Protected Attributes

YX_Logger logger = null

Package Attributes

Map< String, String > error_cases = null
YX_NotificationServer notification_server

Detailed Description

Use one the sendMsg or queueMsg methods to deliver a message. If there are connectivity problems a YX_IOException will be thrown. If that happends, do not use the same YX_Session object anymore. Try creating another YX_Session object instead.

Remember that when using queueMsg, you should use the initNotificationServer() method first. This method will open the specified IP port. The Lyric device will try to contact the API through this port. The notification process will fail if this service is not available for the Lyric to use.

If you have a firewall blocking inbound connections, you may need to specify an exception for the specified IP port.

Member Function Documentation

String cl::yx::YX_Session::getVersion (  )  [inline]

Current API Version in a String.

Returns:
A String indicating the current API version. It may be useful in case you need support.
YX_NotificationServer cl::yx::YX_Session::initNotificationServer ( int  port  )  throws YX_IOException [inline]

Tries to start a notification server and will link it to this YX_Session object. Use the YX_NotificationServer object to test for connectivity problems. Use a port > 1024 if you do not have administrative permissions on the machine, and be sure to enable inbound connections for that port in the firewall, if you are using one.

In v0.2. it always returns null

Returns:
YX_NotificationServer object
null if problems happen. You will not be able to use registerNotifier() nor requestStatus() methods successfully.
Exceptions:
YX_IOException if problems starting the service (e.g. could not open the port)
synchronized YX_Ticket cl::yx::YX_Session::queueMsg ( String  message,
String  to,
int  timeout 
) throws YX_TimeoutException, YX_IOException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Send message to lyric. It will be delivered sometime in the future. It will return a ticket which can be used to request information about it later using the requestStatus() method. You can also use the registerNotifier() method, to be informed when the ticket changes.

Parameters:
message 
to Phone number to send the SMS to
timeout (measured in seconds)
Returns:
Ticket to be used later with requestStatus() to get information
Exceptions:
YX_IOException 
YX_TimeoutException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
boolean cl::yx::YX_Session::registerNotificationServer ( int  port  )  throws YX_NotificationServerNotInitializedException [inline]

internal method. Will try to send NotificationServer information so that server can send reports back here.

Parameters:
port 
Returns:
true Lyric got informed and report back an ok msg
false Something failed
Exceptions:
YX_NotificationServerNotInitializedException When initNotificationServer() has not been called successfully before
boolean cl::yx::YX_Session::registerNotifier ( YX_Ticket  ticket,
YX_Notifier  n 
) throws YX_NotificationServerNotInitializedException [inline]

Register a YX_Notifier object, so that when the ticket changes, the notifier's notify() method will be called. Be sure to call the initNotificationServer() method before and that its return is not null.

In v0.2. it always returns false

Returns:
true, if notifier was successfully registered
false, if a ṕroblem prevented the notifier registration (did you call the initNotificationServer() method before?)
Exceptions:
YX_NotificationServerNotInitializedException When initNotificationServer() has not been called successfully before
YX_SMS_Status cl::yx::YX_Session::requestCompleteStatus ( YX_Ticket  ticket,
int  timeout 
) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Request information on a ticket previously returned by queueMsg(). If more than timeout seconds have passed, and the device has not answered yet, a YX_TimeoutException will occur.

Parameters:
ticket YX_Ticket used for the query
timeout (measured in seconds)
Returns:
A YX_SMS_Status object which contains the ticket status and YX_Date.

The state could be one of these { "queued", "trying", "done", "unknown", "expired", "notification_server_error", "failed" }

Exceptions:
YX_IOException 
YX_TimeoutException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
String cl::yx::YX_Session::requestStatus ( YX_Ticket  ticket,
int  timeout 
) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Request information on a ticket previously returned by queueMsg(). If more than timeout seconds have passed, and the device has not answered yet, a YX_TimeoutException will occur.

Parameters:
ticket YX_Ticket used for the query
timeout (measured in seconds)
Returns:
A string indicating the status of the ticket.

The state could be one of these { "queued", "trying", "done", "unknown", "expired", "notification_server_error", "failed" }

Exceptions:
YX_IOException 
YX_TimeoutException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
String cl::yx::YX_Session::requestStatus ( YX_Ticket  ticket  )  throws YX_NotificationServerNotInitializedException [inline]

Request information on a ticket previously returned by queueMsg(). Call this method only if you have called initNotificationServer().

Returns:
A string indicating the status of the ticket. In v0.2 it always return "expired".

The state could be one of these { "queued", "trying", "done", "unknown", "expired", "notification_server_error", "failed" }

Exceptions:
YX_NotificationServerNotInitializedException When initNotificationServer() has not been called successfully before
synchronized boolean cl::yx::YX_Session::sendMsg ( String  message,
String  to,
int  timeout,
YX_Notifier  n 
) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Tries to deliver a message before the timeout (in seconds) If more than timeout seconds have passed and the message is still undelivered, a YX_TimeoutException will occur. An YX_IOException may occurr also, if there are connectivity problems. Will report to the notifier a string indicating the state.

The state could be one of these { "start", "trying", "done", "unknown" }

Parameters:
message 
to Phone number to send the SMS to
timeout (measured in seconds)
n N will be used to deliver status information
Returns:
true, if message delivered
false, if an error occurred
Exceptions:
YX_IOException 
YX_TimeoutException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
synchronized boolean cl::yx::YX_Session::sendMsg ( String  message,
String  to,
int  timeout 
) throws YX_IOException, YX_TimeoutException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Tries to deliver a message before the timeout (in seconds) If more than timeout seconds have passed and the message is still undelivered, a YX_TimeoutException will occur. An YX_IOException may occurr also, if there are connectivity problems.

Parameters:
message 
to Phone number to send the SMS to
timeout (measured in seconds)
Returns:
true, if message delivered
false, if an error occured
Exceptions:
YX_IOException 
YX_TimeoutException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
synchronized boolean cl::yx::YX_Session::sendMsg ( String  message,
String  to 
) throws YX_IOException, YX_DataException, YX_AuthenticationException, YX_UserPrivilegeException, YX_ServerProblemException [inline]

Tries to deliver a message and does not consider a timeout. However If more than A_LOT(*) seconds have passed and the message is still undelivered, the message delivery will be aborted and the method will return false. An YX_IOException may occur also, if there are connectivity problems. (*) A_LOT is specified inside the API ( = 5 minutes ).

Parameters:
message 
to Phone number to send the SMS to
Returns:
true, if message delivered
false, if an error occurred
Exceptions:
YX_IOException 
YX_DataException Data problem (protocol problem) e.g. a garbled message may have been received, or parameters are missing
YX_AuthenticationException User or password incorrect
YX_UserPrivilegeException User does not have enough privileges to send SMS
YX_ServerProblemException Problems inside the hardware (memory, database, disc, etc.)
The documentation for this class was generated from the following file:
 All Classes Functions
Generated on Fri Sep 24 17:17:00 2010 for Lyric SMS Java API by  doxygen 1.6.3