|
|
This chapter contains the following topics:
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.
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:
Creating the Server Description File
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.
The WLE 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.
The Server Description File has the following four major parts:
About Object Activation and Deactivation
Server Description File Syntax
The sections that follow explain the syntax and how to specify each of these parts of the Server Description File.
Every Server Description File begins with the following required prolog:
<?xml version="1.0"?> 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"?> In the preceding syntax, note the following:
Prolog
<!DOCTYPE M3-SERVER SYSTEM "m3.dtd">
<!DOCTYPE M3-SERVER SYSTEM "m3.dtd" [
<!ENTITY TRANSACTION_POLICY "
transaction_value"
>
<!ENTITY ACTIVATION_POLICY "
activation_value"
>
]>
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" In the preceding syntax, note the following:
SERVER-DESCRIPTOR-NAME="
server_descriptor"
>
</M3-SERVER>
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:
Module and Implementation Declarations
A module declaration uses the following syntax:
<MODULE name="
name"
> In the preceding syntax, note the following:
Module Declaration Syntax
.
.
.
</MODULE>
<MODULE name="com.acme">
.
.
.
</MODULE>
or:
<MODULE name="com">
<MODULE name="acme">
.
.
.
</MODULE>
</MODULE>
An implementation declaration uses the following syntax:
<IMPLEMENTATION name="
name" In the preceding syntax, note the following:
Implementation Declaration Syntax
[implements="
interface_id"
]
[transaction="
transaction_policy"
]
[activation="
activation_policy"
] />
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.
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.
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.
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.
The archive declaration has the following syntax:
<ARCHIVE name="
archive-name"
> In the preceding syntax, note the following:
Archive Declaration
Archive Declaration Syntax
[<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>
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 .
Listing 2-1 shows a sample Server Description File.
Listing 2-1
Sample Server Description File
<?xml version="1.0"?> For an example of another Server Description File, see Creating CORBA Java Server Applications.
Sample Server Description File
<!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>
|
Copyright © 1999 BEA Systems, Inc. All rights reserved.
|