Chapter 7 Developing Applications with PowerJ and EAServer

Building distributed and Web applications that use Jaguar CTS

This section describes how to use PowerJ and Jaguar together to create distributed and Web applications.

About Jaguar CTS

What it is

Jaguar CTS is a component transaction server that hosts components implemented with a variety of technologies, such as PowerBuilder, Java, ActiveX, and C++. Using PowerJ, you can develop Jaguar Java components and Java client programs that connect to Jaguar and execute component methods.

When a client invokes a method on a Jaguar server component, Jaguar intercepts the call, locates an instance of that component that can carry out the request, passes the parameters and invokes the method, then returns the result to the client.

Jaguar components

A Jaguar component is a reusable module of code that combines related tasks into a well-defined interface. Jaguar components are installed on a Jaguar server and contain methods that execute business logic and access data sources. Components are nonvisual--they do not display graphics or user interfaces. You can import a Jaguar component into PowerJ and use the Reference Card to browse its methods and properties.

Data access

To optimize database processing, Jaguar provides support for connection caching. Connection caching allows Jaguar components to share pools of preallocated connections to a remote database server, avoiding the overhead imposed when each instance of a component creates a separate connection. By establishing a connection cache, a Jaguar server can reuse connections made to the same data source.

Architecture of distributed and Web applications

How it works

In a distributed or Web application that uses Java and Jaguar together, a Java client accesses the middle-tier Jaguar server, which in turn accesses a database.

About the distributed architecture

In the distributed architecture, the client is a Java application rather than an applet. The application and Java VM need to be installed on the user's machine and the application files made accessible to the VM.

About the Web architecture

A Web application is a variation on the distributed architecture where the client is a Java applet hosted in a Web browser.

Here a Web server has been added to the basic distributed architecture shown earlier:

About the Web client The browser handles communication with a Web server via the HTTP protocol. The Web page that contains the applet and the applet itself are downloaded via HTTP. The applet then runs in the Web browser but bypasses the Web connection and communicates directly with the Jaguar server. Connecting directly to Jaguar enables persistent connections with the client and avoids the problems with stateless HTTP.

A major advantage of the Web architecture is that the client applet is downloaded when the Web page is requested. You don't have to worry about deployment to individual users.

The main disadvantage of the Web architecture is that an applet must be downloaded each time it is run, and unless it is marked as trusted, cannot provide full application services, such as accessing other files, running other programs, or making native calls.

Jaguar as Web server Jaguar can fill the role of Web server using the HTTP protocol, as well as provide support for IIOP connections that invoke the services of the Jaguar transaction server.

Creating a distributed or Web application

The general procedure for using PowerJ to create a distributed or Web Java application that uses Jaguar is:

Decide what functionality will be encapsulated in a Jaguar component. Typically, the component implements business logic that analyzes data, performs computations, or retrieves and processes data from the database.
In PowerJ, write the code for the component. In addition to implementing the component's business logic, you may also call Jaguar methods to take advantage of transactions and other Jaguar performance features (information about these features follows).
In PowerJ or Jaguar Manager, define connection caches to manage pools of connections to the remote databases that your component connects to.
In PowerJ, set the deployment options for your component, including transaction management, instance pooling, and timeout settings.
In PowerJ, deploy the component to Jaguar. This automatically creates CORBA skeletons for your component, and optionally adds a proxy to the PowerJ component palette.
In PowerJ, create the client, which can be a Java application or applet. Add the proxy object and PowerJ InitialContext object to your client, and you can access your component's methods as easily as if the component were available locally. The InitialContext object takes care of connecting to your Jaguar component and initializing the proxy.
Information about building client applications and applets is in "Building a Java client for a distributed or Web application".

For more information For complete details about creating a three-tier Web application, see the distributed application tutorial in PowerJ Getting Started.

Building Jaguar components with PowerJ

A Java component for Jaguar can be an interface, a class, or a JavaBeans component. You can implement any of these in PowerJ.

A Jaguar Java component can follow any of these implementation models:

Enterprise JavaBeans Enterprise JavaBeans (EJB) components are portable to any server that follows Sun's EJB 1.0 specification. An EJB session Bean models the interaction between an end user and the Jaguar server. For example, in an online purchasing application, a session Bean might keep track of a user's uncommitted purchases. An EJB entity Bean represents a row of data stored in a database. For example, an entity Bean might represent a customer's purchase order. From the client's view, entity Beans persist as long as the associated database row has not been deleted. EJB components use standard javax.ejb APIs for component lifecycle and transaction control.
CORBA CORBA components follow the CORBA standard IDL-to-Java type mappings. CORBA components can implement Jaguar's CtsComponents::ObjectControl interface for lifecycle control, and use the CORBA CosTransactions interfaces for transaction management.
Jaguar 1.1 For backwards compatibility with earlier Jaguar versions, Jaguar supports components that implement the ServerBean interface. The Jaguar ServerBean interface is part of the jaguar.beans.enterprise package and is based on Sun's Enterprise JavaBeans specification, Version 0.4. For information on this model, see the Jaguar CTS Programmer's Guide.

All of these implementation models allow you to use the Jaguar connection caching, transaction management, and lifecycle control features. For compatibility with the latest standards, the EJB or CORBA models are recommended.

There are some restrictions to keep in mind for components. They include:

Jaguar allows EJB component methods to have input/output and output parameters, but the EJB 1.0 specification allows only input parameters. For compatibility with other EJB 1.0 servers, use only input parameters in your EJB component remote interface methods.
Parameters for methods in a Jaguar component must have datatypes that can be defined with CORBA IDL. For a list of type mappings, see the Jaguar CTS Programmer's Guide.
Classes and JavaBeans components must have a default constructor (a constructor with zero parameters). The complete set of restrictions is documented in the Jaguar CTS Programmer's Guide. When you deploy the component to Jaguar, PowerJ warns you about classes and methods that don't conform.

Implementing the component

General procedure

Creating and deploying a Jaguar Java component involves these main tasks:

Define and implement the component in PowerJ.
- EJB components Create an EJB 1.0 target that defines the type of Bean, the Java package and class names, and the component's transactional attribute. PowerJ generates skeleton implementations for the SessionBean or EntityBean's home interface, remote interface, and implementation class. Provide signatures for business methods in the remote interface and for any required methods in the home interface, and add code to implement these methods in the implementation class.
- CORBA components Create a Java Classes target to contain the classes that implement your component's functionality. Optionally define a remote interface that contains the component's business methods. (You must define business methods in a remote interface if the component class implements additional methods that are not to be exposed to clients as business methods.) Define a class that implements the business methods. Optionally add implementations for the methods in the Jaguar CtsComponents::ObjectControl interface to manage transactions and to respond to changes in the component's instance lifecycle.
Set the deployment options for your component, including the Jaguar package name and Jaguar component name.
Deploy to Jaguar so you can test the component. This is an iterative process (deploy, test, debug, and redeploy). PowerJ supports in-process debugging of Jaguar Java components.
For more information about debugging Java components running in Jaguar, see Chapter 26, "PowerJ and Jaguar CTS" in the PowerJ Programmer's Guide.

Jaguar services

When designing the component, you can take advantage of these Jaguar services to enhance your application's performance:

Transaction management
Database access and result set management
Connection caching
Instance pooling

These Jaguar features enable you to write high-performance applications with effective error management. You need to set deployment options in PowerJ to enable some of these features in your component, and your component needs to call methods that allow it to cooperate with other components.

Transaction management

How it works

When a component is transactional and uses Jaguar's connection management feature, commands sent to a data source are automatically performed as part of a transaction. Component methods can call Jaguar's transaction state primitives to influence whether Jaguar commits or aborts the current transaction.

The Jaguar server coordinates the database activity of all transactional components participating in the transaction. The application can roll back everything that took place in the transaction if any component could not complete its part of the work.

To define how a component participates in transactions:

Choose a transaction coordinator for the Jaguar server. The transaction coordinator manages the flow of transactions that involve more than one connection and sometimes more than one data source.
Set the component's transaction attribute to determine how the component participates in transactions.
Code methods to call Jaguar's transaction state primitives to influence the transaction outcome.

Each task is described in detail below.

Choosing a transaction coordinator

The transaction coordinator manages the flow of transactions that involve more than one connection and sometimes more than one data source. To enable transactions involving multiple data sources, you must configure your Jaguar server to use a transaction coordinator that supports two-phase commit, such as OTS/XA. See the Jaguar CTS System Administration Guide for more information.

Setting the transaction attribute

Each Jaguar component has a transaction attribute that determines how instances of the component participate in transactions. Values are:

Attribute	Description
Requires Transaction	The component always executes in a transaction. Use this option when your component's database activity needs to be coordinated with other components, so that all components participate in the same transaction.
Requires New Transaction	Whenever the component is instantiated, a new transaction begins.
Supports Transaction	The component can execute in the context of a Jaguar transaction, but a transaction is not required to execute the component's methods. If a method is called by a base client that has a pending transaction, the method's database work occurs in the scope of the client's transaction. Otherwise, the component's database work is done outside of any transaction.
OTS Style	For CORBA components only. The component can inherit a client's transaction. If called without a transaction, the component can explicitly begin, commit, and roll back transactions by using the CORBA CosTransactions::Current interface.
Not Supported	The component's methods never execute as part of a transaction. If the component is activated by a client that has a pending transaction, the component's work is performed outside the existing transaction.
Mandatory	Component methods must be called in the context of a pending transaction. If a client calls a method without an open transaction, the Jaguar ORB throws an exception.
Bean Managed	For EJB session Beans only. The component can explicitly begin, commit, and rollback new, independent transactions by using the javax.transaction.UserTransaction interface. Transactions begun by the component execute independently of the client's transaction. If the component has not begun a transaction, the component's database work is performed independently of any Jaguar transaction.

Influencing transaction outcome

If your component participates in Jaguar transactions, you can call transaction state primitives to explicitly commit or roll back database updates performed in a method.

Components that use the Bean Managed or OTS Style transaction attribute must explicitly begin and end transactions using the APIs described below. For components that use any other attribute, Jaguar implicitly commits each method's work when the method returns unless the method has requested rollback.

Different component types use different transaction APIs:

EJB components using attribute Bean Managed Only EJB session Beans can use the Bean Managed transaction attribute. Components using this attribute must call the methods in the interface javax.transaction.UserTransaction to begin, commit, and roll back transactions. If the component is not a stateful session Bean, then transactions begun in a method call must be committed or rolled back before the method returns. Otherwise, Jaguar logs a runtime error and returns an exception to the client.
EJB components using any other attribute When an EJB component does not use the Bean Managed transaction attribute, Jaguar implicitly commits the component's work after each method returns. To override the default outcome, call the EJBContext.setRollBackOnly method.
CORBA components using attribute OTS Style Components using this attribute can explicitly begin, commit, and roll back transactions by using the CORBA CosTransactions::Current interface.
CORBA components using any other attribute When a CORBA component does not use the OTS Style transaction attribute, Jaguar implicitly commits the components work after each method invocation. To override the default outcome, call Jaguar's CtsComponents.ObjectContext.setRollbackOnly method.

Database access and result set management

How it works

Java components send result sets to the client using the interfaces in the com.sybase.jaguar.sql package:

Methods in the JServerResultSetMetaData interface define the format of rows in a result set.
Methods in the JServerResultSet interface define column values for rows in a result set and send the rows to the client.

You don't have to implement these interfaces. The jaguar.server.JContext class contains static methods for obtaining objects that implement these interfaces.

Sending a ResultSet object to the client

To send database data to the client:

Get the data by sending a query to the remote server. Use java.sql.Statement or one of its extensions. The appropriate method depends on the query you are making.
Convert the results of the query to TabularResults.ResultSet.

Sending results row by row

You can also send the result set row by row by building another ResultSet object that contains a subset of the original query. Methods in the metadata and resultset interfaces let you specify the columns and data in the result set.

Connection caching

How it works

A connection cache contains a pool of preallocated connections that components can use repeatedly as needed to communicate with a database server using a common user name and password. Connection caching provides:

Improved performance through reuse of connections The Jaguar connection manager allows client sessions to share previously opened third-tier connections so that server CPU time and memory are not consumed by opening more connections than necessary.
Improved scalability Since connection caching allows the same number of clients to be serviced using fewer third-tier connections, less memory and other resources are required.
Support for transaction semantics Jaguar's declarative transaction model requires that you call the connection caching APIs to obtain and release all database connections

To realize these benefits, a component must be coded to use a cached connection only when necessary and to release the connection back to the cache at other times. A component should not hold connections while waiting for more input from the client application. As a general rule, each method call that requires a third-tier connection should take a connection handle when invoked and release it before returning.

JDBC 2.0 drivers provide implicit support for connection pooling. When using JDBC drivers that do not conform to the JDBC 2. 0 specification, you can define a connection cache in Jaguar Manager or PowerJ for your components' use.

Transaction support requires cached connections If your component participates in Jaguar transactions, you must use a JDBC 2.0 driver or define a Jaguar connection cache and obtain connections using the Jaguar connection manager classes.

Java Connection Manager classes

Java components can use the Java Connection Manager (JCM) classes for connection caching. The JCM classes manage JDBC connections.

The JCM classes are:

com.sybase.jaguar.jcm.JCMCache Represents a configured connection cache and provides methods to manage connections in the cache.
com.sybase.jaguar.jcm.JCM Provides access to JDBC connection caches defined in Jaguar Manager. JCM methods return JCMCache instances.

To access a connection cache, configure a PowerJ transaction object to connect to the cache, and use the transaction object. Typically, you will also use a query or DataStore object.

Instance pooling

How it works

Instance pooling allows Jaguar to maintain a cache of component instances and bind them to client sessions on an as-needed basis. When components support instance pooling, the scalability of your application increases. Instance pooling eliminates execution time and memory consumption that would otherwise be spent allocating unnecessary component instances.

Implicit pooling of EJB components

Entity Beans and stateless session Beans can be implicitly pooled after any method invocation. Jaguar calls the activate and passivate methods to indicate when an instance has been bound to a client session.

Stateful session Beans remain bound to a client session as long the server has not crashed, the client has not called remove to unbind from the instance, or the Beans session timeout value has not expired. Jaguar may serialize the instance and save it to disk to conserve memory. Jaguar calls the passivate method before serializing the Bean, and the activate method when the Bean has been deserialized. In the code for these methods, you must release and reacquire any object references that do not support serialization.

Configuring CORBA components to support for instance pooling

In PowerJ or in Jaguar Manager, you can set properties for the CORBA component to control instance pooling and deactivation:

The Pooling option causes your component to always be pooled.
The Auto Demarcation/Deactivation option causes your component to be deactivated after every method invocation.

Building a Java client for a distributed or Web application

Types of clients

The Java client in a Jaguar distributed application can be an applet or an application, depending on whether you want your client to run in a Web browser.

About CORBA

Jaguar includes a Java implementation of a standard CORBA Object Request Broker (ORB). Jaguar supports the CORBA Internet Inter-ORB Protocol (IIOP), and it provides a CORBA-compatible client-side interface implemented according to the CORBA specification for IDL-to-Java mappings. Together these features allow you to create CORBA-compliant Java applications and applets that interact with Jaguar components.

The Jaguar Java ORB programming interface is implemented in the class com.sybase.CORBA.ORB. You can use the Jaguar ORB or any CORBA-compatible ORB to invoke Jaguar components.

Enterprise JavaBeans model for clients

Jaguar also supports the EJB 1.0 client model using stubs that call the Jaguar CORBA ORB.

General procedure

Creating a Java client for Jaguar involves these general steps:

In PowerJ, add the Jaguar component. This creates a proxy on the PowerJ component palette.
Add a proxy object and PowerJ InitialContext object to your client.
Write code that:
- Calls component methods by calling the corresponding method in the stub class.
- Cleans up client-side resources by setting proxy references to null. This expedites Java garbage collection.
Execute the Build command to compile your Java client and then deploy it.

Compiling and deploying the Java client

What you do

In PowerJ, you compile your Java classes with the Build command. Testing the distributed or Web application requires access to the Jaguar server, on either your own machine or another machine accessible to you.

Setting up and publishing a client applet

When PowerJ builds an applet, it generates an HTML file with an APPLET tag that you can use for testing. You can copy the APPLET tag from the generated file into the HTML file you are developing for your applet.

PowerJ provides a WebApplication target type that you can use to collect all the files that you want to deploy.

Deploying a client application

After you build the client application, you can test it within PowerJ. You can run in Debug or Release (nondebug) mode.

When you are ready to deploy the application to a user's machine, you can check the CLASSPATH directories that PowerJ is using so that you can set the CLASSPATH correctly for the users.