DN01161124 1

Issue 1-3 en Copyright © Nokia Corporation 2002.
Nokia Multimedia Terminal Gateway Release 1.0.3
Part of the Multimedia Messaging Service Application Suite
Subscriber API
Development Guide
2
Copyright © Nokia Corporation 2002.
PURPOSE. This document describes the product(s) defined in the introduction of this
document 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 is
submitted. 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 the
instructions contained in the document are adequate and free of material errors and
omissions. This document is provided on an “AS IS” basis, with no warranty of any kind.
NOKIA CORPORATION SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIED
WARRANTIES, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
FITNESS, MERCHANTABILITY AND TITLE. Further, the information or statements
contained 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 Nokia
Corporation in the agreement under which this document is submitted.
Limitation of Liability. Nokia Corporation’ liability for any errors in the document is
limited to the documentary correction of errors. IN NO EVENT SHALL Nokia
Corporation HAVE ANY LIABILITY FOR ANY DAMAGES OF WHATEVER
NATURE, WHETHER DIRECT, INDIRECT, SPECIAL, INCIDENTAL, ECONOMIC
OR CONSEQUENTIAL, that might arise from the use of or inability to use this document
or anything contained herein.
Intellectual Property Rights. This document and the product it describes are protected by
copyright according to applicable laws. No part of this document may be reproduced or
transmitted in any form or by any means without the prior written permission of Nokia
Corporation. Nokia and Nokia Connecting People are registered trademarks of Nokia
Corporation.
Product names mentioned in this document may be trademarks of their respective
companies and are mentioned for identification purposes only.
Copyright © Nokia Corporation 2002. All rights reserved.
DN01161124 3
Issue 1-3 en Copyright © Nokia Corporation 2002.
1 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.1 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.2 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 API development setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 TgwApi.jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 WebLogic context configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Compilation setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 Runtime setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 TGW API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Subscriber creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Subscriber modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 Subscriber retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Subscriber deletion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.6 Subscriber activation/deactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4 AdminSubscriberAction class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 CreateSubscriber method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.5 Required subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 ModifySubscriber method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.5 Required subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3.6 Non-modifiable subscriber data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 RetrieveSubscriber Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5 DeleteSubscriber Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4
Copyright © Nokia Corporation 2002.
4.5.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.5.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6 UpdateUserActiveStatus Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6.3 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5 AdminHelperAction class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 EncryptPassword method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.3 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 Associated classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.1 Subscriber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2 Class declaration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.3 Required fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.4 Optional fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7 Example code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1 CreateSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.2 ModifySubscriber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.3 RetrieveSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.4 DeleteSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.5 DeactivateSubscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.6 ActivateSubscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Preface
DN01161124 5
Issue 1-3 en Copyright © Nokia Corporation 2002.
1 Preface
1.1 About this document
The purpose of this document is to present the Application Protocol Interface (API) that
Terminal Gateway (TGW) exposes. For each exposed interface on the TGW API, this
document presents conceptual information, description of the exposed interface, and
example interacting code. Software developers writing external TGW applications can
use 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 to
TGW but desiring to integrate with TGW-supplied functionality. Software developers
integrating with the TGW API are expected to possess basic knowledge of WebLogic
Application Server including an understanding of how to determine the URL and port on
which a WebLogic Application Server is running. Also, developers integrating with the
TGW 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 TGW
are already installed on a server. The external TGW client application must reside on a
machine 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
Preface
DN01161124 6
Issue 1-3 en Copyright © Nokia Corporation 2002.
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
API development setup
DN01161124 7
Issue 1-3 en Copyright © Nokia Corporation 2002.
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 in
the $WL_HOME/lib directory as part of the TGW installation. Integration with the TGW
API requires the TgwApi.jar file to be copied from the server onto the machine hosting the
external application.
2.2 WebLogic context configuration
com.nokia.ag.ui.action.initialcontext.properties is a properties
file that resides inside the TgwApi.jar file. This properties file contains two property
elements 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 the
WebLogic 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 the
Java 2 Platform Standard Edition (version 1.3.1 or higher) on the external application
development machine. The TgwApi.jar file also must reside on the external
application development machine. Include TgwApi.jar in the system classpath. Once
the classpath is set up correctly, use the java import statement in the source code of the
external 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
Copyright © Nokia Corporation 2002.
2.4 Runtime setup
As with the compilation process described in the previous section, running a TGW
external application requires the Java 2 Platform Standard Edition (version 1.3.1 or
higher). 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 copied
from the server to the external application machine and included in the machine's system
classpath.
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 same
name in the com.nokia.ag.ui.action.initialcontext.properties file
That is, when running a TGW external application from the command line, use the -D
option:
java <classpath settings> -Djava.naming.provider.url=
t3://<WebLogicServerIPAddress>:<WebLogicListeningPort>
See Section 2.2, “WebLogic context configuration”, for more information about this
system property.
TGW API
DN01161124 9
Issue 1-3 en Copyright © Nokia Corporation 2002.
3 TGW API
This section provides the reader with a conceptual understanding of the TGW API. A
general description of the TGW API is presented first, followed by an overview of the
specific functionality.
3.1 Overview
The TGW API supports a subset of the TGW administrative functionality. Normal
administrative tasks are performed via the Web-based MMS Application Administrator.
Through this application, all TGW administrative functionality is available. The TGW
API exposes a functional subset of TGW’s internal administrative interfaces for external
use. The exposed functional subset includes methods for creating, retrieving, and
modifying a TGW subscriber.
3.2 Subscriber creation
The TGW API provides the functionality for creating a TGW subscriber. This
functionality covers adding a new subscriber to the subscriber database, creating a storage
account in the message store for the new subscriber, and performing the necessary cleanup
operations should a failure occur during the creation process. Creation failures could
include: a database system failure, a message store system failure, a create rejection due to
an existing and active subscriber possessing the same user name, or a create rejection due
to an existing, active subscriber possessing the same MSISDN.
3.3 Subscriber modification
The TGW API provides the functionality for modifying an existing TGW subscriber. This
functionality covers changing the subscriber information of the specified subscriber and
performing the necessary cleanup operations should a failure occur during the
modification process. Failures that could result include a database system failure and a
modify rejection due to an existing, active subscriber possessing the same MSISDN.
Subscriber modification does not occur on a per field basis. The subscriber modification
functionality requires complete, new subscriber information to be used for updating a
specific subscriber. This means that all subscriber information must be sent to the
subscriber modification process. The retrieve subscriber functionality exposed by this
TGW API can be used to assist in constructing the unchanged subscriber information.
10
Copyright © Nokia Corporation 2002.
A few caveats exist for the subscriber modification functionality. A subscriber’s user
name cannot be modified using this functionality. The provided user name is used to
determine the subscriber intended for modification. The modification operation can be
used 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. For
the purpose of keeping the TGW API simple, retrieval by subscriber user name is the only
retrieval functionality supported. Upon successful retrieval of the specified subscriber, a
Subscriber object containing the associated subscriber information is returned. Failures
that could result include a database system failure or a failure to find the specified user in
the database.
3.5 Subscriber deletion
The TGW API provides the functionality for deleting one or more existing TGW
subscribers. This functionality covers removing an existing subscriber from the
subscriber 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 store
system 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 existing
TGW subscribers. This functionality covers changing the affected subscribers' statuses to
inactive/active. Deactivation differs from the delete operation in that subscribers that are
deactivated are not removed from the system. Subscriber accounts that have been
deactivated can be recovered by reactivating the subscriber's account.
AdminSubscriberAction class
DN01161124 11
Issue 1-3 en Copyright © Nokia Corporation 2002.
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 administrative
functionality can be accessed. The methods supported for the TGW API are:
• CreateSubscriber
• ModifySubscriber methods
• RetrieveSubscriber
• DeleteSubscriber Method
• UpdateUserActiveStatus method
4.1 Class declaration
public 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, String
filterValue )
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 New
Album (NA) and Personal Album (PA) storage areas for the new subscriber as well as
storage of the subscriber data for the new subscriber. After successful creation of a
subscriber, the message store contains an account under the specified user name. The
database should contain a subscriber record holding the specified subscriber information.
12
Copyright © Nokia Corporation 2002.
4.2.2 Parameters
The lone parameter expected by the createSubscriber method is a Subscriber object. The
received 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 it
must be in encrypted format (see Section 5.2, “EncryptPassword method” for information
about encrypting passwords).
4.2.3 Return value
A value is not returned from this method. Execution is simply returned to the invoker after
successful completion.
4.2.4 Exceptions
Two types of exceptions can be thrown from the createSubscriber method,
ApplicationException and SystemException. An
ApplicationException is thrown when the database or the message store rejects
storing the subscriber information or creating the subscriber mailbox. The database may
reject storage of the subscriber information because the user name or MSISDN is the same
as that of an existing subscriber. Also, the database may reject subscriber information
storage because the creation of the subscriber exceeds the maximum subscriber limit
allowed 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 is
imperative to the successful operation of the TGW system. The following fields are
considered mandatory subscriber information. Subscriber creation should not be carried
out without the following subscriber data (see Section 6.3, “Required fields” for more
information):
• User name
Note: Password - The password is not required for the API. However, if the
subscriberPasswordRequired property of the security configuration
parameter is set to true by the administrator, and no password is set up for the
subscriber, 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
AdminSubscriberAction class
DN01161124 13
Issue 1-3 en Copyright © Nokia Corporation 2002.
• COS name
4.3 ModifySubscriber method
4.3.1 Description
The modifySubscriber method updates an existing subscriber's information with
new subscriber information. Specify the subscriber to be updated by user name. After
successful modification of the specified subscriber, the database record corresponding to
that 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 required
subscriber information (see Section 4.3.5, “Required subscriber data”). If a password is
specified in the Subscriber object it must be in encrypted format (see information about
encrypting passwords). With the exception of the user name, all of the data contained in
the received Subscriber object replaces the existing subscriber information in the
database.
Note: The retrieveSubscriber method can be used to load the
Subscriber object with subscriber information for the subscriber
specified for updating.
4.3.3 Return value
A value is not returned from this method. Execution is returned to the invoker after
successful completion.
4.3.4 Exceptions
Two types of exceptions can be thrown from the modifySubscriber method;
namely, ApplicationException and SystemException. An
ApplicationException is thrown in the case when the database rejects updating
the subscriber information. The database may reject updating the subscriber information
if an existing subscriber has the same MSISDN. A database rejection may also occur when
the user name of the specified subscriber does not match a user name of any existing
subscriber. A SystemException is thrown in all other error cases.
14
Copyright © Nokia Corporation 2002.
4.3.5 Required subscriber data
Data validation is not included as part of the TGW API. However, certain information is
imperative to the successful operation of the TGW system. The following fields are
considered mandatory subscriber information. Subscriber modification should not be
carried out without the following subscriber data (see Section 6.3, “Required fields” for
more information):
• User name
Note: Password - The password is not required for the API. However, if the
subscriberPasswordRequired property of the security configuration
parameter is set to true by the administrator, and no password is set up for the
subscriber, 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 subscriber
creation. The subscriber modification process uses the provided subscriber user name to
determine the existing subscriber intended for modification.
AdminSubscriberAction class
DN01161124 15
Issue 1-3 en Copyright © Nokia Corporation 2002.
4.4 RetrieveSubscriber Method
4.4.1 Description
The retrieveSubscriber method retrieves a Subscriber object according to
the specified subscriber user name. The subscriber information associated with the
specified subscriber user name is retrieved from the database and returned in a
Subscriber object.
4.4.2 Parameters
This method possesses two parameters. The first parameter specifies the subscriber field
on which to search. The TGW API supports only search by subscriber user name. As a
result, the first parameter passed into this method will always be the same. Searching by
subscriber user name requires the first parameter to receive a string containing
“userName”. The second parameter expects a string specifying the user name of the
subscriber to be retrieved.
4.4.3 Return Value
The subscriber information associated with the specified subscriber user name is retrieved
from 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. An
ApplicationException is thrown in the case when a subscriber containing the
specified user name cannot be found in the database. A SystemException is thrown
in all other error cases.
4.5 DeleteSubscriber Method
4.5.1 Description
The deleteSubscriber method permanently removes each existing, specified
subscriber from the system. Subscriber removal from the system involves erasing the
subscriber's information from the subscriber database as well as removal of the
subscriber's message store account.
4.5.2 Parameters
The lone parameter expected by the deleteSubscriber method is an ArrayList of user
names. Each user name in the received list identifies a subscriber who is to be deleted.
16
Copyright © Nokia Corporation 2002.
4.5.3 Return Value
A value is not returned from this method. Execution is simply returned to the invoker after
successful completion.
4.5.4 Exceptions
Two types of exceptions can be thrown from the deleteSubscriber method;
namely, ApplicationException and SystemException. An
ApplicationException is thrown when a failure occurred in either erasing one or
more subscribers' data from the database or removing one or more subscribers' accounts
from 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 a
subscriber 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 statuses
updated with this value.
4.6.3 Return Value
A value is not returned from this method. Execution is returned to the invoker after
successful completion.
4.6.4 Exceptions
Two types of exceptions can be thrown from the updateUserActiveStatus
method; namely, ApplicationException and SystemException. An
ApplicationException is thrown when the database reports an error in updating
one or more of the specified subscribers. A SystemException is thrown in all other
error cases.
AdminHelperAction class
DN01161124 17
Issue 1-3 en Copyright © Nokia Corporation 2002.
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 before
a subscriber’s password can be submitted to the create or modify subscriber methods of
the 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 subscriber
creation 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 returned
from this method.
5.2.4 Exceptions
Two types of exceptions can be thrown from the createSubscriber method:
ApplicationException and SystemException. A SystemException is
thrown in the case when an error occurs in the communication process with TGW’s
security EJB. An ApplicationException is thrown in all other error cases.
18
Copyright © Nokia Corporation 2002.
Associated classes
DN01161124 19
Issue 1-3 en Copyright © Nokia Corporation 2002.
6 Associated classes
6.1 Subscriber
An instance of the Subscriber class is used for the createSubscriber and
modifySubscriber methods. The data held by this instance indicates the information
that should be used in the creation or modification process. The Subscriber class is
mainly a subscriber information holder consisting of get and set methods for retrieving
and holding information.
6.2 Class declaration
public class Subscriber
implements 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()
{
}
20
Copyright © Nokia Corporation 2002.
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)
{
}
Associated classes
DN01161124 21
Issue 1-3 en Copyright © Nokia Corporation 2002.
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 )
{
}

}
22
Copyright © Nokia Corporation 2002.
6.3 Required fields
Field Name
Size Limit
(characters)
Description
Assignment
Method
User name 256 Name used by a subscriber
when accessing TGW’s Web or
WAP application.
setUserName
Billing ID 20 Associates a billing ID with a
subscriber. Used to track
billable actions performed by a
subscriber.
setBillingId
Active Not
Applicable
Indicates whether the
subscriber 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 MSISDN
assigned by the operator.
setMsisdn
Device e-mail 256 Subscriber’s e-mail address
assigned by the operator.
setEmail
SMSC
MSISDN
20 MSISDN of the SMSC to which
the subscriber has been assigned
for Short Message Service.
setSmscMSISDN
NA URL 256 Subscriber’s New Album
address within the message
store.
Note: Only required for the
modifySubscriber
method
setNabUrl
PA URL 256 Subscriber’s Personal Album
address within the message
store.
Note: Only required for the
modifySubscriber
method
setPabUrl
COS name 50 The subscriber’s assigned Class
of Service.
setCosName
Table 3 Required fields
Associated classes
DN01161124 23
Issue 1-3 en Copyright © Nokia Corporation 2002.
6.4 Optional fields
Field Name
Size Limit
(characters)
Description Assignment Method
Address 256 The subscriber’s street
address.
setAddress
City 256 The city in which the
subscriber currently
lives.
setCity
State/Province 256 The state or province in
which the subscriber
currently lives.
setStateProvince
Postal code 256 The postal code
corresponding to the
subscriber’s home
address.
setPostalCode
Country 256 The country in which the
subscriber currently
resides.
setCountry
External e-mail 256 Any e-mail address
belonging to the
subscriber except for the
device e-mail assigned
by the operator (that is
business e-mail address).
setExternalEmail
Telephone
Number
20 Any MSISDN belonging
to the subscriber other
than the subscriber’s
mobile MSISDN
assigned to him/her by
the operator (that is
business phone number).
setTelephoneNumber
Password 20 Password (see note
regarding password on
page 12) used by a
subscriber when
accessing TGW.
setPassword
Table 4 Optional fields
24
Copyright © Nokia Corporation 2002.
Example code
DN01161124 25
Issue 1-3 en Copyright © Nokia Corporation 2002.
7 Example code
This section provides sample code for using the createSubscriber and
modifySubscriber methods of the TGW API. Example code for using the
encryptPassword 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 data
Subscriber 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 password
String 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 = new
AdminSubscriberAction();
adminSubscriberAction.createSubscriber( newSubscriber );
}
catch( SystemException sysException )
{
// Error handling code …
}
catch( ApplicationException appException )
{
// Error handling code …
}
}
26
Copyright © Nokia Corporation 2002.
7.2 ModifySubscriber
public void modidfySubscriber()
{
// Create a new Subscriber instance with the same user name as an
// existing subscriber
Subscriber 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 information
newSubscriberInfo.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 TgwApi
AdminSubscriberAction adminSubscriberAction = new
AdminSubscriberAction();
adminSubscriberAction.modifySubscriber( newSubscriberInfo );
}
catch( SystemException sysException )
{
// Error handling code …
}
catch( ApplicationException appException )
{
// Error handling code …
}
}
Example code
DN01161124 27
Issue 1-3 en Copyright © Nokia Corporation 2002.
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 )
{
// Error handling code …
}
}
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 adminSubscriberAction = new
AdminSubscriberAction();
adminSubscriberAction.deleteSubscriber( deleteList );
}
catch( SystemException sysException )
{
// Error handling code …
}
catch( ApplicationException appException )
{
// Error handling code …
}
}
28
Copyright © Nokia Corporation 2002.
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" );
// Perform the delete operation
AdminSubscriberAction adminSubscriberAction = new
AdminSubscriberAction();
adminSubscriberAction.updateUserActiveStatus( deactivateList, 0 );
}
catch( SystemException sysException )
{
// Error handling code …
}
catch( ApplicationException appException )
{
// Error handling code …
}
}
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" );
// Perform the delete operation
AdminSubscriberAction adminSubscriberAction = new
AdminSubscriberAction();
adminSubscriberAction.updateUserActiveStatus( activateList, 1 );
}
catch( SystemException sysException )
{
// Error handling code …
}
Example code
DN01161124 29
Issue 1-3 en Copyright © Nokia Corporation 2002.
catch( ApplicationException appException )
{
// Error handling code …
}
}
30
Copyright © Nokia Corporation 2002.