ClarifyCRM® eFrontOffice 11.

Using ClearBasic to Access Java

Part Number. M20227-00E11050000

September, 2002
© 1995–2002, Amdocs. All Rights Reserved.
Amdocs Confidential
This manual and the software described herein are subject to your Amdocs Software License and are copyrighted with
all rights reserved. This manual and the software may not be copied, in whole or in part, without written consent of
Amdocs, except as permitted by your Amdocs Software License.
The information in this manual is furnished for informational use only by authorized persons, is subject to change
without notice, and should not be construed as a commitment by Amdocs. Amdocs assumes no responsibility or
liability for any errors or inaccuracies that may appear in this book.
The trademark and service marks of the respective Amdocs companies, including the Amdocs mark and logo, are the
exclusive property of such companies, and may not be used without permission. All other marks mentioned in this
material are the property of their respective owners.

For technical assistance, visit http://clearanswer.clarify.com to submit a case at any time.

 Contents

About This Guide

Audience for This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1 Creating Java and EJB Objects Using ClearBasic APIs

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Global Basic Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
ConnectEjbServerImpl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
DisconnectEjbServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
CreateJavaObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
CreateEjbObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
CallStaticJavaFunction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
GetStaticJavaField. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
GetObjectStaticJavaField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
CreateJavaArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
CreateJavaObjectArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Basic Object Type and JavaObject . . . . . . . . . . . . . . . . . . . . . . . . 19
JavaObject::IsArray. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
JavaObject::GetAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
JavaObject::GetAtObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
JavaObject::Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
JavaObject::ClassName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
JavaObject::IsNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
JavaObject::SetNull. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
JavaObject::Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
JavaObject::CallObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
JavaObject::Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
JavaObject::GetObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
JavaObject::Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Contents 3
 Data Type Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Single Signon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Sample Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Java Exception to ClearBasic Error Mapping . . . . . . . . . . . . . . 29
Java Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Configuration Settings in the clarify.env File . . . . . . . . . . . . . . 32
Extending the EJB host Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
The com.clarify.cb2ejb.EjbAccessor Class . . . . . . . . . . . . . . 33
WlsCSM class implementation . . . . . . . . . . . . . . . . . . . . . . . 36

Index

4 Contents
 About This Guide

This guide describes how to create and call methods on Java and EJB objects.
It provides information on how to integrate a billing system with the
ClarifyCRM Classic Applications.

Audience for This Guide

This guide is intended for implementors and system administrators
responsible for your ClarifyCRM eFrontOffice application.

To use this guide you need to understand:

• ClarifyCRM eFrontOffice and its implementation.
• The ClearBasic language.
• Your billing system.
• The hardware, operating, and database platforms on which CeFO and
Billing Manager are installed.

5
Related Documentation

Related Documentation
You may want to consult the following CeFO Documentation:
• Using RPM for CeFO Installation on UNIX
• ClearBasic Language Reference
• ClearBasic Object Reference
• ClearBasic Programmer’s Guide
• Client Installation Guide
• Data Dictionary Guide
• Flexible Deployment Guide
• Billing Manager Implementation Guide
The various CeFO applications are documented in ClarifyCRM Help. It
includes documentation on using the Billing Manager application.

In addition, check for software release notes containing any late-breaking

information, and check the ClearAnswer web site periodically for further
updates.

6 About This Guide

 How to Use This Guide

How to Use This Guide

This guide contains the following sections:
• Global Basic Methods on page 10, describes how global methods are
called, their uses and where they are implemented.
• Basic Object Type and JavaObject on page 19, describes the Basic Object
Type and JavaObject.
• Data Type Mapping on page 25, describes data type mapping from Basic
type to Java type including Variant.
• Single Signon on page 26, describes how the Single Signon feature works.
• Java Exception to ClearBasic Error Mapping on page 29, describes how
the Extension library converts Java Exceptions into Basic errors.
• Java Output on page 30, describes how the System outputs Java
information, and also describes the contents of the JavaOutput.log file.
• String Handling on page 31, describes how ClearBasic strings are
handled.
• Configuration Settings in the clarify.env File on page 32, describes the
configuration keys used by the Extension library.
• Extending the EJB host Type on page 33, describes how to extend the EJB
host Type.

About This Guide 7

Conventions

Conventions
These special formats are used:

NOTE: Provides additional information that is useful but not always essential.

More Information: Refers you to other sections of this guide or to other documents
for more information.

IMPORTANT: Highlights key considerations to keep in mind.

CAUTION: Highlights important situations that could potentially damage data or

cause system failure.

TIP: Highlights guidelines and helpful hints.

• Monospace is used for programming elements (such as code fragments,

objects, methods, parameters, and HTML tags) and system elements
(such as file names, directories, paths, and URLs).
• Monospace bold is used to distinguish system prompts or screen
output from user responses, as in this example:
username: oracle
home directory: home\app\oracle
• Monospace italic is used for placeholders, which are general names
that you replace with names specific to your site, as in this example:
Clarify_home_directory\dbadmin\dbupgrade\
• Straight brackets signal options in command-line syntax.
deRead [-llf log_filename] [-debug]

8 About This Guide

Chapter 1

Creating Java and EJB Objects

Using ClearBasic APIs

In This Chapter
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Global Basic Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Basic Object Type and JavaObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Single Signon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Java Exception to ClearBasic Error Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Java Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
String Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Configuration Settings in the clarify.env File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Extending the EJB host Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

9
Overview

Overview
This guide describes how to create Java and EJB (Enterprise Java Beans)
objects and to call methods on these objects using the ClearBasic interface.
This feature can be used by all CeFO application customers.

This guide also contains information on agent Single Signon and Billing
System Launching. This function allows users to launch a connection to a
billing system using the CeFO application interface. It also allows a single
login feature so that users can log in to both systems at the same time.

Global Basic Methods

You can call these global methods from any location using Basic script. All
of these methods can set the Basic Script Error object. These methods are
implemented in the Summit Extension module.

ConnectEjbServerImpl
Function ConnectEjbServerImpl ( [HostUrl as String],
[ UserName as String ],
[ Password as String ],
[ Domain as String ],
[ HostType as String ] ) as String

Table 1 describes the ConnectEjbServerImpl parameters.

Table 1 ConnectEjbServerImpl Parameters

parameter name Description

HostUrl The Host Server URL. The URL includes the protocol. For example: t3://
www.amdocs.com. If this parameter is not specified, the setting in the clarify.env
file is used (Ejb_HostUrl). If the Ejb_HostUrl parameter is not specified in the
clarify.env file, the program returns an error message.
UserName The user name for authentication. If the Ejb_UserName parameter in the
clarify.env file contains a value, that setting overrides the UserName value, and
the system uses a global proxy used for all authentication.
Password The password for authentication. If the Ejb_Password setting in the clarify.env file
contains a value, that setting overrides this value, and the system uses a global proxy
used for all authentication.

10 Chapter 1
 Global Basic Methods

Table 1 ConnectEjbServerImpl Parameters (Continued)

parameter name Description

Domain This domain is used when the host requires a domain value. If no value is given (or
set), the Ejb_Domain setting in the clarify.env file is used.
HostType This value specifies the type of the EJB host. This value is case sensitive. It is a
combination of the EJB container and EJB application types. The only host types
supported is WlsGeneric. WlsAmdocs and WlsCSM are reference implementations that
must be customized for your system.
You must use the fully qualified path name of the host type, for example
com.cb2ejb.WlsCSM.
If this value is empty, the Ejb_HostType setting in the clarify.env file is used.
If this value is empty and the Ejb_HostType setting in the clarify.env file does not
exist, the EJB connection may fail and EJB access may not work correctly. You must
provide a correct Ejb_HostType either as a function parameter or as a clarify.env
file setting.
You can extend this functionality to include new host types.

Return Value
This method returns a ConnectionId String. This string gives a unique
identity for an authenticated connection to the EJB server. It can be used
across processes by the Amdocs API. This string typically contains the
remote server URL, the security context, and other information.

Basic scripts must call this method before they create any EJB objects. This
method establishes a connection with a Web Logic EJB server and
authenticates a user.

Usage
Applications do not use this method directly. To connect to the server they
use the ConnectEjbServer() Basic script method substitutes the
Password and UserName value if required and calls the
ConnectEjbServerImpl method.

Creating Java and EJB Objects Using ClearBasic APIs 11

Global Basic Methods

DisconnectEjbServer
Sub DisconnectEjbServer ( ConnectionId as String )

Description
The ConnectionId is the string returned by the ConnectEjbServerImp
method.

This method releases all resources held by the connection string. After this
method is called, the application must not use the ConnectionId.

CreateJavaObject
Function CreateJavaObject (ClassName as String,
[ Param1 as Variant ],
[ Param2 as Variant ],
...
[ Param27 as Variant ] ) as JavaObject

Table 2 describes the CreateJavaObject parameters.

Table 2 CreateJavaObject Parameters

Name Description
ClassName The fully qualified class name. If this is an empty string, a null Java object is created. If
this is not an empty string, this class must exist in the Java class path.
Param1 to These are optional parameters that must match an existing constructor. If no
Param27 parameters are passed, the default constructor is invoked.

Description
This method creates a Java Object instance from the ClassName. It creates a
local Java Object and returns it as a Basic Object with the type set to
JavaObject. The JavaObject type is a Basic application object that is
implemented in the Extension library.

You must call Set <Variable>=<Object Ref>. This method calls a

constructor with matching parameters. To create a null Java object pass this
method an empty ClassName string.

12 Chapter 1
 Global Basic Methods

CreateEjbObject
function CreateEjbObject ( ConnectionId as String,
EjbJndiName as String,
HomeInterfaceClassName as String,
ProxyClassName as String ) as JavaObject

Table 3 describes the CreateEjbObject parameters.

Table 3 CreateEjbObject Parameters

Name Description
ConnectionId This parameter is the string returned by the ConnectEjbServerImpl method.
EjbJndiName This parameter is the JNDI name for the EJB class.
HomeInterface The fully qualified class name for the Home class interface
ClassName
ProxyClassNam The fully qualified class name for the local client proxy
e

Description
This method creates an EJB object and returns the Proxy instance as a
JavaObject. The JavaObject is a Basic application object that is implemented
in the Extension DLL library. It has life-time semantics similar to ActiveX
objects. You must call Set <variable> = <Object Ref>.

Example
The ClearBasic implementation of this function can look like the following:
gCmBean = “amdocsBeans.”
gCmHomePath = “amdocs.csm3g.sessions.interfaces.home.”
gCmApiPath = “amdocs.csm3g.sessions.interfaces.api.”
set CreateCustomer = CreateEjbObject
(gBillingConnId,gCmBean+”NewCustomerConvHome”,gCmHomePat
h+”NewCustomerConvHome”,gCmApiPath+”NewCustomerConv”)

Creating Java and EJB Objects Using ClearBasic APIs 13

Global Basic Methods

CallStaticJavaFunction
Function CallStaticJavaFunction ( ClassName as String,
MethodName as String,
[Param1 as Variant ]
[Param2 as Variant ],
...
[ Param26 as Variant ],
) as Variant

Table 4 describes the CallStaticJavaFunction parameters.

Table 4 CallStaticJavaFunction Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
MethodName The name of the method. This parameter is case sensitive.
Param1 to These are optional parameters. The parameters you use must match the parameters of
Param26 the Java method.

Description
This method calls a static Java method and returns the value as a Variant
type. If the return value of the Java method’s is Void, this method returns
an empty Variant value.

The parameters are matched with the Java parameter data types. For more
information see, Data Type Mapping on page 25

GetStaticJavaField
Function GetStaticJavaField (ClassName as String,
FieldName as String ) as Variant

Table 5 describes the GetStaticJavaField parameters.

Table 5 GetStaticJavaField Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
FieldName The field name. This parameter is case sensitive.

14 Chapter 1
 Global Basic Methods

Description
This function accesses a static field member from a Java class. For example,
to write to the output stream you must access the System.out object. The
returned Java type is converted to a Basic type. If the Java method returns a
JavaObject this function returns a Basic JavaObject type. For more
information see Data Type Mapping on page 25.

GetObjectStaticJavaField
Function GetObjectStaticJavaField ( ClassName as String,
FieldName as String ) as Variant

Table 6 describes the GetObjectStaticJavaField parameters.

Table 6 GetObjectStaticJavaField Parameters

Name Description
ClassName The fully qualified class name. This class must exist in the Java class path.
FieldName The name of the field from which you want to retrieve a value. This parameter is case
sensitive.

Description
This method retrieves a field value from a static class and returns it as a
JavaObject. If the field represents a Java primitive type this method converts
it to the corresponding JavaObject. The type Int is converted to the
java.lang.Integer type.

CreateJavaArray
Function CreateJavaArray ( CbArray as Array,
[CoercionType as String ] ) as JavaObject

Table 7 describes the CreateJavaArray Parameters.

Table 7 CreateJavaArray Parameters

Name Description
CbArray This is a ClearBasic array. The array must be of Basic primitive type.
CoercionType Some Basic data types can be coerced into Java types. For more information see Data
Type Mapping on page 25

Creating Java and EJB Objects Using ClearBasic APIs 15

Global Basic Methods

Description
This method creates a new Java Array object from a ClearBasic array. It
copies the data from the ClearBasic array to the Java array and returns a
JavaObject. Java array indexes always start at 0 and the ClearBasic lower
bound value is mapped to Index 0.

If the ClearBasic array is a multi-dimensional array, this method converts it

to a single dimension Java array.

For example the following Basic array:

dim a(2,3) ‘Basic array

is converted to the following Java array:

a(0,0) Low address (0 index)
a(0,1)
a(0,2)
a(0,3)
a(1,0)
a(1,1)
a(1,2)
a(1,3)
a(2,0)
a(2,1)
a(2,2)
a(2,3) High address (size-1 index)

In some cases you can use the CoercionType string parameter to coerce the
Basic data type to a specific Java type. This action allows you to call Java
methods that take byte[] or char[] parameters from ClearBasic. The
CoercionType string parameter is not case sensitive. This function supports
only Basic primitive types. If you need to create a JavaObject array, use the
CreateJavaObjectArray function. For more information see Data Type
Mapping on page 25

Table 8 describes the legal values for coercing Basic data types to Java types.
Table 8 Legal Values for Coercing Basic Data Types to Java Types

Basic Array Element Type Java Array Element Type Coercion Type
Integer short
Integer byte Byte
Integer char Char
Long int

16 Chapter 1
 Global Basic Methods

Table 8 Legal Values for Coercing Basic Data Types to Java Types (Continued)

Basic Array Element Type Java Array Element Type Coercion Type
Long Long Long
String java.lang.String
Single Long Long
Single float
Double Long Long
Double double
Date java.util.Date
Boolean boolean
Currency <not supported>

Creating Java and EJB Objects Using ClearBasic APIs 17

Global Basic Methods

CreateJavaObjectArray
Function CreateJavaObjectArray ( CbArray as Array ) as
JavaObject

Table 9 describes the CreateJavaObject Array parameters.

Table 9 CreateJavaObjectArray Parameters

Name Description
CbArray This is a ClearBasic array. The array elements must be of JavaObject type.

This method creates a new Java array object from the ClearBasic array. It
creates a Java array of Java Objects. It returns a JavaObject. Java array
indexes always start from 0 and the ClearBasic Lower Bound value is
mapped to Index 0.

If the ClearBasic array is a multi-dimensional array, this method converts it

to a single dimension Java array.

For example the following Basic array:

dim a(2,3) ‘Basic array

is converted to the following Java array:

a(0,0) Low address (0 index)
a(0,1)
a(0,2)
a(0,3)
a(1,0)
a(1,1)
a(1,2)
a(1,3)
a(2,0)
a(2,1)
a(2,2)
a(2,3) High address (size-1 index)

18 Chapter 1
 Basic Object Type and JavaObject

Basic Object Type and JavaObject

The JavaObject represents a local Java object in Java Virtual Machine (JVM).
It has the same life-time semantics as an ActiveX object. The JavaObject
represents all Java Objects, including Java arrays and Java null objects.

JavaObject::IsArray
Function IsArray () as Boolean

Description
This function returns a True value if the JavaObject references a Java array.

JavaObject::GetAt
Function GetAt ( index as Long ) as Variant

Description
The index parameter specifies a location in a 0-based index for a Java array.
This function returns the array element at the specifed index location. If the
source JavaObject does not reference a Java array, an error occurs. The
JavaObject is converted to a Basic type. For more information see Data Type
Mapping on page 25.

JavaObject::GetAtObject
Function GetAtObject ( index as Long ) as JavaObject

Description
The index parameter specifies a location in a 0-based index for a Java array.
This function returns the array element at the specifed index location. If the
source JavaObject does not reference a Java array, an error occurs.

The array element is always converted to a JavaObject. If the array element

is a primitive type, it is converted to the corresponding Java object.

Creating Java and EJB Objects Using ClearBasic APIs 19

Basic Object Type and JavaObject

JavaObject::Size
Function Size () as Long

Description
This method returns the size of a Java array. An error occurs if the
JavaObject does not reference a Java array.

JavaObject::ClassName
Function ClassName () as String

Description
This function returns the fully qualified Java class name of the Java Object.

JavaObject::IsNull
Function IsNull () as Boolean

Description
This function returns a True value if the Java Object is null.

JavaObject::SetNull
Sub SetNull()

Description
If the object references a null object, <null> is returned.

20 Chapter 1
 Basic Object Type and JavaObject

JavaObject::Call
Function Call ( MethodName as String,
[ Param1 as Variant ],
[ Param2 as Variant ],
...
[ Param27 as Variant ],
) as Variant
Sub Call ( Method Name as String,
[Param1 as Variant ],
[Param2 as Variant ],
...
[Param27 as Variant ],
)

Table 10 describes the JavaObjectCall:: parameters.

Table 10 JavaObjectCall:: Parameters

Name Description
MethodName The name of the method you want to call.
Param1 to These are optional parameters. The parameters you use must match the parameters of
Param27 the Java method. You cannot use a ClearBasic array as a parameter. If you need to use
the values in a ClearBasic array as parameters, you must convert the array to a Java
array. Use the CreateJavaArray() global function and the JavaObject as a parameter to
carry out the conversion.

Description
This function calls a Java method on a Java object instance and returns the
value. If the Java method returns a Void value, this method returns an
empty Variant value. Basic parameter types are converted to Java types.
Returned Java types are converted to Basic type. If the Java method returns a
Java Object, this function returns a Basic JavaObject type. For more
information on Basic to Java type mapping see Data Type Mapping on
page 25.

Creating Java and EJB Objects Using ClearBasic APIs 21

Basic Object Type and JavaObject

JavaObject::CallObject
Function CallObject ( MathodName as String,
[ Param1 as Variant ],
[ Param2 as Variant ],
...
[Param27 as Variant ],
) as Variant

Table 11 describes the JavaObject::CallObject parameters.

Table 11 JavaObject::CallObject Parameters

Name Description
MethodName The method name. This parameter is case sensitive.
Param1 to These are optional parameters. The parameters you use must match the parameters of
Param27 the Java method. You cannot use a ClearBasic array as a parameter. If you need to use
the values in a ClearBasic array as parameters, you must convert the array to a Java
array. Use the CreateJavaArray() global function and the JavaObject as a parameter to
carry out the conversion.

Description
This function calls a Java method on a Java object instance and returns the
value as a JavaObject. Java primitive types are converted to their
corresponding Java Objects (for example, int is converted to
java.lang.Integer). This allows programs to access string types as
java.lang.String objects and to access each character code using the
charAt() method.

22 Chapter 1
 Basic Object Type and JavaObject

JavaObject::Get
Function Get ( FieldName as String ) as Variant

Table 12 describes the JavaObject::Get parameters.

Table 12 JavaObject::Get Parameters

Name Description
FieldName This is the name of the field you want to access. This is a case sensitive parameter.

This function returns a field value. The returned Java type is converted to a
Basic type. If the Java method returns a Java Object, the Basic JavaObject
type is returned. For more information on type mapping between Basic and
Java types, see Data Type Mapping on page 25.

JavaObject::GetObject
Function GetObject ( FieldName as String ) as JavaObject

Table 13 describes the JavaObject::GetObject parameters.

Table 13 JavaObject::GetObject Parameters

Name Description
FieldName This is the name of the field you want to access. This is a case sensitive parameter.

Description
This function returns a field value as a JavaObject. If the field represents a
Java primitive type, it is converted to the corresponding JavaObject. For
example, int is converted to java.lang.Integer.

Creating Java and EJB Objects Using ClearBasic APIs 23

Basic Object Type and JavaObject

JavaObject::Set
Sub Set ( FieldName as String, value as Variant )

Table 14 describes the JavaObject::Set parameters.

Table 14 JavaObject::Set Parameters

Name Description
FieldName The name of the field you want to access. This parameter is case sensitive.
value The value you want to set in the field.

Description
This function sets a field value. Any basic type is converted to a Java type.
For more information on type mapping between Basic and Java types, see
Data Type Mapping on page 25.

24 Chapter 1
 Data Type Mapping

Data Type Mapping

If the Basic type is Variant, Variant type is used to map to a Java type.
Table 15 describes the mapping from Basic types to Java types.
Table 15 Basic type to Java type mappings

Basic Type Java Type Also compatible with Java types

Integer short int, byte, char, long, float, double
Long int long, float, double
String java.lang.String
Single float long, double
Double double long, float
JavaObject Object, Array
Date java.util.Date
Boolean boolean
Currency This conversion is not directly supported. You can
convert to a double type and use that value if
accuracy is not important.
Array This conversion is not directly supported. You
must convert the array to a JavaObject using the
CreateJavaArray() function.

Table 16 describes the mapping from Java types to Basic types.

Table 16 Java type to Basic type mappings

Java type Basic type

int Long
short Integer
char Integer (16 bit unicode value)
byte Integer
float Single
double Double
long Double (some loss can occur)
boolean Boolean
java.lang.String String
java.util.Date Date
Object (Except String and Date) JavaObject

Creating Java and EJB Objects Using ClearBasic APIs 25

Single Signon

Single Signon
The Single Signon feature utilizes user login information that is given as part
of the classic client authentication process to connect to the EJB server. The
ClearBasic engine has been enhanced to support the
ConnectEjbServerImpl() method. If you do not specify all the
parameters required by this method, then the method uses the settings in the
clarify.env file. You must implement a ClearBasic wrapper routine to call the
ConnectEjbServerImpl() function. This routine can access user details
including the AltUserName value that is exposed by the App object. The
AltUserName corresponds to the SUM authentication name.

The following is a recommended function for implementing the ClearBasic

wrapper routine:
Function ConnectEjbServer ( [HostUrl as String ],
[ UserName as String ],
[ Password as String ],
[ Domain as String ],
[ HostType as String ],
[ RemoteCB as Boolean ] ) as String

Table 17 describes the ConnectEjbServer function parameters.

Table 17 ConnectEjbServer function parameters

Name Description
HostUrl The Host Server URL. The URL includes the protocol, for example: t3://
www.amdocs.com. If this parameter is empty, the function uses the default value in the
clarify.env file
UserName The user name for authentication.
If the UserName parameter contains a value, this value is used for authentication.
If the UserName parameter is empty, the user name value from the CeFO login process
is used for authentication.
The Basic App object exposes two properties, UserName and AltUserName.
User_Name corresponds to the login_name field in the table_user table. AltUserName
corresponds to the alt_user_name field in the table_user table.
If the AltUserName property contains information, the AltUserName value is used for
authentication.
If the AltUserName property is empty, the UserName value is used for authentication.
If the Ejb_UserName parameter in the clarify.env file is not empty, that setting
overrides both values, and the Ejb_UserName value is used for authentication.

26 Chapter 1
 Single Signon

Table 17 ConnectEjbServer function parameters (Continued)

Name Description
Password The password for authentication.
If the Password parameter is not empty, this value is used for authentication.
If the Password parameter is empty, the password value from the CeFO login process is
used for authentication.
If the Ejb_Password setting in the clarify.env file is not empty, that setting
overrides both values, and the system use the Ejb_Password for authentication.
Domain This is used when the host requires a domain value. If this value is empty, the
Ejb_Domain setting in the clarify.env file is used.
HostType This value specifies the EJB host type. This value is case sensitive. It is a combination of
the EJB container and EJB application types. The currently supported host types are:
• com.clarify.cb2ejb.WlsAmdocs
• com.clarify.cb2ejb.WlsGeneric
You must use the fully qualified path name of the host type, for example
com.Cb2ejb.WlsCSM
If this value is empty, the Ejb_HostType setting in the clarify.env file is used.
If this value is empty and the Ejb_HostType setting in the clarify.env file does not
exist, the default value is WlsAmdocs.
You can extend this functionality to include new host types.
RemoteCB If this parameter is set to True, the connection to the EJB server is established from a FD
server machine by calling the ConnectEjbServerImpl() method remotely. The default
value for the RemoteCB parameter is False.

Return Value
This method returns a ConnectionId String. This string uniquely identifies
an authenticated connection to the EJB server and can be used across
processes by the Amdocs API. This string typically contains the remote
server URL, the security context, and other information.

Basic scripts must call this method before they create any EJB objects. This
method establishes a connection with a Web Logic EJB server and
authenticates a user.

Creating Java and EJB Objects Using ClearBasic APIs 27

Single Signon

Implementation
You can implement this method as a ClearBasic function. This method calls
the ConnectEjbServerImpl() method which establishes an EJB connection.
The purpose of this wrapper function is to hide the logic for extracting the
user name and password values from the client login process.

Sample Implementation
Function ConnectEjbServer (HostUrl as String, UserName as
String, Password as String, Domain as String, HostType as
String, RemoteCB as Boolean ) as String
Dim RemoteCBTmp as String
Dim ConnId as String
If UserName=”” Then
UserName=app.AltUserName
If UserName=”” Then
UserName=app.UserName
End If
If Password = ““ Then Password = App.Passwd
If RemoteCB = TRUE Then
Dim tmpRtnStatus as Integer
Dim strCID as String
tmpRtnStatus = App.CallCB
(“strCID=ConnectEjbServerImpl
(HostUrl,UserName,Password,Domain,HostType)”)
ConnectEjbServer=strCID
Else
ConnectEjbServer=ConnectEjbServerImpl
(HostUrl,UserName,Password,Doamin,HostType)
End If
End Function

28 Chapter 1
 Java Exception to ClearBasic Error Mapping

Java Exception to ClearBasic Error Mapping

When Basic Script calls a method, an error can occur in the Extension library
of the Java subsystem. The Java subsystem captures Java local exceptions.
The Extension library converts the exceptions into Basic errors. If the Java
Native invocation API fails or a data type conversion fails, the Extension
library generates an error.

The Extension DLL uses Basic Error codes in the range 14000 to 14099 to
report all errors.

Table 18 describes the Basic Err object properties.

Table 18 Basic Err Object Properties

Property Value
Err.Description Error description
Err.HelpContext 0
Err.HelpFile ““
Err.LastDLLError 0
Err.Number An error number in the range 14000 to 14099
Err.Source For a Java exception this is the class name of the
exception. For other errors this is the Extension library
method name that causes the error.

Creating Java and EJB Objects Using ClearBasic APIs 29

Java Output

Java Output
The Java System Object has an out device to which messages are sent. Java
code uses the System.out device to print alert messages. When you launch
the Java Virtual Machine (JVM) it creates a log file called JavaOutput.log,
it assigns this file to the System.out and System.err devices. Any text that is
sent to the output device is written to this file. It creates the file in the current
working directory. If the file creation process fails, no errors are reported
and all output is lost.

The clarify.env file contains a Java_Trace setting. To activate tracing, set

this value to Y. To disable tracing, set this value to ‘N’. If this value is set to
‘Y’, all calls to the Java subsystem are sent to the JavaOutput.log file.

The output from the trace process lists all JVM arguments that the Extension
library passes to the JVM and records each call made to the Java subsystem.
The trace listing specifies the type of operation performed and the
parameters used. If the parameter is null, string null is written. If the
parameter is a primitive type, a Date or a String, the value of the parameter
is written. For all other parameter type the class name is written.

If an operation causes a Java exception, the error details are written to the
JavaOuput.log file. If any Java code writes data to the System.out device, it is
written into the JavaOuput.log file. Each operation written to the
JavaOutput.log file is separated by a short dashed line.

30 Chapter 1
 String Handling

String Handling
ClearBasic strings use a multibyte value to represent a character. Each
character in a ClearBasic string has a value between 0 and 255. Java uses a
16bit Unicode value to represent a character.

When Java returns a string value, the default code page of the operating
system is used to convert the string from a Unicode to a multibyte value.
This multibyte string is passed to ClearBasic.

When a ClearBasic string is passed as a parameter to a Java method, the

operating system default code page is used to convert it from a multibyte
characters to Unicode. The Unicode string is passed to Java.

If Java encodes a value using a character set that is not part of the default
code page of the FD server or the classic client, some characters are lost
when the string is converted to a ClearBasic string. To avoid this, you can
use the CallObject(), GetAtObject(), or GetObject() methods. These methods
return the Java string as a Java String Object. The ClearBasic program can
access each character using the charAt() method. This character is returned
as a Basic Integer type and contains the Unicode code value.

Creating Java and EJB Objects Using ClearBasic APIs 31

Configuration Settings in the clarify.env File

Configuration Settings in the clarify.env File

Table 19 describes the configuration keys used by the Extension library
Table 19 Extension library clarify.env settings

Name Description
Java_ClassPath The JVM uses this value to locate all proxy classes and local classes. If you do not
specify this value, the system uses the current working directory as the classpath value.
Java_LibPath The JVM library path. The JVM uses this value to load modules. This is normally
empty.
Java_Args These are additional arguments for the JVM. They are specific to the JVM and depend
on the JVM platform. For example, they can specify the stack size and the type of
compiler.
Java_Trace To activate tracing, set this value to Y. To disable tracing, set this value to N. If this
value is set to Y, all calls to the Java subsystem are sent to the JavaOutput.log file.
Ejb_HostType The EJB server type. This value is case sensitive. The supported host types is
com.clarify.cb2ejb.WlsCSM.
Ejb_HostUrl The URL to the EJB server. This URL includes the protocol, for example: t3://
www.clarify.com.
Ejb_Domain The EJB server uses this value to locate authentication information. Typical values for
this variable are either SUM or LDAP.
Ejb_UserName The global user name. This value is used for authentication.
Ejb_Password The global password value. This value is used for authentication.

32 Chapter 1
 Extending the EJB host Type

Extending the EJB host Type

You can implement new EJB Host types to support options other than the
WlsCSM type. To add a new EJB Host type:
1. Choose a Host type name which is a fully qualified Java class name. You
will be implementing this class.
2. Implement a Java class using the Host Type Name. This class must be a
subclass of the com.clarify.cb3ejb.EjbAccessor class.
3. Implement the three abstract methods (connect(), disconnect(),
and createEjbObject()).
4. The system ignores all constructors except the class default constructor.
5. The system creates only one instance of this class. All methods must be
multithread safe and possibly stateless.
6. The EjbAccessor class contains a helper implementation that creates an
EjbObject from the javax.naming.Context object.

The com.clarify.cb2ejb.EjbAccessor Class

To implement a new EJB HostType, create a subclass of the
com.clarify.cb2ejb.EjbAccessor abstract class. This class has no constructor
and has three abstract methods:
• connect on page 34
• disconnect on page 34
• createEjbObject on page 35

Creating Java and EJB Objects Using ClearBasic APIs 33

Extending the EJB host Type

connect
This method returns a string value representing a connection.
public abstract String connect (String strHostUrl, String
strUsr, String stPwd, String strDomain)

Table 20 describes the connect method parameters.

Table 20 Connect method parameters

Name Description
strHostUrl The URL of the Host server. The URL includes the protocol and port, for example: t3:/
/www.clarify.com:7020
strUsr The user name. This value is used for authentication.
strPwd The password. This value is used for authentication.
strDomain Use this string if the Host requires an additional Domain value.

disconnect
This method closes the connection and releases all resources used by the
connection.
public abstract void disconnect (String strHostUrl,
String strConnection)

Table 21 describes the disconnect method parameters

Table 21 Disconnect method parameters

Name Description
strHostUrl The URL you used to create the connection with the connect() method.
strConnectio The string value returned by the connect() method.
n

34 Chapter 1
 Extending the EJB host Type

createEjbObject
This method creates an EjbObject instance on the server and returns the
proxy client class instance as an object.
public abstract Object createEjbObject (String
strHostUrl, String strConnection, String JndiHomeName,
String proxyHomeClassName, String proxyClassName)

Table 22 describes the createEjbObject method parameters.

Table 22 createEjbObject method parameters

Name Description
strhostUrl The URL you used to create the connection with the connect() method.
strConnection The string value returned by the connect() method.
JndiHomeName The Jndi name for this object.
proxyHomeClas The fully qualified class name for the Home class interface.
sName
proxyClassNam The fully qualified proxy class name.
e

Creating Java and EJB Objects Using ClearBasic APIs 35

Extending the EJB host Type

WlsCSM class implementation

This section describes the WlsCSM class implementation. Use this as a
reference when you extend the host type.
//-----------------------------------------------------
// WlsCSM class implementation.
//----------------------------------------------------
package com.clarify.cb2ejb;
import javax.naming.*;
import java.util.*;
public class WlsCSM extends EjbAccessor {
// Connect to EJB server and return the aunthetication
// ticket. If Domain is empty, use SUM as default domain
public String connect( String strHostUrl, String strUsr,
String strPwd, String strDomain) {
// No authentication done. Just return some dummy string.
// Customer may need to implement this
String strTicket = new String("test");
return strTicket;
}
// Disconnect from EJB Server
// strConn is the authentication ticket returned by
// connect() method
// strHostUrl is the URL used in connect() method
public void disconnect(String strHostUrl, String strConn)
{
// Customer may need to implement this.
}

// Create Ejb OBject identified by JndiHomeName.

// The client side proxy object must be of type
// proxyClassName
// strConn is the authentication ticket returned by
// connect() method
// strHostUrl is the URL used in connect() method
// Retrieve Context from ticket
// Use the helper method in EjbAccessor to create the EJB
// Object

36 Chapter 1
 Extending the EJB host Type

public Object createEjbObject( String strHostUrl,

String strConn,
String JndiHomeName,
String proxyHomeClassName,
String proxyClassName )
{
Context initialContext = null;
Properties h = new Properties();
// Initilization of Home Interfaces of CSM beans with
// received ticket
h.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
h.put(Context.PROVIDER_URL, strHostUrl);
try
{
initialContext = new InitialContext(h);
}
catch (javax.naming.NamingException e)
{
throw new RuntimeException("Error in createEjbObject:
NamingException " + e.getMessage());
}
catch (Exception e)
{
throw new RuntimeException("Error in createEjbObject:
Exception " + e.getMessage());
}
return createEjbObject( initialContext, JndiHomeName,
proxyHomeClassName, proxyClassName );
}
}

Creating Java and EJB Objects Using ClearBasic APIs 37

Extending the EJB host Type

38 Chapter 1