sms internet api for java - orange developer · sms internet api for java: sdk manual abstract this...

Version 1.0.0-000

Sms Internet API for Java

SDK Manual

Version 1.0.0-000

Sms Internet API for Java: SDK Manual

Abstract

This manual is a collection of topics related to develop code using all the advanced features of Orange™ Sms Internet with our SDK.

By the end of this manual you will be able to send and receive sms through the Orange France Generic Pop-Up Server using thetoolkit (SDK) we've built for an easy integration within your applications. Our SDK has been designed to hide all the complexity ofthe underlying communication and to help leverage the power of Object Oriented Programming.

You will learn the minimum configuration to write in order to run our SDK and create your first API calls.

The audience of this manual targets new developers or decidors who are interested in empowering their applications with the SMSInternet features we are providing.

This API will be reachable by XML protocol over HTTPS.

Revision History

Revision 1.0.0-000 2009/02/05First release.

Version 1.0.0-000

Table of Contents1. Overview ........................................................................................................................................................ 1

1. Introduction ............................................................................................................................................ 12. SMS Internet features ............................................................................................................................. 13. Concepts ................................................................................................................................................ 1

2. General .......................................................................................................................................................... 21. Business objects ..................................................................................................................................... 22. Client certificate ..................................................................................................................................... 3

3. The SMS Internet SDK ................................................................................................................................... 51. Exception ............................................................................................................................................... 62. Sms Internet ........................................................................................................................................... 73. Business data rules ................................................................................................................................. 84. Business data request .............................................................................................................................. 95. Business data response .......................................................................................................................... 156. Notification ........................................................................................................................................... 177. Xstream ................................................................................................................................................ 178. Logging ................................................................................................................................................ 189. Create a project for Eclipse or Netbeans with the Sms Internet SDK ........................................................ 20

4. SDK methods ............................................................................................................................................... 241. SDK description ................................................................................................................................... 242. Java Sms Internet configuration file for the SDK .................................................................................... 243. Method sendRequest ............................................................................................................................. 254. Method subscribeNotifications/ unsubscribeNotifications ........................................................................ 31

A. Error codes .................................................................................................................................................. 351. Result causes ........................................................................................................................................ 352. Error messages ..................................................................................................................................... 38

Version 1.0.0-000 1

Chapter 1. Overview1. Introduction

Now you've downloaded the various files and libraries, you're ready to get started. We'll take you through howto use the SDK to make simple calls, send an SMS Text ...

2. SMS Internet featuresSMS Internet enables your application to send and receive SMS.

With SMS Internet, your applications are enabled to inform, alert, collect information or broadcast instructionsin remote.

The solution is based on linking businesses to Orange France network through the SMS center (SMS-C). Itallows companies to benefit from following functions:

• track delivery,• manage queues,• storage modes.

3. ConceptsConnecting to SMS-C allow your application servers to send or receives 2 types of SMS:

• SMS-MO (Short Message Services – Mobile Originated): SMS issued from mobile towards a computerapplication.

• SMS-MT (Short Message Services – Mobile Terminated): SMS issued from a computer application andreceived on mobile

In all cases, SMS are composed of 160 characters maximum or 140 bytes depending type of coding used.

SMS Internet works on Orange France mobile terminals and does not require subscription to Orange fleet offer.

An exclusive Popup option enables the possibility to make SMS more interactive.

Performance wise, SMS Internet enables to send and receive a large number of SMS with an importantthroughput: up to 5000 SMS-MO (no acknowledged) can be stored and 100 SMS-MT per mobile number. Thisoffer guarantees a 4 SMS-MT per second per connexion.

Version 1.0.0-000 2

Chapter 2. General1. Business objects

This section describes business objects used in the SMS Internet service.

1.1. MSISDN

The Mobile Station International ISDN Number is a mobile number in international format (E164).

It is broken down as follows: MSISDN = CC+NDC+SN. This is the combination of the country ode (CC), thenational destination code (NDC) and the subscriber number (SN).

The country code for France is 33.

1.2. SMS types

The SMS Internet service allow your application servers to send or receives 2 types of SMS.

1.2.1. SMS mobile originated

SMS-MO are SMS issued from a mobile towards a computer application.

SMS-MO messages may be sent to the application server:

• Either in text format restricted to the ISO-8859-1 character set (described in the appendices to the AdvancedDevelopment Guide).

• In a transparent binary format.

The MO transmission format is an option in the offer.

1.2.2. SMS mobile terminated

SMS-MT are SMS issued from a computer application and received on a mobile. The SMS Internet serviceprovides 4 types of SMS-MT.

1.2.2.1. SMS Text

SMS Text are textual SMS as defined by the GSM standard.

They are composed of 160 characters maximum

1.2.2.2. SMS Bin

SMS Bin are binary SMS as defined by the GSM standard.

They are composed of 140 bytes maximum

1.2.2.3. SMS Popup

Popup option is an exclusive offer proposed by no other operator than Orange.

Sms Internet API for Java - General

Version 1.0.0-000 3

It enables to prompt SMS receiver with a action in response:

• capture an answer to a question,• acknowledge meeting,• answer to application server through the send of SMS.

Receiver can execute up to 5 actions when receiving the SMS

4 types of actions are possible:

• ask for data,• list of choices,• display text,• and send SMS.

These actions are sequential and consist in just one SMS of 140 bytes.

1.2.2.4. SMS Flood

The SMS Internet service makes it possible to send SMS in bulk mode.

An SMS_Flood sends the same SMS Text to a list of recipients with one query.

1.3. Acquitments

Messages received from the pop-pup server (SPG) must be acknowledged. If this is not the case, the pop-upserver will re-send them until acknowledgement.

In the same way, the pop up server will acknowledge each message individually: send an SMS, request to cancelthe sending of an SMS, if this is not the case, it should be considered that the pop-up server has not receivedthe message.

1.4. Notifications

A notifications connection, that comprises an HTTP-type connection, gives a timestamp to the application serverto let it know from the arrival of a message on the pop-up server. Then, the application server has to send arequest to the the pop-up server via the message connection in order to retrieve the message. Each time a newmessage is available on the pop-up server for the given application server, a notification with a update timestampwill be send to the application server.

However, it is possible to not use the notification connection and check the arrival of new messages by pollingon the message connection. The notifications is optional but its use is recommended by Orange France.

The notifications connection is initiated or stopped by the application server when subscribing or unsubscribingto the notifications mecanism.

2. Client certificateEach request made to the SMS Internet service requires a client authentication to verify that the client is who itclaims to be. This client authentication is done through client certificates.

A password-protected client certificate is provided with the SMS Internet SDK. It must be referenced in the SMSInternet configuration file by providing its path and its password.

Sms Internet API for Java - General

Version 1.0.0-000 4

Please refer to the SDK configuration to get more details on the SMS Internet service configuration file

Version 1.0.0-000 5

Chapter 3. The SMS Internet SDKHereafter is described a global view of the Sms Internet SDK architecture. Basically, the smsInternet SDK package isbased on Commons libs from Apache and is composed of:

• SmsInternet Service is a front end with static access to the webmethods.• Business Model: a high level view that lets the developper get quickly involved in the Sms Internet API.

Figure 3.1. Diagram of the global architecture of SmsInternet Sdk

Figure 3.2. UML model diagram of SmsInternet Sdk

Sms Internet API for Java - The SMS Internet SDK

Version 1.0.0-000 6

Figure 3.3. UML model diagram of SmsInternet package

1. ExceptionThe com.orange.api.smsInternet.exception package is made of three main classes.

• FunctionalException class: encapusulates an exception that had been raised by the Orange API.• TechnicalException class: encapsulates an exception that had been raised before reaching the Orange

API.• ConfigurationException class: encapsulates an exception that had been raised during configuration

of the SDK.

Figure 3.4. Exception class diagram from the API.


Version 1.0.0-000 7

Figure 3.5. Configuration exception UML class diagram.

2. Sms InternetThe class com.orange.api.smsInternet.smsInternet is a front end to call webmethods of theSmsInternet API.

Figure 3.6. SmsInternet UML class diagram.

Here are listed all the methods and webmethods that can be grouped as follows:


Version 1.0.0-000 8

Configuration Methods:

• loadFromConfigFile(..) initializes proxy, service Url, notification url from a configuration file.Calling loadFromConfigFile() with no parameter initializes the SMS Internet SDK from theconfiguration file reacheable in the CLASSPATH at /sms.properties.

Network configuration methods:

• InitializeProxy(..) is the access point to configure your proxy in case your machine access internetvia another one.

Service:

• setServiceUrl(..) modify the end point of the service.• setNotifUrl(..) modify the end point of the notification service.

Functional:

• sendRequest(..) send a request to the SmsInternet platform.

Notification:

• subscribeNotifications(..) subscribe to the notification from SmsInternet platform.• unsubscribeNotifications(..) unsubscribe to the notification from SmsInternet platform.

The com.orange.api.smsInternet.Diffuser class represents a diffuser for the SmsInternet API:

• Diffuser class: provides a java instance of a well configured diffuser and contains the certificates.

Figure 3.7. Diffuser UML class diagram

3. Business data rulesThe com.orange.api.smsInternet.businessData.rules package provides all the rules for the business data of theSms Internet API.


Version 1.0.0-000 9

Figure 3.8. BusinessData Rules UML class Diagram

4. Business data requestThe com.orange.api.smsInternet.businessData.request package provides all the classes to store data to send tothe Sms Internet API.


Version 1.0.0-000 10

Figure 3.9. BusinessData request acquit UML class Diagram

Figure 3.10. BusinessData request delete UML class Diagram


Version 1.0.0-000 11

Figure 3.11. BusinessData request binary Sms UML class Diagram


Version 1.0.0-000 12

Figure 3.12. BusinessData request flood Sms UML class Diagram


Version 1.0.0-000 13

Figure 3.13. BusinessData request text Sms UML class Diagram


Version 1.0.0-000 14

Figure 3.14. BusinessData request popup Sms UML class Diagram

Figure 3.15. BusinessData request command UML class Diagram for popup Sms.


Version 1.0.0-000 15

5. Business data responseThe com.orange.api.smsInternet.businessData.request package provides all the classes to retrieve data from theSms Internet API.

Figure 3.16. BusinessData response acquit Sms UML class Diagram

Figure 3.17. BusinessData response error UML class Diagram


Version 1.0.0-000 16

Figure 3.18. BusinessData response result UML class Diagram

Figure 3.19. BusinessData response Sms Mobile originated UML class Diagram


Version 1.0.0-000 17

6. NotificationThe com.orange.api.smsInternet.notification package provides all the classes necessary to deal with notificationsubscription to the Sms Internet API.

Note that to be notified by the Sms Internet server, it is necessacy to subscribe via the given SmsInternet frontend by feeding the subsribeNotifications methods with a parameter which extends the Observer abstract class.

Figure 3.20. Notification Observer UML class Diagram

7. XstreamXStream is a simple library to serialize objects to XML and to unserialize from XML to objects. Here is a shortlist of XStream features:

• No mappings required. Most objects can be serialized without need for specifying mappings.• Performance. Speed and low memory footprint are a crucial part of the design, making it suitable for large

object graphs or systems with high message throughput.• Clean XML. No information is duplicated that can be obtained via reflection. This results in XML that is

easier to read for humans and more compact than native Java serialization.• Requires no modifications to objects. Serializes internal fields, including private and final. Supports non-

public and inner classes. Classes are not required to have default constructor.• Full object graph support. Duplicate references encountered in the object-model will be maintained. Supports

circular references.• Integrates with other XML APIs. By implementing an interface, XStream can serialize directly to/from any

tree structure (not just XML).• Customizable conversion strategies. Strategies can be registered allowing customization of how particular

types are represented as XML.

XStream is an Open Source project under BSD license.

Here's a couple of simple classes. XStream can convert any instances of these to XML and vice versa.


Version 1.0.0-000 18

Figure 3.21. Java-Xml mapping with XStream

For more information please go to http://xstream.codehaus.org/index.html

8. LoggingFor debugging purposes, please create a log4j.properties file in your classpath with the following content.

log4j.debug=false# log4j.threshold=offlog4j.rootLogger=INFO, stdoutlog4j.logger.com.orange.api= DEBUG, sdk

log4j.logger.httpclient.wire=DEBUG, Flog4j.logger.org.apache.commons.httpclient=DEBUG, stdout

# stdout on System.out. with info Thresholdlog4j.appender.stdout=org.apache.log4j.ConsoleAppenderlog4j.appender.stdout.Target=System.outlog4j.appender.stdout.Threshold=infolog4j.appender.stdout.layout=org.apache.log4j.SimpleLayout

# HTTP Apache Common logging log4j.appender.F=org.apache.log4j.FileAppenderlog4j.appender.F.File=logs/wire.loglog4j.appender.F.layout=org.apache.log4j.PatternLayoutlog4j.appender.F.layout.ConversionPattern =%5p [%c] %m%n

# sdk is a file max 5Mo with 2 backup named 'sdk.log' with ERROR Thresholdlog4j.appender.sdk=org.apache.log4j.RollingFileAppenderlog4j.appender.sdk.File=logs/sdk.loglog4j.appender.sdk.Append=truelog4j.appender.sdk.Threshold=DEBUGlog4j.appender.sdk.MaxFileSize=5MBlog4j.appender.sdk.MaxBackupIndex=2log4j.appender.sdk.layout=org.apache.log4j.PatternLayoutlog4j.appender.sdk.layout.ConversionPattern=%m%n

The output file sdk.log and wire.log will be stored in the logs folder created at the root level of yourclasspath.

Here is a sample of the content of the wire.log file:

http://xstream.codehaus.org/index.html


Version 1.0.0-000 19

DEBUG [httpclient.wire.header] >> "CONNECT spg-test.bordeaux.cvf.fr:443 HTTP/1.1"DEBUG [httpclient.wire.header] >> "User-Agent: Jakarta Commons-HttpClient/3.1[\r][\n]"DEBUG [httpclient.wire.header] >> "Host: spg-test.bordeaux.cvf.fr[\r][\n]"DEBUG [httpclient.wire.header] >> "Proxy-Connection: Keep-Alive[\r][\n]"DEBUG [httpclient.wire.header] >> "[\r][\n]"DEBUG [httpclient.wire.header] << "HTTP/1.0 200 Connection established[\r][\n]"DEBUG [httpclient.wire.header] << "HTTP/1.0 200 Connection established[\r][\n]"DEBUG [httpclient.wire.header] << "Proxy-Agent: NetCache NetApp/6.1.1[\r][\n]"DEBUG [httpclient.wire.header] << "[\r][\n]"DEBUG [httpclient.wire.header] >> "POST /cgi-bin/messages.cgi HTTP/1.1[\r][\n]"DEBUG [httpclient.wire.header] >> "User-Agent: Jakarta Commons-HttpClient/3.1[\r][\n]"DEBUG [httpclient.wire.header] >> "Host: spg-test.bordeaux.cvf.fr[\r][\n]"DEBUG [httpclient.wire.header] >> "Content-Length: 77[\r][\n]"DEBUG [httpclient.wire.header] >> "Content-Type: text/html; charset=ISO-8859-1[\r][\n]"DEBUG [httpclient.wire.header] >> "[\r][\n]"DEBUG [httpclient.wire.content] >> "<DOC_SPG VERSION="1.0" SID="2177">[\n]"DEBUG [httpclient.wire.content] >> " <ACK TYPE="RESULT" SMID="1"/>[\n]"DEBUG [httpclient.wire.content] >> "</DOC_SPG>"DEBUG [httpclient.wire.header] << "HTTP/1.1 200 OK[\r][\n]"DEBUG [httpclient.wire.header] << "HTTP/1.1 200 OK[\r][\n]"DEBUG [httpclient.wire.header] << "Date: Wed, 23 Jul 2008 14:04:46 GMT[\r][\n]"DEBUG [httpclient.wire.header] << "Server: Apache[\r][\n]"DEBUG [httpclient.wire.header] << "Transfer-Encoding: chunked[\r][\n]"DEBUG [httpclient.wire.header] << "Content-Type: text/html; charset=iso-8859-1[\r][\n]"DEBUG [httpclient.wire.header] << "[\r][\n]"DEBUG [httpclient.wire.content] << "3"DEBUG [httpclient.wire.content] << "3"DEBUG [httpclient.wire.content] << "e"DEBUG [httpclient.wire.content] << "[\r]"DEBUG [httpclient.wire.content] << "[\n]"DEBUG [httpclient.wire.content] << "<?xml version="1.0" encoding="ISO-8859-1" ?>[\n]"DEBUG [httpclient.wire.content] << "<DOC_SA VERSION="1.0" >[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="23" STATUS="0" CAUSE="0" TIMESTAMP="210708100745" MESSAGE="submitted" MSISDN="06xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="23" STATUS="0" CAUSE="0" TIMESTAMP="210708101547" MESSAGE="submitted" MSISDN="06xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="24" STATUS="0" CAUSE="0" TIMESTAMP="210708100746" MESSAGE="submitted" MSISDN="+336xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="24" STATUS="0" CAUSE="0" TIMESTAMP="210708101548" MESSAGE="submitted" MSISDN="+336xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="24" STATUS="0" CAUSE="0" TIMESTAMP="210708101855" MESSAGE="submitted" MSISDN="06xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="24" STATUS="4" CAUSE="0" TIMESTAMP="210708102215" MESSAGE="unknown" MSISDN="+336xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "<RESULT SMID="24" STATUS="4" CAUSE="0" TIMESTAMP="210708102235" MESSAGE="unknown" MSISDN="06xxxxxxxx" />[\n]"DEBUG [httpclient.wire.content] << "</DOC_SA>[\n]"DEBUG [httpclient.wire.content] << "[\r]"DEBUG [httpclient.wire.content] << "[\n]"DEBUG [httpclient.wire.content] << "0"DEBUG [httpclient.wire.content] << "[\r]"DEBUG [httpclient.wire.content] << "[\n]"DEBUG [httpclient.wire.content] << "[\r]"DEBUG [httpclient.wire.content] << "[\n]"DEBUG [httpclient.wire.header] << "[\r][\n]"

For detailed information and advanced configuration on log4j, please refer to the reference web site: http://logging.apache.org/log4j/1.2/index.html.

http://logging.apache.org/log4j/1.2/index.html

http://logging.apache.org/log4j/1.2/index.html


Version 1.0.0-000 20

9. Create a project for Eclipse or Netbeans with theSms Internet SDK

A "Hello World"-like WebService has been created to both test and check your machine environment and yourconnectivity to the Contact Everyone API. Please do the following steps:

• Create a new java project in your favorite IDE (netBeans, Eclipse...).• Add the sms-1.0.1.jar to the build path of the project.• Unzip the file dependencies.zip and add all the extracted *.jar files to the build path of your project.• Copy the sms.properties file at the root of the CLASSPATH of your project. Here is an example:

#-------------------------------------------------------------# (1) Configuration service #-------------------------------------------------------------# http proxy (optional)proxyHost = yourProxyHostproxyPort = 5555proxyUsername = proxyPassword =

# SSL: trust file or public key (server authentication)# by giving an absolute path# [Windows] : C:\\yourKeyStoreFile.jks# [Linux, Unix] : /yourKeyStoreFile.jks## by giving the relative path of the classpath root (for advanced user)# [Windows] : ..\\yourFolder\\yourKeyStoreFile.jks# [Linux, Unix] : ../yourFolder/yourKeyStoreFile.jks

# keystore path file (mandatory)keyStoreFile = C:\\orangeKeyStore.jks

# keystore password (optional) keyStorePassword = yourPassword

#-------------------------------------------------------------# (2) Configuration API (mandatory)#-------------------------------------------------------------sid = 1234serviceUrl = https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxnotifUrl = http://yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

• Finally create a main java class as follows (without using the config file):

package com.orange.api.smsInternet.doc.sdkManual;

import com.orange.api.smsInternet.Diffuser;import com.orange.api.smsInternet.SmsInternet;import com.orange.api.smsInternet.businessData.request.Request;import com.orange.api.smsInternet.businessData.request.RequestDelete;import com.orange.api.smsInternet.businessData.request.RequestSmsText;import com.orange.api.smsInternet.businessData.response.Response;import com.orange.api.smsInternet.exception.FunctionalException;import com.orange.api.smsInternet.exception.TechnicalException;

import java.util.Calendar;import java.util.GregorianCalendar;


Version 1.0.0-000 21

import java.util.Queue;import java.util.concurrent.ConcurrentLinkedQueue;

public class FirstApiCall_WithoutConfigFile {

public static void main(String[] args) { try { String phoneNumber = "0612345678"; String smid = "1";

// Initialize a diffuser with appropriate setter. String sid = "your_sid_number"; // replace with your sid number String keyStorePath = "C:\\yourKeyStoreFile.jks"; // replace with your keyStore file String keyStorePassword = "your_keystore_password"; // replace with your keyStore password Diffuser diffuser = new Diffuser(); diffuser.setSid(sid); diffuser.setKeyStorePath(keyStorePath); diffuser.setKeyStorePassword(keyStorePassword); // prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); RequestSmsText sms = new RequestSmsText("Hello from the Sms Internet service", smid, phoneNumber);

requests.offer(sms);

// Initialize Sms Internet Service SmsInternet.setServiceUrl("https://spg-test.bordeaux.cvf.fr/cgi-bin/messages.cgi"); SmsInternet.initializeProxy("your_proxy_host", your_proxy_port); Queue<Response> responses = null; responses = SmsInternet.sendRequest(diffuser, requests);

System.out.println(diffuser.toString());

for (Response response : responses) { System.out.println("Response : \n" + response.toString()); }

} catch (FunctionalException ex) { System.err.println("Functional Error : " + ex.getErrorMessage()); } catch (TechnicalException ex) { System.err.println("Technical Error : " + ex.getErrorMessage()); } }}

• ... or create a main java class as follows (using the config file):


import com.orange.api.smsInternet.Diffuser;import com.orange.api.smsInternet.SmsInternet;import com.orange.api.smsInternet.businessData.request.Request;import com.orange.api.smsInternet.businessData.request.RequestDelete;import com.orange.api.smsInternet.businessData.request.RequestSmsText;import com.orange.api.smsInternet.businessData.response.Response;


Version 1.0.0-000 22

import com.orange.api.smsInternet.exception.ConfigurationException;import com.orange.api.smsInternet.exception.FunctionalException;import com.orange.api.smsInternet.exception.TechnicalException;

import java.util.Calendar;import java.util.GregorianCalendar;import java.util.Queue;import java.util.concurrent.ConcurrentLinkedQueue;

public class FirstApiCall_WithConfigFile {

public static void main(String[] args) { try { String phoneNumber = "0612345678"; String smid = "1";

// Initialize a diffuser from the default config file 'sms.properties' Diffuser diffuser = new Diffuser(); diffuser.loadFromConfigFile();

// prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); RequestSmsText sms = new RequestSmsText("Hello from the Sms Internet service", smid, phoneNumber); requests.offer(sms); // Initialize Sms Internet Service from the default config file 'sms.properties' SmsInternet.loadFromConfigFile();

Queue<Response> responses = null; responses = SmsInternet.sendRequest(diffuser, requests); System.out.println(diffuser.toString()); for (Response response : responses) { System.out.println("Response : \n" + response.toString()); } } catch (ConfigurationException ex) { System.err.println("Configuration error: " + ex.getMessage()); } catch (FunctionalException ex) { System.err.println("Functional Error : " + ex.getErrorMessage()); } catch (TechnicalException ex) { System.err.println("Technical Error : " + ex.getErrorMessage()); } }}

• Run your project, the response for both code snippets should give you a welcome message from Sms as follows:

[com.orange.api.smsInternet.Diffuser]sid = your_server_idkeyStoreFile = C:\yourKeyStoreFile.jkskeyStorePassword = your_keystore_password

Response:[com.orange.api.smsInternet.businessData.response.ResponseResult]smid='1'msisdn='0612345678'


Version 1.0.0-000 23

status='2'timestamp='230708163951'message='SMS non remis au 0612345678 : MSISDN portÚ par un autrecause='206'

Version 1.0.0-000 24

Chapter 4. SDK methodsIn this chapter you will learn how to use the base objects we defined for you inside our SDK through some ready-to-use samples.

What are the basic steps?

1. Create a Diffuser and initialize its parameters.2. Use the SmsInternet front end to configure your proxy settings if necessary.3. Use the SmsInternet front end to configure the notification and service url.4. In the end, call the API method.

1. SDK descriptionIf you want to well understand what you will achieve into the next samples you should be aware of the followingSDK properties:

• com.orange.api.smsInternet is the root package of SmsInternet SDK.• com.orange.api.smsInternet.businessData is the root package of objets you will have to use to generate your

requests.

Do not forget that you can consult at any time the reference manual of the SDK to refer to objects and methodsdescription. You should first make sure you've read the prerequisites document before coding and running thefollowing programlistings. The prerequisites explain, among others, how to set up your proxy information andyour account information through a configuration file. For simplicity, samples code use a configuration filesms.properties like described in the following section:

2. Java Sms Internet configuration file for the SDKThis configuration file must be named sms.properties and has to be located at the classpath root of yourapplication.

#-------------------------------------------------------------# (1) Configuration service #-------------------------------------------------------------# http proxy (optional)proxyHost = proxyPort = proxyUsername = proxyPassword =

# SSL: trust file or public key (server authentication)# by giving an absolute path# [Windows] : C:\\yourKeyStoreFile.jks# [Linux, Unix] : /yourKeyStoreFile.jks## by giving the relative path of the classpath root (for advanced user)# [Windows] : ..\\yourFolder\\yourKeyStoreFile.jks# [Linux, Unix] : ../yourFolder/yourKeyStoreFile.jks

# keystore path file (mandatory)keyStoreFile =

Sms Internet API for Java - SDK methods

Version 1.0.0-000 25

# keystore password (optional) keyStorePassword =

#-------------------------------------------------------------# (2) Configuration API (mandatory)#-------------------------------------------------------------sid = serviceUrl = notifUrl =

Tip

The keyStoreFile property expects a path value so do not forget that the format of the path isdepending on the OS you are running.

Tip

Please escape the back slash character '\' in attributes of the property file. For example, characters of thepassword 4fg!ws\ must be escaped as follow: 4fg!ws\\

To apply these settings, you can use the loadFromConfigFile method on the Diffuser Object and theSMSInternet Class:

try{ // Initialize server id, the service URL, notification URL and HTTP proxy (optional) from 'sms.properties' SmsInternet.loadFromConfigFile();

//Create the diffuser from 'sms.properties' Diffuser diffuser = new Diffuser(); diffuser.loadFromConfigFile(); }catch(ConfigurationException ex){ System.err.println("Error Configuration: '" + ex.getErrorMessage() + "'" );}

Note that a ConfigurationException exception can be raised if:

• The configuration file sms.properties has not been found.• A mandatory key is missing (i.e. the server id key is missing).

3. Method sendRequestIn the following examples, for the matter of simplicity, we've used the data of the configuration file.

3.1. Description

This web method send all the requests to the server.


Version 1.0.0-000 26

3.2. Input parameter

Table 4.1. SendRequest: Input parameters.

Name Type Description Cardinality

diffuser Diffuser an diffuser for the SmsInternet service 1..1

requests Queue<Request> The queue of requests to send. 0..*

3.3. Output parameter

Table 4.2. SendRequest: Output parameters.


responses Queue<Response> The queue of responses send by the server. 0..*

3.4. Exceptions

This web method may throw TechnicalException or FunctionalException.

3.5. Sample code

These samples use the sms.properties file, don't forget to fill in your information.

3.5.1. Send a sms text, sms flood , binary sms, sms popup.

This sample Class shows you how to send SMS messages of each type. Each method "sendxxxxSms()" sendsone SMS and retrieves the response.

The initialization is done by loading the default configuration file sms.properties, in the setUpConf() method.


import java.util.ArrayList;import java.util.Calendar;import java.util.GregorianCalendar;import java.util.Queue;import java.util.concurrent.ConcurrentLinkedQueue;

import com.orange.api.smsInternet.Diffuser;import com.orange.api.smsInternet.SmsInternet;import com.orange.api.smsInternet.businessData.request.EnumYesNo;import com.orange.api.smsInternet.businessData.request.Recipient;import com.orange.api.smsInternet.businessData.request.Request;import com.orange.api.smsInternet.businessData.request.RequestAcquitResult;import com.orange.api.smsInternet.businessData.request.RequestDelete;import com.orange.api.smsInternet.businessData.request.RequestSmsBin;import com.orange.api.smsInternet.businessData.request.RequestSmsFlood;import com.orange.api.smsInternet.businessData.request.RequestSmsPopup;import com.orange.api.smsInternet.businessData.request.RequestSmsText;import com.orange.api.smsInternet.businessData.request.command.CommandDisplayText;import com.orange.api.smsInternet.businessData.request.command.CommandSelectItem;import com.orange.api.smsInternet.businessData.response.Response;import com.orange.api.smsInternet.exception.ConfigurationException;import com.orange.api.smsInternet.exception.FunctionalException;


Version 1.0.0-000 27

import com.orange.api.smsInternet.exception.TechnicalException;

/** * SDK Manual Example for sending sms * */public class SendSmsRequest {

private static String phoneNumber = "0612345678"; private static Diffuser diffuser = new Diffuser(); private int intSmid = 6100; public void setUpConf() throws ConfigurationException { // Initialize a diffuser from the default config file diffuser.loadFromConfigFile(); //Initialize Sms Internet Service from the default config file SmsInternet.loadFromConfigFile(); } //-------------------------------- SEND TEXT SMS -------------------------------- public void sendTextSms() throws FunctionalException, TechnicalException, ConfigurationException { //prepare configuration (see method for more detail) setUpConf(); // prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); //prepare smid String smid = getNextSmid(); //Prepare sms RequestSmsText sms = new RequestSmsText("Hello from the Sms Internet service, this is a text sms", smid, phoneNumber); //Put the sms in the queue requests.offer(sms); //actualy send sms Queue<Response> responses = SmsInternet.sendRequest(diffuser, requests); doSomethingWithResponses(responses); } //-------------------------------- SEND FLOOD SMS -------------------------------- public void sendFloodSms() throws FunctionalException, TechnicalException, ConfigurationException { //prepare configuration (see method for more detail) setUpConf(); // prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); //Prepare the floodId String floodId = getNextSmid(); // Prepare a queue of 5 recipients (the smid and the phone Number should be filled as needed) Queue<Recipient> recipients = new ConcurrentLinkedQueue<Recipient>(); recipients.offer(new Recipient(floodId + "1", phoneNumber)); recipients.offer(new Recipient(floodId + "2", phoneNumber)); recipients.offer(new Recipient(floodId + "3", phoneNumber)); recipients.offer(new Recipient(floodId + "4", phoneNumber)); recipients.offer(new Recipient(floodId + "5", phoneNumber)); //prepare sms RequestSmsFlood smsFlood = new RequestSmsFlood(floodId, "Meeting moved forward on Monday.", recipients); //Put the sms in the queue requests.offer(smsFlood);


Version 1.0.0-000 28

//actualy send sms Queue<Response> responses = SmsInternet.sendRequest(diffuser, requests); doSomethingWithResponses(responses); }

//-------------------------------- SEND BIN SMS -------------------------------- public void sendBinSms() throws FunctionalException, TechnicalException, ConfigurationException { //prepare configuration (see method for more detail) setUpConf(); // prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); //prepare smid String smid = getNextSmid(); //Prepare the binary message to send String messageHexa = "A2456FFE"; //Prepare sms // Add binary SMS (hexa message: A2 45 6F FE) (smid=300) RequestSmsBin smsBin = new RequestSmsBin(smid, phoneNumber, messageHexa); //Put the sms in the queue requests.offer(smsBin); //actualy send sms Queue<Response> responses = SmsInternet.sendRequest(diffuser, requests); doSomethingWithResponses(responses); }

//-------------------------------- SEND POPUP SMS -------------------------------- public void sendPopupSms() throws FunctionalException, TechnicalException, ConfigurationException { //prepare configuration (see method for more detail) setUpConf(); // prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); //prepare smid String smid = getNextSmid(); // Prepare a SMS popup Queue<CommandSelectItem.Item> items = new ConcurrentLinkedQueue<CommandSelectItem.Item>(); items.offer(new CommandSelectItem.Item("Yes")); items.offer(new CommandSelectItem.Item("No")); CommandSelectItem command1 = new CommandSelectItem("Accept ?", items); RequestSmsPopup smsPopup = new RequestSmsPopup(0, command1, smid, phoneNumber); smsPopup.setNotif("7"); smsPopup.setPlayTone(EnumYesNo.Yes); CommandDisplayText command2 = new CommandDisplayText("Do you accept the mission ?"); smsPopup.setCommand(1, command2); //Put the sms in the queue requests.offer(smsPopup); //actualy send sms Queue<Response> responses = SmsInternet.sendRequest(diffuser, requests); doSomethingWithResponses(responses); }//-------------------------------- MAIN -------------------------------- public static void main(String[] args) { try {

SendSmsRequest mySender = new SendSmsRequest(); mySender.sendTextSms(); mySender.sendFloodSms(); mySender.sendBinSms(); mySender.sendPopupSms();


Version 1.0.0-000 29

} catch (ConfigurationException ex) { System.err.println("Configuration error: " + ex.getMessage()); } catch (FunctionalException ex) { System.err.println("Functional Error : " + ex.getErrorMessage()); } catch (TechnicalException ex) { System.err.println("Technical Error : " + ex.getErrorMessage()); } }

//-------------------------------- UTILS -------------------------------- private static void doSomethingWithResponses(Queue<Response> responses) { for (Response response : responses) { System.out.println("Response : \n" + response.toString()); } } private String getNextSmid() { intSmid++; return "" + intSmid; }}

The output looks like:

Response : [com.orange.api.smsInternet.businessData.response.ResponseAcquitShort] type='TEXT' smid='6101' count='null'

Response :[com.orange.api.smsInternet.businessData.response.ResponseAcquitFlood] type='FLOOD' floodId='6102' count='null'

Response :[com.orange.api.smsInternet.businessData.response.ResponseAcquitShort] type='BIN' smid='6103' count='null'

Response :[com.orange.api.smsInternet.businessData.response.ResponseAcquitShort] type='POPUP' smid='6104' count='null'

3.5.2. Send a acknowledgement and a delete command.

This sample shows how to acknowlege a result and how to delete a diffrered text sms.

• First a 4 minutes differed sms is submitted• Then a delete command is submitted to prevent SMS-C from transmitting the message to the terminal• Finally the result is acknowleged..



Version 1.0.0-000 30

import com.orange.api.smsInternet.*;import com.orange.api.smsInternet.exception.*;import com.orange.api.smsInternet.businessData.response.*;import com.orange.api.smsInternet.businessData.request.*;

import java.util.Calendar;import java.util.GregorianCalendar;import java.util.Queue;import java.util.concurrent.ConcurrentLinkedQueue;

public class SendAcknowledgeAndDelete {

public static void main(String[] args) {

try { String smid = "6213"; String phoneNumber = "0612345678";

// Initialize a diffuser from the default config file 'sms.properties' Diffuser diffuser = new Diffuser(); diffuser.loadFromConfigFile();

// Initialize Sms Internet Service from the default config file 'sms.properties' SmsInternet.loadFromConfigFile();

// 1) prepare Sms for sending Queue<Request> requests = new ConcurrentLinkedQueue<Request>(); RequestSmsText sms = new RequestSmsText("you shouldn't receive this !", smid, phoneNumber); //Differing the transmission (4 minutes) Calendar cal = GregorianCalendar.getInstance(); cal.setTimeInMillis(cal.getTimeInMillis() + 240 * 1000); sms.setDeferred(cal); requests.offer(sms);

// Actually send the sms (call to service) Queue<Response> responses = SmsInternet.sendRequest(diffuser, requests); //Display responses System.out.println("###Response from the service to the text sms request :"); for (Response response : responses) { System.out.println(response.toString() + "\n"); }

// 2) Send Delete Command for the smid requests = new ConcurrentLinkedQueue<Request>(); // Add a delete command for smid requests.offer(new RequestDelete(smid)); // Call the service responses = SmsInternet.sendRequest(diffuser, requests); //Display responses System.out.println("###Response from the service to the delete request :"); for (Response response : responses) { System.out.println(response.toString() + "\n"); }

// 3) Acknowlege Commands for the smid requests = new ConcurrentLinkedQueue<Request>(); // Add a Ack command for smid requests.offer(new RequestAcquitResult(smid)); // Call the service responses = SmsInternet.sendRequest(diffuser, requests);


Version 1.0.0-000 31

//Display responses System.out.println("###Response from the service to the Ack request (should be empty):"); for (Response response : responses) { System.out.println(response.toString() + "\n"); } } catch (ConfigurationException ex) { System.err.println(" Configuration error: " + ex.getMessage()); } catch (FunctionalException ex) { System.err.println(" Functional Error : " + ex.getErrorMessage()); } catch (TechnicalException ex) { System.err.println(" Technical Error : " + ex.getErrorMessage()); } }}


###Response from the service to the text sms request :[com.orange.api.smsInternet.businessData.response.ResponseAcquitShort] type='TEXT' smid='6213' count='null' ###Response from the service to the delete request :[com.orange.api.smsInternet.businessData.response.ResponseAcquitShort] type='DELETE' smid='6213' count='null' ###Response from the service to the Ack request (should be empty):

4. Method subscribeNotifications/unsubscribeNotifications

In the following examples, for the matter of simplicity, we've used the data of the configuration file.

4.1. Description

These web methods allow to subscribe/unsubscribe to the notification mecanism of the Orange server.

The subscribeNotifications method starts a new thread that listen the notification channel of the givenserver (the Sid property of the given Observer):

• The dateSeen method inherits from the given Observer will be called each time the Orange Server senda notification.

• The exceptionSeen will be called when any exceptions arise.

The unsubscribeNotifications method stops the thread that listen the notification channel of the givenserver (the Sid property of the given Observer).


Version 1.0.0-000 32

4.2. Input parameter

Table 4.3. SubscribeNotifications: Input parameters.


observer Observer an observer for the SmsInternet service 1..1

Table 4.4. unsubscribeNotifications: Input parameters.


observer Observer an observer for the SmsInternet service 1..1

4.3. Output parameters

none

4.4. Exceptions

This web method may throw FunctionalException or TechnicalException.

4.5. Sample code

This sample shows you how subcribe and unsubscribe to Orange Notifications mechanism.


import java.text.SimpleDateFormat;import java.util.Calendar;import java.util.GregorianCalendar;import java.util.Queue;import java.util.concurrent.ConcurrentLinkedQueue;

import com.orange.api.smsInternet.Diffuser;import com.orange.api.smsInternet.SmsInternet;import com.orange.api.smsInternet.businessData.request.Request;import com.orange.api.smsInternet.businessData.request.RequestAcquitResult;import com.orange.api.smsInternet.businessData.request.RequestDelete;import com.orange.api.smsInternet.businessData.request.RequestSmsText;import com.orange.api.smsInternet.exception.ConfigurationException;import com.orange.api.smsInternet.exception.FunctionalException;import com.orange.api.smsInternet.exception.TechnicalException;import com.orange.api.smsInternet.notification.DateEvent;import com.orange.api.smsInternet.notification.ExceptionEvent;import com.orange.api.smsInternet.notification.Observer;

public class YourObserver extends Observer {

static Diffuser diffuser = new Diffuser();

public static void main(String[] args) { try { String smid = "6301"; String phoneNumber = "0612345678";


Version 1.0.0-000 33

// Initialize a diffuser from the default config file 'sms.properties' diffuser.loadFromConfigFile(); // Initialize Sms Internet Service from the default config file 'sms.properties' SmsInternet.loadFromConfigFile();

// Prepare observer YourObserver yourObserver = new YourObserver(); yourObserver.setSid(diffuser.getSid()); // Subsrcibe to the notification SmsInternet.subscribeNotifications(yourObserver);

// prepare requests Queue<Request> requests = new ConcurrentLinkedQueue<Request>();

//Prepare sms RequestSmsText sms = new RequestSmsText("This is a sms for testing notifications", smid, phoneNumber);

sms.setNotif("7"); //Put the sms in the queue requests.offer(sms);

//actualy send sms don't care of the responses SmsInternet.sendRequest(diffuser, requests); //do something with responses // Unsubscribe notification SmsInternet.unsubscribeNotifications(yourObserver);

} catch (ConfigurationException ex) { System.err.println(" Configuration error: " + ex.getMessage()); } catch (FunctionalException ex) { System.err.println(" Functional Error : " + ex.getErrorMessage()); } catch (TechnicalException ex) { System.err.println(" Technical Error : " + ex.getErrorMessage()); }

}

public void dateSeen(DateEvent dateEvent) { try { SimpleDateFormat sdf = new SimpleDateFormat("dd/mm/yyyy HH:mm:ss Z"); System.out.println("Notification date: " + sdf.format(dateEvent.getDate().getTime())); // Send a empty request or delegate a handler request do get acual responses. } catch (Exception e) { System.err.println(e.getLocalizedMessage()); } }

public void exceptionSeen(ExceptionEvent ex) { try { System.err.println(" Exception seen : " + ex.getCause().getMessage()); System.out.println(ex.getSource().getClass()); // Do something : process the error. } catch (Exception e) { System.err.println(e.getLocalizedMessage()); } }}



Version 1.0.0-000 34

Notification date: 03/03/2009 17:03:55 +0100

The error output looks like:

Exception seen : Notification error : Invalid SID

Version 1.0.0-000 35

Appendix A. Error codes1. Result causes

Here is a description of the possible values of the Cause field of ResponseResult when the message statusis SpgError and SmscError.

1.1. SPG errors

Table A.1. SPG errors

Code Detail

1 Read error.

2 Invalid request.

3 Not well-formed document.

4 Invalid document root.

6 Invalid protocol version.

7 Syntax error.

8 Internal error.

9 Bad serveur identifier.

10 Bad channel.

12 Bad smid.

13 Illegal request.

14 Illegal keynum.

15 Message too long.

16 Missing setupcall msisdn.

17 Forbidden setupcall with this key.

18 Missing GETINPUT mandatory argument LMIN.

19 Missing GETINPUT mandatory argument LMAX.

20 Missing GETINPUT mandatory argument TEXT.

21 Missing SELECTITEM.TITLE mandatory argument.

22 Missing ITEM.TEXT mandatory argument. Aborting.

23 PLI cmd forbidden with this key

24 Popup compiled too long.

25 Bad class.

26 Bad smid.

27 Bad ack type.

28 No msisdn.

29 No timestamp in mo ack.

Sms Internet API for Java - Error codes

Version 1.0.0-000 36

Code Detail

30 Unknown ack type.

1.2. SMS-C errors

Failure when attempting to deliver to the recipient:

Table A.2. SMS-C errors

Code Detail

0 Name: Unknown subscriber

Possible reason: Unknown subscriber.

1 Name: Service temporary not available

Possible reason: SMSC temporarily not available.

100 Name: Facility not supported

Possible reason: The mobile does not support SMS messages.

103 Name: Call barred

Possible reason: The subscriber has not paid the invoices, the operator refuses SMS MT.

108 Name: Delivery fail

Possible reason: SIM card inbox full or SMS period of validity expired.

109 Name: SC congestion

Possible reason: SMSC congested.

110 Name: Protocol error

Possible reason: Error during transmission.

111 Name: MS not equipped

Possible reason: The subscriber does not have SMS MT rights (in the HLR) or does not accept class0 SMS.

114 Name: Illegal MS

Possible reason: Mobile stolen.

116 Name: Error in MS

Possible reason: Mobile problem.

117 Name: SMS lower layer not provisioned


Version 1.0.0-000 37

Code Detail

Possible reason: SMS badly formatted.

118 Name: System failure

Possible reason: Trash error.

119 Name: PLMN System failure

Possible reason: Network problem.

120 Name: HLR System failure

Possible reason: HLR problem.

121 Name: VLR System failure

Possible reason: VLR problem.

122 Name: Previous VLR system failure

Possible reason: Error in handover.

123 Name: Controlling MSC system failure

Possible reason: MSC control problem.

124 Name: VMSC system failure

Possible reason: MSC problem.

125 Name: EIR system failure

Possible reason: EIR problem

126 Name: Radio Subsystem system failure

Possible reason: Radio link problem.

Failure when attempting to deliver to the SMSC:

Table A.3. SPC errors

Code Detail

4 Name: Maximum messages for the address exceeded

Possible reason: Maximum messages for the same subscriber exceeded.

5 Name: Recipient address is in black list

Possible reason: The recipient address is in the black list.


Version 1.0.0-000 38

Code Detail

22 Name: Invalid short message validity period

Possible reason: Validity period incorrect.

2. Error messagesHere is a description of the possible values of the Message field of ResponseError.

Table A.4. Error messages

Message Detail

Bad root tagname Incorrect main node.

Bad root version Version attribute does not exist.

Bad Version Incorrect version attribute.

Bad root SID SID attribute does not exist.

Bad SID Service does not exist.

Service closed Service closed.

Not well formed Incorrect XML frame.

Bad DN DN incorrect.

SMID not valid SMID attribute incorrect.

No SMID SMID attribute does not exist.

No Valid DN for thisSID

Internal SPG error.

Bad request Internal SPG error.

sms internet api for java - orange developer · sms internet api for java: sdk manual abstract this...

Documents