
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WLE Doc Home \| CORBA Programming & Related Topics \| Previous \| Next \| Contents \| Index

Server Description File

This chapter contains the following topics:

Creating the Server Description File. This section includes the following topics:
- About Object Activation and Deactivation
- Server Description File Syntax
Sample Server Description File

When you create a Java server application meant to be run in the WLE environment, the buildjavaserver command accepts the following information:

Default activation and transaction policies for all the objects implemented in the server application
The server declaration, which includes the name of the Server object and the name of the server descriptor file
The declarations of each of the modules and interfaces defined in the server application's OMG IDL file
Nondefault activation and transaction policies for specific objects implemented in the server application
A description of the content of the server application's jar archive, which contains all the files needed by the server application

You specify all the preceding information in a Server Description File, which is used by the buildjavaserver command to create the server descriptor file and, optionally, build a server jar file.

Creating the Server Description File

The means to provide the information required by the buildjavaserver command is the Server Description File, which is expressed in the XML language. XML looks very similar to HTML; its key difference is that no XML tag is predefined. Every XML file uses a Document Type Definition (DTD) file that specifies:

What the XML tags are
What attributes can be attached to an element
What elements can be used in other elements

The DTD required by the WLE system is packaged with the WLE software. You create the Server Description File using a common text editor. The section "About Object Activation and Deactivation" on page 2-2 provides important background information about the policies you define in the Server Description File, and the section "Server Description File Syntax" on page 2-3 provides the details on how to specify the server description information in a Server Description File.

<?xml version="1.0"?>
<!DOCTYPE M3-SERVER SYSTEM "m3.dtd">

If you want to override the default activation or transaction policy used by the buildjavaserver command, you can override those defaults in the prolog using the following syntax:

<?xml version="1.0"?>
<!DOCTYPE M3-SERVER SYSTEM "m3.dtd" [
       <!ENTITY TRANSACTION_POLICY "
transaction_value"
>
       <!ENTITY ACTIVATION_POLICY "
activation_value"
>
]>

In the preceding syntax, note the following:

transaction_value represents one of the following: never , ignore , optional , or always . (Note that the double quotes are a required part of the syntax.)
activation_policy represents one of the following: method , transaction , or process .
The square brackets ([ and ]) preceding and following the!ENTITY tags are required; that is, the brackets in the preceding syntax do not imply that the enclosed text is optional.

Note that you specify default activation and transaction policies in the prolog only if you want to override the following WLE system defaults:

Activation Policy

method

Transaction Policy

optional

Server Declaration

Immediately following the prolog is the server declaration, which is an optional part of the Server Description File. The server declaration contains the following:

The fully qualified name of the Server object
The fully qualified name of the file containing the server descriptor

To specify the server declaration, use the following syntax:

<M3-SERVER SERVER-IMPLEMENTATION="
server_name"

           SERVER-DESCRIPTOR-NAME="
server_descriptor"
>
</M3-SERVER>

In the preceding syntax, note the following:

server_name represents the fully qualified name of the class that contains the Server object. Qualified names use dot separators, not slashes. If you do not specify the Server object, the WLE system creates a default Server object that opens and closes the XA resource manager associated with the server application, if any, when the server application is started and stopped, respectively. (Note that the double quotes are a required part of the syntax.)
server_descriptor represents the name of the file where the server descriptor will be stored. This file name typically has a .ser suffix. If you do not specify a server descriptor, the buildjavaserver command uses Server.ser by default.

Module and Implementation Declarations

After the prolog and the server declaration (if present), the Server Description File contains module and implementation declarations, which may be specified as nested elements.

The module declarations specify Java packages for the server application. Interface declarations specify:

The interface repository ID for the interface being implemented
Optionally, nondefault activation or transaction policies for objects that implement the interface

Module Declaration Syntax

A module declaration uses the following syntax:

<MODULE name="
name"
>
     .
     .
     .
</MODULE>

In the preceding syntax, note the following:

name represents the name of either a single Java package, or a set of nested packages. This variable is needed if it exists in the OMG IDL file, and it is used for scoping and grouping. Its use must be consistent with the way it is used inside the OMG IDL file.
A module declaration can contain an implementation declaration, nested module declaration, or both.
You can specify a nested package in a single module declaration using the dotted notation, or you can factor out the package name using nested module declarations. For example, either of the following module declarations for the com.acme package is valid:
<MODULE name="com.acme">
.
.
.
</MODULE>

or:
<MODULE name="com">
<MODULE name="acme">
.
.
.
</MODULE>
</MODULE>

Implementation Declaration Syntax

An implementation declaration uses the following syntax:

<IMPLEMENTATION name="
name"

  [implements="
interface_id"
]
  [transaction="
transaction_policy"
]
  [activation="
activation_policy"
] />

In the preceding syntax, note the following:

name represents the name of the implementation class. If the implementation declaration is not nested inside any module declaration, name must be the fully qualified class name, using the dotted notation.
If the implementation declaration is nested inside one or more module declarations, the names of the modules will be prepended to the implementation name to specify the whole name. The base class of the implementation name must be a skeleton class generated by the m3idltojava command.
interface_id represents the IDL interface repository ID for the interface being implemented. This clause in the implementation declaration is optional. If you do not specify an interface ID, the WLE system uses the most derived interface ID found in the skeleton class by default. The interface ID must match the most derived interface ID found in the skeleton class.

transaction_policy represents the transaction policy used by the implementation in the server, and must be one of the keywords listed and described in the following table:

Policy	Description
never	The implementation is not transactional. Objects created for this interface can never be invoked within the scope of a transaction. The system generates an exception (INVALID_TRANSACTION ) if an implementation with this policy is involved in a transaction. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored.
ignore	The implementation is not transactional. The system allows requests on this object to be made within the scope of a transaction, but the object is not part of the transaction. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored. (The BEA TUXEDO infrastructure always enforces the use of the TPNOTRAN flag (see tpcall(3) in the BEA TUXEDO System Reference Manual) for requests associated with implementations that have this policy.
optional	The implementation may be transactional. Objects can be invoked either inside or outside the scope of a transaction. If the AUTOTRAN parameter is enabled in the UBBCONFIG file for the interface, the implementation is transactional. Servers containing transactional objects must be configured within a group associated with an XA-compliant RM.
always	The implementation is transactional. Objects are always transactional. If a request is made outside the scope of a transaction, the system automatically starts a transaction before invoking the method, and the transaction is committed when the method ends. (This is the AUTOTRAN feature.) Servers containing transactional objects must be configured within a group associated with an XA-compliant RM.

Policy

Description

never

The implementation is not transactional. Objects created for this interface can never be invoked within the scope of a transaction. The system generates an exception (INVALID_TRANSACTION ) if an implementation with this policy is involved in a transaction. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored.

ignore

The implementation is not transactional. The system allows requests on this object to be made within the scope of a transaction, but the object is not part of the transaction. An AUTOTRAN policy specified in the UBBCONFIG file for the interface is ignored. (The BEA TUXEDO infrastructure always enforces the use of the TPNOTRAN flag (see tpcall(3) in the BEA TUXEDO System Reference Manual) for requests associated with implementations that have this policy.

optional

The implementation may be transactional. Objects can be invoked either inside or outside the scope of a transaction. If the AUTOTRAN parameter is enabled in the UBBCONFIG file for the interface, the implementation is transactional. Servers containing transactional objects must be configured within a group associated with an XA-compliant RM.

always

The implementation is transactional. Objects are always transactional. If a request is made outside the scope of a transaction, the system automatically starts a transaction before invoking the method, and the transaction is committed when the method ends. (This is the AUTOTRAN feature.) Servers containing transactional objects must be configured within a group associated with an XA-compliant RM.

The transaction clause is optional. If you do not specify a transaction policy, the default is optional , unless the default value has been overridden in the prolog.

activation_policy represents the activation policy used by the implementation in the server, and must be one of the keywords listed and described in the following table:

Policy	Description
method	The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the method. At the completion of a method, the object is deactivated. When the next method is invoked on the object reference, the CORBA object is activated (the object ID is associated with a new servant). This behavior is similar to that of a BEA TUXEDO stateless service.
transaction	The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the transaction. During the transaction, multiple object methods can be invoked. This is a model of resource allocation that is similar to that of a BEA TUXEDO conversational service. This model is less expensive than the BEA TUXEDO conversational service in that it uses fewer system resources. This is because of the WLE ORB's multicontexted dispatching model (that is, the presence of many servants in memory at the same time for one server), which makes it possible for a single server process to be shared by many concurrently active servants, which service many clients. In the BEA TUXEDO system, the process would be dedicated to a single client and to only one service for the duration of a conversation.
process	The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the process. Note: The TP Framework API provides an interface method (com.beasys.Tobj.TP.deactivateEnable() ) that allows the application to control the timing of object deactivation for objects that have the activation policy set to process . For a description of this method, see the Javadoc.

Policy

Description

method

The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the method. At the completion of a method, the object is deactivated. When the next method is invoked on the object reference, the CORBA object is activated (the object ID is associated with a new servant). This behavior is similar to that of a BEA TUXEDO stateless service.

transaction

The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the transaction. During the transaction, multiple object methods can be invoked. This is a model of resource allocation that is similar to that of a BEA TUXEDO conversational service.

This model is less expensive than the BEA TUXEDO conversational service in that it uses fewer system resources. This is because of the WLE ORB's multicontexted dispatching model (that is, the presence of many servants in memory at the same time for one server), which makes it possible for a single server process to be shared by many concurrently active servants, which service many clients. In the BEA TUXEDO system, the process would be dedicated to a single client and to only one service for the duration of a conversation.

process

The activation of the CORBA object (that is, the association between the object ID and the servant) lasts until the end of the process.

Note: The TP Framework API provides an interface method (com.beasys.Tobj.TP.deactivateEnable() ) that allows the application to control the timing of object deactivation for objects that have the activation policy set to process . For a description of this method, see the Javadoc.

The activation policy determines the default in-memory activation duration for a CORBA object. A CORBA object is active in a POA if the POA's active object map contains an entry that associates an object ID with an existing servant. Object deactivation removes the association of an object ID with its active servant.

The activation clause is optional. If you do not specify an activation policy, the default is method , unless the default value has been overridden in the prolog.

Archive Declaration

The archive declaration describes the content of the jar archive that contains all the server application files. This section of the Server Description File is optional; if you do not provide this section, you can build the jar archive by using the jar command directly. However, declaring an archive in the Server Description File simplifies the process of collecting and identifying the files.

The archive declaration is the last section of the Server Description File. If you do not include an archive declaration, the buildjavaserver command produces only the server descriptor and places it in the file specified by the server-descriptor-name attribute in the server declaration.

You specify the content of the <ARCHIVE> element as either fully qualified Java classes or file names. When specifying file names, note that path specifications are system dependent, which has implications on archive portability.

The buildjavaserver command has the searchpath option, which you can use to specify the search path for the files and classes included in the archive.

Note: After you use the buildjavaserver command to create the jar archive, you might find it useful to verify the contents of the archive by using the jar tvf command. This helps make sure that the archive contains all the intended files.

Archive Declaration Syntax

The archive declaration has the following syntax:

<ARCHIVE name="
archive-name"
>
      [<CLASS name="
class-name"
 />] [...]
      [<PACKAGE name="
package-name"
 />] [...]
      [<PACKAGE-RECURSIVE name="
package-name"
/>] [...]
      [<PACKAGE-ANONYMOUS />]
      [<FILE prefix="
file-prefix"
 name="
file-name"
 />] [...]
      [<DIRECTORY prefix="
dir-prefix"
 name="
dir-name"
 />] [...]
</ARCHIVE>

In the preceding syntax, note the following:

Each of the entities nested inside the <ARCHIVE> element is optional, and there are no default values for any of these entities.
The [...] construct next to an entity indicates that you can provide multiple such entities.
archive-name represents the name of the jar archive file to be created by the buildjavaserver command. The archive created contains all the classes, packages, and files specified within the <ARCHIVE> element.
class-name represents the fully qualified name of the class to be included in the archive. All inner classes of that class are included as well.
package-name represents the fully qualified name of a package to be included in the archive. All the classes belonging to that package are included as well.
If you want to include nested packages, use the <PACKAGE-RECURSIVE> element.
Use the <PACKAGE-ANONYMOUS> element to specify that all classes not in a package are to be included in the archive. (This refers to the classes that do not have a package statement in the Java source.)
file-name represents the name of a file to be included in the archive. You can use the file-prefix construct to specify a path name. This path name is prepended to the file name when the file is located to be included in the archive; however, the file is stored in the archive only with the name specified by file-name.
For example, if the file-name is acme/iconf.gif , and the file-prefix is /dev , the buildjavaserver command looks for the file /dev/acme/iconf.gif and stores it in the archive as acme/iconf.gif .
dir-name represents the path name of the directory to be included in the archive. All subdirectories are included as well. You can use the dir-prefix construct to specify a directory path. The directory path is prepended to the directory name when the directory is located to be included in the archive; however, the file is stored in the archive only with the name specified by dir-name.

Sample Server Description File

Listing 2-1 shows a sample Server Description File.

Listing 2-1 Sample Server Description File

<?xml version="1.0"?>
<!DOCTYPE M3-SERVER SYSTEM "m3.dtd"]>
<M3-SERVER
server-implementation="com.beasys.samples.BankAppServerImpl"
      server-descriptor-name="BankApp.ser">

      <MODULE name="com.beasys.samples">
           <IMPLEMENTATION
                  name="TellerFactoryImpl" />
                  activation="process"
                  transaction="never"
           />

           <IMPLEMENTATION
                  name="TellerImpl"/>
                  activation="method"
                  transaction="never"
           />

           <IMPLEMENTATION
                  name="DBAccessImpl"
                  activation="method"
                  transaction="never"
           />

     </MODULE>

     <ARCHIVE name="BankApp.jar">
           <PACKAGE name="com.beasys.samples"/>
     </ARCHIVE>
</M3-SERVER>

For an example of another Server Description File, see Creating CORBA Java Server Applications.