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
Previous Next Contents Index


Designing a Netscape Extension

This chapter describes Netscape Extension Builder Designer, a tool used to design the components of a Netscape Application Server extension.

The following topics are included in this chapter:


About Netscape Extension Builder Designer
Netscape Extension Builder Designer is a Graphical User Interface (GUI) tool you use to rapidly design the interfaces and coclasses that compose an extension. These interfaces and coclasses are specified using KIDL, and they link Netscape Application Server application components to legacy and third-party functionality.

You define the extension interfaces and coclasses by making selections within Netscape Extension Builder Designer. When you are finished, you generate IDL files in which Netscape Extension Builder Designer translates your GUI selections to KIDL syntax. Netscape Extension Builder Designer also generates a source code tree and makefiles, which are used to compile the IDL and extension class (.cpp and .java) files. These files are compiled using the KIDL Compiler.

Overview of the Graphical User Interface (GUI)
The GUI of Netscape Extension Builder Designer is divided into several parts. The most prominent portions of the GUI are the tree view, the component view, the menu bar and the tool bar.

The following illustration introduces the main parts of Netscape Extension Builder Designer:

Tree View
The tree view displays the component hierarchy of the extension tree. The components of the extension are displayed as they relate to each other. For example, methods are displayed within the interfaces to which they belong, and the interfaces are displayed within the access module to which they belong, and so on.

Component View
The component view provides information about a component selected in the tree view. The component view is where you specify the attributes of a component and perform most of your design work.

The component view is context sensitive according to the item selected in the tree view. For example, when a method is selected, the component view displays GUI controls to allow you to define parameters for that method. If an interface is selected, the GUI controls are relevant only to interfaces.

Menu Bar
The menu bar provides standard features, such as file management, as well as access to the various actions you might perform while designing the components of a Netscape extension. The menu bar has the following menu items, as described in the following table:

Menu Items
Description
File
Contains actions specific to managing files, such as open, close, save and import.
Edit
Contains actions specific to editing particular extension components.
Insert
Contains actions specific to creating the different components of an extension. Some of the items in this menu are disabled at various times depending on which component is selected in the tree view.
Tools
Provides access to the generation and deployment functionality of Netscape Extension Builder Designer. These are used when you are ready to generate IDL files or deploy the extension to a Netscape Application Server.
Help
Provides access to HTML help topics specific to using Netscape Extension Builder Designer and building Netscape extensions.

Tool Bar
The tool bar provides access to the common actions you might perform when designing a Netscape extension. For example, in addition to the standard items such as opening and saving a file, there are icons for importing IDL files, creating new modules, interfaces, and coclasses, generating IDL files and deploying the extension to a server.

Certain menu and tool bar items are enabled or disabled as appropriate for the design of an extension component. For example, the button used to add a new method is only enabled when you have an interface or method selected in the tree view.


How to Use Netscape Extension Builder Designer
Before using Netscape Extension Builder Designer, you should have determined the names of the interfaces (API) needed to integrate the third-party or legacy technology into a Netscape Application Server application. The interfaces that need to be exposed for a Netscape Application Server application are the interfaces you will design using Netscape Extension Builder Designer.

Extension Design Flow Using Netscape Extension Builder Designer
There is no right or wrong design flow for building a Netscape extension using Netscape Extension Builder Designer. The following, however, is a methodical approach to designing a complete extension from start to finish:

  1. Start Netscape Extension Builder Designer

  2. Create an Extension Module

  3. Create the Access and Service Modules

  4. Design the Interfaces

  5. Design the Coclasses

  6. Generate the IDL Files

  7. Complete the Extension Method Stubs

  8. Compile the Extension Source Code

  9. Test and Deploy the Extension
Aside from completing the extension method stubs and compiling the extension source code, all of the above steps are completed using Netscape Extension Builder Designer. Information about completing the method stubs and compiling the source code is provided in a subsequent section of this guide.

This design flow assumes you are creating a new extension. For extensions that are work in progress, you might be at any stage of this design flow.

In addition, each of the steps above is a high-level procedure usually consisting of several to many sub-procedures that must be completed before the overall procedure is complete. For example, when designing a coclass, you might need to assign certain decorations to the interfaces, methods, or parameters within the coclass. Assigning decorations to these components is a sub-procedure of designing a coclass.

Start Netscape Extension Builder Designer
The first step in using Netscape Extension Builder Designer is to start it. For more information about starting Netscape Extension Builder Designer, see Starting Netscape Extension Builder Designer.

Create an Extension Module
Once you start Netscape Extension Builder Designer, the next step is to create the extension module, which represents the extension as a whole. The extension module contains the access modules and the service modules that compose the entire extension. The procedural information about creating an extension module is covered in Creating an Extension Module.

Create the Access and Service Modules
After you create the extension module, the next logical step is to create the access and service modules. An access module groups related interfaces of the extension, and a service module groups related coclasses of the extension. Once you create these modules, you have the base structure around which the extension takes form. More information about creating the access and service modules is provided in later sections of this guide.

Design the Interfaces
After creating an access module, you are ready to design the interfaces used by application components or other extensions to interact with the technology being extended. Designing interfaces consists of naming the interface, defining the methods that the interface contains, and defining the parameters of each of those methods. Procedural information about designing interfaces is provided in Designing an Interface.

Design the Coclasses
After creating a service module and designing the interfaces, you are ready to design the coclasses of the extension. Coclasses contain information for how the extension classes are implemented. For example, the designation of whether an extension supports access by both Java and C++ clients is made in a coclass. Coclasses become skeleton classes after you generate and compile the IDL files generated by Netscape Extension Builder Designer.

Each coclass implements one or more interfaces defined in the access modules. You determine the interfaces that are implemented by a coclass as well as provide the implementation details, called decorations, for those interfaces (and the interface's methods and parameters). Procedural information about designing coclasses is covered in Designing a Coclass.

Generate the IDL Files
Once you have defined your interfaces and extension classes, you are ready to generate the IDL files. The IDL files compose most of the source code for the extension. These files are then compiled using the KIDL Compiler. Netscape Extension Builder Designer quickly generates IDL files. Generating IDL files is covered in a later section in this guide.

Complete the Extension Method Stubs
The KIDL Compiler converts IDL files and generates extension source code and method stubs. The method stubs are incomplete source code files. You need to complete the method stubs before compiling the source code and deploying your extension. Information about completing the method stubs is provided in Completing Method Stubs.

Compile the Extension Source Code
Once you complete the method stubs, you are ready to compile the extension source code to create the extension runtime libraries and classes. Compiling the source code requires the use of the Netscape Extension Builder-generated makefiles. Procedural information about compiling the extension source code is provided in Compiling the Extension Source Code.

Test and Deploy the Extension
The final step is to test and deploy the extension. You can use Netscape Extension Builder Designer to quickly deploy your extension to host Netscape Application Servers. Information about deploying extensions is provided in Deploying and Managing a Netscape Extension.


Starting Netscape Extension Builder Designer
Start Netscape Extension Builder Designer to begin building your Netscape extension.

To start Netscape Extension Builder Designer

  1. In Windows NT, choose Start - Programs - Netscape Extension Toolkit - Netscape Extension Builder Designer.

  2. In UNIX, from a shell prompt, type neb.

    3. Netscape Extension Builder Designer starts.


Creating an Extension Module
The extension module groups the components that compose an extension, as described in the following list:

When you create an extension module, a sample extension is loaded into Netscape Extension Builder Designer. The sample extension contains a sample access module that has one interface with two methods. The sample extension also contains a sample service module that has a coclass that implements the interface defined in the sample access module. The sample extension also contains the required Netscape Application Server access module.

The sample extension is designed to guide you in creating an extension. The sample components provide a framework for how an extension is organized. You can use this framework to build the rest of your extension.

The sample access and service modules are meant to be edited to reflect your particular extension. This means you can rename the modules, and their components, and add components, as necessary, to these modules. Only the Netscape Application Server Access module is not meant to be modified.

To create an extension module

  1. If you are working on a current extension project, choose File - New.

    2. A new extension module, called Sample, appears in Netscape Extension Builder Designer. This sample provides a skeleton for the main components of an extension.

    The sample extension is the default extension loaded into Netscape Extension Builder Designer at startup. For this reason, choosing File - New is only necessary when you are currently working on another extension project.

  2. In the Tree view, rename the sample access and service modules for your extension.

  3. As appropriate, rename the sample interfaces and coclasses, including methods and parameters, for your extension.

  4. In the Component view, specify the appropriate decorations for this extension, as described in the following table. Decorations applied at the extension level apply to all components of the extension.
    5. Decoration
    		Description
    Package Name
    		Specifies the package name for extensions written in Java and extensions written in C++ with a Java access layer. The package name should reflect the name of the extension.
    Language
    		Specifies the language in which the extension is written; either C++ or Java.
    Create a Lock
    		Only available for C++ extensions. This decoration enables method locking for extensions that must run in single-threaded mode. When on, methods within the extension can only be used by one client at a time.
    Java Access Layer
    		Only available for C++ extensions. This decoration allows Java clients to call into the C++ extension.

  5. When you are finished, choose File - Save.

    6. At the prompt, save the file as .gxp

    You are now ready to create the additional components of your extension.


Creating an Access Module
Create an access module when you need to separate and group extension interfaces. An access module provides a way to logically group similar interfaces. For example, an extension might have several interfaces used to connect to and query a backend server. The extension might also have interfaces that provide access to business logic. It makes sense, therefore, to group the connection interfaces in one access module, and the business interfaces in another access module.

For extensions with a small set of interfaces, you most likely need only one access module. Therefore, it is most convenient to rename the sample access module initially loaded into Netscape Extension Builder Designer to a name that better describes your extension.

Use the following procedure to create an additional access module when necessary:

To create an access module

  1. When creating a new extension, first rename the access module named iSample to better describe your extension. Most extensions only need one access module.

  2. For extensions that require more than one access module, choose Insert - Access Module or click the "Create a new Access Module" tool-bar icon.

    3.

    A new access module is created.

  3. Change the name of the NewAccessModule to a name representative of your extension.

  4. To describe this access module, enter a comment in the Comment text box.

    5. This comment will appear in the IDL file that corresponds to this access module.

  5. If this access module is going to support global constants, add them in the constant table at the bottom of the Component view. For more information about using global constants, see Defining a Global Constant.

  6. Choose File - Save to save your changes.
Defining a Global Constant
Netscape Extension Builder Designer allows you to define global constants within an access module. Constants defined in an access module can be used in application and extension code without re-declaring the constants in those code modules.

To define a global constant

  1. In the Component view under the constant table, click Add Constant.

    2.

  2. Under Constant Name, specify a name for the constant.

  3. Under Type, select a data type from the list box.

  4. Under Value, specify a default value for the constant.

  5. For additional constants, click Add Constant and repeat steps 2 through 4.

  6. When you are finished, choose File - Save.

Creating a Service Module
For new extensions, it is most convenient to rename the service module named cSample initially loaded into Netscape Extension Builder Designer to a name representative of your extension.

Use the following procedure to create an additional service module when necessary:

To create a service module

  1. If you have not already done so, rename the service module named cSample to a name representative of your extension.

  2. If you need additional service modules in your extension, choose Insert - Service Module or click the tool-bar icon.

    3.

    A new service module is created.

  3. In the Component view, change the service module named NewServiceModule to a name representative of your extension.

  4. To describe this service module, enter a comment in the Comment text box.

    5. This comment will appear in the IDL file that corresponds to this service module.

  5. In the decoration table, specify the appropriate decorations for this service module, as described in the following table. These decorations are only available if you are developing this extension in C++.
    6. Decoration
    		Description
    Java Access Layer
    		Specifies whether the methods in this service module are accessible to Java clients. Default is same as designation made at extension module.
    If the extension does not use a Java access layer and you turn on the Java layer for a service module, you will be prompted to enable a Java layer for the entire extension or just the service module.
    If you specify access for just this module, methods in other modules cannot be accessed by Java clients, unless you specify otherwise within those modules. Note that this designation will turn the Java Access Layer to ON for the extension, however, only this service module is actually enabled to serve requests from Java clients.
    If you specify to enable the Java access layer for the extension, all methods in the extension can be accessed by Java clients.
    Create a Lock
    		Specifies that the methods in this service module are to be used in single-threaded mode. When accessed by a client, the method is locked to other client calls until finished with current client request.

  6. Choose File - Save to save your changes.

Creating an Access or Service Module by Importing an IDL File
You can also create access and service modules by importing already composed IDL files. An IDL file is usually a text file and, as long as the code is written in KIDL syntax, the file can be read by Netscape Extension Builder Designer.

Netscape Extension Builder Designer cannot import CORBA or Microsoft IDL files. Such files must be re-written using the KIDL syntax.

There are two ways you can import IDL files, as described in the following table:

Type of Import
Description
Import IDL
Imports IDL in editable format, allowing you to change the definitions defined in the file.
Import IDL as Library
Imports the IDL format by referencing the IDL file. The referenced IDL file becomes a #include in the IDL generated by Netscape Extension Builder Designer. The Netscape Application Server Access Module is an example of IDL imported as a library. The definitions for the interfaces in the Netscape Application Server Access Module are #includes in the corresponding IDL file.

Creating an Access Module

When creating an access module, you would either import IDL directly or as a library, depending on what your extension was going to do with the interfaces defined in the files. For example, if you need to add parameters to the methods of the interfaces, import the IDL file directly. If you were not going to make changes to the definitions, import the IDL file as a library.

Creating a Service Module

When creating a service module, you will always want to import the IDL files directly so that you can provide the implementation details for your extension.

To create an access or service module by importing an IDL file

  1. Open the extension project into which you want to import the IDL file.

  2. Choose File - Import IDL or, for an access module, Insert - Import IDL as Library.

  3. In the Select IDL File dialog box, navigate to the directory where the IDL file resides.

    4. You can enter that directory directly or you can browse to find that directory.

  4. Select the file and click Open.

    5. The selected file is imported in Netscape Extension Builder Designer and the contents of that file become accessible through the GUI.

    Any changes made within Netscape Extension Builder Designer are not saved to the source IDL file. Such changes are saved in the IDL file generated by Netscape Extension Builder Designer.

  5. Continue with the appropriate steps to finish your extension.

Designing an Interface
Once you have created your access and service modules, you are ready to design the extension interfaces.

Designing an interface entails creating the interface and defining the methods that compose the interface. This task can only be done in the access module.

To design an interface

  1. First, if working in a new extension, rename the sample interface of the sample extension already loaded into Netscape Extension Builder Designer.

  2. If there is more than one access module in the extension, in the Tree view select the access module to which the new interface will belong.

  3. Choose Insert - Interface or click the "Create a new Interface" tool-bar icon.

    4.

    A new interface, named NewInterface, is created in the selected access module. The new interface can be seen in the Tree view and it becomes the currently selected extension component.

  4. In the Component view, change the NewInterface name to match one of your predefined interfaces.

  5. Specify the interface from which this interface inherits its basic and necessary functionality.

    6. Most interfaces should inherit from the default IGXObject interface.

  6. To describe the interface, enter a comment in the Comment text box.

    7. This comment will appear in the IDL and source code files that correspond to the access module that contains this interface.

  7. To create additional interfaces, repeat steps 3 through 6.

  8. When you are finished, choose File - Save.

    9. You should now define the methods that compose the interface or interfaces you have created. For more information about how to do this, see Defining a Method.

Defining a Method
Once you have created the interfaces for your extension, you must define the methods that these interfaces expose.

To define a method

  1. First, if working in a new extension, rename the sample methods loaded into Netscape Extension Builder Designer as a default.

  2. To add new methods, in the Tree view select the interface to which the new method will belong.

  3. Choose Insert - Method, or click the "Create a new Method" tool-bar icon.

    4.

    A new method, named NewMethod, is created in the selected interface. The new method can be seen in the Tree view and it becomes the currently selected extension component.

  4. In the Component view, change the new method named NewMethod to reflect a name of an actual method for this interface.

    5. An interface cannot have multiple methods with the same name.

  5. To describe the method, enter a comment in the Comment text box.

    6. This comment will appear in the IDL and source code files that correspond to this method.

  6. To create additional methods for this interface, repeat steps 3 through 5.

  7. When you are finished, choose File - Save.

    8. You must now define the parameters used by the methods you have created. For more information about how to do this, see Defining a Parameter.

Defining a Parameter
As you create the methods exposed by the interface or interfaces of your extension, you need to define the parameters that are used by those methods.

To define a parameter

  1. First, if you have not already done so, rename the sample parameters loaded into Netscape Extension Builder Designer as a default.

  2. From the Tree view, select the method for which you want to define a parameter.

  3. To edit an existing parameter, use the Component view and make your changes in the Parameter table.

    4. The bottom-half of the Component view contains a parameter table to allow you to define the parameters for the selected method.

  4. To add a new parameter, click Add Parameter.

    5. A new parameter is created.

  5. Under Parameter Name, change the new parameter named NewParameter to reflect a unique parameter name for this method.

    6. A method cannot have multiple parameters with the same name.

  6. Under Parameter Type, specify the data type for the parameter.

  7. Under In/Out, specify whether the parameter is an In or Out parameter.

    8. It is recommended that methods have only one Out parameter for possibly providing future access to the extension by Java clients. It is mandatory that methods have only one Out parameter for Java extensions and C++ extensions with the Java access layer. This is a Java constraint.

  8. To create additional parameters for the selected method, repeat steps 4 through 7.

  9. When you are finished, choose File - Save.

    10. You are now ready to implement the interfaces, including methods and parameters, by designing coclasses. For more information about doing this, see Designing a Coclass.


Designing a Coclass
A coclass is the design-time representation of a Netscape extension class. A coclass becomes an extension class after the IDL files are compiled using the KIDL Compiler.

Coclasses are designed in the service module so as to separate interface design from interface implementation. The purpose of designing a coclass is to add implementation details, called decorations, to the interfaces you defined in the access module or modules.

Designing a coclass entails creating the coclass, specifying the interface or interfaces that coclass implements, and providing the appropriate decorations for the coclass, interfaces, methods, and parameters.

Typically, you will have more than one coclass in a service module.

To design a coclass

  1. If you have more than one service module, select the module to which you want to add a coclass.

  2. Choose Insert - CoClass or click the "Create a New CoClass" tool-bar icon.

    3.

  3. In the Component view, change the new coclass named NewClass to a name more appropriate for your extension.

    4. A coclass name is the same as a class name and should reflect the function of the service. For example, if the class is a connection manager class, the coclass name might be ConnManager.

  4. If necessary, under Super Class, specify the super coclass this coclass subclasses.

    5. The super class must be defined in the same service module as the coclass that subclasses the super class.

  5. To describe the coclass, enter a comment in the Comment text box.

    6. This comment will appear in the IDL and source code files that correspond to this coclass.

  6. In the decoration table, specify the appropriate decorations for this coclass, as described by the following table:
    7. Decoration
    		Description
    Manager Class
    		Specifies whether this class is the manager class for the service module. A manager class loads the extension into the Netscape Application Server context. There can be only one manager coclass in a service module. A manager class provides extension persistence- allowing the extension to be loaded into Netscape Application Server during bootstrapping.
    Manager coclasses cannot have a super class.
    Template Streaming
    		Specifies whether the results obtained by the methods of this class are handled by the NAS Template Engine so as to stream the results back to the user. For more information about working with template streaming, see Using Template Streaming.
    Java Access Layer
    		Specifies whether the methods in this coclass are accessible to Java clients. The default setting is the same as the designation made at extension and/or service module. The option to specify the Java access layer here allows you to have more control if there are multiple coclasses within the service module.
    If the extension or service module does not use a Java access layer and you enable it for the coclass, you will be prompted to specify whether to enable Java access for the entire extension, the entire service module, or just this coclass.
    If you specify just this coclass, methods in other modules and coclasses cannot be accessed by Java clients, unless you specify otherwise within those modules and coclasses.
    Create a Lock
    		Specifies that the methods of this module are to be used in single-threaded mode. When accessed by a client, the method is locked to other client calls until finished with current client request.
    Poolable Object
    		Specifies whether this object can be pooled. Pooled objects are shared between clients so as to minimize the time clients wait to be served.
    For more information about object pooling and the object pooling decorations described in this section, see Using Object Pools.
    Introspection Interface
    		Only available when Poolable Object is set to Yes. This decoration specifies the interface that defines the methods used by the object pool manager to query the virtual and physical objects for match criteria.

  7. When you are finished, choose File - Save.
Implementing an Interface
Once you have defined your coclass or coclasses, you are ready to implement the appropriate interface or interfaces for that part of the extension.

Coclasses can implement one or more interfaces, and interfaces can be implemented by one or more coclasses. A coclass's implementation of an interface is independent of another coclass's implementation of the same interface. This is useful for providing different functionality for different clients through the same interfaces. This modular functionality is dictated by the implementation code of each coclass.

For example, you might have an ICoolService interface that provides a ProvideService( ) method. The type of service the method provides, however, might vary in discreet ways depending on the type of client that is using the interface. Two or more coclasses would implement the ICoolService interface unique to the type of client that would be accessing the ProvideService( ) method.

To implement an interface

  1. In the Tree view, select the coclass that will implement the interface you want.

  2. Choose Insert - Implement Interface or click the "Add interface(s) for the CoClass to implement" tool-bar icon.

    3.

    The Implement Interface dialog box appears.

  3. From the "List interfaces by" list box, select the view from which you want to select the interface to implement, as described by the following table:
    4. List Interfaces By
    		Description
    Extension
    		Lists interfaces defined in the current extension only.
    System
    		Lists interfaces available on the machine on which you are working.
    All
    		Lists interfaces defined in all extensions and files on the machine on which you are working.

  4. Under Interfaces, select the interface or interfaces you want the selected coclass to implement and click OK.

    5. The selected interface or interfaces appear in the Tree view under the selected coclass after you click OK. The first interface will be the current selection.

  5. To describe the interface, enter a comment in the Comment text box.

    6. This comment will appear in the IDL and source code files that correspond to this implementation of the interface.

  6. If necessary, change the Java Access Layer decoration to provide or not provide Java clients access to methods.

    7. If you turn the Java Access Layer off, all methods within this interface will not be accessible to Java clients.

    If you turn the Java access layer on, and the Java layer was off for the coclass, service module, and/or extension, you will be prompted to specify to which level you want to turn on the access layer. The following table describes the effects of the different choices:

    Level of Java Access
    		Description
    Extension
    		Enables Java clients to access all methods in the extension.
    Service Module
    		Enables Java clients to access only the interface methods implemented in this coclass.
    Note that selecting this level of access will turn on the Java Access Layer for the extension, but it will not enable Java access for the extension. Java clients will only be able to access methods within the service module.
    Coclass
    		Enables Java clients to access just the methods implemented in the coclass in which this interface is implemented.
    Note that selecting this level of access will turn on the Java Access Layer for the service module and the extension, but it will not enable Java access for the service module or extension. Java clients will only be able to access methods within this coclass.
    Interface only
    		Enables Java clients to access just the methods within this interface.
    Note that selecting this level of access will turn on the Java Access Layer for the coclass, service module and the extension, but it will not enable Java access for all the methods in the coclass, service module or extension. Java clients will only be able to access the methods within this interface.

  7. When you are finished, choose File - Save.
Implementing a Method
The final step in designing a coclass is to implement the methods in each interface. Methods provide the functionality of the extension and are the integral link between application components and the extension.

Netscape Extension Builder Designer allows you to specify appropriate decorations for individual methods. The decorations provide the first step in specifying what each method does. Once you have finished decorating the methods in Netscape Extension Builder Designer, you need to write the implementation code in the generated methods stubs. Methods stubs are part of the output of the KIDL Compiler and are described in further detail in Completing Method Stubs.

To implement a method

  1. In the Tree view, open the coclass and interface containing the methods you want to implement.

  2. Select the method to which you will assign decorations.

  3. To describe this method's implementation, enter a comment in the Comment box.

    4. This comment will appear in the IDL and source code files that correspond to this method's implementation.

  4. In the method decoration table, assign decorations as appropriate for this method.

    5.

    The following table describes the available method decorations:

    Decoration
    		Description
    Use Synchronization Lock
    		Specifies to which level, if at all, usage of this method is locked to one client at a time. If object locking is enabled at the extension, service, or coclass levels, you can specify which one of those levels this method synchronizes its usage lock.
    Uses Pooled Object
    		Specify the value of the pooled_object_name decoration that is specified on the Out parameter of the pooled coclass being passed through this method's In parameter.
    Use of this decoration is only necessary when you need to extend the reservation time of the pooled object to the called object at the time of this method call. For more information, see Passing a Pooled Object.
    Pooled In Parameter
    		Enter the name of this method's In parameter that holds the pooled object being passed to the called object. For methods, you must use this decoration if you use the Uses Pooled Object decoration.
    Pooled Object Creation
    		Defines this method as one that creates a pooled object through its Out parameter.
    Keep Pooled Object
    		Specifies whether the virtual object will keep the real object bound (not allowing other matches) for the life of the virtual object. Establishes a persistent connection between the virtual and real object.
    Pooled No Reuse
    		Specifies whether the physical object will be destroyed when the virtual object returns the physical object to the object pool. This is useful for methods known to alter the state of an object in an irreversible and/or undeterminable way, making future use of the physical object unattractive.

    For more information about the concepts of object pooling, see Using Object Pools.

  5. In the parameter decoration table, specify the decorations of each method's Out parameter.

    6.

    The following table describes the available parameter decorations. More information about the use of the object pooling decorations is explained in Using Object Pools.

    Out Parameter Decoration
    		Description
    C++ Class
    		Identifies the coclass in the Netscape Extension Builder runtime layer that wraps the extension coclass. If the value of C++ Class is Connection, _Connection, which is pre-defined in the runtime layer, becomes the wrapper coclass.
    Use this decoration only for Out parameters that implement an interface and use Netscape Extension Builder Runtime Features. Make sure the coclass you specify here exists in your service module and implements the correct interface.
    Java Class
    		This decoration is mandatory for C++ extensions that use a Java access layer. For such extensions, specify the Java coclass used to wrap the C++ extension coclass therefore making the instance of that class (the extension object) available to Java clients. If Java Class is Connection, <packagename>.<servicename>.connection, which is pre-defined in the runtime layer, becomes the wrapper coclass.
    If this Out parameter implements a Netscape Application Server interface, use the correct value of the decoration as specified in Java Class Decorations. If this Out parameter implements an interface you defined, use a coclass defined in this service module and verify that it implements the correct interface.
    For Java extensions, Java Class identifies the coclass in the Netscape Extension Builder runtime layer that wraps the extension coclass. If the value of Java Class is Connection, <packagename>._<servicename>._Connection, which is pre-defined in the runtime layer, becomes the wrapper coclass. Use this decoration only for Out parameters that implement an interface and use Netscape Extension Builder Runtime Features. Make sure the coclass you specify here exists in your service module and implements the correct interface.
    Uses Pooled Object
    		Specify whether a pooled object is to be passed through this Out parameter.
    If an In parameter is specified in the Pooled In Parameter decoration, that parameter's corresponding object is passed to this Out parameter. Otherwise, this method's object is passed.
    Pooled In Parameter
    		(Optional) Enter the name of the In parameter that holds the pooled object when you are passing a pooled object from the In parameter to the Out parameter.
    Pooled Object Name
    		Enter the name of the pooled object. This is a name you determine so as to make it easier to refer to the pooled object. This decoration is required if the Object Pool Name is specified.
    Object Pool Name
    		Specify the name of the pool that will contain the pooled object being passed through this Out parameter. This decoration is required if the Pooled Object Name is specified.
    Object Pool Config
    		(Optional) Enter a key name that specifies this pool in the Netscape Application Server registry. If null, the extension uses Object Pool Name as the default value.
    Keep Pooled Object
    		Specifies the length of binding time between a virtual object and the physical, pooled object represented by this Out parameter.
    If set to No, the virtual object binds to a physical object only for the duration of a method call on the virtual object.
    If set to Yes, the virtual object created binds itself immediately to a physical object and reserves the physical object for the life of the virtual object. This is useful when the physical object maintains state information necessary for future method calls on the virtual object.

  6. When you are finished, choose File - Save.
 

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