Programmers Guide: Creating Configuration Files

Creating Configuration Files

This chapter describes how to create, edit, and maintain configuration files for the application as a whole and for individual components (EJBs and servlets).

The following topics are presented in this chapter:

Introducing Configuration Files

Creating Servlet and Application Configuration Files

Creating EJB Property Files

Creating Datasource Property Files

Introducing Configuration Files

You use configuration files in NAS to describe metadata about the individual components (servlets and EJBs) that make up your application. The information in each configuration file is stored in a registry internal to NAS.

Each application component must have a configuration file associated with it. Servlets use a plain-text format called NTV, Additionally, each application component must be associated with a globally unique identifier, or GUID.

The NAS Registry The NAS registry is a collection of application metadata, organized in a tree, that is continually available in active memory or on a readily-accessible directory server. The process by which NAS gains access to servlets, EJBs, and other application resources is called registration, because it involves placing entries in the NAS registry for each item.

You can change some of the information in the registry at run-time using the NAS Administration Tool. For more information about the registry, and the Administration Tool, see the Administration Guide.

In particular, see Deploying Application Files Manually in the Administration Guide. This section describes how to register servlets, EJBs, and JDBC datasources manually using provided utilities.

GUIDs A GUID is a 128-bit hexadecimal number in the following format:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

GUIDs are guaranteed to be globally unique, which makes them ideal for identifying components in a large-scale heterogeneous system such as a NAS application.

GUIDs are normally assigned automatically by the deployment tool, or by Netscape Application Builder (NAB). You can generate a GUID manually by using a utility named kguidgen. kguidgen is installed by default into the directory BasePath/bin. That directory must be listed in your search path (your PATH environment variable) in order to generate a GUID.

To generate a new GUID, simply run kguidgen from a command line or window.

Creating Servlet and Application Configuration Files

You must provide a configuration for each servlet in order to identify it to NAS and to set up some. A single configuration file can configure multiple servlets. Additionally, each application must have a configuration file that references all servlet configuration files, identifies the application's name, and controls how sessions work in the application.

Servlet and application configuration files are hierarchical lists of name-value pairs with ordinal types. The format is called NTV (name-type-value). Each NTV file must contain certain fields in order to properly register the servlet with NAS.

NTV Syntax The NTV format consists of predefined variable names, their ordinal types, and their values, which depend on the type. In general, an NTV list is surrounded in curly braces { } and delimited with commas. Each entry in the list consists of a name, a type, a value, and a trailing comma. Non-keywords, including strings and numerical values, must be surrounded in double-quotes. String arrays are surrounded with square brackets [ ].

Valid types and syntax are shown below:


Type	Description
Bool	Boolean value: true or false
Date	Date (various standard formats are accepted)
Double	Double-precision floating point value
Int	Integer
NTV	A Name-Type-Value list. Use variables of this type to nest lists.
Str	String. Surrounded in double-quotes.
StrArr	An array of strings, each of which is surrounded in double-quotes. The array is delimited with commas. The entire array is surrounded by square brackets [ ].

Note. Do not use : (the colon character) in NTV attribute values.

Manually Registering Servlets to NAS Normally, servlets are registered to the server registry file upon deployment. In some cases (such as for testing), you may want to register your servlets manually. NAS provides a registration script called servletReg for this purpose.

You can use servletReg.sh as follows on Solaris:

servletReg.sh -i appInfo.ntv

This example shows servletReg.bat under Windows NT:

servletReg.bat /i appInfo.ntv

For more information, see Manually Deploying Servlets and JSPs

Uploading Configuration File Changes

If you change either of the following fields, you must stop the server and re-register your configuration files in order to make the changes active:

Any changes to the ServletRegistryInfo section of a servlet configuration file

Any change to the SessionInfo section of an application configuration file appInfo.ntv

Changes to other fields in application or servlet configuration files do not require a server restart.

To load a new servlet configuration file into NAS, stop the server and redeploy the configuration file, then execute servletReg appInfo.ntv on the server to register the new configuration file. Finally, restart the server.

Application Configuration Information Create an application information file named appInfo.ntv for each application. Only one application can be configured in a given application configuration file. appInfo.ntv normally resides in AppPath/appName/ntv. For more information, see Important Servlet Files and Locations.

Application Configuration File Layout
This pseudocode example shows all the available fields in an application configuration file. Items in bold are required. Items in italics indicate defaults. Ellipses (...) indicate data that you must supply. These fields are described in detail in the following sections.

NTV-ASCII   { 
    "SessionInfo"     NTV      { 
       "timeout"  Int     "1800", 
       "flags"    StrArr  ["SESSION_DISTRIB","SESSION_TIMEOUT_CREATE"], 
       "sessionManagment"  Int  "0", 
    }, 
    "ServletFiles"    StrArr  [...], 

    "AppName"         Str     "...", 
}

Application Configuration File Fields
Each appInfo.ntv file can contain the following fields:


Name	Type	Value
SessionInfo	NTV	Optional session settings for this application. The default is a distributable session with default behavior. This section is required for a local session (in order to specify the session type) and for any non-default behavior in a distributable session.
AppName	Str	Semi-optional. Name of the application, required if the configuration file is associated with a particular application. Do not configure this field for the generic application. This name can not be hierarchical (a/b/c).
ServletFiles	StrArr	Required. Names of all the servlet configuration files associated with this application.

Specifying Session Information
SessionInfo

The SessionInfo section consists of several variables, which are applied to all servlets in the same application. None of these fields is required; if they are not provided, default values are used. All of these fields except sessionManagement are valid only for distributable sessions.

For more information about sessions, see Creating and Managing User Sessions.

The SessionInfo section consists of the following attributes:


Name	Type	Value
secure	Bool	Optional. If set to true, the session cookie is only sent over secure connections (e.g. HTTPS).
timeout	Int	Optional. Duration (in seconds) after which the session expires. The default timeout is 1800 seconds (30 minutes). Note: for local sessions, set the timeout value at run time using setMaxInactiveInterval().
flags	StrArr	Optional. Configures the scope of the distributable session to be created (see below for details).
sessionManagement	Int	Optional. Specifies session type for this application. 0 (the default) indicates a distributable session, 1 indicates a local session.

The flags field can contain up to two flags, one indicating the session's scope and the other indicating expiration behavior. The following values are valid:


Scope Flag	Description
SESSION_LOCAL	Makes the session visible to objects in the local process only.
SESSION_CLUSTER	Makes the session visible to objects within the cluster.
SESSION_DISTRIB	Makes the session visible to objects on all Netscape Application Servers (i.e., including those outside the cluster).


Expiration Flag	Description
SESSION_TIMEOUT_ABSOLUTE	Specifies that the session expires at a specific date and time. NOTE: this flag is not supported in this release.
SESSION_TIMEOUT_CREATE	Specifies that the session expires a certain duration after the session was created. Specify the duration using the timeout field.

If you specify nothing in the SessionInfo section, the default is a distributable session with SESSION_DISTRIB and SESSION_TIMEOUT_CREATE with a default of 1800 seconds (30 minutes), as explicitly described in the following example:

"SessionInfo"     NTV     { 
    "secure"            Bool    "false", 
    "timeout"           Int     "1800", 
    "flags"       StrArr  ["SESSION_DISTRIB","SESSION_TIMEOUT_CREATE"], 
    "sessionManagment"  Int     "0", 
}, 
...

Specifying the Application's Name
AppName

The AppName entry contains the name of the application, which must conform to URL standards for naming as this name is specified when invoking a servlet that is part of this application. For example:

http://server:port/NASApp/AppName/servletName?name=value

This field is required only for applications that have servlets which are part of an application. For the generic application, this field should not be specified.

For more information about invoking servlets, see Invoking Servlets.

Specifying Servlet Configuration Files
ServletFiles

The ServletFiles entry consists of an array of strings, where each string is the name of a servlet configuration file without the .ntv extension. At least one servlet configuration file must be configured. This is a required field.

Since they are identified by name in appInfo.ntv, and since they reside in the same directory as appInfo.ntv, there are no restrictions on how a servlet configuration file is named. By convention, servlet configuration files are named for the servlets they describe. For example:

    "ServletFiles"    StrArr  ["myServlet", "myOtherServlet"],

For more information about servlet configuration files, see Servlet Configuration Information.

Example Application Configuration File
The following is an example appInfo.ntv that creates a distributable session and configures two servlet info files, servInfo1.ntv and servInfo2.ntv:

NTV-ASCII   { 
    "SessionInfo"     NTV     { 
        "timeout"           Int     "400", 
        "flags"             StrArr  ["SESSION_DISTRIB"], 
        "sessionID"         Str     "123456789", 
        "sessionManagment"  Int     "0", 
    }, 
    "ServletFiles"    StrArr  ["servInfo1", "servInfo2"],
    "AppName"         Str     "BookStoreDemo",
}

(For examples of servInfo1.ntv and servInfo2.ntv, see Example Servlet Configuration Files.)

Servlet Configuration Information Create a servlet configuration for each servlet. A servlet configuration resides in a servlet configuration file, which can contain configurations for any number of servlets. Servlet configuration files can be named anything, so long as the name is listed in the ServletFiles attribute in appInfo.ntv (see Application Configuration Information).

Servlet configuration files for servlets that are part of an application reside in AppPath/appName/ntv alongside the application's configuration file AppPath/appName/ntv/appInfo.ntv. AppPath refers to the value for the registry variable AppPath, the base file location for NAS. appName refers to the application's name, as configured in appInfo.ntv.

Servlet configuration files for generic servlets that do not belong to a particular application reside in AppPath/ntv alongside the generic application configuration file AppPath/ntv/appInfo.ntv. Generic servlet configuration files must be listed in AppPath/ntv/appInfo.ntv.

Dynamically Reloading Servlets

If you change either of the following fields, you must stop the server and re-register your configuration files in order to make the changes active:

Any changes to the ServletRegistryInfo section of a servlet configuration file

Any change to the SessionInfo section of an application configuration file appInfo.ntv

Changes to other fields in application or servlet configuration files do not require a server restart.

To load a new servlet configuration file into NAS, stop the server and redeploy the configuration file, then execute servletReg appInfo.ntv on the server to register the new configuration file. Finally, restart the server.

See Manually Registering Servlets to NAS.

Servlet Configuration File Layout
This pseudocode example shows all of the available fields in a servlet configuration file. Items in bold are required. Items in italics indicate defaults. Ellipses (...) indicate data that you must supply. These fields are described in detail in the following sections.

NTV-ASCII   { 
    "..."      NTV    { (indicate servlet filename without the .class extension)

        "ServletRegistryInfo" NTV    { 
            "type"                Str    "j",
            "enable"              Str    "y",
            "encrypt"             Str    "n",
            "lb"                  Str    "y",
            "guid"                Str    "{...}", 
            "serverInfo"          StrArr ["..."], 
            "acl"                 StrArr ["..."], 
        }, 

        "ServletRunnerInfo"   NTV    {
            "ServletClassPath"    Str    "...", 
        }, 

        "ServletData"         NTV    { 
            "CreateDate"          Str    "...", 
            "Description"         Str    "...", 
            "CacheTimeOut"        Int    "...", 
            "CacheSize"           Int    "...", 
            "CacheCriteria"       Str    "...", 
            "RequiredSessionVars" StrArr ["..."], 
            "Parameters"              NTV    {
                "..."                     NTV    { 
                    "inputRequired"           Str    "n", 
                    "inputRule"               Str "...", 
                }, 
            }, 
            "FormActionHandlers"      NTV    {
                "..."                   Str "...", 
            }, 
        },
        "InitArgs"            NTV    {
            "..."                 Str    "...", 
        },
    }, 
}

Servlet Configuration File Fields
A servlet configuration file has several sections nested under each servlet name.


Name	Type	Value
ServletRegistryInfo	NTV	Required. Information needed to register a servlet with NAS.
ServletRunnerInfo	NTV	Required. CLASSPATH information for the servlet engine.
ServletData	NTV	Optional. Information supporting NAS features.
InitArgs	NTV	Optional. Supports NAB-generated code.

Specifying NAS Registry and ACL Information

ServletRegistryInfo

The ServletRegistryInfo section contains information that enables the servlet to be registered into NAS. The only required attribute is guid, which specifies a unique identifier used internally by the server. For more information on the NAS registry, see The NAS Registry.

The ServletRegistryInfo section is made up of the following attributes:


Name	Type	Value
enable	Str	Optional. Indicates whether NAS instantiates and activates the server for use immediately after registration. Valid values are y or n, the default is y.
encrypt	Str	Optional. Indicates whether internal server communications to this servlet are encrypted. Valid values are y or n.
lb	Str	Optional. Indicates whether sticky load balancing is set for this servlet. Valid values are y or n. There is no default; if this field empty, load balancing is determined by the server. lb is automatically set to y for servlets in applications that use local sessions, since those servlets can not be distributed (see Creating and Managing User Sessions).
descr	Str	Optional. Description of the servlet that appears in the NAS Administration Tool.
guid	Str	Required. Globally unique identifier generated by kguidgen. For more information, see GUIDs.
serverInfo	StrArr	Optional array of server descriptions. Each server description uses the syntax: SRVR_IP_ADDR:SRVR_IP_PORT[=SRVR_FLAGS] SRVR_IP_ADDR indicates the server's IP address. SRVR_IP_PORT indicates the Executive Server port number. SRVR_FLAGS is optional: 0x80000000 sets sticky load balancing, 0x00000001 sets the enable flag (settings for each server override the default settings given in the lb and enable descriptions above).
acl	StrArr	Optional. Array of users or user groups and their permissions with respect to servlet execution. For more information, see below.

The acl field defines an array of users and/or groups that can access this servlet. User and group names are defined in the directory server. For information about adding directory server users, see Storing and Managing Users and Groups in the Administration Guide.

For example, the following entry enables the user fred with permission to read and the group managers permission to read and write.

"acl"     StrArr     ["fred=read", "managers=readwrite"]

Your servlet tests for authorization and conditionally executes based on user permissions. For more information about component security in general, see Writing Secure Applications.

Specifying Servlet Engine Information

ServletRunnerInfo

The ServletRunnerInfo section contains information relating to the NAS servlet engine, and consists of the following attribute:


Name	Type	Value
ServletClassPath	Str	The class name of the servlet (without the .class extension), which resides either in a path in the CLASSPATH environment variable or in a path in GX_CLASSPATH (configured in the registry). This enables the servlet engine to know which class file to load. For example, a servlet Foo in package com.mysite.package is defined as: "ServletClassPath" Str "com.mysite.pkg.Foo"

Note. If the NAS class loader is unable to find a class file through the SYSTEM_JAVA parameter, the registry parameter that contains GX_CLASSPATH, NAS hands the request to the Java class loader, which in turn reads the CLASSPATH environment variable to find the class file. This can be potentially confusing behavior, as classes can load even if they are not referenced in GX_CLASSPATH, as long as they are in CLASSPATH.

Specifying Servlet Metadata, Result Cache, Required Session Variables, and NAS Features

The ServletData section consists of information about the servlet itself, information about optional result caching, and particular information about two NAS features: form field validation and named action handlers. For more information about these and other NAS features, see Taking Advantage of NAS Features.

The ServletData section consists of the following attributes:


Name	Type	Value
CreateDate	Str	Optional. Date the servlet was created.
Description	Str	Optional. Description of the servlet. The NAS Administration Tool uses this field as a servlet's description.
CacheTimeOut	Int	Optional. Elapsed time (in seconds) before the memory cache for this servlet is released.
CacheSize	Int	Optional. Size (in kilobytes) of the memory cache for this servlet.
CacheCriteria	Str	Optional. A string of comma-delimited descriptors; if a descriptor matches the input, the results of the servlet are cached. See below for syntax.
RequiredSessionVars	StrArr	Optional. Variable list indicating which variables are required in the session object. Validates that the session is created and the configured values are in the session when the user calls pgix.
Parameters	NTV	Optional. Describes validation input rules for each parameter expected by the servlet. Typically used only in code generated by NAB.
FormActionHandlers	NTV	Optional. Form button names expected by the servlet, specifying the corresponding handler routine name for each button. Typically used only in code generated by NAB.

Use the follow syntax for the CacheCriteria field. For more information, see Caching Servlet Results.


Syntax	Description
arg	Test succeeds for any value of arg in the input parameter list. For example: "EmployeeCode"
arg=v	Test whether arg matches v (a string or numeric expression). For example: "stock=NSCP". Assign an asterisk () to the argument to cache a new set of results every time the servlet runs with a different value. For example: "EmployeeCode="
arg=v1\|v2	Test whether arg matches any values in the list (v1, v2, and so on). For example: "dept=sales\|marketing\|support"
arg=n1-n2	Test whether arg is a number that falls within the given range. For example: "salary=40000-60000"

The Parameters field is a subsection that contains all the parameter names in a form and their corresponding validation input rules. This attribute is normally only used in code generated by Netscape Application Builder. For more information about validation, see Validating Form Field Data..

Each parameter is listed with a name and the following attributes:


Name	Type	Value
inputRequired	Str	Optional, indicates whether an input value must be supplied for that parameter. Valid values are y or n, the default is n.
inputRule	Str	Optional, specifies how the named parameter should be validated. inputRule indicates the type of data the value should be validated against. For more information, see Validation Rules.

The FormActionHandlers field is a subsection that contains all form SUBMIT buttons in a form and a corresponding form action handler method for each. This attribute is normally only used in code generated by Netscape Application Builder (NAB).

Each button name is listed with a the name of an action handler defined in the servlet. The type is Str. For example:

"FormActionHandlers" NTV {
    "Button1"            Str    "Handler1",
    "Button2"            Str    "Handler2",
}

When the form is submitted, the servlet determines which button was clicked and routes the request and response objects to the appropriate action handler. For more information about named event handlers, see Creating Named Form Action Handlers.

The InitArgs section consists of initial parameters to the servlet and their corresponding initial values. This attribute is normally only used in code generated by Netscape Application Builder (NAB).

These parameters are available to the servlet by calling the getInitParameterNames() method in the ServletConfig interface, and the parameter values are available by calling the getParameter() method in the ServletConfig interface. These are usually used by the servlet during the initialization phase.

Example Servlet Configuration Files
This example shows an NTV file that configures two servlets:

NTV-ASCII   { 
    "HelloWorldServlet"   NTV    { 
        "ServletRegistryInfo" NTV    { 
            "guid"       Str  "{E1E5C6BB-A677-161A-8B60-0800209C42F2}",
        },
        "ServletRunnerInfo"   NTV    { 
            "ServletClassPath"    Str    "HelloWorldServlet", 
        }, 
        "ServletData"         NTV    { 
            "CreateDate"          Str    "12-03-1998", 
            "Description"         Str    "Sample with cache criteria", 
            "CacheTimeOut"        Int    "300", 
            "CacheSize"           Int    "5", 
            "CacheCriteria"       Str    "cache", 
        },
        "InitArgs"            NTV    { 
            "name1"               Str    "value1", 
            "name2"               Str    "value2", 
        }, 
    }, 
    "MyServlet"           NTV    { 
        "ServletRegistryInfo" NTV    { 
            "type"                Str    "j",
            "enable"              Str    "y",
            "encrypt"             Str    "n",
            "lb"                  Str    "y",
            "descr"               Str    "Description",
            "guid"       Str  "{F2920FDD-A6A0-161A-F4EB-0800209C42F2}",
        },
        "ServletRunnerInfo"   NTV    {
            "ServletClassPath"    Str    "MyServlet", 
        }, 
        "ServletData"         NTV    { 
            "FormActionHandlers"  NTV    { 
                "submit"              Str    "OnSubmit", 
                "clear"               Str    "OnClear", 
            },
        }, 
    },
}

This example shows a single servlet configured with a number of parameters:

NTV-ASCII   { 
    "ReceiptServlet"      NTV    { 
        "ServletRegistryInfo" NTV    { 
            "type"                Str    "j",
            "enable"              Str    "y",
            "encrypt"             Str    "n",
            "lb"                  Str    "y",
            "group"               StrArr ["BookStore"],
            "guid"       Str  "{9D3CFF79-A81B-161A-CAEF-0800209C42F2}",
        },
        "ServletRunnerInfo"   NTV    {
            "ServletClassPath"    Str    "ReceiptServlet", 
        }, 
        "ServletData"         NTV    { 
            "Description"         Str    "Receipt for books purchased", 
            "Parameters"      NTV    { 
                "zip"             NTV    { 
                    "inputRequired"   Str    "y", 
                    "inputRule"       Str    "VALIDATE_US_ZIPCODE", 
                }, 
                "ssn"             NTV    { 
                    "inputRequired"   Str    "y", 
                    "inputRule"       Str    "VALIDATE_SSN", 
                }, 
                "email"           NTV    { 
                    "inputRequired"   Str    "y", 
                    "inputRule"       Str    "VALIDATE_EMAIL", 
                }, 
                "phone"           NTV    { 
                    "inputRequired"   Str    "n", 
                    "inputRule"       Str    "VALIDATE_US_PHONE", 
                }, 
            },
        },
    }, 
}

Creating EJB Property Files

EJB property files (also known as bean property files) are simple text files that determine how an Enterprise JavaBeans (EJB) container sets up and maintains the beans that are part of your NAS applications.

The following topics are presented in this chapter:

Introducing Bean Property Files

Declaring a Deployment Descriptor

Declaring a Session Bean Descriptor

Declaring an Entity Bean Descriptor

Declaring Control Descriptors

Creating Access Control Entries

Manually Editing Property Files

Introducing Bean Property Files A bean property file is a text file containing EJB property information that might otherwise be encapsulated programmatically in the EJB's javax.ejb.DeploymentDescriptor file. The format of the contents in the file corresponds exactly with s standard JavaBeans property file, except that an EJB file may contain entries specific to EJBs, such as access control entries. There are two advantages to providing property information in a simple text file:

Using a text file instead of a binary serialized class makes it easy to manipulate bean meta data without requiring a specialized development tool.

Storing text in source control systems is easier with text files.

Although bean property files are easy to edit in conventional text and code editors, you may prefer to use the NAS deployment tool or the Netscape Application Builder (NAB) to create and manipulate property files graphically.

A bean property file contains entries for an EJB. It must include a base bean deployment descriptor that lists the bean type, globally unique identifier (GUID), version number, bean home name, and the fully-qualified classfile names that comprise the bean A bean property file also contains either a session bean descriptor (for session EJBs), or an entity bean descriptor (for entity EJBs). Optionally, a bean property file may also contain control descriptor entries that specify transaction and security management for the bean.

Bean property files are standard text files and can be edited with any text editor. They can be named anything, but by convention have a filename suffix of .properties.

Declaring a Deployment Descriptor A base bean deployment descriptor provides general information about an EJB, including its type, its GUID, version number, and classfiles that comprise the EJB.

Specifying the EJB Type
All EJBS are either session beans or entity beans. You must specify an EJB's type information using the BeanType property. This property is required for all EJBs.

For example, the following code declares that an EJB is a session bean:

# BeanType 
# Must be one of {SESSION, ENTITY} 
BeanType=SESSION

Specifying a GUID
A GUID provides a unique identifying number for an EJB, servlet, extension, or old-style NAS AppLogic. The GUID property is mandatory for all EJBS. GUIDs are normally assigned automatically by the deployment tool, or the Netscape Application Builder (NAB). You can also generate GUIDs directly by running the kguidgen utility provided with NAS (GUIDs).

The following code illustrates how a GUID is declared in a bean property file.

# GUID (type:STRING)
GUID={B6B9FE90-7E86-11D2-94D6-0060083A5082}

Specifying a Version Number
The EJB property file format provides a mechanism to support bean versioning, using the VersionNumber property. Currently, however, EJB versioning is not supported in NAS 4.0. If you provide this value, always set it to 1:

# VersionNumber (type:Integer) 
VersionNumber=1

Specifying the EJB Location
The Java Naming and Directory Interface (JNDI), registers each EJB using the EJBs unique storage location. The BeanHomeName property enables you to specify the relative path name to the EJB. This entry is required for each EJB.

For example, the following code snippet sets the relative path for the ShoppingCart EJB:

# BeanHomeName 
BeanHomeName=Bookstore/cart/ShoppingCart

Indicating the Classfiles That Make up an EJB
A deployment descriptor must identify the class names, or classfiles, that compose the bean. There are three class files that are part of every bean:

EnterpriseBeanClassName, the fully qualified class name of the EJB's implementation

HomeInterfaceClassName, the fully qualified class name of EJB's home interface

RemoteInterfaceClassName, the fully qualified class name of bean's remote interface

You must supply all three classfile names for each EJB. Failure to do so prevents you from using the EJB. Use a fully qualified Java class name format for each classfile.

For example, the following code snippet establishes the classfiles for the ShoppingCart EJB:

EnterpriseBeanClassName  = GXApp.OnlineBookstore.cart.ShoppingCartBean 
HomeInterfaceClassName   = GXApp.OnlineBookstore.cart.IShoppingCartHome 
RemoteInterfaceClassName = GXApp.OnlineBookstore.cart.IShoppingCart

Declaring a Session Bean Descriptor Some EJB property file information is specific to session beans. This information can be thought of as a session bean descriptor. The session bean descriptor, however, is actually part of the EJB property file. There are three properties that are specific to session beans:

SessionTimeout, which specifies how long a session bean can remain inactive before it is removed by its container.

PassivationTimeout, which specifies how long a session bean can remain inactive before it passivated (temporarily stored out of memory) by the system.

StateManagementType, which specifies if a session bean is stateless or stateful.

If the BeanType property is set to SESSION, then two of these three properties must be set. SessionTimeout and StateManagementType are mandatory for all session beans. PassivationTimeout is optional.

If you set SessionTimeout or PassivationTimeout to zero, NAS uses the system default setting for these values. The system default setting can be adjusted using the NAS Administration Tool. For more information, see the Administration Guide.

Specifying Session Timeout
SessionTimeout is a property that permits you to set the total time in seconds that a stateful session bean can exist without being accessed before it is automatically removed by the system. A value of zero indicates that the bean should use the system default. The SessionTimeout property is mandatory for all session beans.

For example, the following code snippet tells the container to use the system default setting for determining when to remove an inactive session bean:

# SessionTimeout (type:Integer, units: seconds) 
SessionTimeout=0

Specifying Passivation Timeout
PassivationTimeout is a property that permits you to specify the total time in seconds that a stateful session bean can remain active without being accessed before it is removed from memory and stored in a temporary location. A value of zero indicates that the bean should use the system default. If specified, this value should always be less than the time specified for SessionTimeout, or it is effectively be ignored.

Note. This entry is optional. If it is omitted, the container uses a default passivation timeout to passivate a session bean.

For example, the following code snippet tells the container to use the system default to passivate an inactive session bean:

# PassivationTimeout (type:Integer, units: seconds) 
PassivationTimeout=0

Specifying Session Bean State
The StateManagementType property indicates whether a session bean is stateful or stateless. This property is mandatory for all session beans.

For example, the following code indicates that a session bean is a stateful session bean:

# StateManagementType 
# {STATEFUL_SESSION, STATELESS_SESSION} 
StateManagementType=STATEFUL_SESSION

Note. StateManagementType must match the mode that was supplied to ejbc when compiling stubs and skeletons for the session bean.

Declaring an Entity Bean Descriptor Some EJB property file information is specific to entity beans. This information can be thought of as an entity bean descriptor. The entity bean descriptor, however, is actually part of the EJB property file. There are two properties that are specific to entity beans:

PrimaryKeyClassName, which specifies the fully qualified class name of the entity bean's primary key.

IsReentrant, which indicates whether an entity bean's code can be reentered.

These properties must be present if BeanType=ENTITY. Otherwise, they must omitted.

Specifying the Primary Key Class Name
Use the PrimaryKeyClassName property to specify the fully qualified class name of the entity bean's primary key. This can be either a user-defined class or a simple class (such as java.lang.String), but it must be serializable.

For example, the following code snippet indicates that the primary key corresponds to a Java string type:

# PrimaryKeyClassName 
PrimaryKeyClassName=java.lang.String

Indicating Reentry Support
Entity beans can be optionally reentrant. If you implement an entity bean with the necessary thread synchronization and constructs necessary to support reentrancy, you can set the IsReentrant property to true. Otherwise, always set this property to false.

For example, the following code snippet indicates that an entity bean is not reentrant:

# IsReentrant {true | false} 
IsReentrant=false

Declaring Control Descriptors You can use additional properties to specify EJB transaction and security using control descriptors. Control descriptors also enable you to specify optional, individual property overrides for bean methods.

As with session bean and entity bean descriptors, control descriptors are actually part of the bean property file. Control descriptors, however, have an indexing syntax that enables you to associate an index number with a particular method, and then use that index number to indicate specific property overrides for transaction and security control. For example, you must always provide at least one MethodName control descriptor for all beans, and it takes the form:

ControlDescriptor.0.MethodName=DEFAULT

The ControlDescriptor preface indicates that what follows is a descriptor, rather than a simple bean property. The 0 value is a default index value that indicates a default behavior to apply to all methods that do not have overrides. Each subsequent control descriptor for specific method names must increment the index by 1 without skipping any numbers. MethodName is used to indicates a specific method to override. When MethodName=DEFAULT, the container knows to apply the settings for all control descriptors with an index of 0 to any bean method that does not have overrides. Otherwise, MethodName must always specify the actual name of a bean method.

There are four control descriptor properties you can set for a bean and its methods:

MethodName, which specifies both a default index value for methods that are not overriden, and index values for specifically named EJB methods. The index is used in subsequent control descriptors and access control identifiers to specify which method is affected by the property setting.

TransactionAttribute, which enables you to specify transaction requirements for an EJB or specific methods of an EJB.

RunAsMode, which enables you to specify whether an EJB uses a client's identity to execute methods, or whether it uses a specific user identity to run methods.

RunAsIdentity, which is used to indicate a specific identity to use when running a method whose RunAsMode is set to SPECIFIED_IDENTITY.

RunAsMode and RunAsIdentity are used with access control descriptors to provide secure EJB access. For more information about access control descriptors, see Creating Access Control Entries.

Creating Index Values for EJB Methods
You must always specify at least one MethodName property for each EJB. This property declaration always takes the form:

ControlDescriptor.0.MethodName=DEFAULT

This form of the MethodName property provides a default index value for all EJB methods for which you do not supply explicit index numbers. In effect, it creates a default control descriptor for all EJB methods that do not have their own, specific index entries.

You can also optionally create explicit index values for any EJB methods using the following MethodName syntax:

ControlDescriptor.<n>.MethodName=<insertmethodnamehere>

<n> indicates an index value greater than 0, and <insertmethodnamehere> is a place holder for the name of an actual bean method. You must always increment <n> by one each time you provide an index value for another method, and you cannot skip numbers.

For example, the following code snippet provides a default method control descriptor, and two additional, explicit method control description indexes:

# Method Names
ControlDescriptor.0.MethodName=DEFAULT
ControlDescriptor.1.MethodName=UnloadCart
ControlDescriptor.2.MethodName=TallyCart

Providing index entries for method names enables you to set properties and conditions on them, such as transaction attributes, that differ from the setting for the bean as a whole.

Specifying Transaction Requirements
One of the most powerful features of EJBs is that you can stipulate a global level of transaction support for the bean in the bean property file. In all but one case, when the bean container processes the bean property file, it uses these settings to handle and initiate transactions as needed, freeing you from having to code transaction handling in your bean unless you desire to do so.

The TransactionAttribute property specifies the level of transaction support for a bean.The following table lists the attributes for transaction management and describes what each attribute means.


Transaction Management Attribute	Purpose
TX_BEAN_MANAGED	The EJB or method explicitly controls transaction boundaries using the javax.transaction.UserTransaction interface. The container does not manage transactions for this bean.
TX_MANDATORY	The EJB container invokes the EJB method using the transaction context associated with the calling client. If the client has not started a transaction when the bean is invoked, the container throws the TransactionRequired exception.
TX_NOT_SUPPORTED	The container invokes the EJB without a transaction context. If a client calls with a transaction scope, the container suspends the association of the transaction with the current thread before delegating the method call to the EJB. When the bean's work is completed, the container resumes the transaction.
TX_REQUIRED	The container invokes the EJB using the client's transactional context, unless the client does not have one. If the client does not have a transaction in progress, the container automatically starts a transaction before delegating the method call to the bean. The container attempts to commit the transaction when the method call on the bean is completed, unless the transaction was marked for rollback or an exception was raised.
TX_REQUIRES_NEW	The EJB requires that the container start a new transaction when a method is invoked. The container attempts to commit the transaction when the bean's method call completes. When a client calls into a bean with this attribute, the container suspends the client's transaction before starting the bean's new transaction. Upon completing the bean's transaction, the container resumes the client's suspended transaction.
TX_SUPPORTS	The EJB mirrors the client's transaction scope. If the client has a transaction context, the EJB is invoked in that context. If not, the EJB is invoked without a transaction context.

Note. If you set TransactionAttribute to TX_BEAN_MANAGED, you must handle transactions in your bean code. The bean container will not handle transactions for a bean with TransactionAttribute set to TX_BEAN_MANAGED.

The syntax for the TransactionAttribute property takes the form:

ControlDescriptor.0.TransactionAttribute=<value>

where <value> is one of the transaction levels detailed in the table above.

For example, the following code snippet sets the TransactionAttribute for the EJB to TX_SUPPORTS:

ControlDescriptor.0.TransactionAttribute=TX_SUPPORTS

Specifying Identity Information
By default, when you call an EJB method, it executes under the auspices of the client's identity. The client's identity is something your system administrator uses on your systems to identify users, such as user names. EJB containers read identity information from your system, and translate it into a form usable by EJBs.

You can use the control descriptor's RunAsMode property to specify that a bean or a bean method execute under any client's identity (the default), or that a bean or method execute as if it were accessed by a specific user. If you specify that a bean or method executes under the auspices of a specific user other than the actual client, then you must also use the RunAsIdentity property to specify the identity to run under.

RunAsMode takes the following form:

ControlDescriptor.n.RunAsMode={CLIENT_IDENTITY | SPECIFIED_IDENTITY}

where n is 0 to apply the mode to the entire bean or greater than 0 to apply to a specific bean method.

Note. The EJB specification permits a third option for RunAsMode, SYSTEM_IDENTITY, but support for this option is not available in NAS.

For example, the following code snippet sets the global mode for a bean to use the current client's identity:

# RunAsMode 
ControlDescriptor.0.RunAsMode=CLIENT_IDENTITY

The following code snippet sets the global mode for the bean to a specific user, and then uses RunAsIdentity to list that user as SystemAdministrator:

ControlDescriptor.0.RunAsMode=SPECIFIED_IDENTITY
ControlDescriptor.0.RunAsIdentity=SystemAdministrator

To force a method to run using a specified identity, replace the global index value (0) with the method's index value. For example, the following code sets the global mode for a bean to CLIENT_IDENTITY, then sets the user ID for a specific method associated with index value 1 to SystemAdministrator:

# RunAsMode 
ControlDescriptor.0.RunAsMode=CLIENT_IDENTITY
ControlDescriptor.1.RunAsMode=SPECIFIED_IDENTITY
ControlDescriptor.1.RunAsIdentity=SystemAdministrator

Note. Besides forcing a bean or method to run under the auspices of a certain user, you can also restrict the ability to run a bean or its methods to particular users with access control entries. For information about using access control entries, see Creating Access Control Entries.

Note. Client and group names are defined in the directory server. For information about adding directory server users, see Storing and Managing Users and Groups in the Administration Guide. For more information about component security in general, see Writing Secure Applications.

Specifying Parameter Passing Rules
When a servlet or EJB calls another bean that is co-located within the same process, NAS does not perform marshalling of all call parameters by default. This optimization allows the collocated case to execute far more efficiently than if strict "by-value" semantics were used. In certain cases, however, you may want to ensure that parameters passed to a bean are always passed by value. NAS supports the ability to mark a bean or even a particular method within a bean as optionally requiring pass by value semantics. Because this option can decrease performance by greatly increasing call overhead, the default value is "false" if this entry is unspecified.

The following code snippet forces a bean to pass all parameters by value:

ControlDescriptor.0.AlwaysPassByValue=true

Creating Access Control Entries Access control entries in a bean property file declare security properties of a bean. The access control entry for a bean specifies the name or names of clients or groups that can use the bean. The bean's container uses the information in the bean property file to determine who has access to the bean at run time.

Note. Client and group names are defined in the directory server. For information about adding directory server users, see Storing and Managing Users and Groups in the Administration Guide.

Specifying Access Control
Access control entries for a bean must include a MethodName entry that is set to DEFAULT, and one Identity entry for each client or group that can access the bean. For example, the following access control entries tell a bean container that only members of the groups "manager" and "is-staff" can access a bean.

# default ACL for beans says bean can only be invoked by
# members of the group "managers" or "is-staff"
AccessControlEntry.0.MethodName=DEFAULT 
AccessControlEntry.0.Identity.0=managers 
AccessControlEntry.0.Identity.1=is-staff

The MethodName=DEFAULT entry provides default access control for any method that does not have its own access control entry elsewhere in the property file. For more information about providing access control entry overrides for individual bean methods, see "Overriding Access Control on Bean Methods" on page 205.

You can provide as many or as few access control entries for a bean as desired. As this example illustrates, Identity entries are indexed. The first entry is always 0, and subsequent entries are incremented in value by 1.

Note. Specified Identity values must already be known to the system. A common error message seen when attempting to register a bean with an access control entry containing an unknown identity is:

unable to complete bean meta-data registration
unable to set value for "AllowedIdentity"

Client and group names are defined in the directory server. For information about adding directory server users, see Storing and Managing Users and Groups in the Administration Guide. For more information about component security in general, see Writing Secure Applications.

Overriding Access Control on Bean Methods
Besides providing access control for an entire bean, you can specify different access controls for individual bean methods. Frequently, a bean provides a broad set of access control entries, but some of its methods may require a more restrictive set of rights. If you specify access control for individual bean methods, the method entries supersede the access control rights you specified for the entire bean.

As with bean-level access control entries, method-level access control entries consist of two parts:

MethodName specifies the name of the method for which you are providing the access control entries.

Identity specifies the name of the client or group to whom you grant execute privilege.

MethodName is indexed. The index for the first MethodName entry in a bean property file is 0. It defines the default access for any method that does not have it own access control entry.

All subsequent method-level access control entries increment the index value by 1. For example, the following snippet provides access control for a specific method, IncrementSalary, and limits access to those members of the PayRoll group:

AccessControlEntry.1.MethodName=IncrementSalary
AccessControlEntry.1.Identity.0=Payroll

You can provide as many or as few access control entries for bean methods as desired. Identity entries for each method, too, are indexed. The first entry is always "0", and subsequent entries are incremented in value by 1.

Running as Another User
When you access an EJB, you run the bean as a client with a known identity. You can force a bean or one of its methods to run with a specific identity by adding a RunAsMode statement to the bean property file.

The EJB specification lists three identities that can be used to execute a bean:

CLIENT_IDENTITY, which means that a bean or its methods are executed using the client's identity. This is the default identity for beans without identity entries in the property file.

SPECIFIED_IDENTITY, which means that a bean or its method(s) execute using a particular identity that is supplied as an argument to RunAsMode. A SPECIFIED_IDENTITY overrides the client's actual identity.

SYSTEM_IDENTITY, which means that a bean or its method(s) execute using a system resource identity. Currently NAS does not support using the SYSTEM_IDENTITY mode.

To specify that a bean run in CLIENT_IDENTITY mode, add the following entry to the bean property file:

# RunAsMode
ControlDescriptor.0.RunAsMode=CLIENT_IDENTITY

To specify that a bean run in SPECIFIED_IDENTITY mode, you must add two lines to the bean property file: one that indicates the mode to run in, and a second that indicates the specific identity to use. In the following example, a bean is set up to run using the Payroll identity.

# RunAsMode 
ControlDescriptor.0.RunAsMode=SPECIFIED_IDENTITY 
# RunAsIdentity
ControlDescriptor.0.RunAsIdentity=Payroll

Example Bean Property File This example bean property file comes from the Online Bookstore sample application:

# Shopping CartBean properties
# BeanType
#
# Specify one of session or entity as well as the relevant
# properties below.  Properties in this file for the "other" type 
# of bean will be ignored.
#
# { SESSION, ENTITY }
BeanType=ENTITY
# GUID (type:STRING)
#
GUID={A000E626-0A12-1656-EBD7-0800208055C0}
#######################################################################
# DeploymentDescriptors
#
# VersionNumber (type:DWORD)
VersionNumber=1
# BeanHomeName
#
# This is the name used to register the bean in JNDI.  The name is
# always relative; the JNDI root prefix is specified elsewhere.
#
BeanHomeName=nsOnlineBookstore/BookAccount
# EnterpriseBeanClassName
# HomeInterfaceClassName
# RemoteInterfaceClassName
#
# In order to boostrap from this file, the user must specify these 3
# mandatory classfiles.  Use the java class name format, i.e
# "hello.HelloImpl"
#
EnterpriseBeanClassName=GXApp.nsOnlineBookstore.account.BookAccountBean
HomeInterfaceClassName=GXApp.nsOnlineBookstore.account.IBookAccountHome
RemoteInterfaceClassName=GXApp.nsOnlineBookstore.account.IBookAccount
PrimaryKeyClassName=java.lang.String
# for entity beans, mandatory property
IsReentrant=true
#######################################################################
# ControlDescriptor
# 
# The MethodName must always be specified, and should be the
# special string "DEFAULT" to indicate that the control
# descriptor changes apply to all methods.
# 
# Multiple control descriptors can be specified by
# increasing the index, i.e. ControlDescriptor.1.MethodName=foobar
# Indicies cannot be skipped.
#
ControlDescriptor.0.MethodName=DEFAULT
# RunAsMode
#
# { CLIENT_IDENTITY, SPECIFIED_IDENTITY, SYSTEM_IDENTITY }
#
ControlDescriptor.0.RunAsMode=CLIENT_IDENTITY
# TransactionAttribute
#
# { TX_BEAN_MANAGED, TX_MANDATORY, TX_NOT_SUPPORTED, TX_REQUIRED,
#   TX_REQUIRES_NEW, TX_SUPPORTS }
#
ControlDescriptor.0.TransactionAttribute=TX_REQUIRED

Manually Editing Property Files NAS provides an administrative tool and a visual application tool (NAB) that permit you to build bean property files in a visual manner. Because bean property files are simple text files, however, you can choose to create or modify them by hand, and manually register them to NAS using the provided utility beanreg (for more information, see Manually Deploying EJBs in the Administration Guide).

If you modify a bean's property file by hand in a text editor, here are a few precautionary items to note.

Although the beanreg utility catches most syntactical errors in a property file, it cannot detect all possibly legal semantic variations that you can introduce when editing a file by hand. For example, if you modify a bean's deployment descriptor using the deployment tool, the deployment tool does not permit you to create a bean with a default transaction for a bean of TX_BEAN_MANAGED and a per-method overrride that is anything but TX_BEAN_MANAGED. You can, however, create a bean property file by hand that violates this rule, and beanreg does not catch it.

To facilitate support for Java and EJB method overloading, NAS internally mangles method names to make them unique. For instance, the following methods, have the same method name, but are uniquely identified internally by a mangled identifier:

public void snap() 
public void snap(int snaps)

Although this mangling is normally hidden from the you, it becomes visible when you edit bean property files by hand and want to supply per-method overrides for either access control entries or control descriptors. For example, to manually set the second snap() method to transaction-mode TX_REQUIRED, the property file should contain an entry resembling:

ControlDescriptor.1.MethodName=snap__void__int 
ControlDescriptor.1.TransactionAttribute=TX_REQUIRED

You can discover the mangled names for your bean's methods by using the -p option to the beanreg utility. Given a standard bean property file, run:

beanreg -p <your bean.properties file>

beanreg prints out a list of method names and their corresponding mangled identifiers. Use these identifiers when editing a property file.

Be sure to rerun beanreg if you change your the remote or home interfaces for an EJB. Changing these interfaces may invalidate method-level overrides, and if they become invalid, beanreg refuses to register the bean. If this occurs, comment out the method-level overrides, rerun beanreg -p to identify the new method identifiers, and modify the property file accordingly.

Creating Datasource Property Files

To create a JDBC datasource, you must provide a properties file for the datasource and register it with NAS. This file contains several entries that define the way NAS connects to the datasource.

The file can be named anything, but generally has a suffix of .props. Fieldnames are not case-sensitive.

Datasource Property File Entries A datasource property file contains the following entries:


Property	Example	Description
Database	Database=ksample	Name of the database to connect to.
Datasource	Datasource=ksample	Name to assign to this datasource.
Username	Username=kdemo	Valid user name for this database
Password	Password=kdemo	Valid password for the user name listed.
DriverType	DriverType=ORACLE_OCI	Backend-specific JDBC driver. One of the following: ORACLE_OCI (Oracle) DB2_CLI (DB2) INFORMIX_CLI (Informix) SYBASE_CTLIB (Sybase) ODBC (ODBC)
ResourceMgr	ResourceMgr=oraksample	Optional. If this attribute is set, the datasource is available for distributed transactions by way of the resource manager listed. If this attribute is not specified, the datasource is only valid for a local database. The value must be a name that you create for a resource manager under the RESOURCEMGR key. .

Manually Registering Datasources to NAS You generally specify the datasource properties file when you deploy your application, and your datasources are automatically registered.

If you need to register a datasource manually, use the provided utility dsreg. dsreg is a command-line utility that requires the datasource name and properties file name, as in the following example:

dsreg "dataSource" dsPropsFile.props

For more information, see Manually Deploying Data Sources in the Administration Guide.

© Copyright 1999 Netscape Communications Corp.