"Developer's Guide": Completing Method Stubs

Complete Contents
Introduction
Chapter 1 About Netscape Application Server Extensions
Chapter 2 About the Netscape Extension Builder
Chapter 3 Introduction to Netscape's Interface Definition Language
Chapter 4 Designing a Netscape Extension
Chapter 5 Generating Output Files
Chapter 6 Completing Method Stubs
Chapter 7 Using Template Streaming
Chapter 8 Managing State and Session Information
Chapter 9 Using Object Pools
Chapter 10 Compiling the Extension Source Code
Chapter 11 Deploying and Managing a Netscape Extension
Chapter 12 Example Extension: HelloWorld
Appendix A C++ Helper Functions
Appendix B Java Helper Static Methods
Appendix C Java Class Decorations
Appendix D Reserved Words
Appendix E The ConnManager.cpp File
Glossary

Completing Method Stubs

This chapter describes steps you must follow to complete a method stub.

The following topics are included in this chapter:

Steps to Completing Method Stubs

Locating Stub Files

Locating Interface Code

Adding Implementation Code

Extending the Class Definition

Using Netscape Application Server Services

Using Extensions From Applications

Steps to Completing Method Stubs

To complete a method stub, perform the following general procedure:

Locate a stub file.

Locate the interface code in the stub file.

Add implementation code to the methods defined in each interface.

If necessary, extend the class definition.

Repeat Steps 1 through 4 for each stub file.

Locating Stub Files

When you run the gmake command, each coclass you specified in Netscape Extension Builder Designer is code-generated into a separate file, and each file contains one or more method stubs, according to how you designed the extension. You must find these files in the appropriate cpp or java subdirectory.

For example, in the SchoolDistrict extension, assume the following specifications from the design phase:

The top-level directory is C:\neb\extensions\SchoolDistrict.

A service module named EmployeeClasses contains three coclasses: CTeacher, CPrincipal, and CEmployeeMgr.

The Java package is MySchool.

After code generation, the stub files have the following locations and names:

If the extension is C++ based

C:\neb\extensions\SchoolDistrict\cpp\EmployeeClasses\

CEmployeeMgr.cpp

If the extension is Java based

C:\neb\extensions\SchoolDistrict\java\MySchool\EmployeeClasses\

CPrincipal.java

CEmployeeMgr.java

After locating the stub files, the next step is to edit them. It doesn't matter which file you edit first. To edit the files, locate the interfaces in which the method stubs are defined.

Locating Interface Code

Using your preferred text editor, open a stub file and locate the interfaces. For example, the CTeacher class implements two interfaces: IEmployee and ITeacher.

C++
When you open the CTeacher.cpp file, you see code similar to the following. Note the line that reads "Stub method bodies for interface". Within this interface block are the method stubs you must fill out.

// Stub method bodies for interface: ITeacher

CTeacher::GetClassSize(

/* [out] */ int *pClassSize)

HRESULT hr=GXE_SUCCESS;

//*** Provide your implementation here

//*** and remove the GXASSERT below

GXASSERT(FALSE, GXASSERT_WARNING, "No implementation for

CTeacher::GetClassSize");

CTeacher::SetClassSize(

/* [in] */ int classSize)

HRESULT hr=GXE_SUCCESS;

//*** Provide your implementation here

//*** and remove the GXASSERT below

GXASSERT(FALSE, GXASSERT_WARNING, "No implementation for

CTeacher::SetClassSize");

// Stub method bodies for interface: IEmployee

CTeacher::GetName(

/* [out] */ LPSTR pName,

/* [in] */ int _sizepName)

HRESULT hr=GXE_SUCCESS;

//*** Provide your implementation here

//*** and remove the GXASSERT below

GXASSERT(FALSE, GXASSERT_WARNING, "No implementation for

CTeacher::GetName");

Java
When you open the CTeacher.java file, you see code similar to the following. Note the line that reads "Method bodies for interface". Within this interface block are the method stubs you must fill out.

public class CTeacher

implements com.schooldistrict.ITeacher, com.schooldistrict.IEmployee, com.kivasoft.ITemplateData

public com.schooldistrict.EmployeeServices.CEmployeeMgr m_Module;

public CTeacher(com.schooldistrict.EmployeeServices.CEmployeeMgr

m_Module=module;

public void finalize()

// Method bodies for interface: ITeacher

public int getClassSize()

// **** Provide your implementation here

System.out.println(

"No implementation for CTeacher::getClassSize");

public int setClassSize(

// **** Provide your implementation here

System.out.println(

"No implementation for CTeacher::setClassSize");

// Method bodies for interface: IEmployee

public java.lang.String getName()

// **** Provide your implementation here

System.out.println(

"No implementation for CTeacher::getName");

Adding Implementation Code

How you fill out method stubs depends on the requirements of your extension. You may need to perform one or more of the following coding tasks:

Supply implementation code for user-defined methods; that is, for the methods you defined explicitly in Netscape Extension Builder Designer.

An example of completing a user-defined method stub is provided in the section immediately following, Adding a Creation Method.

Supply implementation code for methods in Netscape Application Server-defined interfaces.

Netscape Application Server-defined interfaces will appear in stub files if you added decorations for certain runtime features, such as template streaming or object pooling. In addition, to manage state and session information, you must use the corresponding Netscape Application Server interfaces, which are not automatically code-generated.

Procedures for completing method stubs for runtime features are described in their own sections on template streaming, state and session management, and object pooling, later in this guide.

Use helper functions or static methods to access Netscape Application Server services.

For an overview of the code to supply for using Netscape Application Server services, see Using Netscape Application Server Services. Reference material on this code is provided in C++ Helper Functions and Java Helper Static Methods.

Adding a Creation Method
As an example in C++, suppose you defined CreateSampleObject( ), a method in the ISampleManager interface. If the CSampleManager coclass implements the ISampleManager interface, then code-generation would produce a file named CSampleManager.cpp. In this file, you might implement the CreateSampleObject( ) method using the following code:

CSampleManager::CreateSampleObject(

/* [out] */ ISampleObject **ppSampleObject)

HRESULT hr=GXE_SUCCESS;

// Create an instance of a class that supports the

// ISampleObject interface. Netscape Extension Builder gives us a

// corresponds to the CSampleObject coclass in Netscape Extension

// Builder Designer.

// The C++ class is also called CSampleObject. It can be

// found in this directory in

// CSampleObject.h / CSampleObject.cpp

*ppSampleObject=new CSampleObject(this);

Extending the Class Definition

Depending on what you add to a method stub, you may need to extend class definitions in any of the following ways:

Add method signatures

Define a member variable that is referenced by a method

Modify inheritance definitions

To extend a class definition, edit the appropriate file. For example, in the SchoolDistrict extension, you extend the definition of the CTeacher class by editing CTeacher.h (for C++ extensions). In Java extensions, the class definition and the method stubs are in the same file, CTeacher.java for example.

Using Netscape Application Server Services

To use Netscape Application Server services from an extension, you add one or more helper function calls to a C++ method stub. For Java access to Netscape Application Server services, you add one or more helper static method calls to your Java method stub. The helper code you add depends on the service you want to use, as shown in the following table:


Service	C++ Helper Function	Java Helper Static Method
database access	GXContextCreateDataConn, GXContextCreateDataConnSet, GXContextCreateHierQuery, GXContextCreateQuery, GXContextCreateTrans, GXContextLoadHierQuery, GXContextLoadQuery	GXContext.CreateDataConn, GXContext.CreateDataConnSet, GXContext.CreateHierQuery, GXContext.CreateQuery, GXContext.CreateTrans, GXContext.LoadHierQuery, GXContext.LoadQuery
mail	GXContextCreateMailbox	GXContext.CreateMailbox
events	GXContextGetAppEvent	GXContext.GetAppEvent
sessions	GXContextDestroySession, GXGetStateTreeRoot	GXContext.DestroySession, GXContext.GetStateTreeRoot
utilities	GXContextGetObject, GXContextLog	GXContext.GetObject, GXContext.Log
security	GXContextIsAuthorized	GXContext.IsAuthorized
Application Component invocation	GXContextNewRequest, GXContextNewRequestAsync	GXContext.NewRequest, GXContext.NewRequestAsync

For information on using Netscape Application Server services, see C++ Helper Functionsor Java Helper Static Methods.

Using Extensions From Applications

To use an extension, application code calls one or more accessors. An accessor is code that gets a reference to a service's manager class. By referencing the manager class, an application is able to access all other functionality in that service.

You need not define accessors. Netscape Extension Builder creates them automatically during code generation. However, you must modify application code by adding the appropriate accessor calls. A C++ accessor is a global function, whereas a Java accessor is a static method in an accessor class.

To use an extension from an application

Determine the names of all accessors the application will invoke.

In the application, add the code to call the accessors.

If necessary, modify the application makefile before linking the application.

Determining Accessor Names
An application communicates with each extension service through a separate accessor. For example, an application that uses five services must contain five accessor calls.

By convention, an accessor derives its name from the service it provides access to. The naming scheme has the following format:

C++
The global function is KET_Get_<service_module> and the function signature is found in <NAS_ROOTDIR>\apps\extensions\include\access_<service_module>.h.

Java
The static method is get<service_module> in class access_<service_module>, in the extension package <package_name>.

Adding Accessor Code to Application Components
C++
To add accessor code to a C++ AppLogic application component:

Include one or more accessor header files in the #include section. For example, if the service module is named EmployeeService, add the following include directive:

#include "access_EmployeeService.h"

In the Execute method, call the necessary accessor functions. Each accessor function returns a pointer to an interface. Use this pointer to call a method of that interface. For example:

MyAppLogic::Execute()

IEmployeeMgr *pInterface=NULL;

if(((hr=KET_Get_EmployeeService(m_pContext, &pInterface,

NULL)) ==GXE_SUCCESS)&&pInterface)

// successfully got extension

pInterface->GetMyName();

Java
To add accessor code to a Java servlet, call a static method against the accessor class. For example:

public class MyApplicationComponent extends HttpServlet {

public void service(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException

// access servlet's underlying AppLogic instance to use accessor

HttpServletRequest2 req2;

req2 = (HttpServletRequest2) req; // legal cast within NAS

AppLogic al = req2.getAppLogic();

com.kivasoft.IContext alContext;

alContext = al.context;

// Here's where the accessor is used

IEmployeeMgr eMgr;

emgr = hello=access_EmployeeService.getEmployeeService(alContext, null, al);

if (eMgr != null) {

eMgr.getMyName();

Linking an Application Component
For C++ extensions, Netscape Extension Builder compiles an accessor library. When you link a C++ AppLogic application component, you must link with this library, which has the following location:

Windows
<NAS_ROOTDIR>\APPS\extensions\lib\axs<extension>.lib

Solaris
<NAS_ROOTDIR>/APPS/bin/libaxs<extension>.so

For Java extensions, Netscape Extension Builder compiles accessor classes and places them in a directory that is already listed in the CLASSPATH variable. As a result, you need not modify your Java makefile.

On Solaris, be sure to modify CLASSPATH to build any application components to have the Netscape Application Server jar files and <NAS_ROOTDIR>/APPS.

Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.