
	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

Java Server Application Concepts

This chapter presents the following WLE topics:

For background information about WLE server applications and how they work, see Getting Started.

Overview

This section provides an overview of the Java server application creation process. The file names shown are based on the Bankapp sample application that is included with the WLE software. Many steps have been omitted from this simple overview. The purpose here is to give you an idea of the overall process, before you read about CORBA object state management and other key concepts in the remainder of this chapter, and before you read about detailed build steps in subsequent chapters.

To create a Java server application:

Create a text file that describes the interfaces for your CORBA objects.
The descriptions are written in the Object Management Group Interface Definition Language (OMG IDL). For example, the BankApp.idl file describes the Teller and TellerFactory interfaces.
Compile the IDL files by using the m3idltojava compiler to generate, for each interface, Java object implementation files, client stubs, server skeletons, Helper classes, and Holder classes. Do not edit these files.
Copy each object implementation file to a new file.
For example, compiling the BankApp.idl file with the m3idltojava compiler generates a Teller.java file and a TellerFactory.java file. To create Java files that you can use as a starting point for adding your business logic and object implementations, you can:
1. Copy Teller.java to TellerImpl.java.
2. Copy TellerFactory.java to TellerFactoryImpl.java.
Edit your object implementation files, adding the business logic to each object's methods.
Create the Server object, which is code that performs the initialize and release functions for the server application.
Use the javac compiler to compile all the *.java files into Java bytecodes (*.class files).
Create a text file called a Server Description File, which is expressed in the XML language.
To see a sample file, open the BankApp.xml file that is included with the WLE software in the following directory:
Windows NT
drive:\M3dir\samples\corba\bankapp_java\jdbc\

UNIX
/usr/local/M3dir/samples/corba/bankapp_java/jdbc/

In your Server Description File, you assign the activation and transaction policies for the interfaces implemented in your server application. This XML file also contains a server declaration, which includes the name of the Server object and the name of the server descriptor file (SER). You can also identify the Java class files that comprise the server application's Java Archive (JAR) file.
Compile the XML-based Server Description File with the buildjavaserver command and generate the SER file and JAR file.
Deploy your Java server application.

The Entities You Create to Build a WLE Java Server Application

To build a WLE Java server application, you create the following entities:

The Java implementation of the CORBA objects that execute your server application's business logic. This topic is explained in the next section.
The Java Server object, which performs the initialize and release functions for the server application, and may perform other functions. This topic is explained in the section The Server Object.
A Java Archive (JAR) file that contains the Java bytecodes (class files) that comprise your server application. In the WLE Java environment, you can optionally use an <ARCHIVE> section of the Server Description File to identify and collect the class files and packages. The Server Description File is written in XML.
The JAR file also contains a server descriptor, which is a Java object that contains information about all the servant classes implemented by the server application, along with the policies attached to the interfaces. Also stored in the JAR file is the name of the Server object that is used to initialize and stop the server.

There are also a number of files that you work with that are generated by the m3idltojava compiler and that you build into an WLE server application. These files are listed and described in Steps for Creating a Java Server Application.

import com.beasys.Tobj.*;

/**
* Provides code to initialize and stop the server invocation.
* BankAppServerImpl is specified in the BankApp.XML input file
* as the name of the Server object.
*/

public class BankAppServerImpl
	extends com.beasys.Tobj.Server {

	public boolean initialize(string[] args)
		throws com.beasys.TobjS.InitializeFailed;

	public boolean release()
		throws com.beasys.TobjS.ReleaseFailed;

In the XML-coded Server Description File, which you process with the buildjavaserver command, you identify the name of the Server object.

The create_servant method, used in the C++ environment of WLE, is not used in the Java environment. In Java, objects are created dynamically, without prior knowledge of the classes being used.

In the Java environment of WLE, a servant factory is used to retrieve an implementation class, given the interface repository ID. This information is stored in a server descriptor file created by the buildjavaserver command for each implementation class.

When a method request is received, and no servant is available for the interface, the servant factory looks up the interface and creates an object of the appropriate implementation class.

This collection of the object's implementation and data compose the run-time, active instance of the CORBA object.

For more information about creating the Server object, see Steps for Creating a Java Server Application.

Understanding Object References and Object State

This section presents important background information about the following topics, which have a major influence on how you design and implement WLE server applications:

Generating object references
Managing object state
Reading and writing an object's data stored on disk
Using design patterns

It is not essential that you read these topics before proceeding to the next chapter; however, this information is located here because it applies broadly to fundamental design and implementation issues for all WLE server applications.

Generating Object References

One of the most basic functions of a WLE server application is providing client applications with object references to the objects they need to execute their business logic. WLE client applications typically get object references to the initial CORBA objects they use from the following two sources:

The Bootstrap object
Factories managed in the WLE domain

Client applications use the Bootstrap object to resolve initial references to a specific set of objects in the WLE domain, such as the FactoryFinder and the SecurityCurrent objects. The Bootstrap object is described in Getting Started and in Creating CORBA Client Applications.

Factories, however, are designed, implemented, and registered by you, and they provide the means by which client applications get references to objects in the WLE server application, particularly the initial server application object. At its simplest, a factory is a CORBA object that returns an object reference to another CORBA object. The client application typically invokes an operation on a factory to obtain an object reference to a CORBA object of a specific type. Planning and implementing your factories carefully is an important task when developing WLE server applications.

Client applications are able to locate via the FactoryFinder the factories managed by your server application. When you develop the Server object, you typically include code that registers with the FactoryFinder any factories managed by the server application.

It is via this registration operation that the FactoryFinder keeps track of your server application's factories and can provide object references to them to the client applications that request them. We recommend that you use factories and register them with the FactoryFinder; this model makes it simple for client applications to find the objects in your WLE server application.

Note: In WLE 4.2, references to objects implemented in Java can be created only by factories that are also implemented in Java. You cannot mix and match factories and objects with regards to implementation language.

Managing Object State

Object state management is a fundamentally important concern of large-scale client/server systems, because it is critical that such systems optimize throughput and response time. The majority of high-throughput applications, such as applications you run in a WLE domain, tend to be stateless, meaning that the system flushes state information from memory after a service or an operation has been fulfilled.

Managing state is an integral part of writing CORBA-based server applications. Typically, it is difficult to manage state in these server applications in a way that scales and performs well. The WLE software provides an easy way to manage state and simultaneously ensure scalability and high performance.

The scalability qualities that you can build into a WLE server application help the server application function well in an environment that includes hundreds or thousands of client applications, multiple machines, replicated server processes, and a proportionately greater number of objects and client invocations on those objects.

About Object State

In a WLE domain, object state refers specifically to the process, or in-memory, state of an object across client invocations on it. The WLE software uses the following definitions of stateless and stateful objects:

Object

Behavior Characteristics

Stateless

The object is mapped into memory only for the duration of an invocation on one of the object's operations, and is deactivated and has its process state flushed from memory after the invocation is complete; that is, the object's state is not maintained in memory after the invocation is complete.

Stateful

The object remains activated between invocations on it, and its state is maintained in memory across those invocations. The state remains in memory until a specific event occurs, such as:

The server process in which the object exists is stopped or is shut down.
The transaction in which the object is participating is either committed or rolled back.
The object invokes the com.beasys.Tobj.TP.deactivateEnable method on itself and the method completes.
Each of these events is discussed in more detail in this section.

Object	Behavior Characteristics
Stateless	The object is mapped into memory only for the duration of an invocation on one of the object's operations, and is deactivated and has its process state flushed from memory after the invocation is complete; that is, the object's state is not maintained in memory after the invocation is complete.
Stateful	The object remains activated between invocations on it, and its state is maintained in memory across those invocations. The state remains in memory until a specific event occurs, such as: The server process in which the object exists is stopped or is shut down. The transaction in which the object is participating is either committed or rolled back. The object invokes the com.beasys.Tobj.TP.deactivateEnable method on itself and the method completes. Each of these events is discussed in more detail in this section.

Both stateless and stateful objects have data; however, stateful objects may have nonpersistent data in memory that is required to maintain context (state) between operation invocations on those objects. Thus, subsequent invocations on such a stateful object always go to the same servant. Conversely, invocations on a stateless object can be directed by the WLE system to any available server process that can activate the object.

State management also involves how long an object remains active, which has important implications on server performance and the use of machine resources. The section How to Manage Object State explains the various mechanisms the WLE system provides to control object state.

Object state is transparent to the client application. Client applications implement a conversational model of interaction with distributed objects. As long as a client application has an object reference, it assumes that the object is always available for additional requests, and the object appears to be maintained continuously in memory for the duration of the client application interaction with it.

To achieve optimal application performance, you need to carefully plan how your application's objects manage state. Objects are required to save their state to durable storage, if applicable, before they are deactivated. Objects must also restore their state from durable storage, if applicable, when they are activated. For more information about reading and writing object state information, see the section Reading and Writing an Object's Data.

How to Manage Object State

WLE provides two basic means to control object state:

By defining object activation policies on an object's interface in the Server Description File. Object activation policies are described in the section Object Activation Policies.
By using a TP Framework feature called application-controlled deactivation, described in the section Application-Controlled Deactivation.

Object Activation Policies

The WLE system provides three object activation policies that you can assign to an object's interface to determine how long an object remains in memory after it has been invoked by a client request. These policies determine whether the object to which they apply is generally stateless or stateful.

The three policies are listed and described in the following table.

Policy

Description

Method

Causes the object to be active only for the duration of the invocation on one of the object's operations; that is, the object is activated at the beginning of the invocation, and is deactivated at the end of the invocation. An object with this activation policy is called a method-bound object.
The method activation policy is associated with stateless objects. This activation policy is the default.

Transaction

Causes the object to be activated when an operation is invoked on it. If the object is activated within the scope of a transaction, the object remains active until the transaction is either committed or rolled back. If the object is activated outside the scope of a transaction, its behavior is the same as that of a method-bound object. An object with this activation policy is called a transaction-bound object.
For more information about object behavior within the scope of a transaction, and general guidelines about using this policy, see Integrating Transactions into a Java Server Application.
The transaction activation policy is associated with stateful objects for a limited time and under specific circumstances.

Process

Causes the object to be activated when an operation is invoked on it, and to be deactivated only under the following circumstances:

The server process that manages this object is shut down.
An operation on this object invokes the com.beasys.Tobj.TP.deactivateEnable method, which causes this object to be deactivated when the method completes. (This is part of a key WLE feature called application-controlled deactivation, which is described in the section Application-Controlled Deactivation.
An object with this activation policy is called a process-bound object. The process activation policy is associated with stateful objects.

Policy	Description
Method	Causes the object to be active only for the duration of the invocation on one of the object's operations; that is, the object is activated at the beginning of the invocation, and is deactivated at the end of the invocation. An object with this activation policy is called a method-bound object. The method activation policy is associated with stateless objects. This activation policy is the default.
Transaction	Causes the object to be activated when an operation is invoked on it. If the object is activated within the scope of a transaction, the object remains active until the transaction is either committed or rolled back. If the object is activated outside the scope of a transaction, its behavior is the same as that of a method-bound object. An object with this activation policy is called a transaction-bound object. For more information about object behavior within the scope of a transaction, and general guidelines about using this policy, see Integrating Transactions into a Java Server Application. The transaction activation policy is associated with stateful objects for a limited time and under specific circumstances.
Process	Causes the object to be activated when an operation is invoked on it, and to be deactivated only under the following circumstances: The server process that manages this object is shut down. An operation on this object invokes the com.beasys.Tobj.TP.deactivateEnable method, which causes this object to be deactivated when the method completes. (This is part of a key WLE feature called application-controlled deactivation, which is described in the section Application-Controlled Deactivation. An object with this activation policy is called a process-bound object. The process activation policy is associated with stateful objects.

You determine what events cause an object to be deactivated by assigning object activation policies. For more information about how you assign object activation policies to an object's interface, see the section Step 5: Define the object activation and transaction policies..

Application-Controlled Deactivation

Application-controlled deactivation provides a means for an application to deactivate an object during run time. The TP Framework provides the com.beasys.Tobj.TP.deactivateEnable method, which a process-bound object can invoke on itself. When invoked, the deactivateEnable method causes the object in which it exists to be deactivated upon completion of the current client invocation on that object. An object can invoke this method only on itself; you cannot invoke this method on any object but the object in which the invocation is made.

The application-controlled deactivation feature is particularly useful when you want an object to remain in memory for the duration of a limited number of client invocations on it, and you want the client application to be able to tell the object that the client is finished with the object. At this point, the object takes itself out of memory.

Application-controlled deactivation, therefore, allows an object to remain in memory in much the same way that a process-bound object can: the object is activated as a result of a client invocation on it, and it remains in memory after the initial client invocation on it is completed. You can then deactivate the object without having to shut down the server process in which the object exists.

An alternative to application-controlled deactivation is to scope a transaction to maintain a conversation between a client application and an object; however, transactions are inherently more costly, and transactions are generally inappropriate in situations where the duration of the transaction may be indefinite.

A good rule of thumb to use when choosing between application-controlled deactivation and transactions for a conversation is whether there are any disk writing operations involved. If the conversation involves read-only operations, or involves maintaining state only in memory, then application-controlled deactivation is appropriate. If the conversation involves writing data to disk during or at the end of the conversation, transactions may be more appropriate.

Note: If you use application-controlled deactivation to implement a conversational model between a client application and an object managed by the server application, make sure that the object eventually invokes the com.beasys.Tobj.TP.deactivateEnable method. Otherwise, the object remains idle in memory indefinitely. (Note that this can be a risk if the client application crashes before the deactivateEnable method is invoked. Transactions, on the other hand, implement a time-out mechanism to prevent the situation in which the object remains idle for an indefinite period. This may be another consideration when choosing between the two conversational models.)

You implement application-controlled deactivation in an object using the following procedure:

In the implementation file, insert an invocation to the deactivateEnable method at the appropriate location within the operation of the interface that uses application-controlled deactivation.
In the Server Description File (XML), assign the process activation policy to the interface that contains the operation that invokes the deactivateEnable method.
Build and deploy your application as described in the sections Step 7: Finish the Server Description File. and Step 8: Deploy the server application..

Choosing Between Stateless and Stateful Objects

In general, you need to balance the costs of implementing stateless objects against the costs of implementing stateful objects.

In the case where the cost to initialize an object with its durable state is expensive (because, for example, the object's data takes up a great deal of space, or the durable state is located on a disk very remote to the servant that activates it), it may make sense to keep the object stateful, even if the object is idle during a conversation. In the case where the cost to keep an object active is expensive in terms of machine resource usage, it may make sense to make such an object stateless.

By managing object state in a way that is efficient and appropriate for your application, you can maximize your application's ability to support large numbers of simultaneous client applications that use large numbers of objects. You generally do this by assigning the method activation policy to these objects, which has the effect of deactivating idle object instances so that machine resources can be allocated to other object instances. However, your specific application characteristics and needs may vary.

When You Want Stateless Objects

Stateless objects generally provide good performance and optimal usage of server resources, because server resources are never used when objects are idle. Stateless objects are generally a good approach to implementing server applications. Stateless objects are particularly appropriate in the following situations:

The client application typically waits for user input between invocations on the object.
The client request typically contains all the data needed by the server application, and the server can process the client request using only that data.
The object has very high access rates, but low access rates from any one particular client application.

By making an object stateless, you can generally assure that server application resources are not being tied up for an arbitrarily long time waiting for input from the client application.

Note the following characteristics about an application that employs a stateless object model:

Information about and associated with an invocation is not maintained after the server application has finished executing a client request.
An incoming client request is sent to the first available server process. After the request has been satisfied, the application state vanishes and the server application is available for another client application request.
Durable state information for the object exists outside the server process. With each invocation on this object, the durable state is read into memory.
The WLE domain may direct successive requests on an object from a given client application to a different server process.
The overall system performance of a machine that is running stateless objects is usually enhanced.

When You Want Stateful Objects

A stateful object, once activated, remains in memory until a specific event occurs, such as the process in which the object exists is shut down, or the transaction in which the object is activated is completed.

Stateful objects are typically appropriate in the following situations:

When an object is used very frequently by a large number of client applications. This is the case for long-lived, well-known objects like factories. When the server application keeps these objects active, the client application typically experiences minimal response time in accessing them. Since these active objects are shared by many client applications, there are relatively few objects of this type in memory.
Note: Plan carefully how process objects are potentially involved in a transaction. Any object that is involved in a transaction cannot be invoked by another client application or object. Process objects meant to be used by a large number of client applications can create problems if they are involved in transactions frequently or for long durations.
When a client application must invoke successive operations on an object to complete a transaction, and the client application is not idle while waiting for user input between those invocations. In this case, if the object were deactivated between invocations, there would be a degradation of response time because state would be written and read between each invocation; such behavior may not be appropriate for transactions. You can trade holding server resources for better response time.

Note the following behavior with stateful objects:

State information is maintained between server invocations, and the servant typically remains dedicated to a given client application for a specified duration.
Even though data is sent and received between the client and server applications, the server process maintains additional context or application state information in memory.
In cases where one or more stateful objects are using a lot of machine resources, server performance for tasks and processes not associated with the stateful object may be worse than with a stateless server model.
For example, if an object has a lock on a database and is caching a lot of data in memory, that database and the memory used by that stateful object are unavailable to other objects, potentially for the entire duration of a transaction.

Reading and Writing an Object's Data

Many of the CORBA objects managed by the server application may have data that is in external storage. This externally stored data may be regarded as the persistent or durable state of the object. You must address durable state handling at appropriate points in the object implementation for object state management to work correctly.

Because of the wide variety of requirements you may have for your client/server application with regards to reading and writing an object's durable state, the TP Framework cannot automatically handle durable object state on disk. In general, if an object's durable state is modified as a result of one or more client invocations, you must make sure that durable state is saved before the object is deactivated, and you should plan carefully how the object's data is stored or initialized while the object is active.

The sections that follow describe the mechanisms available to you to handle an object's durable state, and give some general advice about how to read and write object state under specific circumstances. The specific topics presented include:

The available mechanisms for reading and writing an object's durable state
Reading state at object activation
Reading state within individual operations on an object
Stateless objects and durable state
Stateful objects and durable state
Your responsibilities for object deactivation
Avoiding unnecessary I/O

How you choose to read and write durable state invariably depends on the specific requirements of your client/server application, especially with regard to how the data is structured. In general, your priority should be to minimize the number of disk operations, especially where a database controlled by an XA resource manager is involved.

Available Mechanisms for Reading and Writing an Object's Durable State

Table 1-1 and Table 1-2 describe the available mechanisms for reading and writing an object's durable state.

Table 1-1 Available Mechanisms for Reading an Object's Durable State

Mechanism

Description

com.beasys.
Tobj_Servant.
activate_object method

After the TP Framework creates the servant for an object, the TP Framework invokes the activate_object method on that servant. This method is defined on the Tobj_Servant class, from which all the CORBA objects you define for your client/server application inherit.
You may choose not to define and implement the activate_object method on your object, in which case nothing happens regarding specific object state handling when the TP Framework activates your object. However, if you define and implement this method, you can choose to include code in this method that reads some or all of an object's durable state into memory. Therefore, the activate_object method provides your server application with its first opportunity to read an object's durable state into memory.
Note that if an object's OID contains a database key, the activate_object method provides the only means the object has to extract that key from the OID.
For more information about implementing the activate_object method, see Step 2: Write the methods that implement each interface's operations..

Operations on the object

You can include inside the individual operations that you define on the object the code that reads an object's durable state.

Mechanism	Description
com.beasys. Tobj_Servant. activate_object method	After the TP Framework creates the servant for an object, the TP Framework invokes the activate_object method on that servant. This method is defined on the Tobj_Servant class, from which all the CORBA objects you define for your client/server application inherit. You may choose not to define and implement the activate_object method on your object, in which case nothing happens regarding specific object state handling when the TP Framework activates your object. However, if you define and implement this method, you can choose to include code in this method that reads some or all of an object's durable state into memory. Therefore, the activate_object method provides your server application with its first opportunity to read an object's durable state into memory. Note that if an object's OID contains a database key, the activate_object method provides the only means the object has to extract that key from the OID. For more information about implementing the activate_object method, see Step 2: Write the methods that implement each interface's operations..
Operations on the object	You can include inside the individual operations that you define on the object the code that reads an object's durable state.

Table 1-2 Available Mechanisms for Writing an Object's Durable State

Mechanism	Description
com.beasys. Tobj_Servant. deactivate_object method	When an object is being deactivated by the TP Framework, the TP Framework invokes this operation on the object as the final step of object deactivation. As with the activate_object method, the deactivate_object method is defined on the Tobj_Servant class. You implement the deactivate_object method on your object optionally if you have specific object state that you want flushed from memory or written to a database. The deactivate_object method provides the final opportunity your server application has to write durable state to disk before the object is deactivated. If your object keeps any data in memory, or allocates memory for any purpose, you implement the deactivate_object method so your object has a final opportunity to flush that data from memory. Flushing any state from memory before an object is deactivated is critical in avoiding memory leaks.
Operations on the object	As you may have individual operations on the objects that read durable state from disk, you may also have individual operations on the object that write durable state back to disk. For method-bound and process-bound objects in general, you typically perform database write operations within these operations and not in the deactivate_object method. For transaction-bound objects, however, writing durable state in the deactivate_object method provides a number of object management efficiencies that may make sense for your transactional server applications.