"Developer's Guide": Generating Output Files


<myextension>	The extension name you specified in Netscape Extension Builder Designer.
<service_module>	The name of a service module you defined in Netscape Extension Builder Designer. Each service module will have a corresponding directory.
<package>	The Java package for this extension, expressed as a directory hierarchy. For example, package com.kivasoft.hello translates into directory com\kivasoft\hello.

Method Stubs
After creating the extension module, access modules, and service modules, the corresponding IDL files are used as input to the KIDL Compiler. The KIDL Compiler compiles the IDL files and generates the extension source code and method stubs. Method stubs reside in your extension classes.

A method stub is framework code that you must complete. By completing this code, you tie the extension to the functionality being integrated or extended. The method stub is where you write the code that defines what the methods and parameters actually do.

For example, suppose in Netscape Extension Builder Designer you created an ISetValue interface with a SetTime( ) method. At this point, all you have defined is that the interface and method exists, that there are certain parameters associated with the method, and that all of these methods and parameters use certain decorations, such as the Java Access Layer and Template Streaming.

Now you must define what the SetTime( ) method does, and that is what you do in the method stub. The functionality you implement in method stubs is mapped to the functionality in the object being extended or integrated. This mapping lets AppLogics call into the object.

Location of Method Stubs

For a C++ extension, method stubs are found in .cpp files in the following directories:

<NEB_ROOTDIR>\<myextension>\cpp\<service_module>

For a Java extension, method stubs are found in .java files in the following directories:

<NEB_ROOTDIR>\<myextension>\java\<package>\<service_module>

Netscape Extension Builder Runtime Layer
Based on the decorations you added in Netscape Extension Builder Designer, some of the generated code implements Netscape Extension Builder runtime features such as template streaming, method locking, and object pooling. This code, collectively known as the Netscape Extension Builder Runtime Layer, resides in directories whose names start with an underscore (_). There is no need to edit any code in these directories.

The Netscape Extension Builder Runtime Layer provides the "under-the-hood" processing and functionality for the Netscape Extension Builder Runtime Features. The runtime feature classes reside in the Netscape Extension Builder Runtime Layer and are denoted by the underscore prefix. For example, _YourRuntimeClass.cpp is a C++ feature class that corresponds to the coclass called YourRuntimeClass, which you defined in Netscape Extension Builder Designer.

If a method call to an extension class, for example YourRuntimeClass, uses a Netscape Extension Builder Runtime Feature, then this class is first routed through a corresponding runtime feature class, _YourRuntimeClass. The runtime layer matches the called class with the feature class by using the value you specify in the C++ Class or Java Class decoration. This decoration is made on the appropriate method in Netscape Extension Builder Designer.

The Netscape Extension Builder Runtime Layer also supports the accessor class created by the accessor method. The accessor class, also denoted by the underscore prefix, provides access to a service in the extension. There is typically one access class for each service in an extension. If no runtime features are used in an extension, the method call to the accessor class is the only call to go through the runtime layer. For more information, see Using Extensions From Applications.

Location of Netscape Extension Builder Runtime Layer

For a C++ extension, code for the Netscape Extension Builder Runtime Layer is found in .cpp files in the following directories:

<NEB_ROOTDIR>\<myextension>\cpp\_<service_module>

For a Java extension, code for the Netscape Extension Builder Runtime Layer is found in .java files in the following directories:

<NEB_ROOTDIR>\<myextension>\java\<package>\_<service_module>

Java Access Layer
The Java Access Layer is the set of code that lets Java clients call into a C++ extension. This code is generated only if you set the Java Access Layer decoration to On.

For a C++ extension with a Java Access Layer, the make command generates additional files, none of which require editing.

The directory

<NEB_ROOTDIR>\<myextension>\java\<package>\<service_module>

contains Java native methods and Java classes with native method signatures. Both types of files enable Java code to communicate with the C++ implementation of a service module.

Java native methods are written in C++ and use a naming scheme of native_<class>.cpp, where <class> is one of the classes in the service module. Java classes with native method signatures use a naming scheme of <class>.java.

Java native methods are compiled into a library located in the directory:

<NAS_ROOTDIR>\APPS\bin

The library uses a naming scheme of

Windows
jx2<service_module>.dll

Unix
libjx2<service_module>.so

Java classes with native method signatures are compiled into .class files located in the directory:

<NAS_ROOTDIR>\APPS\<package>\<service_module>

Public Interfaces
Public interfaces are what application components use to communicate with an extension. For a C++ extension, public interfaces are .h files found in the following directory:

<NAS_ROOTDIR>\APPS\extensions\include

For a Java extension, public interfaces are found in .java files and their corresponding .class file. The .java files reside in the following directory:

<NEB_ROOTDIR>\<myextension>\java\<package>

whereas the .class files reside in the following directory:

<NAS_ROOTDIR>\APPS\<package>

Accessors
Accessors enable application components to access a particular service in an extension. For more information, see Using Extensions From Applications.

C++ Accessors

For a C++ extension, accessors are global functions. C++ accessor code includes .cpp implementation files, .h header files, and .lib libraries. Accessor implementation files are located in the following directory:

<NEB_ROOTDIR>\<myextension>\cpp\accessors

You do not need to modify nor reference the accessor implementation files.

Accessor header files use the naming convention access_<service_module>.h, and they are located in the following directory:

<NAS_ROOTDIR>\APPS\extensions\include

A C++ developer must add #include directives to the C++ code in order to use accessors. Accessor libraries are compiled into an axs<myextension>.lib file located in the following directory:

<NAS_ROOTDIR>\extensions\lib

A C++ developer must link this library when compiling the AppLogic application component.

Java Accessors

For a Java extension, accessors are static methods in an accessor class. Java accessor code includes .java files and .class files.

Accessor .java files are in:

<NEB_ROOTDIR>\<myextension>\java\<extension_package>

You do not need to modify nor reference accessor .java files.

Accessor .class files use the naming convention access_<service_module>.java, and they are located in:

<NAS_ROOTDIR>\APPS\<package>

A Java developer must modify the Java code by importing the package containing the accessor class.

Generating Files from the Designer

To generate files from Netscape Extension Builder Designer

Select the Generate IDL command from the Tools menu.

Enter the name of the top-level directory to contain the output.

On Solaris, you can enter absolute and relative pathnames. However, environment variables and the tilde (~) character are not interpreted, so do not use them.

On Windows NT, you can also open directories and choose them from a directory window, as shown in the following figure:

Generating Source Code Using gmake

After you run the Generate IDL command from Netscape Extension Builder Designer, run the gmake utility from your extension's top-level directory:

Windows
gmake -f GNUmakefile.nt

Solaris
gmake -f GNUmakefile.sun

Running gmake performs the following actions:

Invokes the KIDL Compiler, which translates IDL files into source code.

Compiles the source code.

Copies the code to appropriate locations in the Netscape Application Server root directory.

The next two sections summarize the source code found in an extension's top-level directory. Topics are organized by the type of extension:

Source Code for a Java Extension

Source Code for a C++ Extension

Source Code for a Java Extension
For a Java extension, the top-level directory contains a java directory, which in turn contains a series of subdirectories corresponding to your Java package name. For example, if your Java package is com.mycompany.SchoolDistrict, then the top-level directory has the following structure:

java\com\mycompany\SchoolDistrict

The Java package hierarchy contains the following subdirectories:


Subdirectory	Description
<service_module1>, <service_module2>, ..., <service_modulen>	For each service module you define, Netscape Extension Builder Designer creates a directory with that module's name. After code generation, these directories contain files whose method stubs you need to complete.
gen.<service_module1>, gen.<service_module2>, ..., gen.<service_modulen>	Each service module directory has a corresponding working directory, whose name uses a prefix of gen, for generated. As you redesign your extension and regenerate source code, the updated code is stored in the gen. directories in order to preserve manual changes you may have made in the service module directories. After you determine that the gen. directories contain correctly updated files, copy them to the corresponding location in the service module directory.
_<service_module1>, _<service_module2>, ..., _<service_modulen>	For each service module you define, Netscape Extension Builder Designer creates a directory with that module's name and preceded by an underscore (_). After code generation, these directories contain source code for implementing Netscape Extension Builder's runtime features, such as method locking and object pooling. Do not modify any files in these directories.
types	Contains constants that are automatically defined in Netscape Extension Builder Designer.

Source Code for a C++ Extension
For a C++ extension, the top-level directory contains a cpp directory, which in turn contains the following subdirectories:


Subdirectory	Description
<service_module1>, <service_module2>, ..., <service_modulen>	For each service module you define, Netscape Extension Builder Designer creates a directory with that module's name. After code generation, these directories contain files whose method stubs you need to complete.
gen.<service_module1>, gen.<service_module2>, ..., gen.<service_modulen>	Each service module directory has a corresponding working directory, whose name uses a prefix of gen., for generated. As you redesign your extension and regenerate source code, the updated code is stored in the gen. directories in order to preserve manual changes you may have made in the service module directories. After you determine that the gen. directories contain correctly updated files, copy them to the corresponding location in the service module directory.
_<service_module1>, _<service_module2>, ..., _<service_modulen>	For each service module you define, Netscape Extension Builder Designer creates a directory with that module's name and preceded by an underscore (_). After code generation, these directories contain source code for implementing Netscape Extension Builder's runtime features, such as method locking and object pooling. Do not modify any files in these directories.
accessor	This directory contains accessor functions, which are used to enable AppLogics to access an extension's services. Do not modify any files in this directory. For information on accessors, see Using Extensions From Applications.

For a C++ extension with a Java Access Layer, the top-level directory contains both a cpp directory and a java directory. The structure of the cpp directory is the same as for a non-wrapped C++ extension.

The Java package hierarchy contains the following subdirectories:


Subdirectory	Description
<service_module1>, <service_module2>, ..., <service_modulen>	For each service module you define, Netscape Extension Builder Designer creates a directory with that module's name. After code generation, these directories contain Java native methods, which act as the "glue" between Java and C++. Do not modify any files in these directories.
types	Contains constants that are automatically defined in Netscape Extension Builder Designer.

Diagram of Extension Components

The following diagram is an example of how extension components are represented by source code. The extension is named Hello and is written in C++ with a Java Access Layer. Assume also that the extension consists of one access module and one service module, named Access and Service, respectively.