Company information
TeliaSonera Finland Oyj
Teollisuuskatu 15, 00510 HELSINKI, FI Registered office: Helsinki
Business ID 1475607-9, VAT No. FI14756079
T S 1 2 0 9 2 4 3 8 9 0 1 .0
Programmer's Guide for Java API
Description
This document describes how to develop Content Gateway services with Java API.
Version history
Versions Status Date Modified by Comments 1.0 Approved 01.02.2013 TeliaSonera Finland Oyj Renewed version
Table of contents
1 Introduction ... 3
1.1 The Content Gateway API Library ... 3
1.2 Additional Information ... 3
1.3 General Instructions for Using the Java API ... 3
2 Developing Applications with Java API ... 3
2.1 Developing a Send Only Application ... 4
2.2 Developing a Receive Only Application ... 6
2.3 Developing a Query/reply Application ... 7
2.3.1 Closing a Message Session ... 9
2.3.2 Multiple Reply Messages within One Session ... 10
2.4 Developing a Push Application ... 10
2.5 Messages ... 12
2.6 Implementing Positioning Interface ... 12
3 Classes and Methods... 14
1 Introduction
Content Gateway Java API is designed to provide a Java programming interface to the Content Gateway platform. API handles all the connections and data transfer between the platform and content/service provider‘s applications.
This document describes the basic principles of creating and running a Content Gateway service with the Java API. Content Gateway Java API provides you with a simple programming interface for developing mobile value added services and applications. Further and more detailed information about class usage can be found in the JavaDoc documentation.
1.1 The Content Gateway API Library
The Content Gateway software contains the C++, ActiveX and Java API libraries. The API libraries offer you the following functionalities:
− Interpreting the SMSC protocol via Provider Server and Operator Server and controlling
the functional features of the application. Changes in the SMSC do not generally affect your applications.
− Converting messages to a format that Provider Server and SMSC understand. Content
Gateway currently supports SMS messages in a text or binary format. In mobile terminated messages, the system also supports Nokia Smart Messaging.
− Performing character set conversions between the SMSC and API.
− Controlling message handling and routing messages to the correct session instances or
call-back functions.
− Setting parameters for sending messages.
− Developing TCP/IP socket client applications. The API library communicates with Provider
Server, opens the connection and creates the message structure.
− Developing TCP/IP socket server applications. The API library communicates with Provider
Server, opens the connection and creates the message structure.
− Deleting unnecessary characters from the recipient’s MSID number. The MSID number is
currently a mobile station number.
− Controlling sessions automatically.
1.2 Additional Information
The supported service types, billing and general guidelines for service and application development are explained in Service Development Guide.
1.3 General Instructions for Using the Java API
CGW Java API requires the installation and proper configuration of Content Gateway Provider Server version 3.0 (or newer) and JDK 1.3 (or newer).
2 Developing Applications with Java API
The basic function of the Content Gateway platform is to transfer SMS messages between the SMSC and the content/service provider. The transferred messages can be mobile originated (MO) or mobile terminated (MT). One of the important aspects is billing, i.e. charging
transactions between the content/service provider and the subscriber. To create successful Content Gateway applications, it is important to understand the concept of a Content Gateway
session. The term session describes a single money transaction, a single service provided to the subscriber. A session may contain several SMS messages, e.g. a traditional weather service session consists of two SMS messages: a MO query from the subscriber and a MT reply from the content/service provider. The session is billed when the subscriber receives the MT reply successfully. This concept is implemented in the Java API.
The following three classes are used to handle the Content Gateway sessions:
1. The base class CGW provides the interface to the Content Gateway platform, it creates the connections and manages the sessions.
2. The CGWMessage class represents the actual SMS messages that can be sent by the content/service provider or received from the subscriber. It contains all the necessary information, such as the sender, the recipient and the message text.
3. The CGWSession class stores the status of the Content Gateway session, i.e. sending a
CGWMessage always produces an instance of the CGWSession class containing
information on the session success.
2.1 Developing a Send Only Application
The Send Only mode is a common and simple way to use the Java API. It provides an easy way to create an application that only needs to send messages, e.g. an intranet page calling a Java servlet to send SMS messages. The API will be automatically in the Send Only mode if the callback interface is not used, i.e the class CGW is instantiated. In addition, send methods are always blocking in the Send Only mode, which means that the session status information is available immediately after the message has been sent. The following example illustrates how this can be done:
import cgw.*;
public class Sender { public Sender() {
// Construct the new CGW instance
CGW cgw = new CGW();
// send the message and catch the possible exception
try {
cgw.send("007", "0101234567", "CGW Java API"); } catch (CGWException e) {
System.out.println(e);
}
}
// The main method used to start the sender public static void main(String[] args) {
}
}
Note that the class CGW instance was created with no parameters. In this case the Java API uses the default values to connect Provider Server at the localhost in port 21772. The
constructor could also have been called using specified Provider Server connection settings: CGW cgw = new CGW(“server.company.com”, 21772);
The actual sending is done within a try-catch block, since the send method throws an
exception if the sending fails. When the API is in the Send Only mode, you do not have to care about the CGWSession instance the send method returns. The session status will be correct if no exception is thrown. The next example shows how to use the Java API correctly in a Java servlet. The most important thing to notice is that the class CGW should be constructed only once in an application. In a servlet, the correct location is the init() method. This way the connection to Provider Server is kept open and sending messages is faster. If you wish to create a subclass that sends messages, just pass the CGW instance as a reference; do not create a new instance each time the class is used.
import javax.servlet.*; import javax.servlet.http.*; import java.io.*;
import cgw.*;
public class Sender extends HttpServlet { // Define a global CGW instance
CGW cgw;
public void init(ServletConfig config) throws
ServletException {
super.init(config);
// Construct a new CGW instance in servlet init
cgw = new CGW();
}
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
response.setContentType("text/plain");
PrintWriter out = new PrintWriter(response.getWriter()); // Read the message and recipient parameters
String recipient = request.getParameter("recipient"); String message = request.getParameter("message"); // send the message and catch the possible exception
try {
cgw.send("007", recipient, message);
out.println("The message was successfully sent."); } catch (CGWException e) {
out.println("Sending the message failed.");
}
}
}
Following examples show how to use Send Only service type with servlet:
If you have a servlet engine running in the localhost (default http port 80), you will be able to send SMS messages just by calling the servlet:
http://localhost/sms/Sender?message=Test+message&recipient=0101234567
This would be an easy way to create, for example, a service that sends ringing tones to subscribers. An HTTP interface of Provider Server can be used to receive the SMS request and configured to call the servlet. The Provider Server application type should be set to
receive-only for the keyword since the actual ringing tone is sent by the servlet. The application
for incoming message configuration would be as follows:
http://localhost/sms/Sender?message=$(1)&recipient=$(M)
The ringing tone could be ordered by sending an SMS, e.g. ‘TONE FINLANDIA’ and the HTTP request that the servlet gets is:
http://localhost/sms/Sender?message=FINLANDIA&recipient=0101234567 See the JavaDoc documentation for further details on sending binary Messages.
2.2 Developing a Receive Only Application
When an application is designed to receive SMS messages, Java API callback functionality has to be implemented. The callback API is based on an inheritable and overridable
architecture. It is very similar to, e.g. the Servlet API. To use the interface in an application, the application class has to be extended from the superclass CGW. The SMS message interface contains two overridable methods in class CGW that handle incoming messages and session status information. By default, the only method that needs to be overridden, is the
receive(CGWMessage) method.
// Inherit the class from superclass CGW public class Receiver extends CGW { public Receiver() {
// Start the receiver at default port 21779
try {
this.listen();
} catch (CGWException ce) {
System.out.println("Receive error: " + ce);
} // Loop indefinitely while (true) { try { Thread.sleep(10000); } catch (InterruptedException e) {} } }
// Override the receive SMS message method public void receive(CGWMessage message) {
// Print the text of the incoming message
System.out.println("The received message is " +
message.getMessage());
}
// The main method used to start the receiver public static void main(String[] args) {
new Receiver();
}
}
2.3 Developing a Query/reply Application
The possible reply messages are sent blocked (a confirmation by the SMSC is required before the send() method returns). The following example demonstrates a simple application that receives SMS messages to a local port 21779 from Provider Server and sends back a reply message. The session status information can be found from the returned CGWSession class, although an exception is thrown if an error occurs during the sending.
If you wish to send the reply message non-blocking, you have to set the delivery
synchronization off. This can be done with the setDeliverySync() method in the class CGW. In this case the returned CGWSession contains only the message ID of the sent message. The actual session status information has to be received by overriding the receive(CGWSession)
method. The information is just printed on the screen: // Override the session status receive method public void receive(CGWSession session) { if (session.isFailed()) { System.out.println("Session failed: " + session.getMessageId()); } else { System.out.println("Session ready: " + session.getMessageId()); } }
The previous example assumes that the SMS message was received using a Query/reply type application from Provider Server. This type of a session always requires a reply message in order to close the session and bill the event. The reply can be sent in several ways. The receiver example used the simple send()method that requires only the message text to be able to send the reply. You can send the reply, e.g. by constructing a new CGWMessage. Note that the sender and recipient numbers cannot be altered since the reply should be sent to the actual message sender.
public void receive(CGWMessage message) {
// Get the text of the incoming message and send a reply CGWMessage reply = new CGWMessage();
reply.setText("From Java API: " + message.getText());
try {
CGWSession session = this.send(reply);
} catch (CGWException ce) {
System.out.println("Send error: " + ce);
}
}
It is also possible to reply with the same message instance that was received. Although it would be seemingly possible to change the sender and recipient numbers, the reply will still be sent to the original sender using the same Provider Server application, from which the
message was received. Use this only when the reply is sent to the original sender of the message.
public void receive(CGWMessage message) {
// Get the text of the incoming message and send a reply message.setText("From Java API: " + message.getText());
try {
CGWSession session = this.send(message);
} catch (CGWException ce) {
System.out.println("Send error: " + ce);
}
}
2.3.1 Closing a Message Session
If a reply message has to be sent to a different mobile station than where it came from, the original session has to be either aborted or finished. The session has to be aborted, e.g. in high-priced services where invalid subscriber input would be otherwise billed. However, an informational info message should still be sent to explain the situation. In both cases the reply message has to be sent using a different Provider Server application than from which the message was received. When the incoming message session is aborted or finished, it is possible to freely set the sender and recipient numbers of the new message. You should always create a new message instance when the incoming message session has been finished or aborted, for example to send an error message.
public void receive(CGWMessage message) { // Abort the received message (not billed)
message.abort();
// Or finish the session (will be billed)
message.ready();
// Get the sender of the incoming message and send a reply CGWMessage reply = new CGWMessage("007",
message.getSender());
reply.setText("From Java API: " + message.getText());
try {
CGWSession session = this.send(reply);
} catch (CGWException ce) {
System.out.println("Send error: " + ce);
}
2.3.2 Multiple Reply Messages within One Session
In some services it is required to send several reply messages to the same subscriber within one session. The number of the replied messages can differ, but the session will be billed as specified in Content Gateway. When all replied messages are sent within the same receive-callback, they will be combined into one session. Provider Server needs to be informed to wait for more messages for the current session by calling the continueSession() method for the
incoming message:
public void receive(CGWMessage message) {
// Create three reply messages and continue session message.continueSession();
CGWMessage reply1 = new CGWMessage("Reply 1: "
+message.getText());
CGWMessage reply2 = new CGWMessage("Reply 2: " +
message.getText());
CGWMessage reply3 = new CGWMessage("Reply 3: " +
message.getText());
try {
CGWSession session1 = this.send(reply1); CGWSession session2 = this.send(reply2);
CGWSession session3 = this.send(reply3);
} catch (CGWException ce) {
System.out.println("Send error: " + ce);
}
}
If the session callback is used, you will receive three separate CGWSession instances, but the session ID will be the same for all of them. The message ID is the same ID that can be found from the returned CGWSession instance for each message.
2.4 Developing a Push Application
A Push service with the JAVA API is implemented with the Send Only and Receive Only service types. You can use the same mechanisms as described in chapters 2.1 and 2.2. You need to implement a receiver, which handles incoming push open and close messages (See Service Development Guide). Sending the actual content can be done with the send method. You can define the used application with the method String SetApplication(String
application_name).
import cgw.*; import java.util.*; public class TestSend {
// Define a global CGW instance public static void main(String[] args) {
CGW cgw;
cgw = new CGW();
cgw.setHost("localhost");
cgw.setPort(21772);
CGWMessage message = new CGWMessage();
// Service name/service id setting message.setApplication("F1"); message.setSender("12121");
message.setRecipient("0101234567");
message.setText("Hungary GP result: 1. Fernando Alonso, 2. Kimi Raikkonen, 3. Juan Pablo Montoya.");
message.setCharge("78");
message.setBillingInfo("Billing info!");
// send the message and catch the possible exception
try {
cgw.send(message);
System.out.println("The message was successfully sent."); } catch (CGWException e) {
System.out.println("Sending the message failed."); System.out.println("Exception: " + e);
}
}
Query/reply service type cannot be used in implementing the whole push functionality, since receiving push orders and sending the actual content needs to be done separately. In order to receive content, the end user needs to have an active push order.
2.5 Messages
There are two possibilities of receiving for example an error message from the API.
1. Java Api has a class CGWException(java.lang.String info). It can be used to catch error messages if message sending fails. As in the following example:
// send the message and catch the possible exception try {
cgw.send(message);
} catch (CGWException e) {
System.out.println("Exception: " + e);
}
2. Class CGWSession has also methods for handling session related messages. Method
getInfo() gets a string representation of the message associated with the session. Value is
null, if there is no info message available. Otherwise info offers detailed information about the error. For example:
// Get detailed info of session if (session.isFailed()) {
System.out.println("Session failed: " + session.getMessageId());
System.out.println("Info: " + session.getInfo());
}
More information about the message handling can be found from JavaDoc documentation.
2.6 Implementing Positioning Interface
CGW provides end-user location information if agreed with the operator. The basic positioning data includes end-user coordinates and an estimation of the accuracy. The values (latitude, longitude and estimate) can be read using the methods in the CGWMessage class. Other available position- related data can be read using the getProperty() method. See the JavaDoc
documentation for more detailed information.
First, configure the service with Provider Admin and ask the operator to add positioning support to your service. Your service ID number is needed.
Then write your Java application. For example, an extremely simple Java application that only returns the location coordinates:
public class SPSExample extends CGW { // Start the listener and loop
public SPSExample() throws CGWException {
listen(12345); while (true) { try { Thread.sleep(10000); } catch (InterruptedException e) { } } }
// Override the receive SMS message method (with positioning) public void receive(CGWMessage message) {
try {
// Get parameters from incoming message and send reply String position = "Your position:\n";
position += "Lat: " + message.getLatitude() + "\n"; position += "Lon: " + message.getLongitude() + "\n"; position += "Acc: " + message.getEstimate() + "\n"; position += "City: " +
message.getProperty("position-city") + "\n";
this.send(position);
} catch (CGWException ce) {
System.err.println("Send error: " + ce);
}
}
public static void main(String[] args) {
try {
new SPSExample();
} catch (CGWException e) {
e);
}
}
}
NOTE When positioning is enabled, the end-user MSISDN number is displayed as a position ID that has no relation with the actual MSISDN. However, the ID can be used normally when sending messages to the end-user.
3 Classes and Methods
See the JavaDoc documentation about detailed class and method descriptions.
4 Error Messages in Java API
Java API can return the following error messages:
Error Message Description
listen: Address in use. Change port.
The defined port is in use and the listening failed. You need to change the port number or shut down the other listening application.
listen error Listening the defined port failed for some other
reason. Try again later. Timeout: no response in […] seconds
The session has not received a response during the defined time -> timeout has occurred. Find out the reason why the response is delayed and fix it.
Provider Server not responding
Provider Server does not respond. Check that Provider Server is up and running. Check also that you are trying to connect to it properly.
Connection refused
The connection to the defined application is refused. Find out the reason why you cannot connect the application and fix it. The reason can be, for example, insufficient user rights for the application.
Connection failed The connection to the defined application failed for some other reason.
op:err session-id: txt:Java API: end:err
CGW error information on the SMS message transaction. An instance of this message is received in the API when sending or receiving a message fails. The error text can be: “Error
processing message” or something that has
Input queue closed The input queue has been closed for some reason. Try again.
Timeout: close processor The defined timeout has been reached. Message text missing The message to be sent does not include text.
Add the message.
Sender missing The message to be sent does not include the
sender. Add the sender.
Recipient missing The message to be sent does not include the
recipient. Add the recipient. Operation type missing
A type for the operation has not been defined (parameter op). You need to define this parameter (delivery, ok, msg, status, err). Invalid operation type: The defined operation type is unknown. The
type should be: Delivery, ok, msg, status or err. Operation missing: A type for the operation has not been defined
(parameter end).
Message type missing The message type is missing. Add the message type.
Application missing The application is missing. Add the application. Cannot open log file
Opening the log file failed. Try to find out why the log file could not be opened (for example, due to permissions).
Adding customer failed Adding a customer to the user list failed. Removing customer failed Removing a customer from the user list failed. File read error Reading a specified file (text or binary) failed. Cannot read customer file Reading a customer (User Group) file failed.
