|
|
Server Description File
This topic includes the following sections:
When you create a Java server application meant to be run in the BEA WebLogic Enterprise environment, the buildjavaserver command accepts the following information:
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:
The DTD required by the BEA WebLogic Enterprise system is packaged with the BEA WebLogic Enterprise software. You create the Server Description File using a common text editor. The section "About Object Activation and Deactivation" provides important background information about the policies you define in the Server Description File, and the section "Server Description File Syntax" provides the details on how to specify the server description information in a Server Description File.
About Object Activation and Deactivation
The BEA WebLogic Enterprise TP Framework application programming interface (API) provides callback methods for object activation and deactivation. These methods provide the ability for application code to implement flexible state management schemes for CORBA objects.
State management is the way you control the saving and restoring of object state during object deactivation and activation. State management also affects the duration of object activation, which influences the performance of servers and their resource usage. The external API of the TP Framework includes the com.beasys.Tobj_Servant.activate_object and com.beasys.Tobj_Servant.deactivate_object methods, which provide a possible location for state management code. Additionally, the TP Framework API includes the com.beasys.Tobj.TP.deactivateEnable method to enable the user to control the timing of object deactivation. The default duration of object activation is controlled by policies assigned to implementations when the server application is built by the buildjavaserver command.
While CORBA objects are active, their state is contained in a servant. This state must be initialized when objects are first invoked (that is, the first time a method is invoked on a CORBA object after its object reference is created) and on subsequent invocations after objects have been deactivated.
While a CORBA object is deactivated, its state must be saved outside the process in which the servant was active. When an object is activated, its state must be restored. The object's state can be saved in shared memory, in a file, in a database, and so forth. It is up to the programmer to determine what constitutes an object's state, and what must be saved before an object is deactivated, and restored when an object is activated.
You can use the Server Description File to set activation policies to control the duration of object activations in the server process. The activation policy determines the in-memory activation duration for a CORBA object. A CORBA object is active in a Portable Object Adapter (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.
Server Description File Syntax
The Server Description File has the following four major parts:
The sections that follow explain the syntax and how to specify each of these parts of the Server Description File.
Prolog
Every Server Description File begins with the following required prolog:
<?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:
Note that you specify default activation and transaction policies in the prolog only if you want to override the following BEA WebLogic Enterprise 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:
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:
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:
A module declaration uses the following syntax:
<MODULE name="name">
.
.
.
</MODULE>
In the preceding syntax, note the following:
<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:
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.
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 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.
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 BEA WebLogic Enterprise 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 API 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:
If you want to include nested packages, use the <PACKAGE-RECURSIVE> element.
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.
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.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|