Tgw 1.0.3 API Guide

8/11/2019 Tgw 1.0.3 API Guide

http://slidepdf.com/reader/full/tgw-103-api-guide 1/30

8/11/2019 Tgw 1.0.3 API Guide


2Copyright © Nokia Corporation 2002.

PURPOSE. This document describes the product(s) defined in the introduction of thisdocument and is subject to change without notice. This document is intended for the use of

Nokia Corporation’s customers for the sole purposes of the agreement under which it issubmitted. It has been prepared to be used by professional and properly trained personnel,

and the customer assumes full responsibility when using it.PROVIDED “AS IS”. Nokia Corporation has used reasonable efforts to ensure that theinstructions contained in the document are adequate and free of material errors andomissions. This document is provided on an “AS IS” basis, with no warranty of any kind.

NOKIA CORPORATION SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIEDWARRANTIES, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFFITNESS, MERCHANTABILITY AND TITLE. Further, the information or statementscontained in this document concerning the suitability, capacity or performance of the

product(s) concerned are not binding, except as may explicitly be agreed to by NokiaCorporation in the agreement under which this document is submitted.

Limitation of Liability. Nokia Corporation’ liability for any errors in the document islimited to the documentary correction of errors. IN NO EVENT SHALL NokiaCorporation HAVE ANY LIABILITY FOR ANY DAMAGES OF WHATEVER

NATURE, WHETHER DIRECT, INDIRECT, SPECIAL, INCIDENTAL, ECONOMICOR CONSEQUENTIAL, that might arise from the use of or inability to use this documentor anything contained herein.

Intellectual Property Rights. This document and the product it describes are protected bycopyright according to applicable laws. No part of this document may be reproduced ortransmitted in any form or by any means without the prior written permission of NokiaCorporation. Nokia and Nokia Connecting People are registered trademarks of NokiaCorporation.

Product names mentioned in this document may be trademarks of their respectivecompanies and are mentioned for identification purposes only.

Copyright © Nokia Corporation 2002. All rights reserved.

8/11/2019 Tgw 1.0.3 API Guide


DN01161124 3Issue 1-3 en Copyright © Nokia Corporation 2002.

1 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.1 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.2 Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 API development setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 TgwApi.jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 WebLogic context configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Compilation setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 Runtime setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 TGW API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Subscriber creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Subscriber modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.4 Subscriber retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.5 Subscriber deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.6 Subscriber activation/deactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 AdminSubscriberAction class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.1 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 CreateSubscriber method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2.5 Required subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.3 ModifySubscriber method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.5 Required subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.3.6 Non-modifiable subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.4 RetrieveSubscriber Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.5 DeleteSubscriber Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

8/11/2019 Tgw 1.0.3 API Guide



4.5.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.5.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.5.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.6 UpdateUserActiveStatus Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.6.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.6.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.6.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 AdminHelperAction class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.1 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 EncryptPassword method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.2.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6 Associated classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196.1 Subscriber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196.2 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196.3 Required fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226.4 Optional fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

7 Example code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257.1 CreateSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257.2 ModifySubscriber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267.3 RetrieveSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277.4 DeleteSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277.5 DeactivateSubscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287.6 ActivateSubscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

8/11/2019 Tgw 1.0.3 API Guide


Preface


1 Preface

1.1 About this documentThe purpose of this document is to present the Application Protocol Interface (API) thatTerminal Gateway (TGW) exposes. For each exposed interface on the TGW API, thisdocument presents conceptual information, description of the exposed interface, andexample interacting code. Software developers writing external TGW applications canuse this document to gain an understanding of the TGW API.

1.2 Scope

1.2.1 Audience

This document is intended for software developers writing Java applications external toTGW but desiring to integrate with TGW-supplied functionality. Software developersintegrating with the TGW API are expected to possess basic knowledge of WebLogicApplication Server including an understanding of how to determine the URL and port onwhich a WebLogic Application Server is running. Also, developers integrating with theTGW API are required to possess basic knowledge of the Java programming language.

1.2.2 Environment

This document assumes an environment where WebLogic Application Server1 and TGWare already installed on a server. The external TGW client application must reside on amachine that has access to the WebLogic server where TGW resides.

1.3 Acronyms

This section describes the terminology that will be found in the document.

Acronym Meaning

API application protocol interface

TGW Terminal Gateway

NA New Album

PA Personal Album

$WL_HOME WebLogic home directory

EJB enterprise java bean

SMSC Short Message Service Center

Table 1 Acronyms

8/11/2019 Tgw 1.0.3 API Guide


Preface


1.4 Revision history

Date Issue Release version

February 2002 1-0 en TGW 1.0

April 2002 1-1 en TGW 1.0.1

July 2002 1-2 en TGW 1.0.2

August 2002 1-3 en TGW 1.0.3

Table 2 Revision history

8/11/2019 Tgw 1.0.3 API Guide


API development setup


2 API development setup

This section describes the full configuration setup required for using the TGW API.

2.1 TgwApi.jar file

A file named TgwApi.jar contains the TGW API. This file is installed on the server inthe $WL_HOME/lib directory as part of the TGW installation. Integration with the TGWAPI requires the TgwApi.jar file to be copied from the server onto the machine hosting theexternal application.

2.2 WebLogic context configuration

com.nokia.ag.ui.action.initialcontext.properties is a propertiesfile that resides inside the TgwApi.jar file. This properties file contains two propertyelements that must be modified in order to use the TGW API.

The java.naming.provider.url property should be set to the URL and port of theWebLogic Server providing the JNDI naming service.

The java.naming.factory.initial property should simply be uncommented.

2.3 Compilation setup

Compilation of an external application with the TGW API requires the existence of theJava 2 Platform Standard Edition (version 1.3.1 or higher) on the external applicationdevelopment machine. The TgwApi.jar file also must reside on the externalapplication development machine. Include TgwApi.jar in the system classpath. Oncethe classpath is set up correctly, use the java import statement in the source code of theexternal application to import the following classes:

• com.nokia.ag.ui.data.Subscriber

• com.nokia.ag.ui.action.subscriber.AdminSubscriberAction

• com.nokia.ag.tgw.ui.action.AdminHelperAction

• com.nokia.ag.ui.action.SystemException

• com.nokia.ag.ui.action.ApplicationException

8/11/2019 Tgw 1.0.3 API Guide



2.4 Runtime setup

As with the compilation process described in the previous section, running a TGWexternal application requires the Java 2 Platform Standard Edition (version 1.3.1 orhigher). The TGW installation process loads the TgwApi.jar and AgCommon.jar files onto the server in the $WL_HOME/lib directory. The WebLogic installation

process loads the weblogic.jar file into this same directory. These files must be copiedfrom the server to the external application machine and included in the machine's systemclasspath.

Also, a java.naming.provider.url system property must be set. This system property must be set to the same value as the value assigned to the property of the samename in the com.nokia.ag.ui.action.initialcontext.properties fileThat is, when running a TGW external application from the command line, use the -Doption:

java < classpath settings > -Djava.naming.provider.url=t3://< WebLogicServerIPAddress >:< WebLogicListeningPort >

See Section 2.2, “WebLogic context configuration” , for more information about thissystem property.

8/11/2019 Tgw 1.0.3 API Guide


TGW API


3 TGW API

This section provides the reader with a conceptual understanding of the TGW API. Ageneral description of the TGW API is presented first, followed by an overview of thespecific functionality.

3.1 Overview

The TGW API supports a subset of the TGW administrative functionality. Normaladministrative tasks are performed via the Web-based MMS Application Administrator.Through this application, all TGW administrative functionality is available. The TGWAPI exposes a functional subset of TGW’s internal administrative interfaces for externaluse. The exposed functional subset includes methods for creating, retrieving, andmodifying a TGW subscriber.

3.2 Subscriber creation

The TGW API provides the functionality for creating a TGW subscriber. Thisfunctionality covers adding a new subscriber to the subscriber database, creating a storageaccount in the message store for the new subscriber, and performing the necessary cleanupoperations should a failure occur during the creation process. Creation failures couldinclude: a database system failure, a message store system failure, a create rejection due toan existing and active subscriber possessing the same user name, or a create rejection dueto an existing, active subscriber possessing the same MSISDN.

3.3 Subscriber modification

The TGW API provides the functionality for modifying an existing TGW subscriber. Thisfunctionality covers changing the subscriber information of the specified subscriber and

performing the necessary cleanup operations should a failure occur during themodification process. Failures that could result include a database system failure and amodify rejection due to an existing, active subscriber possessing the same MSISDN.

Subscriber modification does not occur on a per field basis. The subscriber modificationfunctionality requires complete, new subscriber information to be used for updating aspecific subscriber. This means that all subscriber information must be sent to thesubscriber modification process. The retrieve subscriber functionality exposed by thisTGW API can be used to assist in constructing the unchanged subscriber information.

8/11/2019 Tgw 1.0.3 API Guide



A few caveats exist for the subscriber modification functionality. A subscriber’s username cannot be modified using this functionality. The provided user name is used todetermine the subscriber intended for modification. The modification operation can beused to inactivate a specified subscriber. A subscriber’s active field maintains the active/

inactive status of a subscriber.

3.4 Subscriber retrieval

The TGW API provides the functionality for retrieving an existing TGW subscriber. Forthe purpose of keeping the TGW API simple, retrieval by subscriber user name is the onlyretrieval functionality supported. Upon successful retrieval of the specified subscriber, aSubscriber object containing the associated subscriber information is returned. Failuresthat could result include a database system failure or a failure to find the specified user inthe database.

3.5 Subscriber deletion

The TGW API provides the functionality for deleting one or more existing TGWsubscribers. This functionality covers removing an existing subscriber from thesubscriber database, removing the subscriber's account from the message store, and

performing the necessary cleanup operations should a failure occur during the deletion process. Possible deletion failures include a database system failure, a message storesystem failure, and failure to delete due to the specified user not being found in the system.

Note: Note: Deleting a subscriber results in the permanent removal of the

subscriber's data from the system.

3.6 Subscriber activation/deactivation

The TGW API provides the functionality for activating/deactivating one or more existingTGW subscribers. This functionality covers changing the affected subscribers' statuses toinactive/active. Deactivation differs from the delete operation in that subscribers that aredeactivated are not removed from the system. Subscriber accounts that have beendeactivated can be recovered by reactivating the subscriber's account.

8/11/2019 Tgw 1.0.3 API Guide


AdminSubscriberAction class


4 AdminSubscriberAction class

The majority of the TGW API is exposed through the AdminSubscriberAction class. This class contains a number of public methods by which TGW administrativefunctionality can be accessed. The methods supported for the TGW API are:

• CreateSubscriber

• ModifySubscriber methods

• RetrieveSubscriber

• DeleteSubscriber Method

• UpdateUserActiveStatus method

4.1 Class declarationpublic class AdminSubscriberAction extends Action{

public void createSubscriber( Subscriber newSubscriber )throws ApplicationException, SystemException

{}

public void modifySubscriber( Subscriber newSubscriberData )throws ApplicationException, SystemException

{}

public Subscriber retrieveSubscriber( String filterType, StringfilterValue )

throws ApplicationException, SystemException{}

…

}

4.2 CreateSubscriber method

4.2.1 Description

The createSubscriber method creates a subscriber according to the subscriber data passed into this method via its lone parameter. This method handles the setup of the NewAlbum (NA) and Personal Album (PA) storage areas for the new subscriber as well asstorage of the subscriber data for the new subscriber. After successful creation of asubscriber, the message store contains an account under the specified user name. Thedatabase should contain a subscriber record holding the specified subscriber information.

8/11/2019 Tgw 1.0.3 API Guide



4.2.2 Parameters

The lone parameter expected by the createSubscriber method is a Subscriber object. Thereceived Subscriber object must contain all required subscriber information (see Section

4.2.5 , “Required subscriber data” ). If a password is specified in the Subscriber object itmust be in encrypted format (see Section 5.2, “EncryptPassword method” for informationabout encrypting passwords).

4.2.3 Return value

A value is not returned from this method. Execution is simply returned to the invoker aftersuccessful completion.

4.2.4 Exceptions

Two types of exceptions can be thrown from the createSubscriber method,ApplicationException and SystemException . AnApplicationException is thrown when the database or the message store rejectsstoring the subscriber information or creating the subscriber mailbox. The database mayreject storage of the subscriber information because the user name or MSISDN is the sameas that of an existing subscriber. Also, the database may reject subscriber informationstorage because the creation of the subscriber exceeds the maximum subscriber limitallowed by the TGW license. A SystemException is thrown in all other error cases.

4.2.5 Required subscriber data

Data validation is not included as part of the TGW API. However, certain information isimperative to the successful operation of the TGW system. The following fields areconsidered mandatory subscriber information. Subscriber creation should not be carriedout without the following subscriber data (see Section 6.3, “Required fields” for moreinformation):

• User name

Note: Password - The password is not required for the API. However, if thesubscriberPasswordRequired property of the security configuration

parameter is set to true by the administrator, and no password is set up for thesubscriber, the subscriber will not be able to log in to the account.

• Billing ID

• Active flag

• First name

• Last name

• MSISDN

• Device e-mail

• SMSC MSISDN

8/11/2019 Tgw 1.0.3 API Guide




• COS name

4.3 ModifySubscriber method

4.3.1 Description

The modifySubscriber method updates an existing subscriber's information withnew subscriber information. Specify the subscriber to be updated by user name. Aftersuccessful modification of the specified subscriber, the database record corresponding tothat subscriber contains the new subscriber information.

4.3.2 Parameters

The lone parameter expected by the modifySubscriber method is a Subscriber

object. The received Subscriber object must contain the complete list of requiredsubscriber information (see Section 4.3.5 , “Required subscriber data” ). If a password isspecified in the Subscriber object it must be in encrypted format (see information aboutencrypting passwords). With the exception of the user name, all of the data contained inthe received Subscriber object replaces the existing subscriber information in thedatabase.

Note: The retrieveSubscriber method can be used to load theSubscriber object with subscriber information for the subscriberspecified for updating.

4.3.3 Return valueA value is not returned from this method. Execution is returned to the invoker aftersuccessful completion.

4.3.4 Exceptions

Two types of exceptions can be thrown from the modifySubscriber method;namely, ApplicationException and SystemException . AnApplicationException is thrown in the case when the database rejects updatingthe subscriber information. The database may reject updating the subscriber informationif an existing subscriber has the same MSISDN. A database rejection may also occur whenthe user name of the specified subscriber does not match a user name of any existingsubscriber. A SystemException is thrown in all other error cases.

8/11/2019 Tgw 1.0.3 API Guide



4.3.5 Required subscriber data

Data validation is not included as part of the TGW API. However, certain information isimperative to the successful operation of the TGW system. The following fields are

considered mandatory subscriber information. Subscriber modification should not becarried out without the following subscriber data (see Section 6.3, “Required fields” formore information):

• User name

Note: Password - The password is not required for the API. However, if thesubscriberPasswordRequired property of the security configuration

parameter is set to true by the administrator, and no password is set up for thesubscriber, the subscriber will not be able to log in to their account.

• Billing ID

• Active flag• First name

• Last name

• MSISDN

• Device e-mail

• SMSC MSISDN

• COS name

4.3.6 Non-modifiable subscriber data

Although the subscriber’s user name is a required field for the subscriber modification process, a subscriber's user name cannot be modified once established during subscribercreation. The subscriber modification process uses the provided subscriber user name todetermine the existing subscriber intended for modification.

8/11/2019 Tgw 1.0.3 API Guide




4.4 RetrieveSubscriber Method

4.4.1 Description

The retrieveSubscriber method retrieves a Subscriber object according tothe specified subscriber user name. The subscriber information associated with thespecified subscriber user name is retrieved from the database and returned in aSubscriber object.

4.4.2 Parameters

This method possesses two parameters. The first parameter specifies the subscriber fieldon which to search. The TGW API supports only search by subscriber user name. As aresult, the first parameter passed into this method will always be the same. Searching bysubscriber user name requires the first parameter to receive a string containing

“userName”. The second parameter expects a string specifying the user name of thesubscriber to be retrieved.

4.4.3 Return Value

The subscriber information associated with the specified subscriber user name is retrievedfrom the database and returned in a Subscriber object.

4.4.4 Exceptions

Two types of exceptions can be thrown from the retrieveSubscriber method;namely, ApplicationException and SystemException . AnApplicationException is thrown in the case when a subscriber containing thespecified user name cannot be found in the database. A SystemException is thrownin all other error cases.

4.5 DeleteSubscriber Method

4.5.1 Description

The deleteSubscriber method permanently removes each existing, specifiedsubscriber from the system. Subscriber removal from the system involves erasing the

subscriber's information from the subscriber database as well as removal of thesubscriber's message store account.

4.5.2 Parameters

The lone parameter expected by the deleteSubscriber method is an ArrayList of usernames. Each user name in the received list identifies a subscriber who is to be deleted.

8/11/2019 Tgw 1.0.3 API Guide



4.5.3 Return Value

A value is not returned from this method. Execution is simply returned to the invoker aftersuccessful completion.

4.5.4 Exceptions

Two types of exceptions can be thrown from the deleteSubscriber method;namely, ApplicationException and SystemException . AnApplicationException is thrown when a failure occurred in either erasing one ormore subscribers' data from the database or removing one or more subscribers' accountsfrom the message store. A SystemException is thrown in all other error cases.

4.6 UpdateUserActiveStatus Method

4.6.1 Description

The updateUserActiveStatus method updates one or more existing subscribers'active/inactive statuses.

4.6.2 Parameters

The updateUserActiveStatus method includes two parameters. The first parameter identifies the list of subscribers whose active/inactive status is to be updated.An ArrayList holds one or more subscriber user names. Each user name identifies asubscriber whose active/inactive status is to be updated. The second parameter specifies

the new status. All users identified in the first parameter are to have their active statusesupdated with this value.

4.6.3 Return Value

A value is not returned from this method. Execution is returned to the invoker aftersuccessful completion.

4.6.4 Exceptions

Two types of exceptions can be thrown from the updateUserActiveStatus method; namely, ApplicationException and SystemException . AnApplicationException is thrown when the database reports an error in updatingone or more of the specified subscribers. A SystemException is thrown in all othererror cases.

8/11/2019 Tgw 1.0.3 API Guide


AdminHelperAction class


5 AdminHelperAction class

The AdminHelperAction class contains an encrypted password method that handles password encryption for all TGW subscriber passwords. This method must be used beforea subscriber’s password can be submitted to the create or modify subscriber methods ofthe TGW API.

5.1 Class declaration

public class AdminHelperAction extends Action{

public String encryptPassword( String password )throws ApplicationException, SystemException

{}

}

5.2 EncryptPassword method

5.2.1 Description

The encryptPassword method converts a specified clear text password into an

encrypted format supported by TGW. After successful encryption of the specified password, the returned password is ready for use in the create or modify subscribercreation process.

5.2.2 Parameters

The encryptPassword method is a clear text password.

5.2.3 Return value

An encrypted TGW password created from the received clear text password is returnedfrom this method.

5.2.4 Exceptions

Two types of exceptions can be thrown from the createSubscriber method:ApplicationException and SystemException . A SystemException isthrown in the case when an error occurs in the communication process with TGW’ssecurity EJB. An ApplicationException is thrown in all other error cases.

8/11/2019 Tgw 1.0.3 API Guide



8/11/2019 Tgw 1.0.3 API Guide


Associated classes


6 Associated classes

6.1 Subscriber An instance of the Subscriber class is used for the createSubscriber andmodifySubscriber methods. The data held by this instance indicates the informationthat should be used in the creation or modification process. The Subscriber class ismainly a subscriber information holder consisting of get and set methods for retrievingand holding information.

6.2 Class declaration

public class Subscriberimplements User, Serializable

{public Subscriber(){}

public final String getUserName(){}

public final void setUserName(String userName){}

public final String getPassword(){}

public final void setPassword(String password){}

public final String getName(){}

public final void setName(String name){}

public final String getFirstName(){}

public final void setFirstName(String firstName){}

public final String getAddress(){}

8/11/2019 Tgw 1.0.3 API Guide



public final void setAddress(String address){}

public final String getTelephoneNumber()

{}

public final void setTelephoneNumber(String telephoneNumber){}

public final String getEmail(){}

public final void setEmail(String email){}

public final String getMsisdn(){}

public final void setMsisdn(String msisdn){}

public final String getCosName(){}

public final void setCosName(String cosName){}

public final String getExternalEmail(){}

public final void setExternalEmail(String externalEmail){}

public final String getBillingId(){}

public final void setBillingId(String billingId){}

public final boolean isActive()throws ApplicationException

{}

public final void setActive(boolean active){}

8/11/2019 Tgw 1.0.3 API Guide


Associated classes


public final String getSmscMSISDN(){}

public final void setSmscMSISDN(String smscMSISDN)

{}

public final String getCity(){}

public final void setCity(String city){}

public final String getStateProvince(){}

public final void setStateProvince(String stateProvince){}

public final String getPostalCode(){}

public final void setPostalCode(String postalCode){}

public final String getCountry(){}

public final void setCountry(String country){}

public final String getNabUrl(){}

public final void setNabUrl( String nabUrl ){}

public final String getPabUrl(){}

public final void setPabUrl( String pabUrl ){}

…

}

8/11/2019 Tgw 1.0.3 API Guide



6.3 Required fields

Field Name Size Limit(characters) Description Assignment

Method

User name 256 Name used by a subscriberwhen accessing TGW’s Web orWAP application.

setUserName

Billing ID 20 Associates a billing ID with asubscriber. Used to track

billable actions performed by asubscriber.

setBillingId

Active NotApplicable

Indicates whether thesubscriber is active or inactive.

setActive

First name 256 Subscriber’s first name. setFirstName

Last name 256 Subscriber’s last name. setName

MSISDN 20 Subscriber's mobile MSISDNassigned by the operator.

setMsisdn

Device e-mail 256 Subscriber’s e-mail addressassigned by the operator.

setEmail

SMSCMSISDN

20 MSISDN of the SMSC to whichthe subscriber has been assignedfor Short Message Service.

setSmscMSISDN

NA URL 256 Subscriber’s New Albumaddress within the messagestore.Note: Only required for themodifySubscriber method

setNabUrl

PA URL 256 Subscriber’s Personal Albumaddress within the messagestore.Note: Only required for themodifySubscriber method

setPabUrl

COS name 50 The subscriber’s assigned Classof Service.

setCosName

Table 3 Required fields

8/11/2019 Tgw 1.0.3 API Guide


8/11/2019 Tgw 1.0.3 API Guide


Example code


7 Example code

This section provides sample code for using the createSubscriber andmodifySubscriber methods of the TGW API. Example code for using theencryptPassword method is also presented in the createSubscriber example.

7.1 CreateSubscriber

public void createSubscriber(){

// Create a Subscriber instance and populate it with the new// subscriber's subscriber dataSubscriber newSubscriber = new Subscriber();newSubscriber.setUserName( "mjordan" );newSubscriber.setCosName( "Gold" );newSubscriber.setBillingId( "23Bulls" );

// The remaining method calls for populating the new Subscriber instance// go here …

try{

// First encrypt the subscriber's passwordString clearTextPassword = newSubscriber.getPassword();String encryptedPassword;AdminHelperAction adminHelperAction = new AdminHelperAction();encryptedPassword = adminHelperAction.encryptPassword(

clearTextPassword );newSubscriber.setPassword( encryptedPassword );

// Pass the new subscriber information into the createSubscriber// method supported by the TgwApi

AdminSubscriberAction adminSubscriberAction = newAdminSubscriberAction();

adminSubscriberAction.createSubscriber( newSubscriber );}catch( SystemException sysException ){

// Error handling code …}catch( ApplicationException appException ){

// Error handling code …}

}

8/11/2019 Tgw 1.0.3 API Guide



7.2 ModifySubscriber

public void modidfySubscriber(){

// Create a new Subscriber instance with the same user name as an// existing subscriberSubscriber newSubscriberInfo = new Subscriber();newSubscriberInfo.setUserName( "mjordan" );

// Populate the subscriber instance with all of the existing subscriber// data that should remain unchanged// NOTE: The retrieveSubscriber method can be used to load a subscriber// object with an existing subscriber's information.newSubscriberInfo.setCosName( "Gold" );

// The remaining method calls for populating the new Subscriber instance// with all of the existing subscriber data that should remain unchanged// go here …

// Populate the subscriber instance with all of the subscriber// information that should replace the corresponding existing// subscriber informationnewSubscriberInfo.setBillingId( "23Wizards" );

// The remaining method calls for populating the new Subscriber instance// with all of the subscriber information that should replace the// corresponding existing subscriber information go here …

try{

// Pass the update subscriber information into the modifySubscriber// method supported by the TgwApiAdminSubscriberAction adminSubscriberAction = new

AdminSubscriberAction();adminSubscriberAction.modifySubscriber( newSubscriberInfo );

}catch( SystemException sysException )

{ // Error handling code …}catch( ApplicationException appException ){


}

8/11/2019 Tgw 1.0.3 API Guide


Example code


7.3 RetrieveSubscriber

public void retrieveSubscriber(){

Subscriber subscriber;

try{

// Retrieve the subscriber information associated with the specified// a user name of "mjordan"AdminSubscriberAction adminSubscriberAction = new

AdminSubscriberAction();subscriber = adminSubscriberAction.retrieveSubscriber( "userName",

"mjordan" );}catch( SystemException sysException ){

// Error handling code …}catch( ApplicationException appException ){


}

7.4 DeleteSubscriber

public void deleteSubscriber()

{

try

{

// Create a list of the subscribers to be deleted

ArrayList deleteList = new ArrayList();

deleteList.add( "mjordan" );

deleteList.add( "dmarino" );

// Perform the delete operation


adminSubscriberAction.deleteSubscriber( deleteList );

}

catch( SystemException sysException )

{


catch( ApplicationException appException )

{

// Error handling code …

}

}

8/11/2019 Tgw 1.0.3 API Guide



7.5 DeactivateSubscribers

public void deactivateSubscribers()

{try

{

// Create a list of the subscribers to be deactivated

ArrayList deactivateList = new ArrayList();

deactivateList.add( "mjordan" );

deactivateList.add( "dmarino" );



adminSubscriberAction.updateUserActiveStatus( deactivateList, 0 );

}catch( SystemException sysException )

{


}


{


}

}

7.6 ActivateSubscribers

public void activateSubscribers()

{

try

{

// Create a list of the subscribers to be activated

ArrayList activateList = new ArrayList();

activateList.add( "mjordan" );

activateList.add( "dmarino" );



adminSubscriberAction.updateUserActiveStatus( activateList, 1 );

}

catch( SystemException sysException )

{


}

8/11/2019 Tgw 1.0.3 API Guide


Example code



{


}

}

8/11/2019 Tgw 1.0.3 API Guide



Tgw 1.0.3 API Guide

Documents

Transcript of Tgw 1.0.3 API Guide