Apcoordinator User's Guide - Fujitsu€¦ · Part 4 Developing EJB Applicat ions ... 21.1.4 EJB-JAR file.....255 . v 21.2 Processing Specific to Session Beans .....256 21.2.1 Exception

J2X1-1190-01ENZ2(00)

Apcoordinator User's Guide

Contents Part 1 Frameworks Provided by Apcoordinator ........................................................1

Chapter 1 Product Overview.....................................................................................3 1.1 About Apcoordinator.................................................................................................................... 3 1.2 Apcoordinator Features............................................................................................................... 5 1.3 How to Read Manuals................................................................................................................. 5

Chapter 2 Overview of Frameworks Provided by Apcoordinator ..............................9 2.1 Apcoordinator Core ..................................................................................................................... 9 2.2 Webcoordinator ......................................................................................................................... 10 2.3 Bccoordinator ............................................................................................................................ 14

2.3.1 EJB.....................................................................................................................................................14 2.3.2 Web Services ......................................................................................................................................15

2.4 Linkage between Applications Developed Using Apcoordinator............................................... 16

Part 2 Functions of Apcoordinator Core..................................................................17

Chapter 3 Major Components of Apcoordinator Applications..................................19 3.1 Business Class.......................................................................................................................... 19 3.2 Data Bean ................................................................................................................................. 21 3.3 Session Class ........................................................................................................................... 22 3.4 Application Class....................................................................................................................... 22 3.5 Factory Class ............................................................................................................................ 23 3.6 Configuration Files .................................................................................................................... 23

3.6.1 Command Map...................................................................................................................................24 3.6.2 Configuration Files Folder ................................................................................................................25

Chapter 4 Programming Using APIs .......................................................................27 4.1 Common Processes.................................................................................................................. 27 4.2 Application Log.......................................................................................................................... 28

4.2.1 Log Function (update) .......................................................................................................................28 4.2.2 Log Queuing (update)........................................................................................................................31 4.2.3 Output of a Context ID (new)............................................................................................................33 4.2.4 Log Output Using the Definition File (new) ....................................................................................34

4.3 Error Processing ....................................................................................................................... 39 4.4 User-Defined Events ................................................................................................................. 40 4.5 Hook for Business Class Calls .................................................................................................. 42 4.6 Resource Files .......................................................................................................................... 44

4.6.1 Creating a Resource File ...................................................................................................................44 4.6.2 Referring to a Character String from a Java Program....................................................................47 4.6.3 Referring to a Character String from a JSP.....................................................................................52

4.7 Retrying Business Classes ....................................................................................................... 53 4.7.1 Overview of the Business Class Retry Function ..............................................................................53 4.7.2 Creating a Business Class for the Retry Function...........................................................................54 4.7.3 Notes on Using the Business Class Retry Function ........................................................................56

4.8 Transaction Management.......................................................................................................... 58

i

4.8.1 Features Provided by the Transaction Management Function .......................................................58 4.8.2 Creating a business class for the transaction management function .............................................59 4.8.3 Using the Transaction Management Function Together with the Business Class Retry

Function ......................................................................................................................................63 4.8.4 JDBC-based Transaction Management............................................................................................65 4.8.5 Notes on using the transaction management function....................................................................67

Chapter 5 Using XML Data .....................................................................................69 5.1 Overview of the XML Linkage Function .................................................................................... 69 5.2 XML Data Bean ......................................................................................................................... 69 5.3 Summary of XPath .................................................................................................................... 72 5.4 Namespace ............................................................................................................................... 73

Chapter 6 Remote Common Interface ....................................................................77 6.1 Overview ................................................................................................................................... 77 6.2 Remote Map.............................................................................................................................. 78 6.3 Calling with the CallFactory Interface and Call Interface .......................................................... 79

Chapter 7 Invoking EJBs ........................................................................................81 7.1 Invoking Session Beans Developed Using Apcoordinator........................................................ 81

7.1.1 Calling a Session Bean Using the Remote Common Interface........................................................81 7.1.2 Invoking a Session Bean Using EJBCallFactory.............................................................................81

7.2 Invoking a General EJB ............................................................................................................ 82 7.2.1 Coding Sample for Getting a Remote Interface from the EJBCallFactory Class...........................83 7.2.2 Coding Sample for Getting a Home Interface from the EJBCallFactory Class .............................83

7.3 Caching a Home Interface ........................................................................................................ 84 7.4 Automatic Deletion of Session Bean Object ............................................................................. 84 7.5 EJB Session Beans Grouping Function.................................................................................... 84 7.6 Retrying EJBs ........................................................................................................................... 88

7.6.1 Overview of the EJB Retry Function................................................................................................88 7.6.2 Calling EJBs Using the EJB Retry Function...................................................................................88 7.6.3 Notes on Creating Session Beans .....................................................................................................92

Chapter 8 Calling Web Services .............................................................................93 8.1 Calling Apcoordinator-based Web Services.............................................................................. 93

8.1.1 Calling Web Services with the Remote Common Interface .............................................................93 8.1.2 Calling Web Services with SOAPCallFactory ..................................................................................93

8.2 Calling General Web Services .................................................................................................. 94 8.2.1 Calling Where the SOAP Server Is Interstage.................................................................................94 8.2.2 Calling Where the SOAP Server Is Apache......................................................................................95

8.3 Coding of Exception Processing ............................................................................................... 97 8.4 Using Different Types of Functions ........................................................................................... 98

8.4.1 Calling the Web Service for the Basic Authentication of a Web Server ..........................................99 8.4.2 Application Linkage through a Proxy...............................................................................................99 8.4.3 Use of Session Management by a Web Service Caller ...................................................................101 8.4.4 Use of Transport ..............................................................................................................................102

Chapter 9 Command Scripting ............................................................................. 105 9.1 Overview of Command Scripting ............................................................................................105 9.2 Using Command Scripting ......................................................................................................106

ii

iii

9.3 Adding User-Defined Tags ......................................................................................................108

Chapter 10 XML-described Data Specifications.................................................... 111 10.1 Overview ............................................................................................................................... 111 10.2 Creating an XML-described Data Specification .................................................................... 113

10.2.1 Coding Data Item Specifications .................................................................................................. 113 10.2.2 Writing a Specification over Multiple Data Items ....................................................................... 118 10.2.3 Writing Control Statements..........................................................................................................120

10.3 Executing an XML-described Data Specification ..................................................................123 10.3.1 Executing an XML-described Data Specification with an Interpreter .......................................123 10.3.2 Executing XML-described Data Specifications with a Compiler.................................................125 10.3.3 Error Handling ..............................................................................................................................127

Chapter 11 Setting Up the Execution Environment............................................... 131 11.1 Apcoordinator JAR Files Required for Applications...............................................................131 11.2 Software Required for Execution...........................................................................................132 11.3 Initialization Parameters(update)...........................................................................................132

Part 3 Development of Web Application ............................................................... 139

Chapter 12 Overview ............................................................................................ 141 12.1 What Is Webcoordinator?......................................................................................................141 12.2 Webcoordinator Features......................................................................................................142

Chapter 13 Webcoordinator Application Framework............................................. 145 13.1 Webcoordinator Operations ..................................................................................................145 13.2 Webcoordinator Application Design ......................................................................................146 13.3 Webcoordinator Application Files..........................................................................................148

13.3.1 Flow of Display Processing............................................................................................................148 13.3.2 Flow of Input Processing...............................................................................................................150 13.3.3 Nesting uji:include Tags................................................................................................................151

Chapter 14 Programming Using the UJI Tags....................................................... 153 14.1 Overview of the UJI Tags ......................................................................................................153 14.2 Screen Part Tags...................................................................................................................153

14.2.1 Overview of the Screen Part Tags.................................................................................................153 14.2.2 Various Screen Part Tags ..............................................................................................................155 14.2.3 Nesting the Screen Part Tags .......................................................................................................158

14.3 Client Script ...........................................................................................................................159 14.3.1 Overview of the Client Script........................................................................................................159 14.3.2 How to Use the Client Script ........................................................................................................161 14.3.3 User-Defined Checking .................................................................................................................162

14.4 Programming Using Component Tags ..................................................................................163 14.4.1 Overview of Component Tags........................................................................................................163 14.4.2 Using Field Tags............................................................................................................................165 14.4.3 Using Collection Tags....................................................................................................................169 14.4.4 Using Layout Tags.........................................................................................................................180 14.4.5 Using External Attributes.............................................................................................................182

14.5 Using XML Data with Tags ....................................................................................................186 14.5.1 Basic Use........................................................................................................................................186 14.5.2 XML Item Classes .........................................................................................................................194

iv

14.5.3 Conversion from an Ordinary Data Bean to XML Data Bean.....................................................198 14.6 Window Control.....................................................................................................................198 14.7 Frame Control .......................................................................................................................203

Chapter 15 Programming Using Application Program Interfaces (APIs)............... 209 15.1 Session Management ...........................................................................................................209

15.1.1 Webcoordinator Session Management..........................................................................................209 15.1.2 Object Life Cycle............................................................................................................................ 211 15.1.3 Exclusive Control...........................................................................................................................212 15.1.4 Detecting a Session Disconnection ...............................................................................................213 15.1.5 Advanced Session Management (update) .....................................................................................216

15.2 Sending and Receiving Binary Files .....................................................................................219 15.2.1 Uploading a File ............................................................................................................................219 15.2.2 Downloading a File........................................................................................................................221

15.3 Web Application Error Processing.........................................................................................222 15.3.1 JSP Error Page ..............................................................................................................................222 15.3.2 Data Bean Error Processing .........................................................................................................224

Chapter 16 Linkage to Databases ........................................................................ 227 16.1 Overview of the Database Linkage .......................................................................................227 16.2 Database Linked Applications...............................................................................................227

Chapter 17 Linkage to Applets.............................................................................. 233 17.1 Overview ...............................................................................................................................233 17.2 Applications with Applet Linkage .........................................................................................233

17.2.1 Creating a Server Application.......................................................................................................234 17.2.2 Creating a Client Applet ...............................................................................................................235

17.3 Session Management ...........................................................................................................236 17.3.1 Cookie Policy..................................................................................................................................236 17.3.2 Session Management When JBK Plugin is Used.........................................................................236

17.4 Setting Up the Execution Environment .................................................................................238

Chapter 18 Notes on Designing an Application .................................................... 239 18.1 Specifying a Data Bean.........................................................................................................239 18.2 Character Encoding of Send Data ........................................................................................240

Chapter 19 Defining the Web Application Environment ........................................ 241 19.1 Files Required at Execution ..................................................................................................241 19.2 File Allocation at Execution ...................................................................................................242 19.3 Using Multiple Relationship Definition Files ..........................................................................243

Part 4 Developing EJB Applications...................................................................... 245

Chapter 20 Overview ............................................................................................ 247

Chapter 21 Developing Session Beans ................................................................ 251 21.1 Creating Session Beans........................................................................................................251

21.1.1 Creating Java Source Files and Relationship Definition Files ...................................................251 21.1.2 Setting Up Session Bean Initialization Parameters ....................................................................254 21.1.3 Deployment Descriptor (ejb-jar.xml).............................................................................................254 21.1.4 EJB-JAR file ..................................................................................................................................255

v

21.2 Processing Specific to Session Beans..................................................................................256 21.2.1 Exception Handling.......................................................................................................................256 21.2.2 Referencing the Enterprise Bean Environment...........................................................................256 21.2.3 Getting SessionContext.................................................................................................................257 21.2.4 Object Life Cycle............................................................................................................................257 21.2.5 Using a User-Defined Business Method.......................................................................................258

21.3 Linkage between Session Bean and Client ..........................................................................259 21.3.1 Session Data Synchronization ......................................................................................................259 21.3.2 Local Invocation.............................................................................................................................260 21.3.3 Data Bean Conversion...................................................................................................................261 21.3.4 Inputting Data Using HashMap...................................................................................................269 21.3.5 Linkage to Non-Apcoordinator Clients.........................................................................................269 21.3.6 Objects Usable as Arguments or Return Values of EJBs.............................................................271

Chapter 22 Setting Up the Session Bean Execution Environment........................ 273 22.1 Deploying a Session Bean....................................................................................................273 22.2 Setting Up Execution Classpaths..........................................................................................273 22.3 Setting Up the Interstage Session Bean Environment..........................................................273 22.4 Setting Up Execution Classes for Execution at WorkUnit Startup ........................................274

Part 5 Developing Web Services .......................................................................... 277

Chapter 23 Overview ............................................................................................ 279

Chapter 24 Developing SOAP Server Applications............................................... 281 24.1 Overview ...............................................................................................................................281 24.2 Designing an XML Document Structure Used for Service Data input-output .......................281 24.3 Developing Service Classes .................................................................................................281 24.4 Developing Business Classes...............................................................................................281 24.5 Exception Handling in Business Classes..............................................................................284 24.6 Life Cycle of Objects .............................................................................................................284 24.7 Using Functions Specific to Servers .....................................................................................285

24.7.1 Using Functions Specific to Interstage.........................................................................................285 24.7.2 Using Functions Specific to Apache SOAP...................................................................................286

24.8 Calling Services from a Non-Apcoordinator SOAP Client Application..................................287

Chapter 25 Setting Up the SOAP Server Application Execution Environment ...... 291 25.1 Environment for Interstage SOAP.........................................................................................291 25.2 Environment for Apache SOAP ...........................................................................................293

Appendix A Sample Application ............................................................................ 297 A.1 Simple Sample........................................................................................................................297 A.2 Sample Screen Parts..............................................................................................................303

Appendix B Overview of Apcoordinator Operations.............................................. 315

Appendix C Compatibility with Earlier Versions of Apcoordinator (update) ........... 319 C.1 Information Common to All Types of Applications ..................................................................319 C.2 Web Application......................................................................................................................319

vi

Appendix D Linkage with Struts ............................................................................ 321 D.1 Summary ................................................................................................................................321 D.2 Programming That Uses UJI Tags..........................................................................................321

D.2.1 Setting the Data Bean ....................................................................................................................322 D.2.2 Editing the JSP...............................................................................................................................323 D.2.3 Getting the Data Bean ...................................................................................................................326 D.2.4 List of Usable UJI Tags ..................................................................................................................327

D.3 Using the Remote Common Interface ....................................................................................330 D.4 Using Struts Applications Together with Apcoordinator Applications......................................330

Terms .................................................................................................................. 335

Part 1 Frameworks Provided by Apcoordinator

1

2

Chapter 1 Product Overview

1.1 About Apcoordinator

Apcoordinatorprovides application frameworks that support development of applications based on Java TM 2 Platform, Enterprise Edition (J2EE).Apcoordinator provides functions for executing applications developed using Apcoordinator frameworks.

Application Framework

To develop business applications efficiently, determine their frameworks at first, and then include the detailed portions in the frameworks. The framework of an application is called an application framework, or simply a framework. When a framework is used to develop an application, the application's logical parts, screens, and other elements are created according to the specified rules for the framework, and then placed in the framework. Although the rules specified for the framework restricts flexibility in application design, the rules result in a definite application structure that automatically makes the application easy to maintain and easy to reuse.

Frameworks Provided by Apcoordinator

The application frameworks provided by Apcoordinator are designed to support J2EE applications. Developing applications using frameworks allows you to do the following: · Provide uniform application structures, improving readability of source programs. · Create logical parts, windows, and other application components independently and improve the

efficiency of maintenance. · Easily break down an application into components that can be reused. · Hide communication-handling elements and other secondary elements with the framework so that they

can be operated automatically . Web applications created using a framework

Types of Applications that Apcoordinator Supports

Apcoordinator supports development of the following types of applications: · Web application - Apcoordinator provides frameworks used for Web applications with JavaServer Pages (JSP) or

servlets. The frameworks support separation and structured configuration between screens and logic.

- Apcoordinator provides functions for communicating with applets. · Enterprise JavaBeans (EJB) - Apcoordinator provides frameworks that improve compatibility between EJB and Web

3

applications. · Web service - Apcoordinator provides frameworks for Web services based on the Simple Object Access Protocol

(SOAP). Application types supported by Apcoordinator

Configuration of Apcoordinator

Apcoordinator consists of the following components: · Apcoordinator core

The Apcoordinator core specifies the structure of an application. The Apcoordinator core provides the following functions:

- Execution control - XML operations - EJB/SOAP calls - Command scripting - XML-described data specification - Logging for an application · Webcoordinator

Webcoordinator provides functions dedicated to Web applications. - Unified JSP Interface (UJI) tags for creating screens - Session management - Binary file sending/receiving - Linkage with databases - Linkage with applets · Bccoordinator

Bccoordinator provides functions for constructing business service layers for EJB/Web services. - Support for creation of EJB session Beans - Support for creation of SOAP server applications · J Internet Communication Kit (JICK)

JICK provides functions for accessing groupware (mail, directories, and so forth). Configuration of Apcoordinator

4

1.2 Apcoordinator Features

The frameworks provided by Apcoordinator allow you to develop uniform and expandable applications.

Compliance with J2EE

Apcoordinator complies with JSP1.2 and Servlet 2.3. It also complies with EJB1.1 and EJB2.0. On an application server on which any of the J2EE specifications above is supported, you can create three-tier applications using Apcoordinator frameworks.

Uniform Application Structure

Creating applications using frameworks makes their structures uniform, eliminating differences due to application programmers. The structures of applications developed using a framework are easy to understand and to maintain. It is also easy to extract desired parts from them. In particular, in Web applications, screens and logic parts can be created separately, making Web applications easy to develop and maintain.

Highly Expandable Frameworks

The Apcoordinator frameworks have grouped entry points to applications that simplify the addition of functions. Externally attachable definition files improve the expandability of applications by allowing tasks and their screens to be replaced.

Productivity-enhancing Functions

The UJI tags enables tables, combo boxes, and other screen elements to be represented by the coding of simple tags. XML-described data specifications enable the logic of tasks to be set without Java code.

Support for the Latest Technologies

Apcoordinator supports development of applications for Web services, and other new technologies.

1.3 How to Read Manuals

Before developing an application using Apcoordinator, find the manuals related to the functions and components that will be used in the application from the list below and read them. · Find the manual for a function - Common functions - Web applications - EJB - Web services · Find the manual for the component

5

Find the Manual for a Function

Purpose: To Manual Sample

Common functions

Understand the basics of frameworks Overview of the Frameworks Provided by Apcoordinator

Code a processing flow in XML Command Scripting Command Scripting Reference

commandMap

Code the specifications of data in XML

XML-Described Data Specification XML-Described Data Specification Reference

eSpecCalc, carrent

Read and save XML files and use XML data Using XML Data

Specify string data for use by an application, in an XML file Resource Files meetingroom

Call business services created by Apcoordinator

Developing EJB/SOAP Clients ejbOffice, soap

Outputs application logs Application Logs logTest

Control calls to business classes Hook for Business Class Calls

Use events User-Defined Events

Create a Java source from an XML-described data specification

XML-Described Data Specification

eSpecCalcc, carrentc

Send mail J Internet Communication Kit Online Manual

sendMail

Authenticate users using LDAP J Internet Communication Kit Online Manual

ldapLogin

Web application

Understand control of the Apcoordinator screens

Webcoordinator Application Framework

simpleForm, sample

Use UJI tags Programming Using the UJI Tags UJI Tag Reference

board, catalog, address, script, model, include

Use browser subwindows Window Control subwin

Divide a screen into frames Frame Control frame

Manage data at the session level Webcoordinator Session Management

Send and receive binary files Sending and Receiving a Binary File

updown, browse

Display XML data Using XML Data with Tags Tag reference

xmlAddress

Display data in a database Linkage to Databases office

Link an application with an applet Linkage to Applet applet

Create combo boxes on a screen Using Collection Tags board,

6

UJI Tag Reference comboBox

Create tables on a screen Using Collection Tags UJI Tag Reference

address, scrollTable, model

Detect disconnection of a session Detecting a Session Disconnection timeout

Prevent double processing Advanced Session Management click

Prevent requests from unexpected screens

Advanced Session Management sessionControl

EJB

Understand the configuration of an EJB Overview

Create EJB session Beans Developing Session Beans ejbOffice

Call EJBs created using Apcoordinator

Calling Session Beans Developed Using Apcoordinator

ejbOffice

To call a general EJB Calling a General EJB

Web service

Understand the configuration of a Web service Overview

Create SOAP server applications Developing SOAP Server Applications soap

Call Web services created using Apcoordinator

Calling Web Services Developed Using Apcoordinator

soap

Call a general Web service Calling a General Web Service

Find the Manual for a Component

Component Manual Sample

Apcoordinator core

Functions common to all frameworks Functions of Apcoordinator Core

commandMap, eSpecCalc, logTest, and so forth (* 1)

Webcoordinator

Web application Developing Web Applications

simpleForm, sample, board, etc. (* 1)

Bccoordinator

EJB session Bean Developing EJB Applications ejbOffice

SOAP server application Developing Web Services soap

JICK

Use of groupware (mail, directories, etc.)

J Internet Communication Kit Online Manual

sendMail, ldapLogin

7

8

*1 Other samples are also available. For the other samples, see Find the manual for a function or see the Samples.

Chapter 2 Overview of Frameworks Provided by Apcoordinator

Apcoordinator consists of Webcoordinator, which is the Web application framework, and Bccoordinator, which is a framework of EJB and Web services. Each framework includes the Apcoordinator core, which is the common framework of Apcoordinator.

This chapter explains the Apcoordinator core, Webcoordinator, Bccoordinator, and linkage of the frameworks.

2.1 Apcoordinator Core

The Apcoordinator core is the common framework for Apcoordinator applications. As shown in the following figure, every application developed using Apcoordinator uses components specified by the Apcoordinator core:

Generally, the Apcoordinator core consists of the following components:

Business class Java class that implements application processing

Data Bean Java class for storage of data input from clients and output to clients

Command map File defining the correspondence between types of data input from clients and processing handled by applications.

The following figure shows the relationship among these components:

9

The sections below describe the configurations of Web applications, EJBs, and Web services, and the Apcoordinator core is essential to each of them.

2.2 Webcoordinator

This section describes the configuration of programs and files in a Web application developed using Apcoordinator. The following figure shows a sample Web application for registering users:

This application provides a screen to users so that they can input their names and addresses. Clicking the [Register] button sends an input name and address to a Web server. A program on the Web server registers the user information and creates a user ID for the user. The application then displays a screen that indicates successful user registration and shows the user ID.

10

Input-output page, business class, and data Bean

Web applications created using Apcoordinator normally consist of the following elements:

Input-output page An input-output page is JSP files that implement display of a screen. The sample page shown below displays two screens: one for input of user names and addresses, and the other for notification of successful registration. Input-output pages are created for the screens. Input-output pages are normally coded with HTML tags and UJI tags. UJI tags are supported by Apcoordinator. UJI tags are used to display data output from programs and to build screens, thereby saving programmers a lot of time that would otherwise be required for writing HTML tags.

Business class A business class is a Java class used for processing on Web servers. The sample business class shown below is for registering new users and creating user IDs for them.

Data Bean A data Bean class is a Java class for storage of data input on a screen and data output from a business class and displayed on a screen. The sample data Bean shown below stores user's names, addresses, and user IDs.

The above three types of elements are linked to operate as follows: · The data input by a user on a data entry screen is stored in a data Bean. · The data in the data Bean is input to a business class. · The business class obtains the user input data from the data Bean and processes it as necessary. The

business class sets display data in a data Bean, and outputs it. · The data Bean output from the business class is assigned to an input-output page. UJI tags coded on the

input-output page obtain the data from the data Bean and display it. HTML tags display their own content directly.

Command map

Only one data entry screen is used in the above sample application. In general, an application has more than one data entry screen and each item of data that is input on such a screen is processed in a different way on servers. The sample shown below illustrates a case where an input-output page is added to the case of the above sample application. The additional input-output page for user IDs allows users to delete their registration, and accordingly, processing for deleting a user's registration is added to the business class.

11

In this case, different calls must be used for registration processing and deletion processing. To define settings for the different calls, specify them in a file called the command map. Define the different calls as follows: · Create one data Bean class for each data entry screen. · On an input-output page, specify a data Bean class for storage of data input. · In the command map, specify the names of business class methods called for each data Bean class. The following applies to the model of the above sample: · Two data Bean classes are used: UserInfo for the screen on which users can input their names and

addresses, and RemoveInfo for the screen on which users can delete their registered IDs. · The input-output page for user data input is associated with the UserInfo class, and the input-output

page for user ID deletion is associated with the RemoveInfo class. · Two business class methods are used for the required processing: addUser for user registration, and

removeUser for user deletion. · The classes are associated with the methods as follows in the command map: - UserInfo class -> addUser method - RemoveInfo class -> removeUser method

Command

Sometimes, more than one button must be placed on one screen, and each button must be associated with specific processing. For example, if the user data entry screen in the model of the above sample had two buttons, [Register] and [Search], each of the buttons would have to be associated with specific processing.

To specify specific processing for each button, use "commands", as explained below.

12

· Assign a command name to each button. The command name must be a name that indicates the processing performed when the associated button is pressed. As the command names in this example, "add" is assigned to the [Register] button and "search" is assigned to the [Search] button.

· In the command map, specify the name of a business class method called for each pair of a data Bean class and command name. The following is specified for this example:

- UserInfo class, add command -> addUser method - UserInfo class, search command -> searchUser method

Web application summary

A brief description of components in a Web application is given below. Input-output page

JSP files that implement display of a screen Business class

Java class used for processing on Web servers Data Bean

Java class for storage of data input on a screen and data output from a business class and displayed on a screen

Command map File listing the correspondence between individual pairs of a data Bean class and command name and the names of the business class methods called for the pairs. The command names assigned to buttons on screens indicate the processing that is performed.

In addition, the components listed below are required for Web applications. For information about the components, see "Developing Web Applications".

Control page JSP page that receives requests from browsers, and then issues an instruction to start processing on the server.

Page map File defining the correspondence between data Beans output by business classes and input-output pages used to display data of the output data Beans.

The figure below illustrates how the components are linked.

13

The above samples of simple Web applications are used to describe only the most basic Apcoordinator functions. Apcoordinator also provides the following functions to facilitate creation of Web applications:

UJI tags These tags are used to build screens. UJI tags make it possible to display data output from programs and build screens easily, where the same tasks would require a lot of time to accomplish with HTML tags.

Session management This allows requests from one client to be handled as a single session. Session management makes it easy to manage data at the session level.

Split-screen display The Apcoordinator screen can be split into parts that are associated with data Beans and input-output pages.

2.3 Bccoordinator

2.3.1 EJB

Apcoordinator provides a framework for creating EJB session Beans.In Apcoordinator, session Beans normally consist of the following components:

Business class Java class used for processing in session Beans

Data Bean Java class used for data input from clients to session Beans and for data returned from session Beans to clients

Command map File listing the correspondence between individual pairs of a data Bean class and command name and the names of the business class methods called for the pairs

The components listed above have almost the same function as they do in Web applications. However, there are slight differences in how data Beans and commands are assigned to a business class and in the use of output data Beans. For EJBs, data Beans and commands are sent from clients. Data Beans output from a business class are received by clients. The following figure shows how business classes, data Beans, and the command map are linked.

14

For more information on how to develop session Beans using Apcoordinator, see "Developing EJB Applications".

2.3.2 Web Services

Apcoordinator provides frameworks of Web services for creating applications using SOAP. You can use the frameworks to create SOAP server applications that receive XML data and command names as input and that return XML data as output.

SOAP server applications normally consist of the following components: Business class

Java class used for processing in SOAP server applications Data Bean

Java class for storage of data input to and output from a business class. The stored data is coded in XML.

Command map File defining the names of the business class methods called for individual pairs of an input data type and command name.

The components listed above have almost the same function as they do in Web applications. However, there is a slight difference in how XML data is transmitted to and from clients. XML data sent from a client is stored in data Beans, and then delivered to a business class. Conversely, before XML data is sent to a client, it is retrieved from data Beans output from a business class.

15

For more information on how to develop Web services using Apcoordinator, see "Developing Web Services".

2.4 Linkage between Applications Developed Using Apcoordinator

Applications developed using Apcoordinator link to one another and operate as shown in the following figure:

16

Part 2 Functions of Apcoordinator Core

17

18

Chapter 3 Major Components of Apcoordinator Applications

This chapter describes the following major components of Apcoordinator applications:

Business Class A business class is a Java class that processes data that is input from clients.

Data Bean A data Bean is a class used by Apcoordinator applications to store data input from and output to clients.

Session Class A session class holds the data to be managed in a session.

Application Class An application class stores data shared by all sessions.

Factory Class A factory class creates instances of application classes and session classes.

Configuration Files Configuration files specify the operations and settings of an Apcoordinator application.

For an overview of Apcoordinator's internal operation, see Overview of Apcoordinator Operation. See this section when debugging an Apcoordinator application or if you need a better understanding of frameworks.

3.1 Business Class

In a business class, create methods for processing data input from clients. Multiple business classes can be set. The following is an example of a business class:

package calc; import com.fujitsu.uji.DispatchContext; public class CalcHandler extends com.fujitsu.uji.GenericHandler { public boolean init() { return true; } public void add(DispatchContext context, BodyBean dataBean) { double result = dataBean.getVal1() + dataBean.getVal2(); dataBean.setMessage("Addition done."); dataBean.setResult(result); dataBean.setVerb("resmode"); context.setResponseBean("body", dataBean); } public void sub(DispatchContext context, BodyBean dataBean) { double result = dataBean.getVal1() - dataBean.getVal2();

19

dataBean.setMessage("Subtraction done."); dataBean.setResult(result); dataBean.setVerb("resmode"); context.setResponseBean("body", dataBean); } public void next(DispatchContext context, BodyBean dataBean) { dataBean.setVerb("reqmode"); context.setResponseBean("body", dataBean); } public void startup(DispatchContext context) { BodyBean dataBean = new BodyBean(); dataBean.setVerb("reqmode"); context.setResponseBean("body", dataBean); } }

Create business classes in which the com.fujitsu.uji.Handler interface is implemented. The easy way to create a business class is by inheriting the com.fujitsu.uji.GenericHandler class. The GenericHandler class provides an easy implementation of the Handler interface.

Specify the argument for a method that processes data input as follows:

public void someMethod(com.fujitsu.uji.DispatchContext context, [input-data-class-name] data);

Note, however, that for a method that is invoked when the data input is null, you can simply specify as an argument the DispatchContext class as follows:

public void someMethod(com.fujitsu.uji.DispatchContext context);

The data input from clients can be any of the four types shown in the table below. The type of data to be used depends on the type of application.

Type of application(*1) Type Description

Web EJB SOAP

Data Bean

Class that holds data in the form of JavaBean format properties. For details, see Data Bean.

o o -

XML data Bean (com.fujitsu.uji.xml.XmlDataBean class)

Class that holds data in the XML format. For details, see Making Use of XML Data.

o o o

HashMap (java.util.HashMap class) Used in EJB session Beans. For details,

- o -

20

Type of application(*1) Type Description

Web EJB SOAP see Inputting Data Using HashMap.

*1 In the table above, the types of application are abbreviated as follows: · Web application -> Web · EJB session Bean -> EJB · SOAP server application -> SOAP

The symbols have the following meaning: · o: The type of input data can be used for the type of application. · - : The type of input data cannot be used for the type of application. The type of return value from a method depends on the type of application or how the method is used. For details, see the following: · Web application: Files for a Webcoordinator Application. · EJB session Bean: Creating a Java Source File and Relationship Definition File. · SOAP server application: Developing a Business Class. By overriding the init method of the Handler interface to change the return value, you can select either of the following business class life cycles: · When the init method returns true: An instance is created when the business class is invoked, and the

instance is used until the session ends. When the session ends, the destroy method of the business class is invoked.

· When the init method returns false: An instance is created whenever a client makes a request for an instance.

For the description about what is specific to the type of application on creating a business class, see the following: · Web application: Files for a Webcoordinator Application · EJB session Bean: Creating a Java Source File and Relationship Definition File · SOAP server application: Developing a Business Class

3.2 Data Bean

A data Bean is used by Apcoordinator applications to store data input from and output to clients. Inherit the com.fujitsu.uji.DataBean class to create a DataBean, and create the property in JavaBean form.

The following is an example coding of a data Bean. To create a property message of the String class in a data Bean, create the message variable, setMessage method, and getMessage method as follows:

public class BodyBean extends com.fujitsu.uji.DataBean { protected String message; public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } }

To define both the get method and set method, be sure to set the same type for the argument of the set method and the return value of the get method. Otherwise, the application may be unable to get or set properties, and generate an exception when it is executed.

21

Specify the names of data Bean properties according to the following recommendations and restrictions:

In general, use lowercase. For a multiple-word name, use an uppercase letter for the first letter of each word after the first. The following are examples:

today, orderDate

Underscores and numerals can also be used: my_value0

Specify a name completely in uppercase only in cases such as the following: URL

Any property name that violates the following naming conventions causes a runtime error:

A name that begins with an uppercase character followed by lowercase characters, such as the following example, cannot be specified:

Today

A name whose second character is uppercase, such as the following example, cannot be specified:

aSample

A name consisting of a single uppercase character, such as the following example, cannot be specified:

X In addition, reserved Java names and names not allowed to be used in Java for variables cause an error during building.

3.3 Session Class

A session class holds data to be managed in a session. One instance of a session class is created for one session, and the instance continues to be used until the session ends. A subclass of com.fujitsu.uji.SessionProfile is used as the session class.

To store data specific to an application in a session class, create a user-defined session class as follows:

For a Web application Inherit com.fujitsu.uji.http.HttpSessionProfile. To do advanced session management, inherit com.fujitsu.uji.http.HttpControlStateProfile. To do advanced session management in Web applications, see Advanced Session Management.

For an EJB session Bean Inherit the com.fujitsu.uji.ejb.bean.EJBSessionProfile class.

For a SOAP server application Inherit the com.fujitsu.uji.soap.service.SOAPSessionProfile class.

If you create a user-defined session class, create a factory class to use the user-defined session class. For information about how to do this, see Factory Class.

If you do not create a user-defined session class, one of the classes listed in the table below is used as the session class:

Type of application Session class used

Web application com.fujitsu.uji.http.HttpSessionProfile

EJB session Bean com.fujitsu.uji.ejb.bean.EJBSessionProfile

SOAP server application com.fujitsu.uji.soap.service.SOAPSessionProfile

3.4 Application Class

An application class holds data shared by all sessions. A separate instance of an application class is created for each application. The com.fujitsu.uji.ApplicationProfile class or a subclass is used as the application class.

To store data specific to an application into an application class, do the following:

22

· Create a user-defined application class by inheriting the ApplicationProfile class. · Create a factory class to use the user-defined application class. For information about how to do this, see

Factory Class. When you do not create a user-defined application class, com.fujitsu.uji.ApplicationProfile is used.

3.5 Factory Class

A factory class creates instances of application classes or session classes. When you use user-defined application classes and user-defined session classes, you must prepare user-defined factory classes.

Create a user-defined factory class taking the following into consideration: · Inherit the following classes:

Type of application Class to be inherited

Web application com.fujitsu.uji.http.HttpFactory

EJB session Bean com.fujitsu.uji.ejb.bean.EJBFactory

SOAP server application com.fujitsu.uji.soap.service.SOAPFactory · To use a user-defined application class, override the newApplicationProfile method so that a new instance

of the application class is returned. · To use a user-defined session class, override the newSessionProfile method so that a new instance of the

session class is returned. · Specify the class name of the factory class in the initialization parameter. For details of specifying the

factory class name, see the following: - Web application: Setting Up the Web Application Execution Environment - EJB session Bean: Setting Up Initialization Parameters for a Session Bean - SOAP server application: Developing a Service Class The following is an example of coding a factory class:

import com.fujitsu.uji.SessionProfile; import com.fujitsu.uji.ApplicationProfile; public class SampleFactory extends com.fujitsu.uji.http.HttpFactory { public SessionProfile newSessionProfile() { return new SampleSessionProfile(); } public ApplicationProfile newApplicationProfile() { return new SampleApplicationProfile(); } }

3.6 Configuration Files

Apcoordinator uses the configuration files listed in the table below.Apcoordinator applications always require a command map file.The other configuration files are required depending on the functions that will be implemented.

Configuration file: Description Reference

Command map Writes the methods of the business classes to be invoked according to the data that is input from a client.

Command Map

Page map Associates data Beans that are processing results from business classes and their display mode with input/output pages. Use a page map

Files for a Webcoordinator Application

23

Configuration file: Description Reference for a Web application.

Resource file Defines data about character strings used in the application. Resource File

Remote map Defines the name of an application to be invoked through the remote common interface.

Remote Map

XML file for command scripting

Writes the processing flow for command scripting.

Command Scripting

XML file that conforms to XML-described data specification

Specifies how properties of data Beans are to be checked and how data items are to be transferred to associated entries in the XML-described data specification.

XML-described Data Specification

Business class configuration file

Specifies business class settings for the business class retry function and the transaction management.

Business Class Retry Function Transaction Management Function

Data Bean conversion map

Specifies how the data Bean converter converts data Beans when EJBs are invoked.

Data Bean Conversion

Place the configuration files in a configuration files folder.

The following describes the command map and configuration files folder.For the other configuration files, see the description of the respective functions that use them.

3.6.1 Command Map

Specify the methods of the business classes to be invoked according to the data input from a client.

Each line in the command map represents as a pair data input and the method to be invoked for that data. The coding format of the lines depends on the type of data received.

Data Bean [input-data-bean-class-name];[command]=[business-class-name].[method-name]

XML data Bean (com.fujitsu.uji.xml.XmlDataBean class) /[input-xml-data-bean-root-element-name];[command]=[business-class-name].[method-name]

An XML data Bean is a class used to store data in XML. For details, see Making Use of XML Data. If a root element has been qualified with a name space, be sure to specify only the local name (do not specify the prefix).

For HashMap (java.util.HashMap class) $[input-hashmap-data-type];[command]=[business-class-name].[method-name]

Data input by HashMap is used for EJB session Beans. For details, see Inputting Data Using HashMap.

When received data is null and a command is specified ;[command]=[business-class-name].[method-name]

When received data and command are null: ;=[business-class-name].[method-name]

You can write only one line in this format. For a Web application, specify the method to be invoked for the first access from a user in this format.

Lines that begin with "#" are comments.

24

25

Writing a plus sign (+) and the name of a file includes the file for processing. Specify the name of the file using a relative path from the folder where the command map is located. The path delimiter is a slash (/). When the name of a file included has the .xml extension, the file is handled as a command scripting.

# Include sub.map, which is located in the folder where the file is located. +sub.map # Include the command script comscr.xml located in the subfolder xscript. +xscript/comscr.xml

The following are examples of command maps:

Sample for a data Bean

# commands.map calc.BodyBean;add=calc.CalcHandler.add calc.BodyBean;sub=calc.CalcHandler.sub calc.BodyBean;next=calc.CalcHandler.next ;=calc.CalcHandler.startup

Sample for an XML data Bean

# commands.map /catalog;update=sample.CatalogHandler.update /catalog;search=sample.CatalogHandler.sear ch/userinfo;update=sample.UserHandler.update sample.BodyBean;maintain=sample.CatalogHandler.maintain ;=sample.CatalogHandler.startup

In the sample above, Line 5 contains a standard data Bean that is used together with the specific data Bean.

Sample for HashMap

# commands.map $catalog;update=sample.CatalogHandler.update $catalog;search=sample.CatalogHandler.search $userinfo;update=sample.UserHandler.update ;=sample.CatalogHandler.startup

3.6.2 Configuration Files Folder

Place Apcoordinator configuration files in a configuration files folder. The table below shows the location of default configuration files folders by application type.

Type of application Default location

Web application /WEB-INF

EJB session Bean

A configuration files folder is stored according to the name of the session Bean class as follows:

/[package-folder]/[class-name]_inf

[package-folder] is the folder of the session Bean class package, and [class-name] is the name of the session Bean class.

SOAP server application /SOAP-INF

For an EJB session Bean or SOAP server application, the uji.infoPath initialization parameter makes it possible to change its configuration files folder. For the details of initialization parameters, see Initialization Parameters.

Chapter 4 Programming Using APIs

4.1 Common Processes

Processes for a business class or processes that are common to all business classes can be created collectively.

Preprocess

When the preprocessor is installed, the preprocess method is called before executing the business class.The preprocessor can be installed in a business class, session class, or application class.When the preprocessor is installed in a business class, the preprocess method is called before executing the method of the class. When the preprocessor is installed in a session class or application class, the preprocess method is called before executing the methods of the business classes.The GenericHandler used in the business class installs the preprocessor. The preprocess method can be overridden to add processing.

public class SampleHandler extends com.fujitsu.uji.GenericHandler

{

public int preprocess(DispatchContext context) {

return Preprocessor.EVAL;

}

}

The preprocess method of a session can be used, for example, to display the login screen only when the user does not log in to the system.

Postprocess

When the postprocessor is installed, the postprocess method is called after executing the business classThe postprocessor can be installed in a business class, session class, or application class as well as the preprocessor.When the postprocessor is installed in a business class, the postprocess method is called after executing the method of the class. When the postprocessor is installed in a session class or application class, the postprocess method is called after executing the methods of all business classes. The postprocess method can be used for setting a common screen. The interface must return an object while applications other than the file download application return a null.


{

....

public Object postprocess(DispatchContext context, Object result) {

....

context.setResponseBean("head", headBean);

return result;

}

}

When using the preprocessor, the handleException method must also be installed if the class is not derived from GenericHandler class. For more information on the handleException method, see Error Processing.

27

4.2 Application Log

Apcoordinator provides function for collecting an application log. These application log function include the following functions: · Apcoordinator outputs a log that describes the behavior of an application, even if the application contains

no special description to that effect. · By setting the output level, a user can narrow down the log that is output. · The log cache function is supported, and log can be output without affecting execution of an application. · Output destination files can be automatically divided. · Context IDs that associate the logs output by Web applications with those output by EJB applications are

output. · The output destination, the format, and other information can easily be specified with descriptions in the

log definition file.

4.2.1 Log Function (update)

Basic operation for log output

The log can be output by using the LogComposer object. The object can be referred to from an application class or DispatchContext.

import com.fujitsu.uji.log.*;


{

....

public void startup(DispatchContext context) {

....

LogComposer lc = context.getApplicationProfile().getLogComposer();

lc.println("Starting the processing");

}

}

Customizing the log output function

The LogComposer object can be arbitrarily set up within an application class. By overriding the newLogComposer method of the ApplicationProfile class and returning the LogComposer object, the log format and output destination can be changed. . By default, the queue is valid, and messages together with date information are output to the standard output.

public class SampleApplication extends com.fujitsu.uji.ApplicationProfile

{

public LogComposer newLogComposer() {

LogComposer lc;

try {

lc = LogComposer.getFileOutputInstance("c:¥¥myapp¥¥mylog.txt", true, new LineLogFormat("%d %m"));

28

} catch(IOException e) {

return null; // The default setting is used.

}

lc.setQueueSize(1000);

lc.enableQueue();

lc.setLogLevel(9);

return lc;

}

}

If log output is disabled, a null LogComposer object is returned.

public LogComposer newLogComposer() {

return new LogComposer();

}

Log levels

Different importance levels can be set for an Apcoordinator log. Log level 0 is the highest importance level, and the higher the importance level, the lower the level number. Any level can be set.

Apcoordinator uses the following levels.

Level Output log Explanation

3: Error log level for Apcoordinator Error code which starts by UJI and message are output.

10: Information log level of Apcoordinator The log which shows an internal situation is output.

20: Trace log level of Apcoordinator The log which shows data Bean dump and a detailed executing state is output.

In the future, the output log has the possibility of changing by the function addition and the improvement, etc. to Apcoordinator.

Prepared The following default levels.

Level Output log Explanation

0: Most important log The level is specified for user application's most important log.

5: Initial value of the default level for messages for which no log level is specified default output level

A log level is set when the log is displayed.


29

lc.println(7, "Starting the processing")

If no level is specified, the default level is used. The initial value of the default level is 5, but this setting can be changed with the setDefaultLevel method.

lc.setDefaultLevel(7);

lc.println("Starting the processing")

By specifying the log output level, unnecessary log output can be suppressed. The default log output level is 9 (all log data of level 9 or lower is output).

lc.setLogLevel(5); // Log data of level 5 or lower is output.

Also, log output levels can be specified in initialization parameters and in the log definition file. However, priority is given to the log levels that have been set with the setLogLevel method. For details on initialization parameters, refer to Initialization Parameters.For details on the log definition file, refer to "Log Output Using the Definition File". In the following example, a log output level is specified in the web.xml file for a Web application.

<web-app>

<context-param>

<param-name>logLevel</param-name>

<param-value>5</param-value>

</context-param>

</web-app>

If a conversion to character strings is required for log output, unnecessary processing can be omitted beforehand according to an evaluation based on log levels.

int level = 5;

if(lc.isLogged(level)) {

String message = "Character string" + a + "operation is" + b + "highly costly.";

lc.println(level, message);

}

Setting a format

The LineLogFormat object sets the log output format. Any format can be specified when the LogComposer object is created.

30

lc = LogComposer.getFileOutputInstance("c:¥¥myapp¥¥mylog.txt", true,

new LineLogFormat("%d %m"));

System information can be displayed according to the settings listed below. In addition, a context ID is output at the time of use of the LogComposer object referred to from the DispatchContext class.

%m Message text

%i Context ID

%d Time

%t Thread name

%s Method name

%l Log level

%% Displays the % symbol.

For example, if "%d %m" is specified, log is output as follows.

2001/01/05 16:47:49 uji:no entry in commands.map for TestUseBean.dataBean1;submit

4.2.2 Log Queuing (update)

Application processing is suspended during output of an application log. With use of the log queuing function, however, log can be output at any convenient time after application processing is completed. With use of this function, log can be output without affecting the response of an application. The log queuing function is enabled by default in the logging mechanism of Apcoordinator.

Enabling and disabling the queue

If the sequence of messages must be controlled within an application, disable the queue temporarily. Output is suspended while messages remain in the queue.


synchronized(lc) {

lc.disableQueue(true);

lc.println(3, "An important message")

lc.enableQueue();

}

The queue for an application log can be disabled in advance. If false is specified in the "uji.log.enablecache" initialization parameter, the cache is disabled. The initialization parameter is valid for the Application Profile class and for the LogComposer object referred to by the getLogComposer() method of the DispatchContext class.An indication of whether to enable or disable the queue can also be specified in the initialization parameter or in the log definition file. However, priority is given to the indication specified with the disableQueue method. For details on initialization parameters, refer to Initialization Parameters.For details on the log definition file, refer to "Log Output Using the Definition File". In the following example, the web.xml file for a Web application has a definition to disable the queue.

31

<web-app>

<context-param>

<param-name>uji.log.enablecache</param-name>

<param-value>false</param-value>

</context-param>

</web-app>

When log queuing is made effective, the queue of each LogComposerinstance is generated. Therefore, another log might interrupt in the log according to the timing that each queue outputs, when two or more instances output log to the same output destination. This is called mixed log. Moreover, mixed log might be occured when the log is output to a standard output or the standard error output, and when excluding the log output class such as System.out.println or the container outputs the log. Please set the same LogSink instance to each LogComposer instance when you output the log from two or more LogComposer instances to the same output destination to evade mixed log. To prevent the mixed log with the container output log, please use the log output class specifying not a standard output as the output destination but an individual file, etc.

Setting the queue size

Setting an appropriate queue size (i.e., the number of messages that can be present in the queue at one time) prevents log messages from using too much memory and causing a shortage of memory. If this upper limit is reached and output of a message to the queue is attempted, message output is suspended until the queue outputs messages and has free space. Default queue size is 1000.


Queue setting of a customized log mechanism

During use of a customized log mechanism, the queue is inhibited immediately after the log mechanism is obtained. In such cases, the queue must be started.


{

LogComposer newLogComposer() {

LogComposer lc;

lc = LogComposer.getFileOutputInstance("c:¥¥myapp¥¥mylog.txt", true,

new LineLogFormat("%d %m"));


lc.enableQueue();

lc.setLogLevel(9);

32

return lc;

}

}

4.2.3 Output of a Context ID (new)

A Web application creates a context ID each time it accepts a request. When a Web application calls an EJB application, both the Web application and EJB application output the same context ID to their logs. Therefore, the logs can be associated with each other and then referred to based on the individual context IDs that were output when the Web application called the EJB application.

Operation for log output

To output log data with context IDs, use the LogComposer object obtained from the DispatchContext class.



{

....


....

LogComposer lc = context.getLogComposer();


}

}

The output is as follows when the default format "%d %i%m" is used.

Nov 1, 2004 12:08:21 PM [0108-DBAE32B58ECE02A0D32DAFA6E1BFEF96.IJServer_001-000]Processing begins.

Context IDs are not output when the LogComposer object obtained from the application class is used.



{

....


....

33



}

}

The output is as follows when the default format "%d %i%m" is used.

Nov 1, 2004 12:08:21 PM Processing begins.

4.2.4 Log Output Using the Definition File (new)

The log normally used by Apcoordinator (standard log) and the log used by user applications can be separated by use of the log definition file. Without any special description in the application, Apcoordinator outputs log data to the log normally used. Refer to the Configuration Files Folder for the storing place of a log definition file.

The logs output by Apcoordinator are classified as follows.

Classification Management name Use

Standard log system Outputs the operating status of Apcoordinator.

User log Any name except the above Any type of use by an application

· "journal" and "performance" cannot be used as a management name. · The LogComposer object returned by the newLogComposer method of the

ApplicationProfile class is not used when the log definition file is used.

Descriptions of log output

For a business method, the log can be output by using the description below. The log output class (LogComposer) is obtained with a log management name specified in an argument of getLogComposer of the DispatchContext class. Methods of LogComposer are used to output the log.


....

public Object someMethod(DispatchContext context, DataBean bean) {

....

LogComposer myLogger = context.getLogComposer("mylog");

myLogger.println("someMethod start");

....

}

34

Descriptions in the log definition file

The management name "system" indicates a sample definition file for output of the log to the standard error output, and the management name "mylog" indicates a sample definition file for output of the log to the standard output.

<logConf.xml>

<?xml version="1.0" encoding="UTF-8" ?>

<logConfig

xmlns="http://interstage.fujitsu.com/schemas/uji/logConf"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/logConf

http://interstage.fujitsu.com/schemas/uji/logconf.xsd">

<config>

<version>7.0</version>

</config>

<logComposer name="system">

<output name="systemOutput" type="stderr"/>

</logComposer>

<logComposer name="mylog">

<output name="mylogOutput" type="stdout"/>

</logComposer>

</logConfig>

logComposer tag Specifies the type of a log. A management name is specified for name.

output tag Specifies the output destination of a log. Details are provided below.

Specifying the output destination of a log The output tag specifies the output destination of a log. To output a log to multiple destinations, specify multiple output tags.


<output name="sysStdOut" type="stderr"/>

<output name="sysFileOut" type="file">

<param name="path" value="/var/log"/>

<param name="prefix" value="myapp"/>

<param name="extension" value=".log"/>

</output>

</logComposer>

35

For the name attribute, specify a name that identifies an output tag. For the type attribute, specify any of the names explained below. Any required parameter is specified with the param tag.

Name to be specified Explanation Parameters

stdout Standard output None

stderr Standard error output None

file File

Output folder (path), file name (prefix), and file extension (extension) The output folder is specified as follows: "/var/log" (for Solaris OE or Linux) or "C:¥log" (for Windows).

logComposer Use of another log definition logComposer tag name (target)

When outputting to a file, it is necessary to output to a different file for every process.Moreover, in outputting to the same file from a different definition name, please give a definition as follows.






</output>

</logComposer>

<logComposer name="mylog01">

<output name="myLogOut" type="logComposer">



<param name="target" value="system"/>

</output>

</logComposer>

Specifying the log format The log format is specified with the logFormat tag.


<output name="sysStdOut" type="stderr">

36

<logFormat>%d %m</logFormat>

</output>

</logComposer>

Specifying the log output class and log level With use of the class attribute of the logComposer tag, the log output class can be changed. The log output level is specified with the level tag.

<logComposer name="mylog">

<level>20</level>

<output name="mylogOut" type="stdout"/>

</logComposer>

Alternatively, the output level of the system log can be specified with the logLevel initialization parameter. If it is specified with both the initialization parameter and the level tag, priority is given to the specification in the initialization parameter.

Specifying the log output class and queue The cache for the log can be specified with the queue attribute of the logComposer tag. If -1 is specified, the cache is disabled.

<logComposer name="mylog" queue="100">

<output name="mylogOut" type="stdout"/>

</logComposer>

Alternatively, disabling of the system log cache can be specified with the uji.log.enablecache initialization parameter. If disabling of the cache is specified with the initialization parameter, and if the queue attribute of the logComposer tag is specified, priority is given to the specification in the initialization parameter.

Please output the log to the destination of other management name specifying "logComposer" for type attribute of output of the log definition file to evade mixed log when outputting the log to the same output destination by two or more management names. Please refer to the following example.


<output name="sysStdOut" type="stdout">

</output>

</logComposer>

<logComposer name="mylog01">

37

<output name="myLogOut" type="logComposer">



<param name="target" value="system"/>

</output>

</logComposer>

Dividing a log output file automatically If file is specified for the output destination, the output file can be divided automatically. in the example below, the maximum number of files (number) and the number of bytes per file (byte) are specified. Also, division according to date can be specified. In that case, the date format (dateFormat) and division time (timeOffset) are specified for the division. For details, refer to the reference material for the log definition file.






<param name="number" value="10"/>

<param name="byte" value="60000"/>

</output>

</logComposer>

Enabling progressive updates of the log definition file With watchPeriod specified in the parameter of the common tag, the log output class is rebuilt whenever the specified time interval has elapsed. In the following example, the log definition file is referenced at an interval of 10 minutes.


<logConfig

xmlns="http://interstage.fujitsu.com/schemas/uji/logConf"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/logConf

http://interstage.fujitsu.com/schemas/uji/logconf.xsd">

<config>


</config>

<common>

38

<param name="watchPeriod" value="10"/>

</common>


<output name="systemOutput" type="stderr"/>

</logComposer>

....

</logConfig>

· If a setting is changed directly with the LogComposer method, the changed setting

remains valid until the next progressive update of the log definition file. · The log is rebuilt when the update time in the definition file has been changed after

the last reference to the log definition file.

4.3 Error Processing

To subtly control exceptions that occur in the business class, use the try-catch block.


dm = new DataManager();

try {

dm.prepareData();

} catch(DataManagerException e) {

// setResponseBean to display the screen for the exception.

....

} catch(IOException e) {

// setResponseBean to display the screen for the exception.

....

}

....

}

Apcoordinator can collectively process exceptions that seldom occur using the Postprocessor interface.When the Postprocessor interface is installed in the business class, session class, and application class, the handleException method is called when an exception occurs during processing.If Apcoordinator can take action for the exception, it takes appropriate action and ends normally. If Apcoordinator cannot take action for the exception, it rethrows the exception.The handleException method can receive exceptions that occur outside the business class. Apcoordinator determines whether it can take action for the exception. If Apcoordinator cannot take action for the exception, the exception must be rethrown.

39


implements com.fujitsu.uji.Postprocessor

{

public Object handleException(DispatchContext context, Throwable th) {

if(th instanceof MyException) {

// setResponseBean to display the screen for the exception

....

} else {

// Undefined exception

throw th;

}

return null; // Required when the download servlet is used

}

}

An exception may be converted to NestedException so that it can be reported instead of the format when the exception occurs.For an exception having the NestedException format, the getRootCause method is used to confirm the cause of the exception.

import com.fujitsu.uji.log.NestedException;

....


while(th instanceof NestedException) {

th = ((NestedException)th).getRootCause();

}

// th indicates the exception of the cause.

....

}

....

4.4 User-Defined Events

You can use user-defined events using the DispatchContext class to do the following: · Register event listeners. Register in DispatchContext required objects that will function as event

listeners. · Report the occurrence of user-defined events. Notify DispatchContext of occurrence of user-defined events

so that all event listeners that have been registered will be called. For example, use user-defined events to release resources when an error occurs: · Register an event listener for releasing a resource acquired for a file or network connection. · Notify DispatchContext that a user-defined event (error) has occurred. · The event listener is called to release the resource.

40

Because of user-defined events, processing in which an error is detected no longer needs to identify resources to be released.The following is the procedure for using a user-defined event: · Register event listener objects in DispatchContext using the addUjiEventListener method of the

DispatchContext class. · Notify DispatchContext of an event using the fireUjiEvent method of the DispatchContext class. Next,

pass the object of the user-defined event to the fireUjiEvent argument. This action calls all the registered event listeners.

Create a class that represents a user-defined event by inheriting the com.fujitsu.uji.event.UjiEvent class as follows:

public class MyEvent extends com.fujitsu.uji.event.UjiEvent {

static public final int TYPE0=0;

static public final int TYPE1=1;

protected int type;

// type indicates the type of the event

// and source indicates the object in which the event occurred.

public MyEvent(int type, Object source) {

// Set an initialization procedure below.

super(source);

this.type=type;

}

public int getType() {return type;}

}

The constructor always requires an argument for Object. The argument indicates the object in which the event occurred. Null is not allowed.

Create an event listener using the com.fujitsu.uji.event.UjiEventListener interface as follows:

import com.fujitsu.uji.event.UjiEvent;

import com.fujitsu.uji.event.UjiEventListener;

public class MyListener implements UjiEventListener {

java.io.File file;

public MyListener(java.io.File file) {

this.file=file;

}

// This method is called when the event occurs.

public void eventRaised(UjiEvent evt) {

if (evt instanceof MyEvent &&

41

((MyEvent)evt).getType()==MyEvent.TYPE1) {

file.delete();

}

}

}

In the business class, use the event listener and event as follows:


context.addUjiEventListener(new MyListener(new File("foo"));

....

}

public Object postprocess(DispatchContext context,Object result) {

....

if (failed) {

context.fireUjiEvent(new MyEvent(MyEvent.TYPE1,this));

}

}

To delete event listeners from DispatchContext, use the removeUjiEventListener method.

Registered event listeners are valid until processing of a request ends. Processing of a request means the execution of <uji:dispatch/> in a Web application, a call to a business method in an EJB session Bean, or a call to a service class in a SOAP server application.

4.5 Hook for Business Class Calls

You can make a call to a user-defined class before making a call to the business class, and use the user-defined class to control calls to the business class. For example, you can use a user-defined class to log data before and/or after business class processing or control retries of calls to the business class if an error occurs in the class.

Usually, the application profile, session profile, and methods of the business class are called in the following order: 1. preprocess of the application profile 2. preprocess of the session profile 3. preprocess of the business class 4. methods of the business class (those specified in the command map) 5. postprocess of the business class or handleException 6. postprocess of the session profile or handleException 7. postprocess of the application profile or handleException However, the preprocesses are called only when the Preprocessor interface is used. The postprocesses and handleException are called only when the Postprocessor interface is used.

With a handler hook, you can call a user-defined class for 3, 4, or 5 above. A user-defined class used for this purpose is called a hook class. Using a hook class allows the following to be called in order in which they are listed:

42

1. preprocess of the application profile 2. preprocess of the session profile 3. preprocess of the hook class 4. dispatch of the hook class 5. preprocess of the business class 6. methods of the business class (those specified in the command map) 7. postprocess of the business class or handleException 8. postprocess of the hook class or handleException 9. postprocess of the session profile or handleException 10. postprocess of the application profile or handleException When the hook class supports the Preprocessor interface, its preprocess is called. If the Postprocessor interface is supported, its postprocess and handleException are called. For information about the Preprocessor and Postprocessor interfaces, see Common Processes.

The dispatch method of a hook class can call preprocess of the business class, methods specified in the command map, postprocess of the business class, or handleException in the order shown above.Create a hook class by inheriting the HandlerHook class.

import com.fujitsu.uji.DispatchContext;

import com.fujitsu.uji.ThreadSafeDispatchHandler;

import com.fujitsu.uji.DispatchException;

public class MyHook extends com.fujitsu.uji.HandlerHook {

public MyHook() {

// Code a procedure for initialization below.

}

public Object dispatch(DispatchContext ctx,

ThreadSafeDispatchHandler dispatchHandler)

throws DispatchException {

System.out.println("MyHook: dispatch()");

// Retry twice.

DispatchException lastEx=null;

for (int i=0; i<3; i++) {

System.out.println("MyHook: try "+i);

try {

return dispatchHandler.dispatchSafely(ctx);

}

catch (DispatchException e) {

e.printStackTrace();

lastEx=e;

}

}

throw new DispatchException("Failed 3 times",lastEx);

43

}

}

ThreadSafeDispatchHandler is passed to the dispatch method. When the dispatchSafely method of this class is called, the preprocess method of the business class, methods specified in the command map, and postprocess method are called. As the argument of the dispatchSafely method, use DispatchContext that has been delivered as the argument of the dispatch method.

To enable a hook class that has been created, override the newHandlerHook method of the factory class so that a new object of the hook class is created and returned. The following is a coding sample in which a Web application factory class is used:

import com.fujitsu.uji.http.HttpFactory;

import com.fujitsu.uji.HandlerHook;

public class HookFactory extends HttpFactory {

// Make a new object of the created hook class and return it.

public HandlerHook newHandlerHook() {

return new MyHook();

}

}

A user-defined factory class must have its initialization parameter set. For information about how to use a factory class, see Factory Class.

4.6 Resource Files

A resource file is an XML file with definitions of character string data used by applications. This type of file can be used to define the following character string data: · Messages output to screens and logs · Initial values of options such as a combo box Since a resource file enables you to define character strings in an external file, you can change character strings without recompiling a program. It is easy to support multiple languages because a resource file can be created per locale.

Apcoordinator provides API and UJI tags for the following processing with character strings defined in a resource file: · Getting of the character strings defined in the resource file · Setting of options in combo boxes, list boxes, and button lists according to the character strings defined in

the resource file · Creation of messages from the message template defined in the resource file · Output of the character strings defined in the resource file to screens, according to UJI tags

4.6.1 Creating a Resource File

The following is an example of resource file coding:

<?xml version="1.0" encoding="ISO-8859-1"?>

<ujiResource

44

xmlns="http://interstage.fujitsu.com/schemas/uji/ujiResource"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/ujiResource

http://interstage.fujitsu.com/schemas/uji/ujiresource.xsd">

<config>


</config>

<text id="target">Meeting room in XX building</text>

<text id="RESVOK">{0} reservations were made.</text>

<text id="RESVPT">Out of {0} cases, {1} were reserved. Check the contents.</text>

<array id="prior">

<elem>192.168.96</elem>

<elem>192.168.97</elem>

</array>

<map id="rooms">

<elem key="room101">Meeting room 101</elem>


</map>

</ujiResource>

The following data is defined in the resource file: · Single character strings · Character string array · Keyed character string array The keyed character string array consists of data keyed to each array element. It is used in such cases as when options are set in a combo box.

The coding format of the resource file is as follows:


<ujiResource





<config>


</config>

45



</ujiResource>

Define character strings by using the tags described below. Specify an ID in the id attribute of each tag. IDs are used when Java programs and UJI tags refer to character strings. Each ID in a resource file must be unique.

text tag The text tag is used to define a single character string. For the contents of this tag, specify a character string.

<text id="target">Meeting room in building XX</text>

array tag The array tag is used to define a character string array. For the contents of the array tag, write one or more elem tags; and for the contents of each elem tag, specify a character string that serves as an array element.

<array id="priorIPs">

<elem>192.168.96</elem>

<elem>192.168.97</elem>

</array>

map tag The map tag is used to define a keyed character string array. For the contents of the map tag, write one or more elem tags; and for each elem tag, specify a character string that serves as an array element. Also, specify a key value in the key attribute of each elem tag.

<map id="rooms">



</map>

If you want to include <, >, ", or & in a character string definition, replace it with <, >, ", or &, respectively. For example, specify the following to define "R&D center" as a character string:

<text id="office12">R&D center</text>

The resource file is named ujiresource.xml by default. The name can be changed by modifying the uji.resource initialization parameter. For more information about the initialization parameter, see Initialization Parameters.

46

One resource file can be created per locale. In this case, the resource file name is ujiresource_[locale].xml. In the name, each locale is represented in either of the following formats: · [language-code]_[country-code] · [language-code] The language and country codes are the same as those used in the java.util.Locale class.For example, the resource file corresponding to a locale represented as en_US is named ujiresource_en_US.xml.

Place a resource file in a configuration file folder. Standard configuration file folders are as follows:

Type of application Configuration file folder

Web application /WEB-INF

EJB session Bean

The configuration file folder for this application is determined from the session Bean class name as follows:

/[package-hierarchy]/[class-name]_inf

[package-hierarchy] is a folder at the same level as that of the package of the session Bean class and [class-name] is the session Bean class name.

SOAP server application /SOAP-INF

4.6.2 Referring to a Character String from a Java Program

In order to refer to a character string defined in a resource file from a Java program, get the character string by using an application class or the UjiResource class.

Getting a character string by using an application class

An application class (com.fujitsu.uji.ApplicationProfile class) has the following methods, which can be used to get the single character strings, character string array, and keyed character string array defined in a resource file: · getResourceText method: Gets a single character string. · getResourceArray method: Gets a character string array. · getResourceMap method: Gets a keyed character string array. Specify the IDs of the character strings to be gotten in the arguments of these methods. The following is a coding example of these methods:

import com.fujitsu.uji.ApplicationProfile;


import java.util.Map;

...


ApplicationProfile ap = context.getApplicationProfile();

// Getting of single character string

String targetStr = ap.getResourceText("target");

// Getting of a character string array

String[] priorStr = ap.getResourceArray("prior");

// Getting of a keyed character string array

Map.Entry[] roomsStr = ap.getResourceMap("rooms");

...

47

}

If a locale (java.util.Locale class) is specified in the second argument, the resource file corresponding to the locale is used. For example, if en_US is specified for a locale, a search for the following files is performed in the order listed, and the file found first is used: · ujiresource_en_US.xml · ujiresource_en.xml · ujiresource.xml

Getting a character string by using the UjiResource class

The com.fujitsu.uji.util.UjiResource class has the static methods listed below, which can be used to get character strings. Specify the IDs of the character strings to be gotten and the DispatchContext class in the arguments of these methods. · getResourceText method: Gets a single character string. · getResourceArray method: Gets a character string array. · getResourceMap method: Gets a keyed character string array.


import com.fujitsu.uji.util.UjiResource;

import java.util.Map;

...


// Getting of single character string

String targetStr = UjiResource.getResourceText(context, "target");

// Getting of a character string array

String[] priorStr = UjiResource.getResourceArray(context, "prior");

// Getting of a keyed character string array

Map.Entry[] roomsStr = UjiResource.getResourceMap(context, "rooms");

....

}

In a Web application, the definition of a locale is gotten from the HTTP request received. If the HTTP request header has the Accept-Language header, the resource file corresponding to the locale specified in the Accept-Language header is used. The following is an example of the Accept-Language header:

Accept-Language: de,en-us;q=0.5

In this example, a search for the following resource files is performed in the order listed: · ujiresource_de.xml · ujiresource_en_US.xml · ujiresource_en.xml

48

· ujiresource.xml The Q value of the Accept-Language header is not used.

As well as the character string getting methods, the following functions are provided by the UjiResource class:

Initialization of the item class of a combo box, list box, or button list The keyed character string array defined in a resource file is set as option information for the item class of the combo box, list box, or button list by the initObject method of the UjiResource class. Keys are used as option values, and character strings are used as option display character strings. Examples of setting a character string array for the item class of a button list are shown below.

Example of data Bean coding

import com.fujitsu.uji.DataBean;

import com.fujitsu.uji.compo.ButtonList;

public class MyDataBean extends DataBean {

protected ButtonList blRoom = new ButtonList();

....

public ButtonList getBlRoom() {

return blRoom;

}

....

}

The blRoom property of the ButtonList type is created by specifying it in the data Bean.

Example of resource file coding


<ujiResource





<config>


</config>

<map id="rooms">



</map>

49

</ujiResource>

In the example, the two options are defined for the button list. "Meeting room 101" and "Meeting room 102" are option labels, and "room101" and "room102" are option values.

Example of business class coding


import com.fujitsu.uji.compo.ButtonList;


...


MyDataBean bean = new MyDataBean();

...

ButtonList blRoom = bean.getBlRoom();

UjiResource.initObject(context, "rooms", blRoom);

...

}

In the example, the item class of the button list is retrieved from the data Bean, and an option is set in the initObject method. "rooms" is the ID of the character string array defined in the resource file.

Example of JSP coding

<uji:buttonList bean="body" property="blRoom" multipleMode="true" columns="3" />

The uji:buttonList tag is the UJI tag used to display the button list. The property specified in the property attribute indicates the type of item class of the button list. The "Meeting room 101" and "Meeting room 102" options set in the item class are displayed.

The initObject method can also be used for a user-defined class. In such a case, implement the com.fujitsu.uji.util.KeyValueList interface in the user-defined class.

Creation of messages from the message template The getMessage method of the UjiResource class creates a message character string from the IDs of character strings, supplemental information, and the message template defined in a resource file. This method is used to dynamically embed information in part of a message. Specify single character strings to define the message template in a resource file.

<text id="RESVPT">Out of {0} cases, {1} were reserved. Check the contents.</text>

50

Write the message template in the format used by java.text.MessageFormat. The getMessage method replaces {0} and {1} with corresponding supplemental information, and creates a message. Implement the com.fujitsu.uji.util.MessageInformation interface, and create a class for storing message information. The ID of the message template is returned when the getMessageId method of this class is implemented, and the supplemental information array is returned when the getMessageParams method is implemented.

import com.fujitsu.uji.util.MessageInformation;

class Message implements MessageInformation {

String id;

Object[] params;

public Message(String id, Object[] params) {

this.id = id;

this.params = params;

}

public String getMessageId() {

return id;

}

public Object[] getMessageParams() {

return params;

}

}

getMessage uses the DispatchContext and MessageInformation implementation classes as its arguments. The getMessage return value is the character string of the created message.



...


Message msg = new Message("RESVPT", new String[]{"3","2"});

String msgStr = UjiResource.getMessage(context, msg);

...

}

In the above example, the getMessage method creates and returns the following message:

51

Out of 3 cases, 2 were reserved. Check the contents.

If you want your Web application to display the character string created by getMessage, store the character string in a data Bean property and display the string using the UJI tags written on a JSP.For information on how to display character strings, using a Web application, see Flow of Display Processing.

The MessageInformation interface is implemented in the ESpecResultException exception class used in an XML-described data specification, so getMessage can be used to create data check result messages. For more information about XML-described data specifications, see XML-described Data Specifications.

4.6.3 Referring to a Character String from a JSP

In order for a Web application to display a character string defined in a resource file, specify the uji:resourceText tag on a JSP as follows:

<uji:resourceText id="target"/>

The id attribute specifies the ID of a character string defined in a resource file. If a character string includes HTML special character <, >, ", or &, the character is converted to <, >, ", or &, respectively, and output. If this conversion is unnecessary, specify false in the escape attribute of the uji:resourceText tag. In the following examples, character strings are defined such that characters are correctly displayed:

- Example of defining character string "R&D center" so that it is correctly displayed Specify "R&D center" as a character string in a resource file. According to XML rules, if you want to include <, >, ", or & in a definition of a character string, the character must be replaced with <, >, ", or &, respectively.

<text id="office12">R&D center</text>

Omit the escape attribute of the uji:resourceText tag. The defined character string is output in HTML as follows:

R&D center

"R&D center" is displayed on the screen. - Example of defining character string "<B>Note</B>" in combination with HTML tags so that it is correctly displayed

Specify "<B>Note</B>" as a character string in a resource file. According to XML rules, if you want to include <, >, ", or & in a definition of a character string, the character must be replaced with <, >, ", or &, respectively.

52

<text id="caution"><B>Note</B></text>

Specify escape="false" in the uji:resourceText tag. The defined character string is output in HTML as follows:

<B>Note</B>

"Note" is displayed in bold on the screen, according to the B tag of HTML.

If the HTTP request header has the Accept-Language header, the resource file corresponding to the locale specified in the Accept-Language header is used, which is the same as when the UjiResource class is used. For details, see Getting a character string by using the UjiResource class.

4.7 Retrying Business Classes

4.7.1 Overview of the Business Class Retry Function

The business class retry function reexecutes a business class for which an exception occurred. Use this function to reexecute a business class that has terminated with an error but might end normally next time because the cause of the error was, for example, unsuccessful access to a temporarily locked database.

You can use the business class retry function for retrying business classes in the following cases: · The methods of a business class have been specified in a command map (such method is called "business

methods" hereafter) and any of the methods throw java.lang.Exception or a subclass (java.lang.RuntimeException and its subclasses excluded). In the following, exceptions that cause retry of a business class are called retry exceptions.

· The setRetry method of the com.fujitsu.uji.DispatchContext class is called. In this case, even though no method causes a retry exception, the class is retried after the method ends. To retry a business class without causing an exception, use this method.

The number of retries is limited.If either case above occurs but the retry limit is exceeded, no more retries are made.

If an error occurs (java.lang.Error or any of its subclasses) while a business class is executing, a retry that has already been scheduled is canceled.

For information about operation of the retry function when it operates with the Transaction Management, see Using the Transaction Management Function Together with the Business Class Retry Function.

53

4.7.2 Creating a Business Class for the Retry Function

To use the business class retry function, create a business class that implements the com.fujitsu.uji.RetriableHandler interface.You can easily create such a business class by extending com.fujitsu.uji.GenericRetriableHandler. The GenericRetriableHandler class simplifies implementation of the RetriableHandler interface.

The default retry settings are as follows: · Retry is valid for all business methods of a business class that implements RetriableHandler. · The retry interval is 100 ms. · The maximum number of retries is 2 (including the initial execution, the class is executed three times).

Determining whether to retry a class after its business methods have been executed

To make business methods refer to the related data in the business class or session class after execution and then to determine whether the class is to be retried, code this processing in the beforeMethodCompletion method of the business class. The beforeMethodCompletion method is invoked whenever a business method ends execution.

To enable class retry using the beforeMethodCompletion method, invoke the setRetry method of the com.fujitsu.uji.DispatchContext class. Specify true as the argument. To cancel a retry that has already been scheduled, invoke the setRetry method specifying false as the argument.

To check for a scheduled retry, use the getRetry method of the DispatchContext class. If all of the conditions for retry have been met after an exception has occurred, retry has been scheduled, and the getRetry method returns true.

Specifying retry settings with a business method

To specify whether retry is enabled, the retry interval, and the number of retries for each business method, create a business class configuration file (handlerconfig.xml) in the configuration files folder and specify the details for each method.

The following is an example of coding a business class configuration file (handlerconfig.xml):

<?xml version="1.0" encoding="iso-8859-1"?>

<handlerConfig

xmlns="http://interstage.fujitsu.com/schemas/uji/handlerConfig"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/handlerConfig

http://interstage.fujitsu.com/schemas/uji/handlerconfig.xsd">

<config>


</config>

<handler name="sample.SampleHandler"> 

<method name="doUpdate"> 

<retry enabled="true" retryInterval="200" retryCount="1" /> 

</method>

<method name="*"> 

<retry enabled="false"/> 

54

</method>

</handler>

</handlerConfig>

· (1) Specify one business class in one handler tag. In the name attribute, code the name of the business class with its package name.

· (2) Using a method tag, code the settings of the business methods of the business class that you specified in (1). Write the name of the method in the name attribute. Use one method tag for each method of the class. A method tag is used in the content of the handler tag.

· (3) Code the retry settings for the business method specified in (2) using a retry tag. Use one retry tag in the content of the method tag. Specify the following attributes for the retry tag: enabled

Specifies whether to enable retries. Specifying true enables the business class retry function for the business method specified in (2), and specifying false disables it. The default is true.

retryInterval Specifies the retry interval in milliseconds. The default interval between retries is 100 ms.

retryCount Specifies the maximum number of retries. For example, when 2 is specified for this attribute, the method is executed up to three times, including the initial regular execution. The default maximum number of retries is 2.

· (4) and (5) To define the default settings, specify name="*" in a method tag. The default settings are applied to a business method for which a method tag has not been specified or a retry tag has not been specified for the associated method tag.

In the coding sample above, the business class retry function is enabled for the doUpdate method of the sample.SampleHandler class, and disabled for other business methods.

The precision of the retry interval depends on the system being used.Some systems cannot support an interval at a 10 ms or higher precision.

Order of executing methods

The business class retry function invokes business class methods in the following order:

When a business class has implemented the com.fujitsu.uji.Postprocessor interface, either the postprocess method or handleException method is invoked. handleException is invoked in the cases described below, and postprocess is invoked in all other cases. · A business method threw an exception, but the method was not retried. This situation occurs in the

following cases: - The exception thrown is not a retry exception.

55

- After the exception occurred, setRetry(false) was executed in the beforeMethodCompletion method.

- The maximum number of retries has been exceeded. · The business method has terminated normally, and setRetry(true) has been executed, but the

maximum number of retries has been exceeded. As a result, no more retries were possible, and com.fujitsu.uji.RetryCountExpiredException is reported to handleException.

handleException was not notified of an exception occurred in beforeMethodCompletion.

Even though a business class has implemented the RetriableHandler interface, the beforeMethodCompletion method is not invoked when the business class retry function has been disabled in the business class configuration file.

4.7.3 Notes on Using the Business Class Retry Function

If a business class is retried, any processing that the business class has already performed is not canceled.Therefore, observe the following when you create a business class.

Notes on invoking an EJB using a business method

When a business method creates EJB session Bean objects, be sure to delete the EJB session Bean objects before attempting retry. When you create EJB session Bean objects using the createCall method of the com.fujitsu.uji.ext.CallFactory interface or the createUjiSessionCall method of the com.fujitsu.uji.ejb.EJBCallFactory class, you can remove them using the remove method of the com.fujitsu.uji.ejb.UjiSessionCall interface. For a Call interface obtained using createCall, cast UjiSessionCall, then execute remove.

If you create EBJ session Bean objects using a business method but do not remove them before attempting retry, the objects continue to exist after the retry is performed.

Notes on data Beans specified in business method arguments

Be sure to change the data Beans specified in the arguments of a business method only after the processing in which a retry exception has occurred has been completed. In addition, when you use setRetry(true), do not change data Beans. If a business class is retried after the data Beans are changed, the data Beans that have been changed are specified in the arguments of the business method when retry invokes the business method.

Notes on changes to the data of business class, session class, and application class objects

Objects of classes of the types listed below are not deleted after invocation of an associated business class has been completed. If changes are made to the data of such objects and then a retry is performed, the data of the objects remains in its changed state when the retry invokes the business method. · Business class (When the init method returns true) · Session class · Application class If a problem would result because changes made to data before a retry remain in effect after the retry, make changes to the data of business class, session class, or application class after completion of the processing in which a retry exception could occur. In addition, when you use setRetry(true), do not make any changes to the data of a business class, session class, or application class.

The following program code outlines how to make changes to the data of a business class, session class, or application class after completion of the processing in which a retry exception could occur.


import com.fujitsu.uji.GenericRetriableHandler;

...

56

public class SomeHandler extends GenericRetriableHandler {

public boolean init() {

return true;

}

public Object doSomething(DispatchContext context, SomeBean dataBean) throws MyException {

// If an exception occurs between try and catch,

// the program throws the MyException retry exception.

// In this range,

// no change must be made in any business class, session class, or application class.

try {

...

} catch (Exception e) {

throw new MyException(e.getMessage(),e);

}

// No retry exception occurs hereafter.

// Make changes to the data of business class, session class, or application class or

// change data Beans specified in the arguments of a business method here.

...

return dataBean;

}

...

}

Notes on using the setResponseBean method

Do not allow a retry exception to occur after execution of the setResponseBean method of the com.fujitsu.uji.DispatchContext class. In addition, when setRetry(true) is used, do not execute setResponseBean. If a retry is made after execution of setResponseBean, setResponseBean processing cannot be canceled.

4.8 Transaction Management

4.8.1 Features Provided by the Transaction Management Function

The transaction management function enables Apcoordinator to start, commit, and roll back transactions. When you use the transaction management function, you do not need to specify when to start and end transactions in applications and you can manage transactions easily.

57

The transaction management function allows Apcoordinator to manage a transaction as follows: · Apcoordinator starts handling a transaction just before the methods of a business class ("business

methods" hereafter) specified in a command map are invoked. · If the invoked business methods end normally, Apcoordinator commits the transaction. · Apcoordinator rolls back the transaction in the following cases: - A business method threw a rollback exception. The following are used as a rollback exception by

default. You can also add entries for rollback exceptions: · java.lang.RuntimeException and any of its subclasses · java.lang.Error and any of its subclasses - The setRollbackOnly method of the com.fujitsu.uji.DispatchContext class is invoked.

Even though a business method does not throw a rollback exception in this case, Apcoordinator rolls back the transaction after the business methods end. To have Apcoordinator roll back the transaction without throwing an exception, use setRollbackOnly.

- The business class retry function is in use and business classes are subject to retry. Apcoordinator can handle transactions that can be managed through the following interfaces: javax.transaction.UserTransaction interface

UserTransaction is an interface for transaction management. UserTransaction is based on the JTA (Java Transaction API) specification. In general, UserTransaction is used to manage transactions related to EJBs, JMSs, and JDBCs.

java.sql.Connection interface java.sql.Connection is an interface that represents a connection to a database. java.sql.Connection is based on the JDBC specification. java.sql.Connection is used for direct access to a database independently of an application server.

For some other interfaces not mentioned above, you may be able to use Apcoordinator to manage them by creating an adapter. For information about creating such an adapter, see JDBC-based Transaction Management.

By default, the UserTransaction interface is used to manage transactions. For details of transaction management using the java.sql.Connection interface, see JDBC-based Transaction Management.

The table below shows the types of applications that can link their transactions and the types of resources that can be managed in transactions when transactions are managed through the UserTransaction interface and Interstage is used as the application server: · Types of applications that can be linked to transactions: In the following combinations of application

types, a calling application (one that calls other applications) can run called applications in a transaction that the calling application has started.

Called application Calling application In a non-distributed transaction In a distributed transaction

Web application EJB on the IJServer on which the calling application is running (*1)(*2)

(A distributed transaction is not allowed.)

EJB session Bean EJB on the IJServer on which the calling application is running (*1)

EJB running on the IJServer on the same machine (*1)(*3)

58

Called application Calling application In a non-distributed transaction In a distributed transaction

SOAP server application

EJB on the IJServer on which the calling application is running (*1)(*2)

(A distributed transaction is not allowed.)

*1 Each called EJB needs to be set up so that it can run in the transaction of the calling application. Therefore, set the transaction type of the called EJBs to Container, and the transaction attribute to Mandatory, Required, or Supports. *2 For the IJServer type, use "Run Web Applications/EJB Applications on the Same JavaVM". *3 The IJServers of the calling application and called applications need to be of one of the types below. In addition, distributed transactions must be enabled in both the calling and called applications:

- Run only EJB applications - Use Different JavaVMs for Web Applications/EJB Applications · Resources that can be managed in transactions: The table below shows the types of resources that can be

used while a transaction is in progress. The resources are put under management of the transaction. Distributed transaction Types of resources that can be managed

Unused · JDBC data source (*1)(*2)

Used · JDBC data source (*3) · JMS connection factory (*3) · connector connection factory (*3)

*1 Only one data source can be used in one transaction. To use a data source more than once, use the same user ID and password each time. *2 The JDBC data source to be used must be registered with Interstage. To register it, use the Interstage Management Console. *3 The resource to be used must be registered with Interstage. In addition, the resource must support distributed transaction. To register it, use the Interstage Management Console.

Resources that can be managed in a transaction depend on the execution environment, such as the application server.

4.8.2 Creating a business class for the transaction management function

To use the transaction management function, create a business class that implements the com.fujitsu.uji.transaction.TransactionHandler interface.You can easily create such a business class by extending the com.fujitsu.uji.transaction.GenericTransactionHandler class. The GenericTransactionHandler class simplifies implementation of the TransactionHandler interface.

By default, Apcoordinator manages transactions as follows: · The transaction management function is valid in all business methods of every business class that

implements TransactionHandler. · The javax.transaction.UserTransaction interface is used to manage transactions.

Executing specific processing just before starting a transaction

To execute specific processing just before starting a transaction, code a processing statement in the beforeTransactionBegin method of the business class. This method is invoked just before the transaction starts.

Executing specific processing just before the end of a transaction

To execute specific processing just before a transaction is committed or rolled back, code a processing statement in the beforeTransactionCompletion method of the business class. The beforeTransactionCompletion method is invoked just before the transaction is committed or rolled back after the business method ends execution. To obtain the status of the transaction at that time, use the getRollbackOnly method of the com.fujitsu.uji.DispatchContext class. If an exception has occurred or execution of setRollbackOnly determines that a rollback is required, getRollbackOnly returns true.

The transaction is rolled back when beforeTransactionCompletion: · Throws a rollback exception to generate.

59

· Calls the setRollbackOnly method of the DispatchContext class.

Executing specific processing after the end of a transaction

To execute specific processing after a transaction is committed or rolled back, code a processing statement in the afterTransactionCompletion method of the business class.afterTransactionCompletion is invoked just after the transaction is committed or rolled back.

Setting the operation of the transaction management function using a business method

To specify whether the transaction management function is valid or any additional rollback exceptions for each business method, create a business class configuration file (handlerconfig.xml) in the configuration files folder and specify the details for each of the methods.

The following is an example of coding a business class configuration file (handlerconfig.xml):


<handlerConfig





<config>


</config>

<handler name="sample.SampleHandler"> 

<method name="doUpdate"> 

<transaction enabled="true"> 

<rollbackException class="some.pkg.MyException"> 

</transaction>

</method>

<method name="*"> 

<transaction enabled="false"/> 

</method>

</handler>

</handlerConfig>

· (1) Specify one business class in one handler tag. In the name attribute, write the name of the business class with its package name.

· (2) Using a method tag, code the settings of the business methods of the business class specified in (1). Write the name of the method in the name attribute. Use one method tag for each method of the business class. A method tag is used in the content of a handler tag.

· (3) Code the settings for the business method specified in (2) using a transaction tag. Use one transaction tag in the content of the method tag. Specify the following

60

attributes for the transaction tag: enabled

Specifies whether to enable the transaction management function. Specifying true enables the transaction management function for the business method specified in (2), and specifying false disables it. The default is true.

· (4) If necessary, code a rollbackException tag in the transaction to add rollback exceptions. In the class attribute, code the name of an exception class with its package name. The specified class and its subclasses are assigned as rollback exceptions. You cannot specify the following classes in the class attribute because they are fixed rollback exceptions:

- java.lang.RuntimeException and any of its subclasses - java.lang.Error and any of its subclasses · (5) and (6) To define the default settings, specify name="*" in a method tag. The default

settings are applied to a method for which no method tag has been specified or no transaction tag has been specified for its method tag.

In the coding sample above, the transaction management function is enabled for the doUpdate method of the sample.SampleHandler class, and disabled for other methods. For rollback exceptions, doUpdate uses some.pkg.MyException as well as RuntimeException, Error, and their subclasses.

Order of executing methods

The transaction management function invokes business class methods in the following order:

When a business class has implemented the com.fujitsu.uji.Postprocessor interface, either the postprocess method or handleException method is invoked. handleException is invoked when an exception is thrown in any of the following cases. In all other cases, postprocess is invoked. · beforeTransactionBegin · Start of a transaction · Business method If an exception occurs in preprocess, beforeTransactionBegin, or the transaction startup sequence, part of the subsequent processing is skipped. The table below shows where an exception can occur and the processing skipped by the exception.

61

Whether subsequent processing executed or skipped Processing in

which exception

occurs

before Transaction

Begin

Start of a transactio

n

Business

method

before Transacti

on Completi

on

End of a transact

ion

after Transacti

on Completi

on

handle Exception

(*1)

preprocess Skipped Skipped Skipped Skipped Skipped Skipped Skipped (*2) beforeTransactionBegin Not applicable Skipped Skipped Skipped Skipped Skipped Executed

Start of a transaction Not applicable Not

applicable Skipped Executed Skipped Executed Executed

*1 Invoked when the business class has implemented the Postprocessor interface. *2 Neither handleException nor postprocess is invoked.

Even though the business class has implemented the TransactionHandler interface, the beforeTransactionBegin, beforeTransactionCompletion, or afterTransactionCompletion method is not invoked when the transaction management function has been disabled in the business class configuration file.

4.8.3 Using the Transaction Management Function Together with the Business Class Retry Function

To use the transaction management function together with the business class retry function, create a business class that implements the com.fujitsu.uji.transaction.TransactionHandler and com.fujitsu.uji.RetriableHandler interfaces. You can easily create such a business class by extending the com.fujitsu.uji.transaction.RetriableTransactionHandler class. The RetriableTransactionHandler class simplifies implementation of the TransactionHandler and RetriableHandler interfaces.

Code statements for both the transaction management function and business class retry function in the business class configuration file (handlerconfig.xml) as follows:


<handlerConfig





<config>


</config>

<handler name="sample.SampleHandler">

<method name="doUpdate">

<transaction enabled="true"/> 


62

</method>

<method name="search">


</method>

<method name="*">

<transaction enabled="false"/> 

<retry enabled="false"/> 

</method>

</handler>

</handlerConfig>

The settings in this coding sample are as follows:

· For the doUpdate method of the sample.SampleHandler class, both the transaction management function and the business class retry function are enabled according to specifications (1) and (2).

· For the search method of the sample.SampleHandler class, the business class retry function is enabled according to specification (3). Since nothing is specified for the transaction management function, the transaction management function is disabled according to the default settings in specification (4).

· For other methods of the sample.SampleHandler class, both the transaction management function and the business class retry function are disabled according to specifications (4) and (5).

When the transaction management function is used together with the business class retry function, the business class retry function interlocks with the transaction management function. In a retry, the transaction is rolled back immediately before the retry, then the transaction is restarted.

The business class methods are invoked in the following order. In a retry, execution proceeds to afterTransactionCompletion, then resumes at beforeTransactionBegin.

63

When a business class has implemented the com.fujitsu.uji.Postprocessor interface, either the postprocess method or handleException method is invoked. handleException is invoked in the cases described below, and postprocess is invoked in all other cases. · An exception occurred in beforeTransactionBegin or in the transaction startup sequence. · A business method threw an exception, but the method was not retried. This situation occurs in the

following cases: - The exception thrown is not a retry exception. - After the exception occurred, setRetry(false) was executed in beforeMethodCompletion. - The maximum number of retries has been exceeded. · The business method has terminated normally, and setRetry(true) has been executed, but the

maximum number of retries has been exceeded. As a result, no more retries were possible, and com.fujitsu.uji.RetryCountExpiredException is reported to handleException.

handleException is not notified of an exception occurred in preprocess, beforeTransactionBegin, or the transaction startup sequence.

If an exception occurs in preprocess, beforeTransactionBegin, or the transaction startup sequence, part of the subsequent processing is skipped. The table below shows where an exception can occur and the processing skipped by the exception.

Subsequent processing executed or skipped Processing in which exception

occurs

before Transactio

n Begin

Start of a transactio

n

Business

method

before Transacti

on Completi

on

before Method Complet

ion

End of a transact

ion

after Transacti

on Completi

on

handle Exceptio

n (*1)

preprocess Skipped Skipped Skipped Skipped Skipped Skipped Skipped Skipped

(*2) beforeTransactionBegin

Not applicable Skipped Skipped Skipped Skipped Skipped Skipped Executed

Start of a transaction

Not applicable

Not applicable Skipped Executed Skipped Skipped Executed Executed

*1 Invoked when the business class has implemented the Postprocessor interface. *2 Neither handleException nor postprocess is invoked.

64

4.8.4 JDBC-based Transaction Management

To have Apcoordinator handle a transaction for a JDBC-based database connection, use the preprocess method or beforeTransactionBegin method of a business class as follows: 1. Use the getUjiTransaction method of the com.fujitsu.uji.DispatchContext class to obtain a

com.fujitsu.uji.transaction.UjiTransaction object. UjiTransaction class manages transactions when the transaction management function is used.

2. Use the setSQLConnection method of UjiTransaction to register a java.sql.Connection object in UjiTransaction.

When you register a java.sql.Connection object in UjiTransaction, Apcoordinator manages transactions using the java.sql.Connection interface. Transaction management that uses the UserTransaction interface is invalidated.

The following is an example of coding a business class:

import java.util.Hashtable;

import java.sql.Connection;

import javax.sql.DataSource;

import java.sql.SQLException;

import javax.naming.InitialContext;

import javax.naming.Context;

import javax.naming.NamingException;

import com.fujitsu.uji.transaction.GenericTransactionHandler;

import com.fujitsu.uji.transaction.UjiTransaction;


import com.fujitsu.uji.Preprocessor;

public class SampleHandler extends GenericTransactionHandler

{

Connection connection = null;

public int preprocess(DispatchContext context) {

try {

Hashtable hashtable = new Hashtable();

hashtable.put(Context.INITIAL_CONTEXT_FACTORY, "com.fujitsu.symfoware.jdbc2.jndisp.SYMContextFactory");

hashtable.put(Context.PROVIDER_URL, "SYM://SYMFOSV");

InitialContext ctx = new InitialContext(hashtable);

DataSource source = (DataSource)ctx.lookup("jdbc/sampledb");

connection = source.getConnection("userName", "password"); // (1)

UjiTransaction ujiTransaction = context.getUjiTransaction();

ujiTransaction.setSQLConnection(connection); // (2)

65

// Because connection.setAutoCommit(false) is executed by UjiTransaction,

// you do not have to execute it in the application program.

} catch (SQLException e) {

...

} catch (NamingException e) {

...

}


}

...

public Object postprocess(DispatchContext context, Object result) {

closeConnection();

return result;

}


closeConnection();

return null;

}

private void closeConnection() {

if (connection != null) {

try {

connection.close();

} catch (SQLException e) {

...

}

}

}

}

A connection to the database is established at (1) in the preprocess method, then the connection is registered in an UjiTransaction object at (2). This causes Apcoordinator to manage the transaction for the database connection created at (1). Disconnect the database connection on the application side. In this coding sample, the postprocess method and handleException method

66

are used to disconnect the database connection.

When you use the processing in the coding sample above together with the business class retry function, no new database connection is created by a retry, and the existing database connection is reused.Reuse of the existing connection occurs because the preprocess, postprocess, and handleException methods are not within the retry scope.To create and disconnect a database connection for each retry, use the beforeTransactionBegin method to establish a database connection and register it in an UjiTransaction object, then use the afterTransactionCompletion method to disconnect it.

For non-JDBC interfaces, Apcoordinator can manage transactions by creating an adapter. Program and set up an adapter as follows: · Create an adapter that allows Apcoordinator to manage transactions. The adapter needs to implement

the com.fujitsu.uji.transaction.Resource interface. Create the adapter so that a transaction is started, committed, and rolled back when the begin, commit, and rollback methods of the Resource interface are invoked.

· In the beforeTransactionBegin method of the business class, wrap objects that is managed for the transaction in the adapter, then register the adapter in UjiTransaction using the setResource method of the UjiTransaction class.

When you use the setResource method of UjiTransaction, Apcoordinator manages transactions using an adapter that has been registered. Transaction management that uses the UserTransaction interface is invalidated.

4.8.5 Notes on using the transaction management function

Notes the following points when using the transaction management function: · Since, by default, Apcoordinator manages transactions using the

javax.transaction.UserTransaction interface, do not directly use a UserTransaction interface to manage transactions. If you do so, transactions cannot be managed correctly because Apcoordinator is using UserTransaction.

· When you use the transaction management function in a session Bean, use bean-managed transaction demarcation in the session Bean. If you use container-managed transaction demarcation, the transaction management function becomes unusable, resulting in an exception if a business class cannot be invoked.

67

68

Chapter 5 Using XML Data

5.1 Overview of the XML Linkage Function

The XML linkage function facilitates creation of applications that use the XML data format. The function handles XML data as a data Bean, which is referred to as an XML data Bean. With screen part tags and component tags, you can use XML data Beans to display XML data and update the data with input data items. You can also reference and update XML data items specified with XPath.

To use the XML linkage function, you must have Fujitsu XML Processor or Apache Xerces/Xalan.For details, see Required Software.

An overview of the XML linkage function is shown below.

(1) Loading and saving XML data You can load XML data from a file or InputStream, and save the data to a file or OutputStream.

(2) Working with XML data You can use the methods of an XML data Bean to refer to, update, add, and remove data. Use XPath to specify which item of XML data you want to access.

(3) Using tags for displaying and inputting data With screen part tags and component tags, you can use XML data Beans to display XML data and update the data with input data items. Use XPath to specify which item of XML data you want to use with the tags.

This chapter describes the first and the second function shown above.For the third function, see Using XML Data with Tags.

5.2 XML Data Bean

An XML data Bean is a data Bean used to handle XML data. The com.fujitsu.uji.xml.XmlDataBean class is used as the class for XML data Beans. In an XML data Bean, XML data is maintained as the object tree, which is referred to as an XML tree. Each node of an XML tree corresponds to an XML element, and the root of the XML tree corresponds to the XML root element.

The element corresponding to the root of the XML tree maintained in an XML data Bean is referred to as the

69

root element of the XML data Bean. In the above diagram, the catalog element is the root element of the XML data Bean.

Creating XML Data Beans

The constructor in the XmlDataBean class creates an XML data Bean with empty XML data. To provide the Bean with XML data, load the XML data from a file or another source.

Loading and Saving XML Data

To load XML data, use the loadFrom method in the XmlDataBean class. Specify a file, InputStream, URI, or org.xml.sax.InputSource as a source.

To save XML data contained in an XML data Bean, use the saveTo method in the XmlDataBean class. You can specify a file or OutputStream as a destination. You can also specify a character-encoding scheme.


try {

// Create the File object that indicates a file to be loaded.

ServletContext sc = ((HttpDispatchContext)context).getServletContext(); String root = sc.getRealPath("/"); File file = new File(root, "/WEB-INF/user.xml");

// Create an XML data Bean.

XmlDataBean xmlBean = new XmlDataBean();

// Load XML data.

BufferedInputStream in = new BufferedInputStream(new FileInputStream(file));

xmlBean.loadFrom(in);

// Save XML data.

BufferedOutputStream out = new BufferedOutputStream(new FileOutputStream(file));

xmlBean.saveTo(out,"UTF-8");

context.setResponseBean("body",xmlBean);

} catch (Exception e) { e.printStackTrace(); } }

To specify a document type declaration when data is saved, use the setDoctype method. To specify the type of a line feed code and whether to add blank characters and omitted attributes, use the setWriteOption method.

Working with XML Data

You can use the methods of an XML data Bean to refer to, update, add, and remove data.

Before working with XML data, use XPath to specify the data element to be affected. XPath allows you to specify the desired element using the path to the element, starting from another XML data element.

For an explanation of XPath with examples, see Summary of XPath.

An XML data element can be referenced as a string or XML data Bean.

70

Referencing an XML data element as a string Use the getText method. Use XPath to specify the relative path starting from the root element of an XML data Bean.

String text = xmlBean.getText("item/name");

Referencing a portion of XML data as an XML data Bean Use the getSubBean method. The resultant XML data Bean has a subtree starting from the element specified with XPath.

XmlDataBean subBean = xmlBean.getSubBean("item");

The XML data Bean resulting from the use of getSubBean shares the XML tree with the original XML data Bean, instead of copying the tree. This means that when the resultant XML data Bean is updated, the original XML data Bean is also updated.

Data items specified with XPath include simple elements, complex elements, mixed elements, attributes, and collections of these elements or attributes. The following shows the relationship between the types of data items specified with XPath and values returned by getText and getSubBean.

Simple element Complex element Mixed

element Attribute Collection

getText Element content null null Attribute

value

Only the first element or attribute is referenced and one of the values shown at the left is returned.

getSubBean null

XML data Bean that has the specified element as the root element

null null

Only the first element is referenced and one of the values shown at the left is returned.

In the above table, "null" means that the method returns null.

XML data elements are classified as simple elements, complex elements, or mixed elements, according to whether they have child elements or text.

· Simple element: Does not have any child elements, but can have text. · Complex element: Has more than one child element, and can have only text that consists of

blank or line feed characters. · Mixed element: Has more than one child element and text.

In the XML data below, title is a simple element, header is a complex element, and body is a mixed element.

<doc>

<header>

<title>XML Linkage Function Manual</title>

71

<author>John</author>

</header>

<body>

This manual explains the

<bold>XML linkage function</bold> of

<bold>Apcoordinator</bold>

</body>

</doc>

To update the content of a simple element with a specified string, use the setText method.

xmlBean.setText("item/name", "White Wine");

When an attribute is specified with XPath, the attribute value is updated. When a collection is specified, its first data item is subjected to updating. This method cannot be used for complex elements and mixed elements.

If an element specified with XPath does not exist, it is added to XML data. However, this holds true only when XPath satisfies either of the following conditions: 1. A predicate ([expression] format) is not used (for example, item/name). 2. When a predicate is used, it is in the [integer] or [position()=integer] format (for example,

item[3]/note[position()=5]). Under condition 2 above, if the number of existing elements is less than the integer specified in a predicate, new elements are added so that the total number of the elements becomes equal to the integer. For example, setText("item[4]","foo") is executed for XML data having only one item element, three item elements are added. Then, the XML data now has four item elements in total, and the fourth item element contains foo.

To append a simple element, use the append method.

xmlBean.append("item", "name", "White Wine");

In the case of the above example,a name element is added to the last of children of the item element and the content of the name element is "White Wine".

To insert a simple element, use the insert method.

xmlBean.insert("item", "author", "title", "Online Manual");

In the case of the above example,a title element is inserted before the author element and the content of the title element is "Online Manual".

To remove an element, use the remove method. The method removes an element specified with XPath.

xmlBean.remove("item/name");

To replicate an XML data Bean, use the clone method. Updates to the duplicated XML data Bean are not reflected on the data in the original.

5.3 Summary of XPath

XPath allows you to specify an element or attribute in XML data. Specify the desired XML data element or attribute using the path to the element, starting from another XML data element. For example, the name element of the XML data below is specified with XPath "/book/publisher/name".


<book>

72

<title>Introduction to Apcoordinator</title>

<date>2001/4/1</date>

<publisher lang="en">

<name>Fujitsu Touch Communications</name>

<address>

<zip>10017</zip>

<state>New York</state>

<city>New York</city>

</address>

<phone>000-111-2222</phone>

<phone>000-333-4444</phone>

<phone type="tollfree">800-2222**</phone>

<fax type="g4">000-555-6666</fax>

</publisher>

</book>

There are two types of XPath specifications: absolute path and relative path. An absolute path starts from the root element of XML data. The above example is an absolute path. A relative path specifies the desired element with respect to a predetermined element. The following are some examples of relative paths from the publisher element of the above XML data.

XPath Specified data

address The address element, which is a child of publisher

address/zip The zip element, which is a child of the address element, which is a child of publisher

phone[2] Of the phone elements, which are children of publisher, the second one (the top element is the first one)

phone[@type="tollfree"] Of the phone elements, which are children of publisher, the one whose type attribute value is "tollfree"

. publisher element itself

@lang The lang attribute of publisher

fax/@type The type attribute of the fax element, which is a child of publisher

5.4 Namespace

Identified by referring to the URI, the namespace information in XML data can be used to qualify element names and attribute names. Designing XML data with namespaces in advance makes it possible to prevent value collisions resulting from use of the same element name when XML data is distributed.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<book xmlns:fj="urn:fj-touch-communications">


<date>2001/4/1</date>

<fj:publisher lang="ja">

<fj:name>Fujitsu Touch Communications</fj:name>

73

<fj:address>

<zip>222-0033</zip>

<prefecture>New York</prefecture>

<city>New York</city>

</fj:address>

<fj:phone>000-111-2222</fj:phone>

<fj:phone>000-333-4444</fj:phone>

<fj:phone type="tollfree">800-2222**</fj:phone>

<fj:fax type="g4">000-555-6666</fj:fax>

</fj:publisher>

</book>

An explanation of how to use XML data with namespaces in an XML data Bean is given below.

Registering namespace information To use XML data with namespaces in an XML data Bean, namespace information must be registered in advance. In the following example, the namespace URI "urn:fj-touch-communications" is registered for a namespace whose prefix is "fj". For information about APIs related to namespace registration, refer to the API Reference.


...

xmlBean.addNamespaceDeclaration("fj","urn:fj-touch-communications");

Reference value Specify a value that you want to use as a reference in XPath. At this time, a namespace prefix must also be specified.

String text = xmlBean.getText("fj:publisher/fj:name");

The XML data Bean automatically searches for the namespaces declared by elements higher than XML data Bean root elements.

This automatic search for declared namespaces is valid for the following methods:

· getText(String xpath) · getElement(String xpath) · getNodeSet(String xpath) · getSubBean(String xpath)

74

If namespace information is registered in an XML data Bean, the namespace prefix is resolved only from the registered information, and there is no automatic search for declared namespaces. To enable automatic search for declared namespaces, do not register namespace information in the XML data Bean.

Updating a value The value specified in XPath can be updated. Use the registered namespace prefix to specify XPath.

xmlBean.addNamespaceDeclaration("fj","urn:fj-touch-communications")

xmlBean.setText("fj:publisher/fj:address/city","Seattle");

Adding a namespace declaration Namespace information registered in XML data Bean root elements can be added with a namespace declaration. For details, see the API Reference.

Original XML data


<book>


</book>

Adding a namespace declaration

xmlBean.addNamespaceDeclaration("fj","urn:fj-touch-communications")

xmlBean.addNamespacesToNode()

XML data after addition of a namespace declaration


<book xmlns:fj="urn:fj-touch-communications">


</book>

75

76

Chapter 6 Remote Common Interface

This chapter explains how to call EJBs and Web services using the remote common interface from Apcoordinator applications.

The remote common interface is an API that commonly calls the following two types of applications: · Apcoordinator-based EJB session Beans · Apcoordinator-based SOAP server applications For the methods for calling other general EJBs and SOAP server applications, see the following: · Calling General EJBs · Calling General Web Services Before running an Apcoordinator application that calls an EJB or Web service, define the settings in the application execution environment that are required for calling the EJB or Web service according to the Application Server Handbook of the application server used.

6.1 Overview

The remote common interface is outlined below.

Use the remote common interface in the following procedure: 1. Name the session Bean or SOAP server application that you want to call. 2. Create a remote map, and describe the correspondence between the session Bean or SOAP server

application, and specify a name for it. 3. Acquire the Call interface from the CallFactory interface by specifying the corresponding name. 4. Call the session Bean or SOAP server application, using the Call interface. Specify a data Bean and

command name in arguments. In the following example, either a session Bean or SOAP server application is called from a business class with the remote common interface:

public Object doSomething(DispatchContext context, DataBean dataBean){

CallFactory factory = context.getCallFactory();

Call call = factory.createCall("MySessionBean"); // Specifying the SOAP server application to be called

77

ResponseBean response = (ResponseBean)call.invoke(dataBean,"update"); // Calling the SOAP server application with the data to be sent and command name specified

...

}

The subsequent sections explain how to code a remote map and how to use the CallFactory interface and Call interface.

6.2 Remote Map

The remote map is used to define an alias for a session Bean or SOAP server application used by the remote common interface. Write the remote map in XML as follows:


<remoteMap

xmlns="http://interstage.fujitsu.com/schemas/uji/remoteMap"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/remoteMap

http://interstage.fujitsu.com/schemas/uji/remotemap.xsd">

<config>


<defaultSoapApi>Interstage_JAXM</defaultSoapApi>

</config>



<ejb name="MySessionBean" application="java:comp/env/ejb/MySessionBean"/>



<local name="MyLocalSessionBean" class="mypackage.MySessionBean">

<env-entry>

<env-entry-name>guestUser</env-entry-name>

<env-entry-type>java.lang.String</env-entry-type>

<env-entry-value>guest</env-entry-value>

</env-entry>

</local>



<soap name="myService" url="http://somehost/soap/services/someservice"/>

</remoteMap>

The remote map root is remoteMap. Write the config tag inside the remoteMap tag, and then specify the

78

following two items of information: · Syntax version of remote map: In the version tag, specify the syntax version of the remote map. Always

specify 5.0. · Type of library used for SOAP server applications: In the defaultSoapApi tag, specify the type of library to

be used. Specify either of the following for the library type to be used: - Interstage_JAXM: Use of the libraries supplied with Interstage - Apache: Use of Apache SOAP provided by Apache XML Project After the config tag, specify a name with the tag corresponding to the application to be called. Specify the name of the application to be called in the name attribute.

ejb tag The ejb tag is defined with a session Bean name. Specify the name of the session Bean as the search target, with JNDI as the application attribute.

local tag The local tag is defined with the name of a session Bean that is locally called. Specify the name of the session Bean implementation class in the class attribute. For the contents of the local tag, specify the enterprise Bean environment used by the session Bean. For more information on local calling of session Beans, see Local Calling.

ejbExt tag The ejbExt tag is used to invoke session beans by means of EJB session bean grouping or using the EJB retry function. For details, see EJB Session Beans Grouping function and Retrying EJBs.

soap tag The soap tag is defined with the name of a SOAP server application. Specify the URL of the SOAP server application in the url attribute. Specify either of the following for the service attribute, depending on the SOAP server used by the SOAP server application to be called:

· SOAP server is Interstage: The service attribute is not used. · SOAP server is Apache SOAP: Specify the service identifier written in the

DeploymentDescriptor.xml file. The service identifier is the value specified in the id attribute of the isd:service tag in the deploy information file. For more information about the deploy information file, see Setting up the SOAP Server Application Execution Environment.

For details about these tags, refer to the Remote Map Reference.

6.3 Calling with the CallFactory Interface and Call Interface

In the following example, the CallFactory interface and Call interface is used:

import com.fujitsu.uji.ext.Call;

import com.fujitsu.uji.ext.CallFactory;

import com.fujitsu.uji.ext.UjiRemoteException;

import com.fujitsu.uji.ext.UjiTargetException;

import com.fujitsu.uji.ext.UjiCreateException;



try {

Call call = factory.createCall("MySessionBean"); // Name specification

ResponseBean response = (ResponseBean)call.invoke(dataBean,"update"); // Calling with the data to be sent and command name specified

79

...

} catch (UjiCreateException e) {

// Exception occurring in the createCall method

...

} catch (UjiRemoteException e) {

// Exception thrown during communication

// This exception occurs in the invoke method.

...

} catch (UjiTargetException e) {

// Exception occurring in the called session Bean or SOAP server application

// This exception occurs in the invoke method.

...

}

}

The processing procedure is as follows: 1. Acquire the CallFactory interface by implementing the getCallFactory method of the DispatchContext

class. 2. With a name defined in the remote map specified, call the CallFactory createCall method, and acquire the

Call interface. 3. Call the session Bean or SOAP server application by implementing the invoke method of the Call

interface. The data and command name specified in arguments of the invoke method are transferred to the called session Bean or SOAP server application.

4. The data returned by the session Bean or SOAP server application can be acquired as the return value of the invoke method.

If you want to specify only a command name without transferring data in Step 3, specify null for the data. In this event, in the called session Bean or SOAP server application, the command map is searched to find the line where no input data is specified, and the method appropriate for the specified command is then called.

If the CallFactory createCall method cannot create a Call interface, it throws UjiCreateException. The getRootCause method of UjiCreateException can be used to acquire the exception thrown because a Call interface could not be created.

The invoke method of the Call interface causes the following two exceptions:

UjiRemoteException This exception is thrown if communication with the called object fails. The getRootCause method of UjiRemoteException can be used to acquire the exception thrown because of the unsuccessful communication.

UjiTargetException This exception indicates that an exception was thrown during execution of the called session Bean or SOAP server application. Actually, UjiTargetException is not used. Instead, EJBApplicationException or UjiSOAPException, which is a subclass of UjiTargetException, is used. EJBApplicationException is used by the session Bean, and UjiSOAPException is used by the SOAP server application. The method for acquiring exceptions depends on the subclass. For details, refer to the API Reference Manual.

For an explanation of operations specific to session Beans, see Calling EJBs. For an explanation of operations specific to SOAP server applications, see Calling Web Services.

80

Chapter 7 Invoking EJBs

This section describes how to invoke EJBs from an application created using Apcoordinator. The way in which session Beans created using Apcoordinator are and the way for in which general EJBs are called are different.

7.1 Invoking Session Beans Developed Using Apcoordinator

There are two ways to call session Beans created using Apcoordinator: · Use the remote common interface: This enables you to do the following: - Unify the Web services and the ways in which they are invoked. - Make local invocations to session Beans. - Specify a data Bean conversion map for each session Bean. · Use the EJBCallFactory class: This method has the following advantages: - It can be used exclusively for invoking EJBs. - It requires no remote map. The functions below can be used to invoke a session Bean created using Apcoordinator. For more information, see Linkage between Session Bean and Client. · Session data synchronization · Data Bean conversion · Local invocation

7.1.1 Calling a Session Bean Using the Remote Common Interface

For information about how to use the remote common interface, see Remote Common Interface. This section describes the behavior specific to a session Bean when it is invoked.

Item Behavior specific to a session Bean

Invoking of the createCall method of the CallFactory interface

When a invoking of the createCall method is made, the create method of the remote interface for the session Bean is invoked and an object of the session Bean is created. The object is automatically deleted when the processing that calls the business class ends. For more information, see Automatic Deletion of Session Bean Object.

Call to the invoke method of the Call interface

When the data Bean conversion function is used, data specified in the first argument is converted and then sent to the session Bean. In addition, the result of an overwrite with the data returned from the session Bean is returned from the invoke method. For information about the data Bean conversion function and overwrite function, see Linkage between Session Bean and Client.

UjiTargetException generated by the invoke method of the Call interface

If an exception occurs during execution of the session Bean and if the exception is a type to be reported to the client, the invoke method generates EJBApplicationException, which is a subclass of UjiTargetException. You can obtain the exception that occurred in the session Bean using the getRootCause method of EJBApplicationException. For the types of exceptions to be reported to the client, see Exception Handling.

7.1.2 Invoking a Session Bean Using EJBCallFactory

Invoke a session Bean using EJBCallFactory with the following procedure: 1. Get an object of the EJBCallFactory class from the DispatchContext class. 2. Call the createUjiSessionCall method of the EJBCallFactory class, then get an object of the

UjiSessionCall class by specifying the name of the session Bean. The specified name must be retrievable by the JNDI. UjiSessionCall obtained in this step is a class for accessing the session Bean. As soon as the object of this class is created, the object of the session Bean is created in the EJB container.

3. Call the session Bean using the invoke method of the UjiSessionCall class. Specify the data Bean and command name as the arguments.

The following is a coding sample:

81

import com.fujitsu.uji.ejb.EJBCallFactory;


public void someMethod(DispatchContext context, MyDataBean dataBean) {

...

EJBCallFactory callFactory=(EJBCallFactory)context.getCallFactory(CallFactory.EJB);

UjiSessionCall call=callFactory.createUjiSessionCall("java:comp/env/ejb/someSessionBean");

ResponseBean response=(ResponseBean)call.invoke(dataBean,verb);

...

}

The invoke method of the UjiSessionCall class calls the business class of the session Bean. Either of the following is set for the object to be provided as the second argument for a business class method: · The data Bean specified in the argument of the invoke method when the data Bean conversion function is

not in use · HashMap obtained by converting the data Bean specified in the argument of the invoke method when the

data Bean conversion function is in use Either of the following values is returned to the invoke method: · The object returned by the business class of the session Bean when the data Bean conversion function is

not in use · The result of a reverse-conversion of the object returned by the business class of the session Bean when

the data Bean conversion function is in use. When the overwrite function is enabled, the data Bean specified by the invoke method is returned. The data Bean returned is overwritten with the data returned by the session Bean.

For information about the data Bean conversion function and overwrite function, see Linkage between Session Bean and Client.

If an exception occurs during execution of the session Bean and if the exception is a type to be reported to the caller, the invoke method generates com.fujitsu.uji.ejb.EJBApplicationException. You can obtain the exception that occurred in the session Bean using the getRootCause method of the exception.For the types of exceptions to be reported from a session Bean to the client, see Exception Handling.

The object of a session Bean created using the createUjiSessionCall method of EJBCallFactory is automatically deleted when the processing that calls the business class ends. For more information, see Automatic Deletion of Session Bean Object.

7.2 Invoking a General EJB

Call a general EJB as follows: · To call a session Bean that includes the create method without arguments: 1. Get a remote interface using the create method of the EJBCallFactory class. 2. Call the target method of the remote interface.

For the details of step 1, see "Coding sample for getting a remote interface from the EJBCallFactory class", described later.

· To call the following types of EJBs: - Entity Bean - Session Bean that requires arguments for the create method - Session Bean whose create method name is in createXxx format

Call the EJB with the following procedure: 1. Get a home interface using the getHome method of the EJBCallFactory class. 2. Get a remote interface using the create method of the home interface or a finder method. 3. Call the target method of the remote interface.

82

For the details of step 1, see "Coding sample for getting a home interface from the EJBCallFactory class", described later.

When you invoke an EJB using a local interface and local home interface--for example, to use an entity bean with a CMR field (container-managed relationship field)--do not use the EJBCallFactory class. Instead, in accordance with the EJB specifications, use the javax.naming.InitialContext class to obtain a local home interface.

7.2.1 Coding Sample for Getting a Remote Interface from the EJBCallFactory Class






SomeSession remote=(SomeSession)callFactory.create("java:comp/env/ejb/someSessionBean");

remote.someBusinessMethod(....);

...

}

In the sample above, SomeSession is a remote interface of a session Bean. Obtain an object of EJBCallFactory using the getCallFactory method of the DispatchContext class. The create method of EJBCallFactory creates an object of the EJB with a specified name, then returns its remote interface. A name retrieved by the JNDI is provided as an argument of the create method.

To obtain a remote interface as shown in the coding sample above, a create method without arguments must be defined in the home interface of the EJB.

The object of an EJB created using the create method of EJBCallFactory is automatically deleted when the processing that calls the business class ends. For more information, see Automatic Deletion of Session Bean Object.

7.2.2 Coding Sample for Getting a Home Interface from the EJBCallFactory Class






SomeEntityHome home=(SomeEntityHome)callFactory.getHome("java:comp/env/ejb/someSessionBean");

SomeEntity remote=home.findByPrimaryKey(...);

83

String data=remote.getData();

...

}

In the coding sample above, SomeEntityHome is a home interface of an entity Bean, and SomeEntity is a remote interface of the entity Bean. Obtain an object of EJBCallFactory using the getCallFactory method of the DispatchContext class. The getHome method of EJBCallFactory returns the home interface of the EJB with the specified name. A name retrieved by the JNDI is provided as an argument of the getHome method.

7.3 Caching a Home Interface

Once home interfaces are obtained by executing any of the methods below, they are cached and reused later. As a result, home interfaces can be mapped faster: · getHome method of the EJBCallFactory class · create method of the EJBCallFactory class · createUjiSessionCall method of the EJBCallFactory class · createCall method of the CallFactory interface The cached interfaces are stored in application classes.

7.4 Automatic Deletion of Session Bean Object

Executing any of the following methods creates an object of the session Bean in the EJB container: · create method of the EJBCallFactory class · createUjiSessionCall method of the EJBCallFactory class · createCall method of the CallFactory interface For each of the session Bean objects created using any of the methods above, the remove() method of the remote interface is called as shown in the figure below to delete the object.

7.5 EJB Session Beans Grouping Function

In an operating environment in which several EJB servers are operating, the EJB session Beans grouping function makes it possible to start the same session Beans on different servers and to handle the started Beans

84

as a group. Using EJB session grouping, you can do the following: · Continue data processing by calling the session Beans on another server if one EJB server fails. · Implement simple load distribution by switching the session Beans to be called in order.

Note that the EJB session Beans grouping function allows you to call only session Beans that have been created with Apcoordinator.

Use the Remote Common Interface to call EJBs.How session Beans are called without using EJB session Beans grouping and how Web services are called are the same on the remote common interface.

Creating EJBs for EJB session Beans grouping

Create session Beans for EJB session Beans grouping using an Apcoordinator framework.For details about how to create session Beans, see Developing an EJB Application.

Note the following points about creating session Beans invoked using EJB session Beans grouping: · Each JVM has its own application class instances of session Beans.Therefore, data stored in application

classes is not shared with session Beans on other EJB servers.Because the EJB session Beans grouping function does not always call session Beans from the same server, it is possible that data stored by the previous call to an application class is not loaded by the next call.

Calling EJBs with the EJB session Beans grouping function

To call EJBs using the EJB session Beans grouping function, create an application that calls the EJBs through the remote common interface as explained below: 1. Create a remote map, then define and name the group of the session Beans. An example of coding a

remote map is shown below. In this example, a group of three session Beans (MySessionBean1, MySessionBean2, and MySessionBean3) are named MySessionBeans.


<remoteMap





<config>

85


<defaultSoapApi>Interstage_JAXM</defaultSoapApi>

</config>



<ejbExt name="MySessionBeans" type="proxy" recoverTime="10" >

<application name="java:comp/env/ejb/MySessionBean1" />



</ejbExt>

</remoteMap>

Define a group using an ejbExt tag. Specify the name of the group in the name attribute of the ejbExt tag. In the ejbExt tag, specify the members of the group (i.e., the session Beans) using application tags. In the name attribute of each application tag, specify the name of the session Bean that can be retrieved through the JNDI.

2. Use com.fujitsu.uji.ext.CallFactory and com.fujitsu.uji.ext.Call to call a session Bean. First, execute the createCall method of the CallFactory interface to obtain a Call interface. Specify the name of the group in the argument to createCall. Next, call the invoke method of the Call interface in whose arguments the data Bean and command name are set to select and invoke the session Bean from the group defined in the remote map. The coding sample below shows how to call a session Bean from a business class:



// Specify the group and get a Call object.

Call call = factory.createCall("MySessionBeans");

// Specify the data to be sent and command name, and invoke the session Bean.

ResponseBean response = (ResponseBean)call.invoke(dataBean,"update");

...

}

The remote common interface is independent of the type of application to be invoked. With the remote common interface, you can call any type of application in a common manner. That is, you call applications by setting their names in a remote map and specifying the name of an application to be called in the CallFactory interface.To use the EJB session Beans grouping function, use the name of a session Bean group instead of the name of an application. You will need to specify the name of a group, rather than the name of an application, in an ejbExt tag in a remote map and in an argument to the createCall method of the CallFactory interface.

Setting how EJBs are to be invoked

Executing the invoke method of the Call interface selects one session Bean from the group defined in the remote map and calls it. You can specify either of the following parameters to set up how session Beans are to be

86

selected and called in the type attribute of the ejbExt tag in the remote map.

proxy Selects the session Bean with the highest priority in the group. If the EJB container fails and a session Bean becomes unavailable, another session Bean in the group replaces it. If all session Beans become unavailable, an exception occurs. Priority is assigned in the order in which the session Beans are coded in the ejbExt tag. The earlier the Bean, the higher the priority.In the remote map coding sample above, MySessionBean1 has the highest priority and is used in general. If MySessionBean1 is unavailable, MySessionBean2 is used. If both MySessionBean1 and MySessionBean2 are unavailable, MySessionBean3 is used.

round Uses session Beans in order. If the EJB container fails and a session Bean becomes unavailable, another session Bean in the group replaces it. If all session Beans become unavailable, an exception occurs. A session Bean in use is switched to another when the createCall method of the CallFactory interface is called to create a new Call object. In the remote map coding sample above, the createCall method calls one of the session Beans in the order MySessionBean1, MySessionBean2, MySessionBean3, then MySessionBean1 ... whenever it is called. If an attempt to use MySessionBean2 is made but its EJB container has failed, MySessionBean3 is used instead.

While the same Call object is in use, calling the invoke method repeatedly uses the same session Bean. However, when true has been specified in the createOnInvoke attribute described later and an EJB container failure has been detected, another session Bean is used as a replacement.

To determine whether a Bean is operating normally, an EJB container is checked when a session Bean object is created in it (when the create method of a home interface is called). When a session Bean object is to be created, the EJB container is regarded as not functioning in the following cases: · An exception occurs an attempt to get a home interface through the JNDI is made. · An exception occurs when the create method of a home interface is executed to get a remote interface. · Both the home interface and the remote interface have been obtained, but the session Bean has not been

created with Apcoordinator. If an EJB container is regarded as not functioning, the session Bean that belongs to the container is not used for a specified period of time. Specify, in minutes, the period that a session Bean is to be unused in the recoverTime attribute of the ejbExt tag. The default is 10 minutes.

You can specify when to create a new session Bean object in either of the following two ways using the createOnInvoke attribute of the ejbExt tag: · Create a session Bean object once for each Call object. The created session Bean object created continues

to be used until the Call object is discarded. An operation check is made on the EJB container only once, when invoke is initially executed after the Call object has been created. This way of creating a new session Bean object enables continued use, making it appropriate when performance is more important than precise operation checks for EJB containers. This method is the default.

· Create a session Bean object whenever the invoke method of a Call object is called. When a new session Bean is created this way, an EJB container operation check is made whenever the invoke method is executed. This method is appropriate when precise operation checks for EJB containers are important.To create session Bean objects in this manner, specify true for the createOnInvoke attribute of the ejbExt tag.Note that a session Bean object actually invoked changes every time the invoke method is executed. Calling stateful session Beans in this manner may make a difference in what is obtained when the EJB session Beans grouping function and when it is not used. For this reason, do not handle stateful session Beans this way.

Notes on setting up the execution environment

To use the EJB session Beans grouping function, note the following points about setting up the execution environment: · To use the EJB session Beans grouping function, set up application servers so that EJB clients can access

multiple EJB servers. If you use Interstage, run naming services on one server by setting up Interstage from the Interstage Management Console or with Interstage integrated commands so that servers operating EJB clients and all EJB servers refer to the naming services. For information about setting up the execution environment, see the Interstage Application Server Operator's Guide.

· You will need to assign different names (retrievable through the JNDI) to session Beans deployed on different EJB servers. To assign session Bean names when Interstage is used, rename the EJB application when you deploy the

87

EJBs.If the name of an EJB application is foo, the JNDI lookup name is "java:comp/env/ejb/foo".

7.6 Retrying EJBs

7.6.1 Overview of the EJB Retry Function

The EJB retry function automatically calls again a session Bean that has thrown an application exception. The EJB retry function can be used in applications that invoke session Beans.Use this function to call again a session Bean that has terminated with an error but might end normally next time because the cause of the error was, for example, unsuccessful access to a temporarily locked database.

Note that the EJB retry function allows you to call only session Beans that were created with Apcoordinator. Use the Remote Common Interface to call EJBs. How session Beans are called without using the EJB retry function and how Web services are called are the same on the remote common interface.

For details about how to create a session Bean using Apcoordinator, see Developing an EJB Application. For notes on creating session Beans to be called by the EJB retry function, see Notes on Creating Session Beans.

Retry timing

When an application calls a session Bean using the invoke method of the Call interface and the session Bean throws a specific application exception, Apcoordinator calls the session Bean again. In the following, application exceptions that cause retry of session Beans are called retry exceptions. Specify exception classes used as retry exceptions in a remote map.

If a session Bean throws a system exception, Apcoordinator does perform retry.Apcoordinator also does not perform retry if an exception occurs during creation of a session Bean object.

For details about application exceptions and system exceptions, see Exception Handling in Developing an EJB Application.

7.6.2 Calling EJBs Using the EJB Retry Function

To call EJBs using the EJB retry function, create an application that calls EJBs through the remote common interface as explained below: 1. Create a remote map, then define the names of session Beans to be called and define the retry

parameters for the session Beans. 2. Call the session Beans using the CallFactory interface and Call interface.

Creating a remote map

Create a remote map, then define the names of session Beans to be called and define the retry parameters for the session Beans. The remote map is an XML file that defines applications to be invoked through the Remote Common Interface. For details of the remote map, see Remote Map. This section describes how to code a remote map for the EJB retry function.

The coding sample below shows a remote map coded for use of the EJB retry function:

88


<remoteMap





<config>


</config>



<ejbExt name="MySessionBean" retryCount="3" retryInterval="150" >

<application name="java:comp/env/ejb/MySessionBean" />

<retriableException class="some.pkg.BusyException" />

<retriableException class="some.pkg.NotReadyException" />

</ejbExt>

</remoteMap>

Using an ejbExt tag, specify a session Bean to be called. Specify the name assigned to the session Bean in the name attribute of the ejbExt tag. In the ejbExt tag, code an application tag. In the name attribute of the application tag, specify the name of a session Bean that can be retrieved through the JNDI.

In addition, specify the following attribute and content parameters for retry in the ejbExt tag and retriableExcpetion tags: Maximum number of retries

Specify the maximum number of retries in the retryCount attribute of the ejbExt tag. For example, specifying 2 calls the session Bean three times which also includes the initial call. The default is 2.

Retry interval Specifies the retry interval in milliseconds in the retryInterval attribute of the ejbExt tag. The default is 100 ms.

Retry exception Using a retriableException tag, specify an application exception class to be used for retry exceptions. Specify retriableException tags in the ejbExt. Specify the exception class in the class attribute of a retriableException tag. When the session Bean is called and an application exception occurs, the session Bean is retried if the class of the exception is the same as the class specified in the class attribute or its subclass. Note that you cannot specify the following classes for retry exceptions:

· java.lang.RuntimeException and any of its subclasses · java.rmi.RemoteException and any of its subclasses · java.lang.Exception · java.lang.Error and any of its subclasses

The precision of the retry interval depends on the system being used.Some systems cannot support an interval specified at a precision of 10 ms or higher.

Calling the session Bean using the CallFactory interface and Call interface

Use com.fujitsu.uji.ext.CallFactory and com.fujitsu.uji.ext.Call to call the session Bean. These

89

interfaces are used to call applications through the Remote Common Interface. For details, see Calling with the Calling Using the CallFactory Interface and Call Interface. This section describes how to use these interfaces with the EJB retry function.

The steps for calling a session Bean with the CallFactory interface and Call interface are as follows: 1. Get the CallFactory interface from the com.fujitsu.uji.DispatchContext class. 2. Specify the name of the session Bean (which has been specified in the name attribute of the ejbExt tag)

to get the Call interface from the CallFactory interface. This step creates a session Bean object. 3. Call the invoke method of the Call interface, setting a data Bean and command name as arguments.

The session Bean is then invoked. If the session Bean throws a retry exception, the same session Bean is called again.

The coding sample below shows how to call the session Bean from a business class:



import com.fujitsu.uji.ext.Call;

import com.fujitsu.uji.ext.UjiCreateException;



...

public Object doSomething(DispatchContext context, SomeBean dataBean) {

// Get the CallFactory interface.


try {

// Specify the name of the session Bean and get the Call interface.

Call call = factory.createCall("MySessionBean");

// Specify the data to be sent and the command name, and invoke the session Bean.

ResBean response = (ResBean)call.invoke(dataBean,"update");

} catch (UjiCreateException e) {

...

} catch (UjiRemoteException e) {

...

} catch (UjiTargetException e) {

...

}

...

}

Even though the session Bean throws an exception during each retry and the maximum number of retries is reached, the invoke method throws com.fujitsu.uji.ejb.EJBApplicationException. You can get an exception that has been thrown by the session Bean using the getRootCause method of EJBApplicationException.

90

If a session Bean throws a system exception, the invoke method throws com.fujitsu.uji.ext.UjiRemoteException. The session Bean is not retried for a system exception.

Using the EJB retry function together with the EJB session Beans grouping function

The EJB retry function can operate together with the EJB session Beans grouping function.

To use the EJB retry function together with the EJB session Beans grouping function, add an ejbExt tag in the remote map as follows:


<remoteMap





<config>


</config>





<ejbExt name="MySessionBeans" type="proxy" >




<retriableException class="some.pkg.BusyException" />

<retriableException class="some.pkg.NotReadyException" />

</ejbExt>

</remoteMap>

Using an ejbExt tag, define a group of session Beans to be called with EJB session Beans grouping. Also define retry exceptions using retriableException tags in the ejbExt tag. If necessary, add the retryCount attribute (maximum number of retries) and/or retryInterval attribute (retry interval) to the ejbExt tag.

When you use the EJB retry function together with the EJB session Beans grouping function, a session Bean object is created and invoked when the invoke method of the Call interface is called in the following two phases: 1. When the invoke method is called for the first time after the Call interface is obtained, a session Bean

object is created. The EJB session Beans grouping function operates at this point. If its EJB container is regarded as not functioning, another EJB container is selected to create a session Bean object again. When a session Bean object is successfully created, phase 2 starts.

2. The session Bean object is called. The EJB retry function starts operation at this point. If the session Bean throws a retry exception, the same session Bean is called again. At this stage, if the EJB container has failed, the session Bean is not created again and UjiRemoteException occurs.

If true has been specified in the createOnInvoke attribute in the ejbExt tag in the remote map, a new

91

session Bean object is created whenever the invoke method of the Call object is called. Specifying true for the attribute always executes phase 1 whenever invoke is called.

7.6.3 Notes on Creating Session Beans

If a session Bean throws a retry exception and is to be retried, any processing that the session Bean has done before the retry exception was thrown is not canceled. Therefore, note the following points when you create session Beans called by the EJB retry function:

Notes on using transactions

When a session Bean requires transactions in its processing, roll back the transactions before a retry exception is made. Once a transaction already started by a session Bean or a transaction already started by a sequence called by a session Bean has been committed, any processing done in the transaction cannot be canceled. For this reason, do not cause a retry exception to occur within a transaction.

In addition, if a session Bean commits or rolls back a transaction, it cannot take part in the transaction that it Bean called.

Notes on using call by reference

In general, for EJB calls, arguments are called by value.Therefore, calling a session Bean using the Call interface passes a copy of the data Bean given to the invoke method to the session Bean.

However, some application servers may permit calling by reference for better performance when clients and EJBs are on the same JVM. If you enable call by reference on such an application server, an instance of the data Bean given to the invoke method of the Call interface is passed to the session Bean. That is, a copy of the data Bean is not made.

If you enable call by reference, do not change any data Bean given to an argument of a business class by processing performed by the business class. If you change such a data Bean, the modified data Bean is given to an argument of the business class during a retry.

Notes on changes to the data of business class, session class, and application class objects

Objects of classes of the types listed below are not deleted even after invocation of an associated session Bean has been completed. If changes are made to the data of such objects and then a retry exception is thrown, the data of the objects remains in its changed state when a retry invokes the session Bean. · Business class (when the init method returns true) · Session class · Application class If a problem would result because changes made to data before a retry remain in effect after the retry, make changes to business class, session class, or application class data after completion of the processing in which a retry exception could occur.

92

Chapter 8 Calling Web Services

This chapter explains how to call Web services from Apcoordinator applications. The method of calling Apcoordinator-based Web services differs from that for calling general Web services. Apcoordinator supports Interstage SOAP and Apache SOAP. For the differences between Interstage SOAP functions and Apache SOAP functions, see Using Different Types of Functions.

8.1 Calling Apcoordinator-based Web Services

The following two methods can be used to call Apcoordinator-based Web services: · Using the remote common interface: This method has the following features: - EJBs and calling methods are unified. - The size of source code is reduced by use of the remote map. · Using the SOAPCallFactory class: This method has the following features: - It is used exclusively to call SOAP services. - It does not use the remote map.

If Interstage SOAP is used, defining options enables transmission of SOAP messages conforming to SOAP1.2. For details, refer to the Interstage Application Server SOAP Service User's Guide.

8.1.1 Calling Web Services with the Remote Common Interface

For information on how to use the remote common interface, see Remote Common Interface.

8.1.2 Calling Web Services with SOAPCallFactory

Call a Web service with SOAPCallFactory by using the following procedure: 1. Get an object of the SOAPCallFactory class from the DispatchContext class. 2. Call the createUjiServiceCall method of the SOAPCallFactory class, and get the UjiServiceCall object,

with a service URL, service identifier, and API type specified in arguments. The specification of the service identifier depends on the SOAP server used by the SOAP server application to be called.

- If the SOAP server is Interstage: Specify null. - If the SOAP server is Apache SOAP: Specify the service identifier written in the deploy

information file. The service identifier is the value specified in the id attribute of the isd:service tag in the deploy information file. For more information about the deploy information file, see Setting up the SOAP Server Application Execution Environment.

3. Call a Web service by implementing the invoke method of the UiServiceCall class. A data Bean and command name must be specified in arguments at this time.

Coding examples are shown below.

Coding if the SOAP server is Interstage

import com.fujitsu.uji.soap.SOAPCallFactory;

import com.fujitsu.uji.soap.UjiServiceCall;

public void someMethod(DispatchContext context, XmlDataBean dataBean) {

...

// Getting of CallFactory

SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP);

// Getting of UjiServiceCall

93

String url = new String("http://some.host/service");

UjiServiceCall call =callFactory.createUjiServiceCall(url,null,SOAPCallFactory.INTERSTAGE_JAXM);

// Service calling

XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb);

...

}

Coding if the SOAP server is Apache SOAP




...





UjiServiceCall call = callFactory.createUjiServiceCall(url,"urn:foobar", SOAPCallFactory.APACHE);

// Service calling


...

}

8.2 Calling General Web Services

8.2.1 Calling Where the SOAP Server Is Interstage

During operation with Interstage, call a general Web service by using the following procedure: 1. In the remote map, define the URL, service identifier, and operation (method) of the service to be called. 2. Get an object of the SOAPCallFactory class from the DispatchContext class. 3. Get the javax.xml.rpc.Call object by implementing the createGeneralCall method of the SOAPCallFactory

class. 4. Specify parameter information and a return value type in javax.xml.rpc.Call, and call the general Web

service. For information about javax.xml.rpc.Call, refer to the Interstage Application Server SOAP Service User's Guide.

Example of calling a general Web service with Interstage SOAP API

94


import javax.xml.rpc.Call;


...



javax.xml.rpc.Call call = factory.createGeneralCall("myservice");

...

}

8.2.2 Calling Where the SOAP Server Is Apache

During operation with Apache, call a general Web service by using the following procedure: 1. Declare the return value type and parameter type as required by the service to be called.

Set type conversion by MappingRegistry if required. 2. Get an object of the SOAPCallFactory class from the DispatchContext class. 3. Call the getServiceCall method of the SOAPCallFactory class, and get the ServiceCall object, with the

URL, method name, service identifier, return value type, and API type of the service to be called specified in arguments.

4. Call the general Web service by implementing the invoke method of the ServiceCall class. 5. Get the return value of the invoke method. Coding examples are shown below.

Example of calling a general Web service without MappingRegistry


import com.fujitsu.uji.soap.ServiceCall; import com.fujitsu.uji.soap.Response; import com.fujitsu.uji.soap.Parameter; import com.fujitsu.uji.soap.Parameters;


...

// Return value type setting

Class[] paramTypes = new Class[]{String.class};

// Method parameter type setting

Parameters params = new Parameters();

params.add("param1", String.class, "add");



95

ServiceCall call = factory.getServiceCall("myservice");

// Service calling

Response resp = call.invoke(params);

// Getting of a return value

Parameter ret = resp.getReturnValue();

String str = (String)ret.getValue();

...

}

Example of calling a general Web service with MappingRegistry


import com.fujitsu.uji.soap.ServiceCall;

import com.fujitsu.uji.soap.Response;

import com.fujitsu.uji.soap.Parameter;

import com.fujitsu.uji.soap.Parameters;

import com.fujitsu.uji.soap.SOAPMappingRegistry_Apache;

import com.fujitsu.uji.soap.QName_Apache;

import org.apache.soap.encoding.soapenc.BeanSerializer;

import org.apache.soap.Constants;


...

// Return value type setting

Class[] paramTypes = new Class[]{String.class};

// Method parameter type setting

SomeClass someClass = new SomeClass();

Parameters params = new Parameters();

params.add("param1", String.class, "test");

params.add("param2", SomeClass.class, someClass);

// MappingRegistry setting

SOAPMappingRegistry_Apache smr = new SOAPMappingRegistry_Apache();

BeanSerializer beanSer = new BeanSerializer();

smr.mapTypes(Constants.NS_URI_SOAP_ENC,

new QName_Apache("urn:some-convert-namespace", "typename"),

SomeClass.class,

beanSer,

96

beanSer);




ServiceCall call = factory.getServiceCall("myservice");

// MappingRegistry setting

call.setMappingRegistry(smr);

// Service calling

Response resp = call.invoke(params);

// Getting of a return value

Parameter ret = resp.getReturnValue();

String str = (String)ret.getValue();

...

}

8.3 Coding of Exception Processing

This section explains the exception processing for Apcoordinator-based Web services and general Web services called with Apache SOAP. For an explanation of exception processing for general Web services called with Interstage SOAP, refer to the Interstage Application Server SOAP Service User's Guide.

If an exception occurs in a called SOAP service, UjiTargetException is thrown.

If Fault information is returned from the SOAP service, UjiSoapException that derived from UjiTargetException is thrown. If you want to process Fault information, catch UjiSoapException and code exception processing.

The following is an example of coding exception processing:





import com.fujitsu.uji.soap.UjiSoapException;

public void someMethod(DispatchContext context, XMLDataBean dataBean) {

...



97



UjiServiceCall call =callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM);

// Service calling

try {


} catch(UjiSOAPException s_e) {

// Fault information processing

Fault f = s_e.getFault();

if(f.getFaultCode().equals("XXX")) {

// Fault code processing

...

} else {

// Non-Fault code processing

...

throw s_e;

} catch(UjiTargetException t_e) {

// Processing when there is no Falut information

...

throw t_e;

} catch(UjiRemoteException r_e) {

// Processing if UjiRemoteException is thrown

...

throw r_e;

}

...

}

8.4 Using Different Types of Functions

This section explains how to use different types of functions when calling Web services. You can use the following functions when calling Web services: · Basic authentication · Proxy use · Session management · Transport use The above functions may or may not be used depending on the SOAP library used and the type of the application to be called. See the table below for an explanation.

SOAP library

Type of application to be called

Basic authentication

Proxy use

Session management

Transport use

Apcoordinator-based O O O X Interstage

General Web service Refer to the Interstage Application Server SOAP Service User's Guide.

98

Apcoordinator-based O O O O Apache

General Web service O O O O

8.4.1 Calling the Web Service for the Basic Authentication of a Web Server

This section explains the Basic authentication performed when an Apcoordinator-based Web service is called or when a general Web service is called with Apache SOAP. For an explanation of the Basic authentication performed when a general Web service is called with Interstage SOAP, refer to the Interstage Application Server SOAP Service User's Guide.

To call the Web service for the Basic authentication of a Web server, code the following immediately preceding the coding for calling a Web service: 1. Specify a user name in setUserName. 2. Specify a password in setPassword. The following is a coding example:



public void someMethod(DispatchContext context, XMLDataBean dataBean) {

...






call.setUserName("username");

call.setPassword("password");

// Service calling


...

}

8.4.2 Application Linkage through a Proxy

This section explains how to set a proxy when an Apcoordinator-based Web service is called or when a general Web service is called with Apache SOAP. For an explanation on how to set a proxy when a general Web service is called with Interstage SOAP, refer to the Interstage Application Server SOAP Service User's Guide.

There are two methods for calling a Web service through a proxy. For both methods, code the following immediately preceding the coding for calling a Web service: · Setting a normal proxy - Specify the host name and port number of the proxy in setProxy.

99

· Setting the proxy for the Basic authentication - Specify the host name, port number, user name, and password of the proxy in setProxy. Coding examples are shown below.

Example of calling a Web service when a normal proxy is set



public void someMethod(DispatchContext context, XmlDataBean dataBean) throws Exception {

...






call.setProxy("proxyaddress", port);

// Service calling


...

}

Example of calling a Web service when the proxy for the Basic authentication is set




...





UjiServiceCall call =callFactory.createUjiServiceCall(url,"urn:foobar", SOAPCallFactory.INTERSTAGE);

100

call.setProxy("proxyaddress", port, "username", "password");

// Service calling


...

}

8.4.3 Use of Session Management by a Web Service Caller

This section explains session management when an Apcoordinator-based Web service is called or when a general Web service is called with Apache SOAP. For an explanation of session management when a general Web service is called with Interstage SOAP, refer to the Interstage Application Server SOAP Service User's Guide.

To enable session management by a Web service caller, code as follows immediately preceding coding for calling a Web service: 1. Specify UjiServiceCall in a class member variable. 2. Check whether UjiServiceCall is null. If UjiServiceCall is null, call the createUjiServiceCall method of

the SOAPFactory class to get the UjiServiceCall object. 3. Set true in setMaintainSession.

An instance of the UjiServiceCall class is set so that it can store session management information. If false is set, no instance of the UjiServiceCall class can store session management information. true is set as the initial value. Therefore, if you do not want to store session management information in an instance of the UjiServiceCall class, call the Web service with false set in setMaintainSession.

The following is a coding example:




private UjiServiceCall call;

...





if(call == null) {

call=callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM);

call.setMaintainSession(true);

}

// Service calling


...

101

}

8.4.4 Use of Transport

Using an API of Apache SOAP to call a Web service enables programming with APIs of the SOAP client application provided by Apache. This section explains programming when the SOAP transport function provided by a SOAP service is used.

This function can be used only when Apache SOAP is used.

To use SOAP transport, code as follows immediately preceding coding for calling a Web service: 1. Create an instance of the SOAPHTTPConnection class. 2. Set the instance in an object of the UjiServiceCall class by implementing the setSOAPTransport method. The following is a coding example:




...





UjiServiceCall call =callFactory.createUjiServiceCall(url,"urn:foobar", SOAPCallFactory.APACHE);

// Example of getting use of transport and setting the Basic authentication

org.apache.soap.transport.http.SOAPHTTPConnection con = new org.apache.soap.transport.http.SOAPHTTPConnection();

con.setUserName("username");

con.setPassword("password");

// Setting of transport.

call.setSOAPTransport(con);

// Service calling


...

}

102

103

104

Chapter 9 Command Scripting

9.1 Overview of Command Scripting

Command scripting allows you to code a processing flow in XML, instead of coding an entire business class with Java, and to code some portions of the flow with Java.

The following is a sample of command scripting:

<?xml version="1.0" encoding="UTF-8"?>

<commandMap

xmlns="http://interstage.fujitsu.com/schemas/uji/commandMap"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/commandMap

http://interstage.fujitsu.com/schemas/uji/commandmap.xsd">

<config>


</config>



<entry bean="sample1.BodyBean" verb="add">

<specSection>

<term property="val1" op="ADD" operand="val2" target="result"/>

</specSection>

<copyValue bean="#Addition has been done." targetProperty="message"/>

<setResponseBean pane="body" verb="resmode"/>

<invoke name="setHead"/>

</entry>



<entry>



<newBean cls="sample1.BodyBean" />

<setResponseBean pane="body" verb="reqmode" />

<invoke name="setHead"/>

</entry>



<procedure name="setHead">

<copyValue bean="uji.session" property="headBean" targetBean="hBean"/>

<specSection bean="hBean" targetBean="hBean">

<term property="count" op="ADD" operand="#1" target="count"/>

</specSection>

<setResponseBean pane="head" bean="hBean"/>

</procedure>

105

</commandMap>

Command scripting has the following advantages: · Code clear processing flows. · Subdivide Java processing into detailed parts that can be easily reused. · Easily make modifications without reconstructing because of the modifications. Java, however, must be used in the following cases: · There are branches and conditions that cannot be represented in one flow. · A higher level of performance is required. Command scripting supports the following functions: · Verification of input values · EJB/SOAP invokes · General class invokes · XML-described data specification invokes · Association with individual data Bean areas · Output of logs · Definition of subroutines · Catching of exceptions

9.2 Using Command Scripting

Defining a Command Map

Code command scripting in a file with XML. Include the XML file for command scripting in the command map.The following is a coding sample that loads an XML file for command scripting "comscript.xml" from a command map:

#commandMap

+comscript.xml

XML file for Command Scripting

Create an XML file for command scripting by setting ".xml" as the extension.You can use UTF-8, ISO-8859-1, and other encodings supported by Java.

Overview of Command Scripting

Command scripting code has the following structure:

XML header

<commandMap>

<config> element

<entry> element

...repetition of <entry> elements

<procedure> element

...repetition of <procedure> elements

</commandMap>

106

config element Specifies information about the command scripting.

entry element Specifies the name of a class of an input data Bean using the Bean attribute and a command using the verb attribute to associate the input data with the command scripting that will be called. The name of the class of the Bean and command must be unique in the command map and command scripting.

procedure element Indicates a command scripting subroutine. Subroutines are valid within the file.

Entry elements and procedure elements can have processing tags coded inside them. The following table shows the processing tags that can be used. For more information, see the Reference.

Tag Description

validate Checks the maximum allowable value and type.

specSection Allows an XML-described data specification to be coded inline.

specValidate Performs processing according to an external file or XML-described data specification.

invoke Invokes a subroutine, business class, Apcoordinator-based EJB, or Web service.

invokeEJB Invokes a general EJB.

invokeObject Invokes a general class object.

setResponseBean Associates a data Bean with an area in which it is displayed.

newBean Creates a data Bean object.

copyValue Copies a value.

copyResource Copies a character string defined in a resource file.

printLog Outputs a log.

catch Allows actions to be coded for an exception. Specify processing tags inside.

An exception that occurs during execution of a command scripting is reported as com.fujitsu.uji.xscript.ScriptingException. You can set up exception handling using the handleException method of a session method or the catch tag in the command scripting.

Command scripting stores objects that indicate states of progress or results of processing in DispatchContext as command scripting data. You can access command scripting data using getScriptData of the DispatchContext class, and specify its settings using the setScriptData method of the DispatchContext class if these methods are included in the Java code. The following table provides the names of the predefined command scripting data items.

Name of command scripting data item Description

uji.current Object currently being handled. The initial value is the same as that for uji.request.

uji.request Input data Bean

uji.verb Name of the command

uji.session Session class

uji.application Application class

uji.exception Object of an exception that occurred

In addition, names that begin with "uji". have already been reserved. Data specified in uji.current when execution of a command scripting ends is used for the return value. Return values are valid for applications that return values using a business class.

107

Overview of Command Scripting Operations

The following is a command scripting coding sample with explanatory comments:

<entry bean="somepackage.EntryBean" verb="ok">

<validate property="value" type="int" minValue="0" maxValue="10" statusText="valueError" />

<invoke name="someEjb" verb="#doOk"/>

<setResponseBean pane="body" verb="resmode"/>

<catch status="valueError">

<copyValue bean="#Set a value between 0 and 10." targetProperty="message" />

<setResponseBean pane="body" verb="retry"/>

</catch>

</entry>

1. When the input data Bean is somepackage.EntryBean and the name of the command is ok, execution of this entry element starts.

2. For the input data Bean stored in uji.current, the validate tag checks the int type of property value and whether the value is within the allowable range.

3. If no error is found in the check, execution of the invoke tag starts. In the sample above, someEjb is specified as the name, doOk is specified as the command name, and the input data Bean that has been specified in uji.current is used for the default parameter.

4. The result of the invoke method is stored in uji.current. The result is then set up with display body and display mode resmode using the setResponseBean tag.

5. If an error occurs during execution of the validate tag, an exception that has status information valueError occurs. The catch element is executed when the exception is received, and it puts the character string in the message area, then sets the pane with pane mode retry.

9.3 Adding User-Defined Tags

You can add tags for command scripting using user definition.

<entry bean="sample1.BodyBean" verb="add">

<myTag param="xxx" />

...

</entry>

Creating a processing class Create a class for processing a user-defined tag by inheriting the XScriptEngine class. Use the getTagDefs method to return the name of the tag and the names of the methods to be handled. For the getTagDefs method, create DispatchContext and the Map object having attributes for their arguments. The command scripting data items allow data exchange with other tags.

public class MyTagEngine extends com.fujitsu.uji.xscript.XScriptEngine {

108

String tagDefs[][] = { { "myTag", "doMyTag" } };

public String[][] getTagDefs() {

return tagDefs;

}

public void doMyTag(DispatchContext context, Map attributes) {

String param = (String)attributes.get("param");

Object val = context.getScriptData("uji.current");

...

context.setScriptData("myTagValue", val);

}

}

Embedding a processing class Return an instance of the processing class using a factory class.

public class SampleFactory extends com.fujitsu.uji.http.HttpFactory

{

...

public XScriptEngine newXScriptEngine() {

return new MyTagEngine();

}

}

109

110

Chapter 10 XML-described Data Specifications

10.1 Overview

Overview of XML-described data specifications

In business applications, value ranges and formats are specified for data items, and the data items are checked for conformity with the specifications at runtime. In addition, default values are set for some data items and some values are transferred or converted between some data items. This type of data processing forms the bulk of a business application. XML-described data specifications make it possible to code data items in business applications in XML and to run the applications without modification. To create an XML-described data specification, you program data item processing in XML, not in Java. You create an XML-described data specification as a set of specifications for checking data Bean items (properties) and transferring data between data items. You can use XML-described data specifications for XML data Beans (com.fujitsu.uji.xml.XmlDataBean) or HashMap (java.util.HashMap) as well as for ordinary data Beans.

XML-described data specifications provide the following benefits: · You can program data checks the same that you define data specifications. That is, writing a set of data

item specifications is easier than coding a program. Using data specifications reduces mistakes in program coding and simplifies maintenance.

· You can run XML-described data specifications from files in external storage with an interpreter. If you need to change some of the data item specifications, you need only replace the related XML-described data specifications. No program modifications are needed.

· You can create user-defined methods for easy customization of functions. · You can link XML-described data specifications with other tools and devices because the coding format is

XML. For example, you can create XML-described data specifications from Excel spreadsheets. · You can use a compiler to translate XML-described data specifications to Java sources.

Overview of an XML-described data specification

1) XML-described data specification

For data items, write a set of data item specifications about the ranges for values, character string patterns, and so on in XML form. The resulting file in XML is called an XML-described data specification.You can run the XML-described data specification through an interpreter as is, or compile it into a Java source.

2) XML-described data specification compiler The XML-described data specification compiler compiles XML-described data specifications into Java classes. When you use the XML-described data specification compiler for the XML-described data specification of an application, syntax analysis is not required for the application when it runs, resulting in better performance than is possible with an

111

interpreter. 3) XML-described data specification execution

XML-described data specifications are executed. For application to data Beans, operations include checking of data items in the XML-described data specifications and data transfer between data items.

Coding sample of an XML-described data specification

The XML-described data specification coding sample shown below is a simple example of using an interpreter to check the range of a value. For details about the tags and error handling used in the sample, see the explanation following the sample.

XML-described data specification

<?xml version="1.0" encoding="iso-8859-1" ?>

<eSpec

xmlns="http://interstage.fujitsu.com/schemas/uji/espec"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec

http://interstage.fujitsu.com/schemas/uji/espec.xsd">

<config>


</config>

<specification name="sampleCheck" >

<section name="sect1" >



<verify property="sampleNumber" op="GE" operand="#0" exception="#ERR01" info="#0 or more" />

<verify property="sampleNumber" op="LE" operand="#10" exception="#ERR01" info="#0 or less" />

</section>

</specification>

</eSpec>

eSpec Indicates that the XML is an XML-described data specification.

config Provides information about the XML-described data specification.

version Indicates the version of the XML-described data specification. Specify "6.0".

specification Indicates a set of data item specifications. A set of data item specifications consists of multiple sections. In this sample, the name of the data item specifications is "sampleCheck".

section Indicates a section in data item specifications. Write data item specifications in a section.

verify Indicates data item specifications for verification. In this sample, the property sampleNumber in data Beans is checked for whether it is in the range from 0 to 10. A value outside this range generates an exception.

112

Creating a business class for the XML-described data specification

import com.fujitsu.uji.xscript.ESpecValidator;

import com.fujitsu.uji.xscript.ESpecResultException;

import com.fujitsu.uji.xscript.ESpecRuntimeException;

...

public void someMethod(DispatchContext context, SomeBean bean) throws java.io.IOException {

ESpecValidator validator = new ESpecValidator("c:¥¥espec¥¥sampleCheck.xml");

String errMsg = null;

try {

validator.validate("sampleCheck", bean);

} catch(ESpecResultException e) {

errMsg = "Error Found:" + e.getInfo();

} catch(Exception e) {

throw e;

}

...

}

import The com.fujitsu.uji.xscript package provides classes related to the XML-described data specification.

ESpecValidator ESpecValidator is a class used for execution. Create it by specifying the name of the XML-described data specification.

validate Calling the validate method of ESpecValidator executes the XML-described data specification. Set the name of a set of data item specifications and data Bean to be checked as arguments.

ESpecResultException If the check generates an error, ESpecResultException is generated.

Other exceptions If the property object could not be found or if a similar error occurred, ESpecRuntimeException is generated. A syntax error in the XML-described data specification generates ESpecException. For these exceptions, rewrite the XML-described data specification.

10.2 Creating an XML-described Data Specification

10.2.1 Coding Data Item Specifications

This section describes how to code data item specifications in an XML-described data specification.In an XML-described data specification, write data item specifications in section tags.

Coding sample of an XML-described data specification


113

<eSpec





<config>


</config>





</section>

</specification>

</eSpec>

The sample above contains two verify tags in a section tag, which designate data item specifications for the property sampleNumber.

Checking the value in the data item

To make a check on the value in the data item, use a verify tag:


property Specifies the name of a property in a data Bean.

op Specifies a relational operator for verification. You can use GT (greater than), GE (greater than or equal to), LT (less than), LE (less than or equal to), EQ (equal to), and NE (not equal to).

operand Specifies an operand. Prefix the operand with a # if it is a constant. A reserved object such as %null and %empty can be used.

exception Specifies an error code. Prefix a character string constant with a #. Specifying an exception attribute throws ESpecResultException if an error is detected.

info Provides supplementary information about the error. Prefix a character string constant with a #.

· The attributes property (property), op (relational operator), and operand (operand) form a conditional expression that compares a property with an operand within the tag. In a verify tag, write a data item specification so that the conditional expression results in true when

114

condition is satisfied. In the example above, when the value in the property sampleNumber is 0 or more, the result is true, and when the value is less than 0, the result is false.

· Operations are based on property type. For example, if you write "#0" in an operand and the property type is String, 0 is handled as a character. If the type of the property is int, the 0 is handled as a numeric value. Likewise, if you write "#true" in an operand and the value is compared with a boolean type property, the value is treated as a boolean type true.

· You can specify the value of another data item in an operand. Specify the name of a property in an operand attribute the same way that you specify a property attribute. You can also specify the name of a property in an attribute such as info or exception.

· To use a data Bean in a subdirectory, use a slash (/) in the property (for example, "xyz/abc"). Hierarchical representation can also be used for HashMap. For an XML data Bean, use XPath.

· If a character string constant is reserved in XML, use entity representation (for example, "<" -> "<"). To represent a comma (","), code it twice (",,").

Collectively checking errors in multiple data item specifications

You can use error attributes to check multiple data item specifications. Although the exception attribute generates an exception as soon as an error is detected in a check, the error attribute allows processing to continue when an error is found in a data item specification.

<verify property="sampleNumber" op="GE" operand="#0" error="#ERR01" info="#0 or more" />

error Specifies an error code. Prefix a character string constant with a #. When you use error attributes, any information about errors is stored and the XML-described data specification continues to run.

· The exception attribute throws information about an error using ESpecResultException as soon as the error is detected. However, if an error is detected in a data item specification check with an error attribute specified, information about the error is only stored; the XML-described data specification processing is not interrupted.

· If any error information has been stored after a set of data item specifications with error attributes designated in the specification tag has been completely processed, ESpecResultException is thrown. To get a list of the errors, use the getErrorInfo method of ESpecResultException as a set of ESpecResultException objects (java.util.Vector).

· If an error is detected in a data item specification with an exception attribute specified and error information stored by error attributes already exists, the information is attached to an exception object and ESpecResultException is thrown. To get the information, use the getErrorInfo method of ESpecResultException.

Checking data items using built-in methods

You can use built-in methods to support checking of data item values for string lengths, patterns, and so on.

<verify property="numberString" function="pattern([0-9]+)" op="EQ" operand="#true"

error="#ERR02" info="#Check Values" />

<verify function="errorcount" op="EQ" operand="#0"

exception="#ERR99" info="#Exception Found" />

function Specifies a method to be applied.

· The built-in methods convert the value of a data item specified in the property to a specified format

115

before the relational operator. In the sample above, the method "pattern([0-9]+)" in the first line of the property numberString is coded to check whether the value is in the range from 0 to 9, then to compare (op="EQ") the result with the operand (true).

· The following built-in methods are provided: Built-in method Description

int, long, double, boolean, String Convert the type of the value to the specified type.

stringLength Returns the length of the character string.

enum(n,m,...) Checks whether the value matches any of the enumerated values n, m, ....

pattern(re) Checks whether the value matches a regular expression.

errorcount Returns the number of errors for which information has been stored by error attributes. This built-in method ignores the values of property attributes (property attributes can be omitted).

Checking data items using user-defined methods

User-defined methods can be used to check or convert data item values. There are two types of user-defined methods: static methods and inherited methods.

<verify property="prop" function="?mypackage.MyClass.myCheck"

op="EQ" operand="#true" error="#ERR11" info="#myCheck" />

<verify property="prop1,prop2,prop3,#1" function="?localCheck" op="EQ" operand="#0"

error="#ERR12" info="#localCheck" />

function To use a user-defined method, specify the name of the method prefixed with a "?".

· To use a static user-defined method, specify it in the function attribute in the form "?package-name.class-name.method-name". Implement a user-defined method as a static method of a class.

· To use an inherited user-defined method, specify it in a function attribute in the form "?method-name". Implement an inherited user-defined method in a subclass that inherits the ESpecValidator class. Execute the validate method using an instance of the subclass that you created instead of using the ESpecValidator class.

· The value of a property specified in a property attribute is used as an argument of the user-defined method. To use multiple arguments, separate properties with a comma (","). You can use property values together with constants. If the number of arguments is not fixed in a user-defined method, handle them as Object[] type arguments.

· Any types or object can be returned from a user-defined method. The following is an example of coding a user-defined method:

package mypackage;

public class MyClass {

public static boolean myCheck(String prop) {

....

return true;

116

}

}


public class CheckClass extends ESpecValidator {

public CheckClass() {}

public int localCheck(String prop1, int prop2, String prop3, int param) {

// int localCheck(Object[] props) is also allowed.

....

return 0;

}

}

Assigning values to data items

To assign a value to a data item, use a term tag:



<term property="sample1" target="targetProp1" />



<term property="sample2" function="stringLength" op="EQ" operand="#0"

value="#none" target="targetProp2" />



<term property="sample3" op="ADD" operand="#1" target="targetProp3" />



<term property="sample4" valueFunction="?myFormat" target="targetProp4" />

property Specifies the name of a property in a data Bean.

target Specifies the name of the data Bean property to which a value is to be assigned.

value Specifies a value to be assigned if a value resulting from a conditional expression does not

117

satisfy the expression. op(relational operator)

Assigns a value to the target only when the result of the indicated operation is true. op(arithmetic operator)

Performs a calculation on the operand using the specified operator (ADD (addition), SUB (subtraction), MUL (multiplication), DIV (division), or REM [remainder]) and puts the result in target. Because the arithmetic operators do not have a value attribute, the result of a calculation is assigned.

valueFunction Sets the result of a conversion or operation by a user-defined method specified in valueFunction in target. Specify the user-defined method the same that you do for the function attribute.

· When you use a method that requires two data Beans (bean and targetBean) to call the validate method of the ESpecValidator class, the resulting data is written to the data Bean specified in targetBean. A method that requires one data Bean writes the resulting data in the data Bean.

validator.validate("spec1", bean); // Updates a data Bean specified in bean according to the contents of bean.

validator.validate("spec2", bean, targetBean); // Updates a data Bean specified in targetBean according to the contents of bean.

Temporarily saving intermediate results

You can specify intermediate variables for the property and target attributes. To specify intermediate variables, prefix variables with a "^".

<term property="sampleValue" op="ADD" operand="#1" target="^tempValue" />

<term property="^tempValue" op="DIV" operand="#4" target="targetProp" />

· Intermediate variables contain a slash ("/") indicating hierarchy.

10.2.2 Writing a Specification over Multiple Data Items

Using conditional blocks

You can use conditional blocks to provide control similar to if-statement control for data item specifications.The following coding sample performs a check when the value of "sampleProp" is 1:

<block property="sampleProp" op="EQ" operand="#1" >

<verify property="sampleNumber" op="GE" operand="#0" exception="#ERR01" info="# or more" />


</block>

118

Writing conditions Use property, function, op, and operand attributes to specify in a block tag the operations that are to be performed. The operations in the block tag are executed when the condition evaluates to true.

· The block tag does not support statements equivalent to else statements. Specify a block tag having opposite conditions.

Using decision tags

XML-described data specifications make it possible to code and check data items in decision table format.

Example of a decision table

No. Data item Value Decision

1 Flight No. 101 x

2 Flight No. 103 x

3 Flight No. 105 x

4 Flight No. 107 x

5 Reservation type Regular x

6 Reservation type

First-class seat x

7 Reservation type

Special discount x x

Condition causing an error

Discount service specified for all seats

Special discount not specified

First-class seats not specified

Special discount not specified

Structure of a decision table The left side of the table lists data items. In the decision cells, an "x" appears when the data item matches the condition stated at the bottom of the column.

To code the table above, create an XML-described data specification as follows:

<value seq="1" property="flight" op="EQ" operand="#101" />




<value seq="5" property="reservation" op="EQ" operand="#regular" />

<value seq="6" property="reservation" op="EQ" operand="#super" />

<value seq="7" property="reservation" op="EQ" operand="#discount" />

<decision exception="#ERR01" info="#Discount service specified for all seats" >

<status seq="1" require="true" />


119

</decision>

<decision exception="#ERR02" info="#Special discount not specified" >



</decision>

<decision exception="#ERR03" info="#First class seats not specified" >



</decision>

<decision exception="#ERR02" info="#Special discount not specified" >



</decision>

value Represents a data item in a decision table (a row in the sample). A seq attribute numbers the data item. Use property, function, op, and operand to code conditions.

decision Represents a restriction in a decision table (a column in the sample). To generate an error when a decision is made, use exception, error, and info attributes. To assign a value to a data item for which a decision is made, use value, valueFunction, and target.

status Specifies a condition for making a decision. seq attributes in status tags correspond to seq numbers in value tags. require attributes evaluate a data item with true/false.

· In the sample above, the value tags are evaluated in turn. For example, if Flight No. is "101", then the seq="1" data item evaluates to true. If reservation (Reservation type) is "regular", the seq="5" data item evaluates to true. The first decision tag is executed when seq="1" is true and seq="5" is true, as indicated by the status tags. In the tag, the specified exception attribute generates ESpecResultException for an exception.

· For the require attributes in status tags, specify "true" or "false" without any suffix or prefix. Although you need to type "#true" in operand attributes to specify a constant, do not put a "#" in status tag.

10.2.3 Writing Control Statements

Specifying a section to be executed in an XML-described data specification

You can control data item specification sections to be executed in XML-described data specifications.


<eSpec




120


<config>


</config>


<control>

<validate section="sect1" />

<validate section="^nextSection" />

</control>


...

<term property="#true" value="#sect2" target="^nextSection" />

</section>


...

</section>

</specification>

</eSpec>

control To control data item specification sections that are to be executed, write a control tag directly under a specification tag. Writing a control tag executes data item specification sections according to validate tags subordinate to it. If a control tag is not written, all sections of a data item specification enclosed by a specification tag are executed in the order in which they are coded.

validate Specifies a data item specification section to be executed according to a section attribute. Use he section attribute to explicitly specify the name of a section as well as to specify internal variables. To specify an internal variable, prefix the variable with "^" and set a value using a term tag. In the sample above, since "sect1" is explicitly specified in the first validate tag, data item specification section "sect1" is executed. In data item specification section "sect1", "sect2" is set for the internal variable "nextSection", and the second validate tag refers to it, enabling execution of data item specification section "sect2".

section Specifies the name of a section in a name attribute.

· To specify the name of a fixed data item specification section in the section attribute of a validate tag, do not prefix the name with a "#". To specify the name of a section as a character string in a term tag, specify it as a constant using the "#" prefix.

Executing data item specification sections for part of a data Bean

When a target data Bean has directories above or below it, you can execute data item specification sections only for data Beans in lower-level directories.


<eSpec

121





<config>


</config>


<control>

<validate section="sect1" node="subBean" targetNode="subTarget" />

<validate section="sect2" node="*detail" />

</control>


...

</section>


...

</section>

</specification>

</eSpec>

validate Includes a node attribute to specify the hierarchy of a data Bean subject to the data item specification section. In the example above, "sect1" is executed by setting Beans obtained by getSubBean() of the data Bean as Beans to be checked and Beans obtained by getSubTarget() of the target data Bean to as Beans to which data is assigned. If an asterisk is prefixed (*) to a node attribute item, the data item specification section is executed for all elements in the array of that object. In the sample above, "sect2" is executed for all elements of arrays obtained by getDetail() of the data Bean.

· When you specify an asterisk (*) for a node attribute, the target objects (objects obtained by getDetail() in the sample above) must be arrays or java.util.List.

· When you specify an asterisk (*) for a node attribute and a data item specification section that is to be executed includes an assignment, be sure to specify targetNode.

· When you specify both node and targetNode and arrays are used, you need to specify an asterisk (*) for both. In addition, both must be arrays or List. If the sizes of the arrays are different, the data item specification section is executed only for the array with the fewer elements.

Setting a return value from an XML-described data specification

Use the result attribute to specify a return value from the validate method of ESpecValidator:

<term result="#abc" />

122

result Specifies a return value for the validate method. When you specify multiple return tags, the tag processed last is valid. In the sample above, the character string "abc" is the return value.

Debugging an XML-described data specification

You can specify a debug tag in an XML-described data specification to log execution states.


<eSpec





<config>


<debug>trace</debug>

</config>


...

</specification>

</eSpec>

debug Logs the operating states of an XML-described data specification. If "snap" is specified in a debug tag, information is logged by tag. If "trace" is specified in a debug tag, detailed information such as the property values and the evaluation state of operations is logged.

· Debugging logs of XML-described data specifications are sent to the standard output. Note, however, that their destination depends on the environment.

· Debugging logs are available only for XML-described data specifications run with an interpreter. When you use the XML-described data specification compiler to convert code that includes a debug tag into a Java source, the debug tag is ignored and no log is output.

10.3 Executing an XML-described Data Specification

10.3.1 Executing an XML-described Data Specification with an Interpreter

Executing an XML-described data specification from a business class

To execute an XML-described data specification with an interpreter, code the XML-described data specification as follows:


123



import com.fujitsu.uji.xscript.ESpecException;

....

public void processOrder(DispatchContext context, OrderBean bean) throws java.lang.Exception {

ESpecValidator validator =

ESpecValidator.getInstance(getClass().getClassLoader()); // (1)

validator.setInfLoader(context.getApplicationProfile().getInfLoader()); // (2)

try {

validator.setXml("checkPrice.xml"); // (3)

validator.validate("checkValue", bean); // (4)


... // (5)


throw e; // (6)

}

...

}

(1) Create an instance of the ESpecValidator class. To call user-defined methods, specify

ClassLoader as an argument.

(2) The InfLoader specification sets the configuration files folder to the location of the XML file to be loaded. The configuration files folder is used for command maps, remote maps, and other configuration files related to Apcoordinator. For example, the configuration files folder for Web applications is the WEB-INF folder.

(3) Specify the setXml method to load the XML-described data specification file.

(4) Specify the validate method to execute the XML-described data specification. If there is another data Bean to which data has been assigned, use a method in which you can specify two data Beans.

(5) Generate ESpecResultException if an error is detected in a data item. In general, display the information about the error and prompt for data input again.

(6) For other exceptions, determine the exception handling according to the XML-described data specification or the environment in which it will be executed.

· To use an inherited user-defined method, use a constructor of a class to which the user-defined method has been added, and inherit ESpecValidator instead of ESpecValidator.getInstance(...).

· ClassLoader specified in (1) loads classes with static user-defined methods. If static user-defined methods are not used, the ClassLoader is not needed. Even though static user-defined methods are used

124

some execution arrangements (environment), ClassLoader can be omitted because the standard ClassLoader can be used. In such situations, however, if you notice a user-defined method causing an error, be sure to specify ClassLoader as an argument.

· If you specify the XML file using its full path or InputStream, you do not have to specify InfLoader in (2). If you use the full path, you can specify the XML file using a constructor instead of using the setXml method in (3).

Executing an XML-described data specification from a command script

You can call XML-described data specifications from a command script.


<commandMap

xmlns="http://interstage.fujitsu.com/schemas/uji/commandMap"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/commandMap

http://interstage.fujitsu.com/schemas/uji/commandmap.xsd">

...

<entry bean="sample.OrderBean" verb="process">

<specValidate file="checkPrice.xml" name="checkValue" />

<specSection>

<term property="val1" op="ADD" operand="val2" target="result"/>

</specSection>

...

<catch exception="ESpecResultException">

...

</catch>

</entry>

</commandMap>

· A specValidate tag in a command script executes an XML-described data specification. · You can explicitly specify a data item specification section to be executed in a specSection tag in a

command script. For the overview of command scripting, see Command Scripting. For detailed information about command scripting, refer to the Command Scripting Reference.

10.3.2 Executing XML-described Data Specifications with a Compiler

Running the compiler

The XML-described data specification compiler compiles an XML-described data specification into a Java source. The XML-described data specification compiler is provided by the com.fujitsu.uji.xscript.compiler.ESpecCompiler class. Run the XML-described data specification compiler by executing the following command:

125

xml-based-script-file-name generated-java-class-name

[-p package-name] [-comment:none] [-s base-class-name-of-generated-java-class]

Coding example

java com.fujitsu.uji.xscript.compiler.ESpecCompiler carrent.xml Carrentc -p carrent

ESpecCompiler Specifies the execution class as shown.

XML-described data specification file name Specifies an XML-described data specification file to be compiled.

Generated Java class name Specifies the name of the Java class to be generated. Do not include a package name.

Package name Specifies the name of a package for the Java class to be generated. If this parameter is omitted, a package is not generated.

-comment:none Specifies that no comments are output to the Java source being generated. If this parameter is omitted, comments are not output to the Java source.

Base class name of generated Java class Specifies a class that implements a user-defined method that inherits the ESpecValidator class for use as the inherited user-defined method. If this parameter is omitted, the ESpecValidator class is inherited directly.

· Before running the compiler, you need to specify the following modules in CLASSPATH: - uji.jar (lib in the Apcoordinator installation folder) - ujiespec.jar (lib in the Apcoordinator installation folder) - jar files provided by the XML processor (Fujitsu XML Processor and related files conforming to

SAX 2.0) · The compiled source file is output to the current folder. If necessary, add the output source to

applications. - Interstage Apworks Apdesigner can import such source files and add them to projects. - Interstage Apworks Component Designer can add such source files to projects. · Note the following restrictions on the XML-described data specification compiler: - Java naming conventions must be followed when specifications and sections are named with

identifiers. - Pay attention to any limits on the size a Java method. The XML-described data specification

compiler handles each specification section as one method. Therefore, if a section is too large, the XML-described data specification compiler may terminate normally but a Java compilation error or runtime error may occur. The recommended number of tags coded in one specification section is no more than 100.

ujiespec.bat is located in the bin folder in the folder in which the Apcoordinator development environment has been installed. Create batch files using this file as a sample.

Calling a compiled XML-described data specification

To use a compiled XML-described data specification, specify the package name and class name in the getInstance method of ESpecValidator.

126




import com.fujitsu.uji.xscript.ESpecException;

....

public void processOrder(DispatchContext context, OrderBean bean) throws java.lang.Exception {

ESpecValidator validator =

//ESpecValidator.getInstance(getClass().getClassLoader()); for the interpreter

ESpecValidator.getInstance(getClass().getClassLoader(), "mypackage.CheckPrice");

validator.setInfLoader(context.getApplicationProfile().getInfLoader());

try {

validator.setXml("checkPrice.xml");

validator.validate("checkValue", bean);


...


throw e;

}

...

}

getInstance Takes the character string argument "package-name.class-name". In the sample above, the return value from the getInstance method is an instance of the mypackage.CheckPrice class.

· In compiled classes, XML-related methods such as setInfLoader and setXml are not processed. If you always use only compiled classes, you do not need to invoke such methods.

· A compiled class generates a method named "uji+data-specification-name". In the sample above, validator.validate("checkValue", bean) can be replaced with ((CheckPrice)validator).ujiCheckValue(bean, bean). The required replacement coding format is two data Beans (targetBean). If targetBean is not required, specify the same data Bean for both.

10.3.3 Error Handling

Getting values from an exception

If an error is detected in a data item in an XML-described data specification, an ESpecResultException exception is generated to notify the associated application of the error. Specify error handling in XML-described data specifications, and obtain information about errors from applications.


127

<verify property="prop1" op="GE" operand="#0" error="#ERR01" info="#prop1" />


<verify property="prop3" op="LE" operand="#10" error="#ERR03" info="#prop3,#10" />

Business class methods

try {



ESpecResultException[] errors = new ESpecResultException[1];

Vector errVec = e.getErrorInfo(); // (1)

if(errVec == null) {

errors[0] = e; // (2)

} else {

errors = (ESpecResultException[])errVec.toArray(errors); // (3)

}

for(int i = 0; i < errors.length; i++) {

String status = errors[i].getStatusText(); // (4)

Object info = errors[i].getInfo(); // (5)

...

}

...


throw e;

}

(1) The getErrorInfo() method of this exception class has a list of the errors that were detected. If

an error attribute is not used in any of the data item specifications, the list is always null. In the coding sample above, the list is converted to an array of ESpecResultException for to standardize processing.

(2) When getErrorInfo() is null, the ESpecResultException object that it catches itself indicates the errors found in the check.

128

(3) When getErrorInfo() is not null, getErrorInfo() has a list of ESpecResultException in java.util.Vector form. In the sample above, the toArray method converts the list into an array.

(4) The getStatusText() method returns a character string specified in the error or exception attribute. In this sample, the string is "ERR01".

(5) The getInfo() method returns the value specified in the info attribute. If an error is detected in the fist line in the XML-described data specification sample, "prop1" is returned. If an error is detected in line 3, "prop3" and "10" are returned.

Editing messages using a resource file

You can edit messages about errors by linking to functions in a resource file.




<verify property="prop3" op="LE" operand="#10" error="#ERR03" info="#prop3,#10" />

Resource file code


<ujiResource





<config>


</config>

<text id="#ERR01">Specify 0 or higher to data item '{0}'</text>

<text id="#ERR02">You specified an incorrect value to data item '{0}'</text>

<text id="#ERR03">Specify {1} or less to data item '{0}'</text>

</ujiResource>

Business class method

try {

129

130



ESpecResultException[] errors = new ESpecResultException[1];

Vector errVec = e.getErrorInfo();

if(errVec == null) {

errors[0] = e;

} else {

errors = (ESpecResultException[])errVec.toArray(errors);

}

for(int i = 0; i < errors.length; i++) {

String message = UjiResource.getMessage(context, errors[i]);

...

}

...


throw e;

}

getMessage Use the getMessage method of the UjiResource class to create messages from the character strings in the resource file and ESpecResultException. The value of the error or exception attribute is used as the resource id, and info is used to edit messages. In the coding sample above, the messages "Specify 0 or more for data item 'prop1'" and "Specify 10 or less for data item 'prop3'" are generated.

Chapter 11 Setting Up the Execution Environment

The execution environment to be set up for applications created with Apcoordinator depends on the type of application. For details, click on the following links: · Web application: Setting Up a Web Application Execution Environment · EJB session Bean: Setting Up a Session Bean Execution Environment · SOAP server application: Setting Up a SOAP Server Application Execution Environment This chapter covers the following topics, which are common to all types of applications created with Apcoordinator: · Apcoordinator JAR files required for applications · Software required for execution · Initialization parameters

11.1 Apcoordinator JAR Files Required for Applications

The following tablelists required JAR files by application type:

Application type Required JAR file

Web application uji.jar

EJB session Bean uji.jar, ujiejb.jar

SOAP server application uji.jar, ujisoap.jar

In addition, the following functions require an additional JAR file:

Function Required JAR file

Database linkage (Web application) ujidb.jar

Access to groupware (J Internet Communication Kit) jick.jar

Linkage to Struts JAR files provided by Struts

Client applications require an additional JAR file to implement the following functions:

Application type Client application requiring an additional JAR file Required JAR file

Web application Applet ujiapplet.jar

EJB session Bean EJB client that does not use the Apcoordinator framework ujiejbcl.jar

Apcoordinator installs JAR files in the directories listed in the table below. The table lists only directories mentioned in this User's Guide.

Default installation directory File

Windows Solaris OE Linux

uji.jar, ujidb.jar, jick.jar (*1) C:¥Interstage¥APC¥lib¥ /opt/FJSVwebc/lib/

ujiapplet.jar C:¥Interstage¥APC¥redist¥applet¥ /opt/FJSVwebc/redist/applet/

ujiejb.jar, ujisoap.jar C:¥Interstage¥APC¥lib¥ /opt/FJSVbcco/lib/

ujiejbcl.jar C:¥Interstage¥APC¥redist¥ejb¥ /opt/FJSVbcco/redist/ejb/

ujiespec.jar (*2) C:¥Interstage¥APC¥lib¥ -

JAR files provided by Struts

C:¥Interstage¥APC¥struts¥lib /opt/FJSVapcst/struts/

*1 Each of the following products supplies jick.jar from the Interstage Apworks server runtime that is in the product. By default, jick.jar is installed in C:¥Interstage¥APW¥JICK (Windows) or /opt/FJSVawjic (Solaris OE).

131

· Interstage Application Server Plus (Windows or Solaris OE) · Interstage Application Server (Windows or Solaris OE)

The following products install jick.jar in C:¥Interstage¥APW¥JICK by default: · Interstage Application Server Plus Developer · Interstage Apworks

*2 ujiespec.jar is available only in the development environment packages.

The following files are re-distributable, and can be distributed to client environments: · ujiapplet.jar · ujiejbcl.jar

11.2 Software Required for Execution

The following software is required to use database linkage, XML linkage, Web service call, or the back-end linkage service, or to create SOAP server applications:

Function to be used or application to be

created Software required Remarks

Database linkage - JDBC driver for the database server being used

In general, the JDBC driver is provided by the database server vendor.

- Fujitsu XML Processor (xmlpro.jar, xmlschema.jar, xmltrans.jar)

Included in this product. XML linkage Any

of: - Apache Xerces - Apache Xalan -

Application server provided by any of the following products: - Interstage Application Server Plus - Interstage Application Server Plus Developer - Interstage Application Server Enterprise Edition - Interstage Apworks

- Any of:

- Apache SOAP -

- Fujitsu XML Processor (xmlpro.jar, xmlschema.jar, xmltrans.jar)

Included in this product.(*1)

Web service call SOAP server application

Any of:

- Apache Xerces - Apache Xalan -

(*1) Modify the isj2ee.properties file to enable Fujitsu XML Processor to be used.

11.3 Initialization Parameters(update)

Initialization parameters can be specified in Apcoordinator applications. Some parameters are specific to a certain type of application.

Application type Parameter Description

Web EJB SOAP

factory Specifies the name of a factory class.

logLevel Specifies the log output level. Specify this parameter to change the level.

132


Web EJB SOAP

commandMap

Specifies the name of a command map file. Specify this parameter to change the name. (*1)

pageMap

Specifies the name of a page map file. Specify this parameter to change the name. Use a path from the application's context root.

- -

uji.remoteMap Specifies the name of a remote map file. Specify this parameter to change the name. (*1)

uji.convMap

Specifies the name of a data Bean conversion map file. Specify this parameter to change the name. (*1)

uji.database.connection.minpoolsize Specifies the number of pool connections in database linkage. - -

uji.database.connection.maxpoolsize

Specifies the number of connections allowed in database linkage. Any connection request with a value exceeding the number causes an error.

- -

uji.defaultEncoding

Explicitly specifies an encoding for data to be sent. The specification applies to all forms. The uji.encoding request parameter has priority if it is coded in the form. Specifying "none" skips encoding.

- -

uji.doublegetdisabled

The double processing prevention function which HttpControlStateProfile class offers is used, and when preventing double processing to the request by the GET method, this parameter is used.Specify the HTTP response code set as the response in following to be the value of uji.doublegetdisabled in 3 figures of numbers.

When it corresponds to following either by the case where received Request B and double processing is detected during processing in Request A.

· When the

- -

133


Web EJB SOAP destination of A is JSP and the destination of B is servlet

· When the destination of A is servlet and the destination of B is JSP

In the above-mentioned case, a screen cannot be returned if double processing prevention is confirmed to a GET method.In this case, the HTTP response code specified to be uji.doublegetdisabled is set as a response. When uji.doublegetdisabled is omitted, the double processing prevention function by HttpControlStateProfile class is available only in the POST method request.

uji.model.viewName

Specifies whether to fix the initial number used for the uji.model.* and uji.pageid request parameters to 1. These request parameters are automatically created in forms by Webcoordinator, and the initial number is set for the asterisk in uji.model.* and as the value of uji.pageid. If uji.model.viewName is not specified, the initial number is unpredictable. Specifying true fixes the initial number to 1.

- -

uji.emptyCellRuled

Specifies whether to put " " in cells automatically to display their internal frames if the cells coded with uji:tableView tags and uji:treeView tags contain only a null character string or white space. Specifying false does not pad such cells with " ". Omitting this parameter or specifying false for this parameter embeds " " in such cells.

- -

uji.backupResponseBeans Specifies the size of the stack for backing up response beans. - -

134


Web EJB SOAP If the number of backups exceeds the number specified by this parameter, backups exceeding the limit are deleted. The default value is 5.

uji.infoPath

Specifies the configuration files folder. Specify this parameter to change the folder. The configuration files folder holds command maps, remote maps, and data Bean conversion maps.

-

uji.informSystemException

Specifies whether to notify the client of a system exception in an EJB session Bean. If client is specified, the client is notified of a system exception. If the parameter is omitted, the EJB container notified of a system exception.

- -

uji.getProperty.escape

Specifies the operation of uji:getProperty tags when there is no escape attribute. Specify false, true, or full. This parameter is not case-sensitive. false

Outputs the values of properties as is.

true Converts '"', '&', '<', and '>' to '"', '&', '<', and '>' respectively, and outputs them.

full Converts ' ' to ' ' in addition to the conversions done with the truespecification and outputs them.

The default value is false.

- -

uji.servlet.defaultErrorPage

When UjiServlet is being used and an exception occurs, defines the error page displayed in place of the servlet container error pages until the dispatch tag is processed .

- -

uji.includeSessionScopeBean

Specifies whether to set session scope for a Bean specified by setResposeBean. Specify false if the Bean is not to be set to session scope (request scope is in effect). Note, however, that if you specify false, the Bean indicates session scope when true is specified in the third parameter of the setResponseBean(String,

- -

135


Web EJB SOAP Object, boolean) method.

uji.frameSyncTimeout

Specifies in seconds the length of time of the wait for completion of display when true is specified in the sync attribute of a uji:frame tag. Specify 0 if a timeout is not to be set.

- -

uji.handleException.wrap

Specifies how a reported exception is thrown. If true is specified, the parent class of the business class (GenericHandler) and the handleException method of the session class (HttpControlStateProfile) wraps a reported exception with HandlerException and throws it. As the default, a reported exception is thrown as is.

uji.resource

Specifies the name of a file to be used as a resource file. Do not put an extension.; the extension ".xml" is used. The default is "ujiresource".

uji.ejb.homeCacheSize

Specifies the size of the cache for EJB home interfaces. Specify the number of home interfaces that can be cached. If 0 is specified, home interfaces are not cached. The default is 100.

uji.handlerConfig

Specifies the name of a file to be used as a business class configuration file. The default is handlerconfig.xml.

uji.logConf

Specifies the absolute path of a log definition file. When omitted, logConf.xml in a setting folder is referred to.

-

uji.log.enablecache

Specifies whether the cache of an application log (standard log) is used. When omitted, a default is "true" and the cache is enabled.

uji.* Reserved by Apcoordinator. - - -

*1 How to specify the name of the file depends on the application type.

· In a Web application, use the path from the application's context root. The context root is the folder in which the application is stored on the server. If the application is included in a WAR file, use the path from the WAR file root.

· The paths of EJB session Beans and SOAP server applications can be specified in two ways. If the specified file name begins with a slash (/), the path is regarded as a path from the folder tht is the root of the package hierarchy. If the specified file name does not begin with a slash (/), the path is regarded as a relative path from the configuration files folder.

As the delimiter in paths, use a slash (/).

136

For information about how to set initialization parameters, see the following pages: · Web application: Setting Up a Web Application Execution Environment · EJB session Bean: Setting Session Bean Initialization Parameters · SOAP server application: Developing a Service Class

137

138

Part 3 Development of Web Application

139

140

Chapter 12 Overview

12.1 What Is Webcoordinator?

Webcoordinator extends the JavaServer Pages (JSP) to provide a Web application framework. Moreover, it also provides Web application execution functions according to this framework. The framework of Webcoordinator contains the Apcoordinator core which is a framework common to Apcoordinator.

Partitioning an Application Using the Webcoordinator Framework

The Webcoordinator framework partitions an application into three elements:

Input-output page A page specified using the JSP. It corresponds to a partitioned screen instead of the overall screen.

Data Bean Sends and receives data between a screen and logic.

Business class Specifies the business logic.

Webcoordinator can link these elements while keeping them independent. This link can promote componentization of the application and improve the application maintainability.

Unified JSP Interface (UJI)

To invoke functions of Webcoordinator,use a JSP extension tag called a UJI tag in JSP files.The UJI tag is a extension tag to use Unified JSP Interface (UJI) provided by Webcoordinator.The UJI tag simplifies descriptions required to invoke functions.

141

There are the following kind of UJI tags. · Tags to control the behavior of an application · Tags to construct a screen to be displayed on a Web browser

Functions Provided by Webcoordinator

Webcoordinator provides the following functions:

Execution control function Webcoordinator executes a developed application according to the Webcoordinator framework. Webcoordinator links the input-output page, data Bean, and business class elements to execute this function.

Screen part tags Webcoordinator provides screen part tags such as the table, tree, and list. These parts expand data repetition to the screen.

Client scripts When specifying JavaScript in the application, Webcoordinator unifies the specification.

Component tag The appearance of a HTML screen can be set up or description can be simplified. There are 23 sorts of tags and it is classified into three groups of a Field tag, a Collection tag, and a Layout Tag.

Application program interface (API) Webcoordinator provides an API to control the fragmented Webcoordinator functions.

12.2 Webcoordinator Features

The Webcoordinator framework has the features described below.

Supporting Componentization

Business applications often use regular items.

142

Webcoordinator has the following functions to support componentization of these formatted items in input-output pages:

Dynamically links screens at execution. Webcoordinator dynamically links multiple input-output pages at execution. Thanks to this dynamic linking, changing an input-output page does not affect other input-output pages.

An application can be developed using grouped data. The same data need not be stored in each screen. The same data Bean and business class is used.

An application that includes data and logic can be parted. Webcoordinator parts an application that includes the input-output page, data Bean, and business class elements. This componentization facilitates the processing of the system that uses the parts.

Provides screen part tags that support a repetitive structure. Screen part tags support three repetitive structures: table, tree, and list. These screen parts facilitate componentization of an application because scripts need not be specified on the screen.

Parts of various grain sizes can be created. Webcoordinator can create parts of various grain sizes (function sizes) regardless of the screen size and the existence of logic for parts.

Improving Maintainability

Webcoordinator has the following features to improve maintainability:

Separates the screen and business logic. Webcoordinator separates the screen and business class. Because these are loosely linked through the data Bean, the screen and business logic can be changed without affecting each other.

Enables data-oriented installation. Webcoordinator data Beans not only send and receive data between the screen and business class, but also manage data. When data is to be added, retrieval using a data Bean name can determine the affected range.

Supports componentization. Parting can gather the same processing to a position. This feature is useful for improving the maintainability.

External relationship definition functions. Webcoordinator uses external relationship definition files to determine input-output page and method names. Rewriting the relationship definition files can replace the input-output pages and methods.

143

144

Chapter 13 Webcoordinator Application Framework

13.1 Webcoordinator Operations

When a Web application receives an HTTP request from the Web browser of a client, it returns processing results as HTML data. A servlet runs a Java application to create the HTML data. JSP coding produces the screen content of web pages where the servlet is generated so that the JSP engine can output the HTML data.

Webcoordinator converts a received HTTP request into a data Bean. Apcoordinator core calls a business class and passes the data Bean to it. The business class processes the data Bean and sets the processing results as another data Bean that is then passed to Webcoordinator. Webcoordinator configures a screen from input-output pages corresponding to the data Bean that has been set with the results, and sends it as HTML data to the relevant client.

The above process is repeated. With regard to only application screen transitions, the following is assumed:

Input on a screen can be received as a data Bean. A business class receives the data Bean as input, and outputs another data Bean. The output data Bean is converted into a screen by combining input-output pages, and the data input process is repeated.

145

13.2 Webcoordinator Application Design

This section describes the concept of Webcoordinator application design.Webcoordinator has no specific item for function design or screen transition design. At this point, the following must be defined:

Input-output items on each screen

Transition from each screen (button names)

Processing outline Clicking a button on a screen starts server processing. The name of a button is hereafter called a command.

Next is designing for componentization. Design for componentization as follows: 1) Grouping data

Webcoordinator represents a single screen input-output item as a data Bean. Determine the data Bean class name and the type and name of each such item (Bean properties). In the simplest case, a screen is assumed to consist of one data Bean. Similar data groups can be used on multiple screens. An example is an inquiry screen and registration screen that use the same data. The difference between these two screens is whether data can be input on the screen.The screens use the same data Beans. The screens must be differentiated by setting the display mode. The display mode has a character string that specifies which screen is selected for a data Bean that corresponds to multiple screens. You can specify any character string that you want for the display mode.

2) Splitting a screen The header and other display areas are often specified independently of processing content. On a split screen, data Beans are separated into these display areas. Specify names for the display areas.An example of display areas is shown below.

head

body

foot

<- Displays the title and login name

<- Processing body

<- Displays the status Data Bean items in the display areas are assigned to individual data Beans according to how the screen is split.Java keywords and JSP defined words (application, out, etc.) cannot be used for display area names. For information about JSP defined words, refer to the books on JSP or Apworks Help.

146

3) Setting the area of parts Of the areas in the processing body (body in the above example), the area name must be specified for the areas used as common parts. When designing the application, items classified as common parts must be created as data Beans for common parts and the data Bean that corresponds to the processing body must be created so as to have a property whose type is the same as that of the data Bean for one of the common parts.

4) Considering repetitive parts Webcoordinator screen part tags can be used for screen parts containing a table, tree, or list. To use these tags, an interface that matches a Webcoordinator API is required. Replace a data Bean item with a class having such an interface.

5) Setting a business class The transmitting button on a screen is associated with a business class. Data input on the screen is passed as a data Bean to an application. In a server application, the transmitting button name is recognized as a command. Set the names of the corresponding business class and method of each data Bean and command.

6) Collecting design information Collect design information. Set JSP file names, business class names, and method names. An example is shown below. XX Registration screen

Screen configuration

Area name Data Bean Display mode JSP name

head HeadBean - head.jsp

body SomeDataBean entry someentry.jsp

body_date DateBean input dateIn.jsp

foot FootBean normal foot.jsp

Buttons

Data Bean Command

(Button name)

Business class Method name

Transition destination

SomeDataBean check SomeDataHandler check XX Check

SomeDataBean ok SomeDataHandler exec XX Main Contents of SomeDataBean

Property name Type name Remarks

name String Name

phone String Telephone number

address String Address

An application can be created based on this design data. Information on how to create an application is given below.

Since a JSP is converted to Java before it is executed, the JSP size is subject to Java restrictions on method size. Java has the following restrictions on method size:

· Code size restriction: The size of a compiled method must be equal to or less than 64 kilobytes.

· Branch range restriction: A branch can be created before and after a compiled method within a maximum range of 32 kilobytes.

If a JSP is large and converting it to Java does not satisfy the above restrictions, an error may occur during execution.

147

For practical development, operation, and maintenance, the recommended maximum size of one JSP file is 200 lines (including 50 UJI tags).

If a JSP is too large, the size of the JSP file can be reduced by dividing the JSP and using the uji:include tag for it.

13.3 Webcoordinator Application Files

This section outlines the files created for a Webcoordinator application. For details about the files, see Appendix A.1.

Control page

The control page is a JSP file that receives HTTP requests and starts Webcoordinator.

main.jsp

Data Bean

A data Bean is a JavaBeans class object that indicates the data transferred between a screen and logic.

HeadBean.java

BodyBean.java

Input-output page

An input-output page is a JSP file that sets the data input to and output from a screen.

header.jsp

request.jsp

response.jsp

Business class

A business class is a Java class of business logic.

SampleHandler.java

Relationship definition files

Relationship definition files can be used to create a command map that specifies the correspondence of business class methods and a page map that specifies which screen is displayed.

commands.map

pages.map Subsequent sections explain the flow of basic input-output processing.See Overview of Apcoordinator Operations for information on debugging an Apcoordinator application or to get a deeper understanding of frameworks.

13.3.1 Flow of Display Processing

This section uses the example given in Appendix A.1 to describe the flow of display processing for a Webcoordinator application. When the application is started with main.jsp specified as the control page, Webcoordinator is started from the uji:dispatch tag. Webcoordinator refers to the following specification in the command map file,commands.map, to determine which method is called first:

;=sample.SampleHandler.startup

As specified above, the startup method of the SampleHandler class is called. To display the application, the following process is required for the business class methods:

148

Set display data in the data Bean.

In the setVerb method in the data Bean, specify the display mode.

In the setResponseBean method of the DispatchContext class, set each data Bean having display data for a display area. Processing of the following is shown in Sample:


BodyBean dataBean = new BodyBean();

dataBean.setVerb("reqmode");

context.setResponseBean("body", dataBean);

setHead(context);

}

private HeadBean headBean;

private void setHead(DispatchContext context) {

if(headBean == null) {

headBean = new HeadBean();

headBean.setLoginTime(new java.util.Date());

}

headBean.setCount(headBean.getCount() + 1);


}

In the above example, BodyBean is created and associated with the body area. In the setHead method, which creates HeadBean, loginTime and count are specified and associated with the head area.When processing of the above is completed, uji:dispatch tag processing is terminated and the control page is redisplayed.At this time, the follow settings are defined:

Area name Data Bean class Display mode Contents of data Bean

head HeadBean None count and loginTime are specified.

body BodyBean reqmode Default value

After control returns to the control page, main.jsp, Webcoordinator is restarted with the uji:include tag specified.

<uji:include pane="head" />

The specified area name is pane="head". Webcoordinator searches for head setting information. In this example, HeadBean is specified.Next, Webcoordinator refers to the page map file, pages.map, to determine which input-output page is displayed. In the above setting information, the data Bean associated with head is a data Bean of the HeadBean class, and it has no display mode specified. The page map contains a row that matches this data. The input-output page name is header.jsp.

sample.HeadBean;=header.jsp

As a result of the above, header.jsp is displayed in this area. Similarly, in the other uji:include tag, request.jsp is displayed with BodyBean as the body area and reqmode as the display mode.For details about coding the page map, refer to the UJI Tag Reference.

149

The contents of header.jsp are described below.

<uji:useBean id="head" cls="sample.HeadBean" request="true" /> The execution count is <uji:getProperty bean="head" property="count" /> .

The uji:useBean tag is a declaration that enables use of HeadBean associated with the head area indicated by variable name "head" on the JSP. Webcoordinator keeps the request="true" specification until the next request is issued.Following the above declaration, variable name "head" and property name "count" are specified in the uji:getProperty tag. This specification enables the information defined in "count" to be displayed. Similarly, loginTime is also displayed.

BodyBean associated with the body area is declared as variable name "body" on the JSP in request.jsp. It is not used as a JSP variable, but Webcoordinator keeps the request="true" specification for BodyBean until the next request is issued.

13.3.2 Flow of Input Processing

This section uses the example given in Appendix A.1 to describe the flow of input processing for a Webcoordinator application.After the [Addition] transmitting button is pressed on the request.jsp form, an HTTP request having the following parameter is sent to the server:

uji.verbs="add,sub" uji.id="body" val1="4" val2="6" add="addition"

"action" in the FORM tag is omitted. The request is sent to main.jsp, which is used as the basis for controlling this screen display.main.jsp receives this request and passes it to Webcoordinator, using the uji:dispatch tag. In the request, uji.verbs specifies a list of button names that can be implemented as commands. In this example, "add" and "sub" can be specified from this form. "add" is added to the request as a command. uji.id indicates the name of an area having data. When the application is displayed, BodyBean is specified for the body area. BodyBean is used. val1 and val2 are normal input items. The setVal1 and setVal2 methods of BodyBean receive them. Webcoordinator selects one of the following data types and automatically converts the values of the input items to the selected type: String, Boolean, byte, char, int, long, float, double, BigDecimal, and BigInteger. If the item values cannot be converted automatically, the default value (null or zero) is specified.

Next, Webcoordinator refers to the command map file, commands.map, to determine the appropriate business class.

sample.BodyBean;add=sample.SampleHandler.add

The input data Bean is BodyBean, and the command is "add". Therefore, SampleHandler.add is obtained as the method name from the command map. Accordingly, the SampleHandler class is loaded or reused, and the add method is called.For details about the command map, see Command Map.

The input data Bean and DispatchContext, which provides access to Webcoordinator, are passed to the add method parameter.

public void add(DispatchContext context, BodyBean dataBean) {

....

}

During the initial start of the application, there is no input for items on the form. Therefore, no HTTP request parameter is specified. Transfer to a data Bean is skipped and the command map is referenced in such cases. Null rows in the command map are searched in order to find the data Bean name and command, and SampleHandler.startup is called.

150

13.3.3 Nesting uji:include Tags

To split the screen into display areas, uji:include can be nested. An example is shown below.

In this example, names are specified for the paste area, data Beans are specified for each area, and a business class is used for dynamic screen transitions of display areas.

Though data Beans can be null, this one must be specified. Specify uji:dispatch only once on the control page. Do not specify it on the second or subsequent pages.

If uji:include is combined with a screen part, it can be implemented with no area name specified. Screen Part Tags contains a description of how to do this.

151

152

Chapter 14 Programming Using the UJI Tags

14.1 Overview of the UJI Tags

An UJI tag is a JSP extension tag provided by Apcoordinator.You can invoke functions of Apcoordinator by specifing UJI tags in a JSP.

There are the following groups of UJI tags. · Tags to control the behavior of an application · Tags to construct a screen to be displayed on a Web browser This chapter describes tags to construct a screen.For information on tags used to control an application,see the following. · Basic tags: Webcoordinator Application Files · Tags used for session management: Advanced Session Management There are the following kind of tags used to construct a screen for Web browsers.

Screen part tags Screen part tags provide a function to support the dynamic screen structure according to the number of data repetitions or the data status.

Client script tag Client script tags generate JavaScript that is processed on a Web browser.

Component tag Component tags enables easy creation of a screen. These tags can be divided into the following groups.

· Field tags create input items. · Component tags represent a collection of data such as selection items and tables. · Layout tags enable easy positioning of items.

Window control tag, Frame control tag A window control tag supports development of an application using sub windows or frames.

The rest of this chapter describes tags mentioned above.

14.2 Screen Part Tags

14.2.1 Overview of the Screen Part Tags

The Webcoordinator screen part tags provide a function to support the dynamic screen structure according to the number of data repetitions or the data status. They also support screen parting by grouping data and input-output pages.Appendix A.2 shows an example of an application that uses screen part tags. The Webcoordinator screen part tags include the following:

Table Creates a two-dimensional table.

Tree Displays tree-structured data while indenting it.

List Simple repetition.

Condition Selects display information according to the conditions.

Composite Bean References each data Bean when there is a data Bean repetition.

Detailed descriptions for parts or HTML can be provided in the screen part tag.When simply creating tables or selection items, they can easily be written by using the component tag.

Before using a screen part tag, prepare a data Bean that installs the interface determined for each part. The

153

input-output pages specify the format for each repetitive structure and condition using a tag called the "renderer".The screen part tag asks the data Bean about the data, selects the corresponding renderer, and transfers the content to the screen.For example, to reference table data, a data Bean is used to create a property that installs the TableModel interface. The uji:table tag references the table data through this interface.

uji:table tag does the following: 1) Obtains the TableModel interface from the uji:table tag attribute.When the summary property of the data Bean associated with "body" returns TableModel, the uji:table tag specifies the following. This is specified by summary.jsp in the following example.

<uji:table bean="body" property="summary">

The SummaryModel class installs TableModel.

public class SummaryModel implements com.fujitsu.uji.model.table.TableModel {

The summary property of the ModelBean class returns the SummaryModel class.

protected SummaryModel summary;

public SummaryModel getSummary() {

return summary;

}

2) The uji:table tag asks the TableModel interface for the table size (rows and columns).The SummayModel class installs the getColumnCount and getRowCount methods for the size.

public int getColumnCount() {

return 6;

}

public int getRowCount() {

return dm.getDataCount() + 1;

}

3) The uji:table tag searches for the renderer of the overall table. The renderer of the overall table is the uji:tableRenderer tag with type="table" specified.If the uji:tableRenderer tag is found, the uji:table tag outputs the content of that tag. If the uji:tableRenderer tag is not found, the uji:table tag outputs the default pattern.summary.jsp specifies the following:

<uji:tableRenderer type="table" >

<TABLE border="2" width="100%"><uji:children/></TABLE>

</uji:tableRenderer>

154

4) If the output information has the uji:children tag, the uji:table tag processes the low-order renderers.For a table, the uji:table tag processes the caption renderer (type="caption") then processes the row renderer (type="row") once for each row.In the example, the row renderer is omitted. The default processing is as follows:

<tr><uji:children/></tr>

5) If the row renderer has the uji:children tag, the uji:table tag processes the low-order cell (type="column"). 6) The row and cell renderers can be selected by specifying the data attributes (cls) from multiple renderers.summary.jsp specifies the following:

<uji:tableRenderer type="column" cls="header" >

<TH bgcolor="#EEFFEE"><uji:value/></TH>


<uji:tableRenderer type="column" cls="editable" >

<TD><INPUT name="<uji:name/>" value="<uji:value/>"></TD>


The data attribute (cls) is an optional character string obtained from the getRowClass and getColumnClass of TableModel interfaces.It is specified in the SummayModel class.

public java.lang.String getColumnClass(int row, int col) {

if(row == 0)

return "header";

else if(col == 5)

return "editable";

return null;

}

In the example, renderers without the class specified are omitted. The default renderer is used for a cell with null specified in the class.

<td><uji:value/></td>

7) If the uji:value tag is contained in the cell renderer, the cell data is output to the tag. The uji:name tag generates a name to write back the information input by the INPUT tag to the data Bean.

Webcoordinator determines the data status on the business logic or data Bean side to specify only the display change on the screen.

14.2.2 Various Screen Part Tags

This section introduces various screen parts.See the UJI Tag Reference for details of the screen part tags.

155

Table

Screen part that generates a two-dimensional table.

The data Bean has a property whose type is a class that installs the com.fujitsu.uji.model.table.TableModel interface.The table has the following data structure:

Tree

Screen part that displays a tree structure while indenting it.

The Data Bean has a property whose type is a class that installs the com.fujitsu.uji.model.tree.TreeModel or com.fujitsu.uji.model.tree.TreeNode interface. The TreeNode interface must be installed in the data of each node. The overall TreeMode1 interface is an object. If the TreeNode interface can be installed in the data of each node, TreeNode is convenient. Otherwise, TreeMode is convenient. The tree has the following data structure:

156

A node can be created for an optional layer. A node having no child in the data is called a leaf. The indent is called only for indenting as required.A character or line can be specified for column indention. For an explanation on how to specify it, refer to the tag reference (uji:treeRenderer tag).

List

Screen part that processes various lists.

A list can be used singly or in combination with the SELECT tag or other composite Bean screen parts to enable dynamic screen configurations.The data Bean has a property whose type is a class that installs the com.fujitsu.uji.model.list.ListModel interface.The list has the following data structure:

Condition

The condition screen part is used to change the display content according to the condition.The following example displays the color of the item according to the condition:

<uji:switch bean="body" property="status" >

<uji:case cls="error" >

<FONT color="red" ><uji:getProperty property="value" /></FONT>

</uji:case>

<uji:case cls="warning" >

<FONT color="yellow" ><uji:getProperty property="value" /></FONT>

</uji:case>

<uji:case>

157

/></FONT>

</uji:case>

</uji:switch>

No special interface is required to use the condition screen part. A specified property is converted into a character string using the toString method, and this value is compared with the class character string specified in "cls". The content of the matched uji:case tag is output.

Composite Bean

The composite Bean operates the content when the data Bean property type is a class of the user-defined data Bean.Particularly, when the data Bean is repeated, the composite Bean is used to reference the content of the data Bean.

<uji:composite>

<uji:compositeRenderer>

<TR>

<TD rowspan="2"><uji:getProperty property="slipNo" /></TD>

<TD><uji:getProperty property="orderDate" /></TD>

<TD><uji:getProperty property="productCode" /></TD>

<TD><uji:getProperty property="productCount" /></TD>

<TD colspan="2"><uji:getProperty property="customerRegion" /></TD>

<TD><input name="<uji:compositeName property='deliveryDate' />"

value="<uji:getProperty property='deliveryDate' />" ></TD>

</TR>

<TR>

<TD colspan="3"><uji:getProperty property="productName" /></TD>

<TD><uji:getProperty property="branch" /></TD>

<TD><uji:getProperty property="customerName" /></TD>

<TD><uji:getProperty property="customerPhone" /></TD>

</TR>

</uji:compositeRenderer>

</uji:composite>

In the uji:compositeRenderer tag, the uji:compositeName tag is used to specify the name that reflects the input content on the data Bean.

14.2.3 Nesting the Screen Part Tags

The table cell, tree node and leaf, and list element can return the data Bean as an item value. Another screen part tag can be applied to this data Bean to nest the screen part tags.The details screen in the example in Appendix A.2 receives the list data Bean using the composite Bean.This method enables the following representations:

158

Representation of data in a deep layer, for example, a list in a table.

Representation of the data Bean repetition. When nesting a screen part tag, the low-order screen part tag can be used as another input-output page.In this case, specify uji:include without the attribute in the renderer of the high-order screen part tag. With this specification, the page map can be referenced by using the data Bean passed from the high-order screen part without using the area name to enable the include operation.All of the low-order input-output page to be included must be enclosed with the uji:includedBody tag.An example of use is given below.

Page to include another page

<uji:list bean="body", property="listData" >

<uji:listRenderer type="element">

<uji:include />

</uji:listRenderer>

</uji:list>

Page to be included

<%@ page contentType="text/html; charset=iso-8859-1" %>

<%@ taglib uri="uji-taglib" prefix="uji" %>

<uji:includedBody>

<uji:composite>


....


</uji:composite>

</uji:includedBody>

In this example, uji:include is used in the list screen part. The input-output page specified in the page map is included according to the list item data Bean and display mode.The included page is enclosed with the uji:includedBody tag to enable use of the list item data Bean. Specify screen items on this page by inheriting the data Bean using uji:composite or uji:getProperty.

14.3 Client Script

14.3.1 Overview of the Client Script

The Webcoordinator client script function generates a JavaScript to be executed on the browser.An example is given below. This example checks the input items to determine which is minimum or maximum when the input item input loses the focus. If an error is detected, an error message is displayed on the status bar.

<uji:form method="post" name="someform">

Input item:

<uji:input name="someinput">

159

<uji:validate event="blur" type="int" minInclusive="10" maxInclusive="20" >

window.status="Use an integer between 10 and 20 to specify the input item.";

target.focus();

</uji:validate>

</uji:input>

....

</uji:form>

Through the use of the client script function, JavaScript for any action can be written directly.A simple input check can be written easily by using the component tag.

Note the following when using the client script or JavaScript:

JavaScript may fail to operate depending on the browser type. In JavaScript, the language specification is not systemized; browsers have different functions and an incompatibility may occur at version upgrading. In the browser setup, JavaScript may be inhibited. An application must be designed so that it can operate even when JavaScript does not operate.

Do not specify the client script or JavaScript using a repetitive item. When JavaScript is specified, the amount of data transmitted from the server to the client is increased. Particularly, when JavaScript is used in a repetitive item, it is sent repeatedly according to the repetition count. This adds a load to JavaScript. In some cases, JavaScript may fail to operate due to the JSP size restriction.

JSP size restriction The JSP screen is a servlet and is expanded to the _jspService method. The upper bound of the Java method size is 64 KB after compilation. If the size exceeds this limit, JavaScript cannot be executed.

Do not include the business logic level determination. Even when JavaScript performs check processing, the server logic must recheck by taking the environments in which JavaScript does not operate into consideration. When JavaScript performs the business logic level determination, the business logic is held by both the server and JavaScript, which reduces maintainability. JavaScript is specified on each screen, which scatters the business logic locations.

Do not make program codes which depend on HTML code patterns generated by UJI tags With the upgrade of Apcoordinator, some changes have been made to HTML code patterns generated by UJI tags because function extension and optimization.Therefore, JavaScript codes which depend on HTML code patterns generated by UJI tags may fail when a future version of Apcoordinator is used.For example, a JavaScript code "elements[index]", which is used to refer input items,will not work if UJI tags of a future version add HTML INPUT tags,because the addition causes change of an index of INPUT tags referred by the JavaScript code.

Referring input created with component tags For details on writing JavaScript codes which refer input items created with component tags,see "Using JavaScript to Reference Input Items Created with Component Tags" in "Tips".

Because of the above, use the client script or JavaScript under the following conditions:

160

Use only for simply checking uninput characters and the character type. Use only for performing checks having unnecessary logic.

Use only for when the client check is effective. Use only when the client check is effective, for example, when checking an item in which an error is liable to occur.

Use the Webcoordinator client script. Use the client script to minimize the JavaScript specification.

14.3.2 How to Use the Client Script

This section describes how to use the client script. See the UJI reference for details of the tags. 1) Replace the INPUT and FORM tags with the Webcoordinator tags.

Replace the INPUT tag to be specified as the client script and the FORM tag that includes the INPUT tag with the uji:input and uji:form tags.When the jsp:getProperty tag is used in the INPUT tag, rewrite it as follows:

before : <INPUT name="someinput" value="<uji:getProperty name='body' property='prop' />" >

after : <uji:input name="someinput" bean="body" property="prop" ></uji:input>

The extension tags and JSP tags cannot be specified in the attribute of the extension tag together with jsp:getProperty.

Specify the form name in the uji:form tag.

before : <FORM method="post"> .... </FORM>

afer : <uji:form method="post" name="someform"> .... </uji:form>

2) Specify the uji:validate or uji:action tag. Specify the uji:validate or uji:action tag for the content of the uji:input tag. The uji:validate tag provides various preinstalled check functions.The uji:action tag optionally specifies the check content.Multiple check items can be specified in an item.

<uji:input name="someinput">

<uji:validate event="blur" type="int" minInclusive="10" maxInclusive="20" >

window.status="Use an integer between 10 and 20 to specify the input item.";

target.focus();

</uji:validate>

<uji:action event="..submit">

161

if(target.value == 15) {

window.status="In this case, 15 cannot be specified.";

target.focus();

return false;

}

</uji:action>

</uji:input>

Specify the check timing in the event attribute. Specify the HTML built-in events by separating with commas. "submit" and "reset" are form events. Therefore, specify them as follows: "..submit", "..reset".The following events are often used:

Event name Description

blur The INPUT item lost the focus.

submit The form send button was pressed.

reset The form reset button was pressed. 3) Specify the error processing JavaScript.

In the uji:validate and uji:action tags, the input object can be referenced by the variable name "target". Use this variable to specify the JavaScript.

14.3.3 User-Defined Checking

The uji:validate tag can call the user definition check function.Specify the uji:validate tag as shown below. In this example, the user definition check "mycheck" is used.

<uji:validate event="blur" custom="mycheck" >

Error processing

</uji:validate>

The custom attribute cannot be used simultaneously with other validate tag attributes, for example, "type" and "length". Java creates a countermeasure. Do the following to create the countermeasure: 1) Creating an extension class

Create the class that inherited the ValidateScriptGenerator class.Create a method having the same name as the user definition check ("mycheck" in this example).Return the content of the script to be generated in this method.The character string must be specified in the format of "if(...) {" or "...; if(...) {" in the JavaScript if statement.The check target items can be referenced using the variable target.An example is given below.

package somepackage;

public class MyScriptGenerator extends com.fujitsu.uji.script.ValidateScriptGenerator

{

public String mycheck() {

return "if(target.value.length != 8) {";

}

162

}

2) Creating an extension class in the factory class. Implement the ValidateScriptGeneratorFactory interface in the user factory class. See Section 3.1 for details of how to create a factory class.Use the newValidateScriptGenerator method to install the class created in step 1) to be returned.An example is given below.

package somepackage;

import com.fujitsu.uji.script.ValidateScriptGenerator

public class MyFactory extends com.fujitsu.uji.GenericFactory

implements com.fujitsu.uji.script.ValidateScriptGeneratorFactory

{

public ValidateScriptGenerator newValidateScriptGenerator() {

return new MyScriptGenerator();

}

}

Before using the extension class, the uji:dispatch tag must be executed at least once.

To change the default JavaScript generation pattern, override the method required for the extension class. For example, "length" is installed as shown below. When these methods are overridden, the output pattern can be changed.

// Processing required before the if statement

public String uji_length_pre(String length) {

return null;

}

// Judgment statement in the if statement

public String uji_length(String length) {

return "target.value.length != " + length;

}

14.4 Programming Using Component Tags

14.4.1 Overview of Component Tags

Component tags facilitate creation of HTML pages. These tags can be divided into three groups: field tags, collection tags, and layout tags.

163

Style sheets and JavaScript are coded in component tags.Style sheets or JavaScript support may not be enabled, depending on the functional level of the browser.For example, this is indicated by the following symbol:

Be sure to enable these items in Netscape Communicator/Navigator 4.x.

Field tags

Field tags are a group of tags that represent input items.

Field tags have the following features:

Attributes of appearance, such as color, size, fonts, and borderlines, can be defined.

The format of numeric items can be defined.

The upper and lower limits of numeric items can be defined. JavaScript enables checking from the browser.

Check boxes can easily be used by specifying the uji:checkbox tag.

The uji:anchor tag facilitates use of anchors for sending forms. The following field tags are provided:

Tag name Function uji:fieldString String input field

uji:fieldLong Integer input field uji:fieldDouble Real number input field uji:fieldBigInteger Decimal integer input field

uji:fieldBigDecimal Decimal fraction input field uji:fieldDate Date/time input field

uji:fieldTextArea Multiline text input field uji:checkBox Check box

uji:radioButton Radio button uji:pushButton Button

uji:anchor Anchor uji:label Label

Collection tags

Collection tags are a group of tags that represent a collection of data such as selection items and tables.

Collection tags have the following features:

Selection items and tables can easily be created.

Attributes of appearance such as the color and size of selection items and tables can be defined. The following collection tags are provided:

Tag name Function

uji:comboBox Selection items in a combo box uji:listBox Selection items in a list box

164

Tag name Function uji:buttonList Group of buttons

uji:recordView Group of input items in a record uji:tableView Table

uji:treeView Tree table

Layout tags

Layout tags are a group of tags that facilitate the positioning of items.

Layout tags have the following features:

Items can be easily arranged on a screen.

The uji:tabbedLayout tag enables switching of the layout of display areas The following layout tags are provided:

Tag name Function

uji:borderLayout Layout that arranges display areas horizontally and vertically

uji:gridLayout Layout that aligns items on a grid

uji:tabbedLayout Layout that can be switched by pressing the tab key This function cannot be used in Netscape 4.x.

Specifying names for colors

The uji:colorMap tag can be used to name colors.Using the created color names enables centralized management of screen colors.

<uji:colorMap name="myForeground" value="rgb(0,240,240)" />

<uji:fieldString bean="body" property="strData"

foreground="myForeground" />

14.4.2 Using Field Tags

Field tags can be used either in combination with corresponding item classes or by themselves.

Using field tags in combination with corresponding item classes

Each field tag has a corresponding item class.For example, the FieldString class corresponds to the

165

uji:fieldString tag. Define this item class as a property in a data Bean.

package sample;

import com.fujitsu.uji.compo.*;

public class BodyBean extends com.fujitsu.uji.DataBean

{

protected FieldString strData = new FieldString();

public FieldString getStrData() {

return strData;

}

...

}

Code a tag on a JSP by associating it with a data Bean property.

<FORM>

<uji:fieldString bean="body" property="strData" />

...

</FORM>

When a form is sent, data entered for an input item is stored in an item class. Data stored in the item class is displayed on a related screen. If data to be displayed includes '"', '&', '<', or '>', the character is converted to '"', '&', '<', or '>', respectively.

The uji:label tag has no corresponding item class. Objects used in screen parts can be inherited by combining field tags and screen part tags.

Using field tags only

If field tags are used by themselves, general data types such as String can be used in data Beans instead of item classes.

package sample;


{

protected String strData;

public String getStrData() {

return strData;

166

}

public void setStrData(String strData) {

this.strData = strData;

}

...

}

JSP definitions are the same as those for item classes.

<FORM>

<uji:fieldString bean="body" property="strData" />

...

</FORM>

When a form is sent, data entered for an input item is stored in a property specified by a property attribute. The value of the property is displayed on a related screen.If the value includes '"', '&', '<', or '>', the character is converted to '"', '&', '<', or '>', respectively.

The uji:pushButton tag and uji:label tag correspond to no item.There is no need to specify any property of a data Bean or tag.

<FORM>

<uji:pushButton name="OK" />

...

</FORM>

Types of data that can be used in data Beans instead of item classes are String, Boolean, byte, char, int, long, float, double, BigDecimal, and BigInteger. These data types can be specified in the uji:fieldDate tag.If data of any of the types is entered on a form, Webcoordinator determines the type and automatically converts the data. If the data cannot be converted automatically, an initial value (null, zero) is set in a data Bean.

Specifying a field color and size

Specify a color and size in attributes of the field tag. Color and size specifications are not supported in Netscape 4.x.

<FORM>

<uji:fieldString bean="body" property="strData"

width="120" height="40" background="yellow" foreground="blue"

borderWidth="3" fontSize="12pt" />

...

167

</FORM>

Some settings, such as character colors, can be changed by defining properties of item classes.Item class specifications take precedence over tag attributes.

dataBean.getStrData().setForeground("red");

Specifying a numeric value format

The format of numeric value items can be specified.

<FORM>

<uji:fieldLong bean="body" property="longData"

outputFormat="¥¥#,##0" />

...

</FORM>

Input data of a general type is automatically converted.For example, in the integer field, strings such as "-1234" and "$2,000" are automatically converted. For data entered in a special format, a conversion method must be created, such as by inheriting it from an item class.

package sample;

import java.text.*;


public class MyFieldDate extends FieldDate {

// Converts the input string, original, into a general format.

public String parse(String original) {

try {

SimpleDateFormat formatter = new SimpleDateFormat("yyMMdd");

return formatter.parse(text).toString();


return "0000/01/01"; // Error value

}

}

}

168

Checking the range of input values

Specifying the upper and lower limits of numeric values in an item class facilitates definition of a range check.

... Before display

dataBean.getLongData().setMinimumValue(0);

dataBean.getLongData().setMaximumValue(100);

... After display

if(dataBean.getLongData().getErrorCode() != FieldLong.NO_ERROR) {

... Error

}

In combination with the uji:form tag, JavaScript code for checking a range can be generated automatically.If an error occurs during a range check before data is sent, a message is displayed in the browser.

<uji:form>

<uji:fieldLong bean="body" property="longData"

minimumValue="0" maximumValue="100" />

...

</uji:form>

14.4.3 Using Collection Tags

Use a collection tag by combining it with the corresponding item class.

Collection tag types

The following collection tags are provided:

uji:comboBox Specify a selection on a pull-down menu.

uji:listBox Select a selection item from a list.

uji:buttonList Select a button to specify a selection.

169

uji:recordView Input item with a label

uji:tableView Item in a table

uji:treeView Displays the first row of a table as a tree.

Basic method of using collection tags

An explanation of the use of collection tags is given below, using the uji:comboBox tag as an example:

170

Create an item class as a property in a data Bean.In this example that uses the uji:comboBox tag, use the ComboBox class in the data Bean.

package sample;



{

protected ComboBox comboData = new ComboBox();

public ComboBox getComboData() {

return comboData;

}

...

}

Add list data to the item class.

... Processing before display

ComboBox cb = dataBean.getComboData();

cb.add("red");

cb.add("blue");

cb.add("green");

...

Using a resource file enables the following to be defined in an external XML file: selection items specified in item classes of combo boxes, list boxes, and button lists. For details, see Resource Files.

Write the uji:comboBox tag on a JSP.

<FORM>

<uji:comboBox bean="body" property="comboData" />

...

</FORM>

When a form is sent, the selection status of a selection item is stored in an item class. When a JSP is displayed, list data added to the item class is displayed as selection items. If the list data includes '"', '&', '<', or '>', the character is converted to '"', '&', '<' or '>', respectively.

171

Color and size can be defined in tag attributes or item class properties.The contents that can be defined depend on the tag.

Color and size definitions are not supported in Netscape 4.x.

<FORM>

<uji:comboBox bean="body" property="comboData"

width="100" background="yellow" fontSize="12pt" />

...

</FORM>

Using uji:tableView

Use the uji:tableView tag as follows:

Setting data Create a TableView class as a property in a data Bean.

package sample;



{

protected TableView tableView = new TableView();

public TableView getTableView() {

return tableView;

}

...

}

Add data lines to the TableView class.

...

TableView table = dataBean.getTableView();

table.addRow(new Object[] { "apple", "300", "1" } ); // Data on line 1

table.addRow(new Object[] { "orange", "50", "2" } ); // Data on line 2

...

Write the uji:tableView tag on a JSP.Specify the table size and cell color in tag attributes.

172

<FORM>

<uji:tableView bean="body" property="tableView"

width="400" background="yellow" />

</FORM>

Creating a header row A header row can be added to tables.

...


table.setHeader(new Object[] { "product-name", "price", "quantity" } );

...

Cells in the header row can be set up as buttons or links by specifying certain tag attributes on JSPs.When such a button is clicked, the command coded after "verb:" ("action" in the example shown below) is executed.

<FORM>


header="verb:action" />

</FORM>

To set up a cell as a link, specify a command following "link:". Only specific columns in the header can be set up as buttons or links.Only the cells in the columns for which "verb:" or "link:" is specified become buttons or links. As shown in the example, a different command can be assigned to each column.

<FORM>


header="title;verb:action1;link:action2" />

</FORM>

Any column of a data line can also be set up as a button or link. In the example, the third column becomes a button.

<FORM>

173


dataCellType="data;data;button:action" />

</FORM>

Creating a character string field Specific columns of a data line can be set up as character string fields by specifying tag attributes.In the example, the second and third columns of the data line become character string fields.

<FORM>


dataEditable="false;true;true" />

</FORM>

Creating radio buttons and check boxes Specific columns of a data line can be set up as radio buttons or check boxes by specifying tag attributes.In the example, the second and third columns become a radio button and check box, respectively.

<FORM>


dataCellType="data;radio;check" />

</FORM>

Specifying column color and size In tag attributes, specify the color and size of the header row and data lines.

<FORM>


headerBackground="gray"

dataFontWeight="bold;normal;normal" />

</FORM>

Some settings such as character color can be specified for individual cells by using the CellAttribute class.Contents specified using the CellAttribute class take precedence over tag attributes.

...

CellAttribute attr = new CellAttribute();

attr.setBackground("red");

174


table.setAttributeAt(attr, 0, 0);

...

Concatenating cells Tag attributes can be used to concatenate cells for display.

<FORM>


multiRow="1,2;1;1$2" />

</FORM>

Specifying the numeric value format of cells An object that implements the CellModel interface can be defined as a cell value.In such cases, the value returned by getValue() of the object that implements CellModel is displayed in the cell. For example, if the following class is provided, numeric values can be displayed after formatting them, such as with "1,500" specified:

package sample;


import java.text.*;

public class NumberFormatCell implements CellModel {

int number;

DecimalFormat formatter = new DecimalFormat("#,##0");

public NumberFormatCell(int number) {

this.number = number;

}

public Object getValue() {

return formatter.format((long)number);

}

public void setValue(Object value) {

try {

// Input of #,##0

number = formatter.parse((String)value).intValue();


try {

175

// Input of ###0

number = Integer.parseInt((String)value);

} catch(Exception e2) {

// Unknown input

}

}

}

}

Specify the created class by using the addRow method of the TableView class.

...


table.addRow(new Object[] { "apple", new NumberFormatCell(1500), "5" } );

table.addRow(new Object[] { "orange", new NumberFormatCell(50), "2" } );

...

Dividing a table by a specified number of lines for display A specified number of lines of a table can be displayed. The table portions displayed can be switched by using scroll buttons such as "Forward" and "Backward".For this purpose, use the ScrollTableView class instead of the TableView class.

package sample;



{

protected ScrollTableView tableView = new ScrollTableView();

public ScrollTableView getTableView() {

return tableView;

}

...

}

To assign a data Bean having ScrollTableView to the area, specify true in the third argument of the setResponseBean method.

176


BodyBean bean = new BodyBean();

....

context.setResponseBean("body",bean,true);

}

Specify the number of display lines by using either the pageSize attribute of the uji:tableView tag or the setPageSize method of the ScrollTableView method. If both are specified, the specification of the ScrollTableView class takes precedence.

<FORM>

<uji:tableView bean="body" property="tableView" pageSize="10" />

</FORM>

To set the scroll button, use the scrollButton attribute of the uji:tableView tag or the uji:pushButton tag. Use the scrollButton attribute to facilitate definition of buttons.In this example, use tags as follows:

· Specify the scrollButton attribute of the uji:tableView tag to specify the position and type of buttons displayed. For the specification, refer to the UJI Tag Reference.

· Add "uji.showback" in the verbs attribute of the uji:form tag or in the uji.verbs request parameter that is sent from a form.

In the following example, the [Forward] and [Backward] buttons are set at the bottom right of a table:

<FORM method="post">

<input type="hidden" name="uji.verbs" value="uji.showback, ....">


pageSize="10" scrollButton="right" />

</FORM>

Use the uji:pushButton tag to specify in detail the position and shape of a button.In this example, use tags as follows:

· Specify the tableName attributes of the uji:tableView tag to add a name to a table. This name is used to specify the table to which to add scroll buttons.

· Use the uji:pushButton tag to create buttons. Specify the following attributes: - type: Specify "scrollTable". - table: Specify the name of the table subject to scrolling. In other words, the name is that

specified in the tableName attribute of the uji:tableView tag. - scroll: Specify one of the following four scrolling operations:

Specification Explanation

forward Advances to the next portion.

backward Returns to the previous portion.

last Advances to the end.

first Returns to the top.

177

· Add "uji.showback" in the uji.verbs request parameter that is sent from a form or in the verbs attribute of the uji:form tag.

A coding example is shown below.


<input type="hidden" name="uji.verbs" value="uji.showback, ....">

...

<uji:tableView bean="body" property="table"

pageSize="10" tableName="employee" />

<uji:pushButton type="scrollTable" label="backward"

table="employee" scroll="backward"/>

<uji:pushButton type="scrollTable" label="forward"

table="employee" scroll="forward"/>

...

</FORM>

In order for scroll buttons to switch the portion displayed, a JSP on a server is executed each time that a scroll button is pressed.Therefore, the application operations performed when scroll buttons are pressed are the same as those performed when an ordinary submit button is pressed except that no business class is called. In other words, the following processes are performed:

· If checking of input items is enabled by using client script tags or component tags, this check is initiated when a scroll button is pressed.

· If checking of validity of the requests is enabled, checking of validity is performed. · Data input to a form is stored in a data Bean. · A JSP is executed.

The following precautions must be observed to use a split screen display: · No split screen display can be used if a XML data Bean is specified in the bean attribute of the

uji:tableView tag. For split screen display of table data stored using XML, add a com.fujitsu.uji.xml.XmlScrollTableView type property in a data Bean, define the XML data of the table in XmlScrollTableView, and specify the added property in the bean and property attributes.

· No split screen display can be used when a request is received with a servlet instead of with a JSP.

Using uji:treeView

The uji:treeView tag is used in almost the same way as the uji:tableView tag.The differences between use of the tags are listed below.

Setting data Create a TreeView class as a property in a data Bean.

package sample;



{

protected TreeView treeView = new TreeView();

public TreeView getTreeView() {

178

return treeView;

}

...

}

Add data lines to the TreeView class.

...

TreeNodeRow root = new TreeNodeRow(new Object[] { "root" });

TreeNodeRow child1 = new TreeNodeRow(new Object[] { "child1" });



root.addChild(child1);



TreeNodeRow grandchild11 = new TreeNodeRow(new Object[] { "grandchild1" });

TreeNodeRow grandchild12 = new TreeNodeRow(new Object[] { "grandchild2" });

child1.addChild(grandchild11);

child1.addChild(grandchild12);

TreeView tree = dataBean.getTreeView();

tree.setRoot(root);

...

Write the uji:treeView tag on a JSP.

<FORM>

<uji:treeView bean="body" property="treeView" />

</FORM>

Defining icons An icon indicating an indent and node icons can be specified in tag attributes.

179

<FORM>

<uji:treeView bean="body" property="treeView"

openIcon="open.jpg"

closeIcon="close.jpg"

leafIcon="leaf.jpg"

indentIcon="child.jpg;lastchild.jpg;hasmorechild.jgp;nomorechild.jpg" />

</FORM>

An icon can be specified for each node by using the TreeNodeRow class. The contents of the TreeNodeRow class take precedence over tag attributes.

...

TreeView tree = dataBean.getTreeView();

TreeNodeRow root = (TreeNodeRow)tree.getRoot();

root.setIcon("special.jpg");

...

14.4.4 Using Layout Tags

The contents of layout tags determine the screen layout. There is no corresponding item class.

uji:borderLayout

This tag defines the position of a display area, horizontally and vertically.

The uji:borderLayout tag identifies the top, bottom, left side, right side, and center of the screen by the names "north", "south", "west", "east", and "center", respectively. Specify these area names with the uji:borderLayoutRenderer tag.

<uji:borderLayout>

<uji:borderLayoutRenderer place="north">

... Define HTML coding as being at the top of the screen.

180

</uji:borderLayoutRenderer>

<uji:borderLayoutRenderer place="west">

... Define HTML coding as being on the left side of the screen.


<uji:borderLayoutRenderer place="center">

... Define HTML coding as being in the center of the screen.


<uji:borderLayout>

uji:gridLayout

Divide the screen into grids, and lay out items by specifying grid coordinates.

uji:gridLayout automatically creates grid coordinates according to the internal uji:gridLayoutRenderer tag.Specify the horizontal grid spacing in the columnWidth attribute. Use the uji:gridLayoutRenderer tag to specify grid coordinates and the number of grids used.If grid coordinates are omitted, each item is positioned following the previous item.If gridWidth="remainder" is coded, grid lines are used for layout items to the ends of the lines.

<uji:gridLayout columnWidth="50;100;100" >

<uji:gridLayoutRenderer gridX="1" gridY="0" gridWidth="2" >

... Define HTML coding to be located according to the grid coordinates.

</uji:gridLayoutRenderer>

<uji:gridLayoutRenderer gridWidth="remainder" >



<uji:gridLayoutRenderer gridX="0" gridY="1" >



<uji:gridLayout>

181

uji:tabbedLayout

Create display areas that can be switched by pressing the tab key. This function is not supported in Netscape 4.x.

uji:tabbedLayout switches areas by using JavaScript and style sheets.Specify each area with the uji:tabbedLayoutRenderer tag.

<uji:tabbedLayout height="400" >

<uji:tabbedLayoutRenderer title="common" >

... Write HTML coding for common use.

</uji:tabbedLayoutRenderer>

<uji:tabbedLayoutRenderer title="specific" >

... Write HTML coding for use in specific cases.

</uji:tabbedLayoutRenderer>

<uji:tabbedLayout>

14.4.5 Using External Attributes

Component tags shown in "the list of UJI tags supporting external attributes"can receive data of an input itemusing a property of a common Java data type, such as String.In this case,attributes of an input item such as color and size can be defined using external attributes.

How to use external attributes

To use external attributes, use the com.fujitsu.uji.AttributeDataBean class instead of the DataBean class.

package sample;

public class BodyBean extends com.fujitsu.uji.AttributeDataBean

{

protected String strData;

182

public String getStrData() {

return strData;

}

public void setStrData(String value) {

strData = value;

}

}

Specify attributes using the setAttribute method of the AttributeDataBean class.Parameters of the method are a property name, an attribute name, and an attribute value.

dataBean.setAttribute("strData", TagAttributeNames.FOREGROUND, "red");

The name and value of external attributes are the same as those of attributes specified by UJI tags and item classes.For example, external attributes supported by the uji:fieldString tagare the same asattributes supported by the FieldString class and the FieldStringModel interface.Attributes which correspond to "get" methods and "is" methods of an interface of an item classcan be used as external attributes.The name of external attributes is defined as a constant of the com.fujitsu.uji.compo.TagAttributeNames class.

In the above example,the AttributeDataBean class is used as a data Bean.Any class can be used instead of the AttributeDataBean class if the data Bean class implements the com.fujitsu.uji.BeanAttributeAccess interface.

Specifying selection items using external attributes

UJI tags which display selections, such as uji:comboBox, uji:listBox, and uji:buttonList,support external attributes.To receive a selected item,create a data Bean which has a property to store the selected item.The type of the property is String.If multiple selection is allowed, the type of the property is String[].When a form submitted,the value of a selected selection itemis set to the property.An example of a data Bean is shown below.

package sample;


public class BodyBean extends com.fujitsu.uji.AttributeDataBean

{

protected String comboData;

183

public String getComboData() {

return comboData;

}

public void setComboData(String value) {

comboData = value;

}

}

To define selection items,set them to an external attribute "values" of type java.util.Map.The key of the Map is the value of a selection item,and the value of the Map is a display character string of the selection item.To define the order of selection items, use the com.fujitsu.uji.util.SequencedMap class. To define an attribute value such as color, and so on, for each selection item,use an array of String as the value of the external attribute.

import java.util.*;

import com.fujitsu.uji.util.*;


....

// Set the value

dataBean.setComboData("SYD");

// Set selection items

Map map = new SequencedMap();

map.put("SYD", "Sydney");

map.put("FRA", "Frankfurt");

dataBean.setAttribute("comboData", TagAttributeNames.VALUES, map);

// Set color of selection items

String[] colors = new String[]{"blue","green"};

dataBean.setAttribute("comboData", TagAttributeNames.COLORAT, colors);

Using a list and a table

When the AttributeDataBean is used,an array can be used instead of the com.fujitsu.uji.model.list.ListModel interface and the com.fujitsu.uji.model.TableModel interfacefor the uji:list tag and the uji:table tag.

The name of external attributes which can be used for uji:list and uji:table is defined as a constant of the ListModel interface and the TableModel interface, respectively.

184

The list of UJI tags supporting external attributes

Tag An item class and an interface used by the tag

Type of the value

External attributes supported by the tag (*1)

uji:fieldString FieldString FieldStringModel String

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, editable, enabled, plain, visible, infoText, maxByteLength, maxLength, fullField, indispensableField, enableChars, enableCharType, uppercase

uji:fieldLong FieldLong FieldLongModel2

long String

uji:fieldBigInteger FieldBigInteger FieldBigIntegerModel2

BigInteger String

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, editable, enabled, plain, visible, infoText, maxByteLength, maxLength, fullField, indispensableField, enableChars, maximumValue, minimumValue

uji:fieldDouble FieldDouble FieldDoubleModel2

double String

uji:fieldBigDecimal FieldDecimal FieldDecimalModel2

BigDecimal String

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, editable, enabled, plain, visible, infoText, maxByteLength, maxLength, fullField, indispensableField, enableChars, maximumValue, minimumValue, maxDecimalDigit, maxIntegerDigit

uji:fieldDate FieldDate FieldDateModel2

Date String

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, editable, enabled, plain, visible, infoText, maxByteLength, maxLength, fullField, indispensableField, enableChars, locale(java.util.Locale), timeZone(java.util.TimeZone)

uji:fieldTextArea FieldTextArea FieldTextAreaModel2 String

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, editable, enabled, visible, infoText, maxByteLength, maxLength, indispensableField

uji:checkBox CheckBox CheckBoxModel String background, fontSize,

fontStyle, fontWeight,

185

Tag An item class and an interface used by the tag

Type of the value

External attributes supported by the tag (*1)

uji:pushButton PushButton PushButtonModelValued PushButtonValued PushButtonModel

Any type (*3)

foreground, textDecoration, tipText, enabled, visible, label

uji:radioButton RadioButton RadioButtonModel Any type (*4)

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, tipText, enabled, visible, label

uji:anchor Anchor AnchorModel Any type (*3)

background, fontSize, fontStyle, fontWeight, foreground, textDecoration, visible, label

uji:comboBox ComboBox ComboBoxModel2 String

values(Map), colorAt(String[]), enabled, visible

uji:listBox ListBox ListBoxModel2

String String[](*2)

values(Map), colorAt(String[]), enabled, visible, multipleMode

uji:buttonList ButtonList ButtonListModel2

String String[](*2)

values(Map), colorAt(String[]), enabled, visible, multipleMode

uji:list DefaultListModel ListModel Object[] elementClass(String[])

uji:table DefaultTableModel TableModel Object[][] rowClass(String[]),

columnClass(String[][]) (*1) External attributes are described in the form of "an attribute name (a type of the attribute value.)" A type is omitted if the type is String. Classes such as the java.lang.Integer class and the java.lang.Boolean class can be set to external attributes of type String, if the external attribute represents a number or a boolean value. In this case, a value returned by the toString method is used as the value of the external attribute. The name of a constant representing an external attribute and defined by a class such as com.fujitsu.uji.compo.TagAttributeNames is capitalized. For example, an attribute name "colorAt" is defined by a constant com.fujitsu.uji.compo.TagAttributeNames.COLORAT. (*2) Use String[] if the multipleMode attribute is set to true. (*3) If the selectedProperty attribute is omitted, it is not necessary to create a property on a data Bean, because values of a button and anchor are not required. (*4) If the pickUpMode attribute is set to "list" or "table", it is not necessary to create a property on a data Bean, because an object assigned to a radio button is not required.

14.5 Using XML Data with Tags

Using the XML linkage function with screen part tags and component tags, you can display XML data and update XML with input data. For more information on the XML linkage function, see Using XML Data. This section describes use of XML data with UJI tags, one of the XML linkage functions.

To use XML linkage functions, a Fujitsu XML processor or Apache Xerces and Apache Xalan are required. For details, see Software Required for Execution.

14.5.1 Basic Use

With screen part tags and component tags, you can use XML data Beans in the same way that you use conventional data Beans; and you can display XML data and update XML with input data. Use XPath to specify which XML data items you want to use with the tags.The following tags can use XML data:

186

Tag Function

uji:table Displays data in a table.

uji:tree Displays data in the form of a tree.

uji:list Displays data in a list.

uji:switch Displays different screens depending on conditions.

uji:composite Retrieves a portion of an XML data Bean.

uji:compositeName Generates a name for an input item for updating a portion of an XML data Bean.

uji:value Displays a value.

uji:getProperty Shows the content of an XML element.

uji:name Generates the name of an input item for updating displayed data.

uji:input Used as a replacement for the HTML INPUT tag if client script is coded.

uji:textarea Used as a replacement for the HTML TEXTAREA tag if client script is coded.

uji:select Used as a replacement for the HTML SELECT tag if client script is coded.

uji:fieldString String input field

uji:fieldLong Integer input field

uji:fieldDouble Real number input field

uji:fieldBigInteger Decimal integer input field

uji:fieldBigDecimal Decimal number input field

uji:fieldDate Date and time input field

uji:fieldTextArea Muti-line text input field

uji:checkBox Check box

uji:radioButton Radio button

uji:pushButton Button

uji:anchor Anchor

uji:comboBox Combo box

uji:listBox List box

uji:buttonList Button list

uji:recordView Record view

uji:tableView Table view

uji:treeView Tree view

If you use any of the following tags to update XML data, you cannot use a name space in the XML data:

· uji:getProperty · uji:fieldTextArea · uji:comboBox · uji:listBox · uji:buttonList This section uses the following XML coding as an example to describe basic input and output:

XML(catalog.xml)


187

<catalog>

<item>

<name>Red wine</name>

<content>1000ml</content>

</item>

<price>2000</price>

</catalog>

In the example, the application displays the name element of this XML data and inputs the content of the price element. The business class creates an XML data Bean. As shown in the following example, XML data is read from the "catalog.xml" file in the WEB-INF folder, and the name "body" is given to a created XML data Bean:

Business class

import java.io.File; import java.io.BufferedInputStream; import java.io.FileInputStream;

import javax.servlet.ServletContext;

import com.fujitsu.uji.DispatchContext; import com.fujitsu.uji.http.HttpDispatchContext;

import com.fujitsu.uji.xml.XmlDataBean;

....


try {

// Create a File object indicating a file to be loaded.

ServletContext sc = ((HttpDispatchContext)context).getServletContext();

String root = sc.getRealPath("/");

File file = new File(root, "/WEB-INF/catalog.xml");

// Create an XML data Bean.


// Read XML data.

BufferedInputStream in = new BufferedInputStream(new FileInputStream(file));

xmlBean.loadFrom(in);

// Define the data Bean to be output.

context.setResponseBean("body", xmlBean);

} catch (Exception e) {

e.printStackTrace();

}

188

}

....

The input-output page uses uji:getProperty to display the name element, and uji:fieldString to input the price element, as shown below.

Input-output page

<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <uji:useBean id="body" cls="com.fujitsu.uji.xml.XmlDataBean" request="true" />

<form method="post">

<input type="hidden" name="uji.id" value="body">

<input type="hidden" name="uji.verbs" value="update">

Commodity information<br>

Name: <uji:getProperty bean="body" xpath="item/name"/> <br>

Price: <uji:fieldString bean="body" xpath="price"/>dollar <br>

<input type="submit" name="update" value="update">

</form>

To specify an XML data element that is displayed, use the bean and xpath attributes of the uji:getProperty tag. In the bean attribute, specify the name given to an XML data Bean. For the xpath attribute, use XPath to indicate which element of the XML data Bean is displayed. Specify this XPath with a relative path starting from the root element of the XML data Bean specified in the bean attribute.

If the xpath attribute is omitted, the root element of the XML data Bean specified in bean is used together with the tag. If the bean attribute is omitted, the current object is used instead of the attribute.

When using XML data Beans, write command maps and page maps differently than usual. For details, see Writing relationship definition files.

The display in a browser is as follows:

189

When XML data is used with tags for input parts such as string input fields and text areas, the XML data is updated with input data. In the above example, uji:fieldString uses the price element. If you were to type "5250" and click the [Update] button in the browser, the price element of the XML data Bean would be updated as shown below.

XML(catalog.xml)


<catalog>

<item>

<name>Red wine</name>

<content>1000ml</content>

</item>

<price>5250</price>

</catalog>

Request parameters required for forms

When you create a form, make sure that the uji.id and uji.verbs request parameters are sent if necessary, as you would do for use of conventional data Beans. Adding the <input type="hidden"> tag allows these request parameters to be sent. To store input data in a new XML data Bean, specify values in the uji.bean and uji.xmlBean request parameters as follows: · For uji.bean, specify com.fujitsu.uji.xml.XmlDataBean. · For uji.xmlBean, specify the name of the root element of XML data.

<form method="post">

<input type="hidden" name="uji.bean" value="com.fujitsu.uji.xml.XmlDataBean">

<input type="hidden" name="uji.xmlBean" value="catalog">

<input type="hidden" name="uji.verbs" value="add">

Commodity information<br>

Name: <uji:getProperty bean="body" xpath="item/name"/> <br>

Price: <uji:fieldString bean="body" xpath="price"/>dollar <br>

<input type="submit" name="add" value="add">

</form>

Writing relationship definition files

When you use XML data Bean, write command maps and page maps differently than usual. Use the name of the root element of an XML data Bean instead of the data Bean class name (com.fujitsu.uji.xml.XmlDataBean). Prefix the element name with "/". The following example uses an XML data Bean in which the root element is "catalog"

190

:

Command map

/catalog;add=sample.CatalogHandler.add

Page map

/catalog;=catalogForm.jsp

Tags that handle a set of multiple data items

Each of the tags listed below require a set of multiple list, table, or other data items. When XML data with any of these tags is used, the structure of the data must match that of the tag.

Tag Description

uji:comboBox Combo box

uji:listBox List box

uji:buttonList Button list

uji:recordView Record view

uji:tableView Table view

uji:treeView Tree view

uji:table Displays data in a table.

uji:list Displays data on a list.

uji:tree Displays data in the form of a tree.

For the XML data structure required for each tag, refer to the UJI Tag Reference. This section uses uji:comboBox as an example to describe how XML data is displayed, how it is input, and the required XML data structure.

The example shows the XML data and tag necessary for display of the following combo box:

Combo box that is displayed

XML

<root>

<selected>Baseball</selected>

<sports>

<data>Baseball</data>

<data>Soccer</data>

<data>Tennis</data>

</sports>

</root>

191

Tag

<uji:comboBox bean="body" xpath="sports" selectedXPath="selected"/>

Use the xpath attribute of uji:comboBox to specify the data that is displayed as options in the combo box. Child elements of the element specified in xpath are used as options. In the above example, the three data elements in the sports element are options.

For the selectedXPath attribute, use XPath to specify the element to which to save a selection from the options. This specification is a relative path starting from the root element of the XML data Bean specified in the Bean attribute. In the example, the selection is saved to the selected element. When a request is processed, the content of the selected element is replaced with the display string of the item selected from the options in the combo box. When the screen is displayed, the content of the selected element is used as the default selection.

An option has its string displayed in the combo box. When the option is used, however, you may want another string saved to the element specified in selectedXPath. If so, use the valueAttr attribute of uji:comboBox. Once the attribute name of an element used as an option is specified for valueAttr, the value of the attribute is saved when that option is saved. Data shown in the above example can be rewritten as follows to make sure that "baseball" is saved to the selected element when "Baseball" is selected:

XML

<root>

<selected>baseball</selected>

<sports>

<data code="baseball">Baseball</data>

<data code="soccer">Soccer</data>

<data code="tennis">Tennis</data>

</sports>

</root>

192

Tag

<uji:comboBox bean="body" xpath="sports"

selectedXPath="selected" valueAttr="code"/>

When an element is selected, an indication of the selected state can be saved in an attribute of the element. To enable this, include @ followed by the attribute name in selectedXPath. The above combo box data can be rewritten as follows to make sure that the value of the selected attribute of element "<data>Baseball</data>" becomes true when "Baseball" is selected:

XML

<root>

<sports>

<data selected="false">Baseball</data>

<data selected="true">Soccer</data>

<data selected="false">Tennis</data>

</sports>

</root>

Tag

<uji:comboBox bean="body" xpath="sports" selectedXPath="@selected"/>

The elements specified in the xpath and selectedXPath attributes must satisfy the following conditions: · For xpath, specify complex elements; do not specify mixed-content elements and simple elements. All

child elements of an element specified in xpath must be simple elements. Not all child element names must be the same.

· For selectedXPath, specify simple elements.

All tags including uji:comboBox use complex elements or simple elements; no tag uses mixed-content elements.

When you use a XML data Bean, no item class is required, even for a tag such as uji:comboBox that would otherwise require an item class. However, use of item classes results in improved performance. You can also use item classes to dynamically change display attributes and other settings. For information about using XML data in item classes, see XML Item Classes.

How data is handled if a specified element does not exist

If an element specified in the xpath attribute does not exist, or an element or attribute specified in the selectedXPath attribute does not exist, data is displayed and updated as described below. · Data is handled as null when it is displayed. If the data must be either true or false, it is handled as false. · A specified element or attribute is added to XML data when it is updated. However, this holds true only if

the XPath specification satisfies either of the following conditions: - A predicate ([expression] format) is not used (for example, item/name). - If a predicate is used, it is in the [integer] or [position()=integer] format (e.g.,

item[3]/note[position()=5]).

193

14.5.2 XML Item Classes

The tags listed in the table below have their own associated item classes that are used to maintain input-output data and to specify attributes and other settings. Each of these item classes has an associated XML item class. The XML item classes differ from conventional item classes in that they contain data as XML trees. The table below lists these tags and their associated XML item classes. For details about each class, refer to the API Reference.

Tag XML item class(*)

uji:table XmlTable

uji:tree XmlTree

uji:list XmlList

uji:fieldString XmlFieldString

uji:fieldLong XmlFieldLong

uji:fieldDouble XmlFieldDouble

uji:fieldBigInteger XmlFieldBigInteger

uji:fieldBigDecimal XmlFieldBigDecimal

uji:fieldDate XmlFieldDate

uji:fieldTextArea XmlFieldTextArea

uji:checkBox XmlCheckBox

uji:radioButton XmlRadioButton

uji:pushButton XmlValuedPushButton

uji:anchor XmlAnchor

uji:comboBox XmlComboBox

uji:listBox XmlListBox

uji:buttonList XmlButtonList

uji:recordView XmlRecordView

uji:tableView XmlTableView, XmlScrollTableView

uji:treeView XmlTreeView

(*) The package for all classes is com.fujitsu.uji.xml.

When you use XML item classes, performance is improved compared with cases where XML data Beans are used directly with tags. In addition: · You can use handlers, instead of tag attributes, to specify display attributes (such as display colors and

fonts) and input checks (such as required input items and a limit on the number of characters). The XML item classes included in the com.fujitsu.uji.xml package can be used without modification.

· You can change tag-based default associations between displayed data or data input on the screen and XML data. To do so, create a class by inheriting a predefined XML item class, and override the methods for getting and setting data.

An explanation on how to use an XML item class is given below. In this example, the following uji:comboBox tag and XML data are used to create a combo box with three options, "Baseball", "Soccer", and "Tennis", and to specify the display color with an XML item class:

XML (sports.xml)


<root>

<member>

<name>David</name>

194

<hobby1>Baseball</hobby1>

</member>

<sports>

<data>Baseball</data>

<data>Soccor</data>

<data>Tennis</data>

</sports>

</root>

Create the subclass of an XML data Bean, and add the property of an XML item class. As shown in the example below, MyXmlDataBean is specified as the subclass name, and XmlComboBox class property comboBox is added. XmlComboBox is the XML item class associated with uji:comboBox.

XML data Bean (MyXmlDataBean.java)


import com.fujitsu.uji.xml.XmlComboBox;

public class MyXmlDataBean extends XmlDataBean {

XmlComboBox comboBox = null;

public void setComboBox(XmlComboBox comboBox) {

this.comboBox = comboBox;

}

public XmlComboBox getComboBox() {

return comboBox;

}

}

In the business class, the MyXmlDataBean class is used as an XML data Bean, and XML data is read from a file. Then, an XML item class is created, and the display color is set. The created XML item class is specified in the comboBox property of MyXmlDataBean.

Business class

1: import com.fujitsu.uji.xml.XmlDataBean;

2: import com.fujitsu.uji.xml.XmlComboBox;

3: import com.fujitsu.uji.http.HttpDispatchContext;

4: import com.fujitsu.uji.DispatchContext;

5:

6: import java.io.*;

7: import javax.servlet.ServletContext;

8:

9: (Omitted)

10:

11:

195

12: public void startup(DispatchContext context) {

13: try {

14: // Create the File object that indicates a file to be loaded.

15: ServletContext sc = ((HttpDispatchContext)context).getServletContext();

16: String root = sc.getRealPath("/");

17: File file = new File(root, "/WEB-INF/sports.xml");

18:

19: // Create an XML data Bean, and load XML data.

20: MyXmlDataBean xmlBean = new MyXmlDataBean();

21: BufferedInputStream in = new BufferedInputStream(new FileInputStream(file));

22: xmlBean.loadFrom(in);

23:

24: // Create an XML item class.

25: XmlComboBox xmlComboBox = new XmlComboBox(xmlBean);

26: xmlComboBox.setXpath("sports");

27: xmlComboBox.setSelectedXPath("member/hobby1");

28:

29: // Specify the display color.

30: xmlComboBox.setColorAt(1,"red");

31:

32: // Specify the XML item class in a property of MyXmlDataBean.

33: xmlBean.setComboBox(xmlComboBox);

34:

35: // Set the XML data Bean to be output.

36: context.setResponseBean("body",xmlBean);

37: } catch (Exception e) {

38: e.printStackTrace();

39: }

39: }

Create an XML item class as follows: · Create an XML data Bean for use with the uji:comboBox tag (lines 20 to 22). · Pass the XML data Bean as an argument to the item class constructor (line 25). · Use XPath to specify which data items are used as options and the element to which to save a selection

using the setXpath and setSelectedXPath methods, respectively, in the same way as that for the xpath and selected attributes of the tag (lines 26 and 27).

· Specify a display attribute or input check if necessary (line 30). · Supply the XML item class to the comboBox property of MyXmlDataBean (line 33). The XML tree maintained in the XML data Bean passed to the constructor is shared with the item class.

Use the bean and property attributes of the tag to specify the comboBox property of MyXmlDataBean.

Tag

196

<uji:comboBox bean="body" property="comboBox" />

When a predefined XML item class is used, as shown in this example, the association between XML data and displayed data and data input on the screen is the same as that applied when XML data Beans are used. For an explanation of the XML data structure required for a specific XML item class, refer to the UJI Tag Reference for the tag associated with the XML item class.

An XML item class is not an XML data Bean. When you use XML item classes, the values of tag attributes specific to the XML linkage function, such as xpath, selectedXPath, and valueAttr, become invalid. Use the methods that correspond to individual attributes and that are provided in XML item classes.

If an option different from XML data must be set, use the item class methods for adding and deleting data in order to change options.

Business class

1: import com.fujitsu.uji.xml.XmlDataBean;

2: import com.fujitsu.uji.xml.XmlComboBox;

3: import com.fujitsu.uji.http.HttpDispatchContext;

4: import com.fujitsu.uji.DispatchContext;

5:

6: import java.io.*;

7: import javax.servlet.ServletContext;

8:

9: (Omitted)

10:

11:

12: public void startup(DispatchContext context) {

13:

14: (Omitted)

15:

16: }

17:

18: public void exec(DispatchContext context, MyXmlDataBean dataBean) {

19:

20: (Omitted)

21:

22:

23: // Get an XML item class

24: XmlComboBox xmlComboBox = dataBean.getComboBox();

25:

26: // Add an option

27: xmlComboBox.add("volleyball", "volleyball");

28:

197

29: // Specify an XML data Bean to be displayed

30: context.setResponseBean("body",dataBean);

31: }

To add an option, get an item class from a data Bean (line 24), and add the option by using the method for addition of the item class (line 27). You can also delete or insert options. For more information, refer to the API Reference for each item class.

14.5.3 Conversion from an Ordinary Data Bean to XML Data Bean

This section contains notes on using an XML data Bean instead of an ordinary data Bean in a created application.

The xpath attribute is not always added to a tag when an ordinary data Bean is replaced with an XML data Bean. The property attribute, instead of xpath, is valid. If an object specified in the bean attribute is an XML data Bean, an element having the name specified in property is selected from the child elements of the root and then used. This also applies when bean is omitted and the current object is used.

To not add the xpath attribute during conversion to an XML data Bean, rewrite the data Bean to XML data as follows: · Specify a data Bean as the parent element and a property as a child element. · As the property value, use the content of the element associated with that property. · If the property value is a data Bean, define the element associated with that property as that obtained by

rewriting the data Bean to an XML one.

14.6 Window Control

The window control feature facilitates the creation of applications that have subwindows. For example, you can easily create an application such as the one shown below:

In this section, the words "main window" and "subwindow" have the following meanings:

198

Main window Indicates a window displayed in a browser when a user starts to run an application. It is assumed that the application has one main window.

Subwindow Indicates a window that is, or can be, opened and closed while the application is running. Multiple subwindows are allowed on one application.

To control windows, use the following classes and UJI tag:

com.fujitsu.uji.http.Window class You can use the open method and close method of the Window class for business classes to control windows. One Window object corresponds to one window.

com.fujitsu.uji.http.WindowController class This class is used to manage objects of the Window class. Use this class to create a new subwindow or get an object of the Window class that corresponds to a window with a specified name.

uji:windowControl tag This tag generates the FORM tag and JavaScript used to control a window according to operations of the Window class. Code the uji:windowControl tag on control pages.

Create JSP

Create the main window and subwindows in an application as follows: · Assign a unique name to each subwindow. The name of the main window is always "main". · Create a control page for each window.On each control page, code one uji:windowControl tag. Code it after

the uji:include tag and before the </BODY> tag.Specify the area names specified using the pane attribute of the uji:include tag so that they are unique on all the control pages.

· To create forms on I/O pages, use the uji:form tag instead of the HTML FORM tag.

To update a screen when using the window control function, create an application so that it receives requests on a JSP (control page). The window control function cannot be used for a request received with a servlet and a screen (JSP) has been returned as a response.

Control of display

For a business class, create a program using the Window class and WindowController class as follows:

Opening a subwindow To allow a subwindow to open, use the open method of the Window class. The coding sample below shows a subwindow opened when the associated button is clicked in the main window:

import com.fujitsu.uji.http.Window;

import com.fujitsu.uji.http.WindowController;

199

import com.fujitsu.uji.http.HttpDispatchContext;

...

public void someHandler(DispatchContext context, MyDataBean dataBean) {

WindowController wCtrl =

((HttpDispatchContext)context).getWindowController(); // (1)

Window subWin = wCtrl.createWindow("subWindow"); // (2)

subWin.open("sub.jsp","resizable=yes,width=300,height=300"); // (3)

context.setResponseBean("subBody",new SubDataBean(),true); // (4)

context.setResponseBean("mainBody",dataBean,true); // (5)

}

· (1) Get WindowController by using the getWindowController method of the HttpDispatchContext

class. · (2) Create a Window object that corresponds to the new subwindow by using the createWindow

method of WindowController. Specify the name of the subwindow in the createWindow argument. · (3) Open the subwindow using the open method of the Window class. Specify the control page and

window style used for the subwindow. Code the window style in the format used for the open method of the JavaScript Window object.

· (4) Assign a data Bean to the area name allocated for the subwindow by using the setResponseBean method. Specify true as the third argument of setResponseBean so that the data Bean is reset by request.

· (5) Assign a data Bean to the area name allocated for the main window by using the setResponseBean method. As in (4), set true as the third argument of setResponseBean.

The coding above allows the subwindow to open when execution of the business class ends and the browser displays the next window.

Closing a subwindow To allow a subwindow to close, use the close method of the Window class. The coding sample below shows a subwindow closed when the associated button is clicked in the main window:




...




Window subWin = wCtrl.getWindow("subWindow"); // (2)

200

subWin.close(); // (3)

context.setResponseBean("mainBody",dataBean,true); // (4)

}


class. · (2) Specify the name of the subwindow by using the getWindow method of WindowController to

get the corresponding Window object. · (3) Close the subwindow by using the close method of the Window class. · (4) Assign a data Bean to the area name used for the main window by using the setResponseBean

method. Set true as the third argument of setResponseBean. The coding above allows the subwindow to close when execution of the business class ends and the browser displays the next window. To allow the button on the subwindow to close it, omit step (4) above.

Updating data in another window To allow a button in a window to update data in another window when it is clicked, use the update method of the Window class. The coding sample below shows a button in a subwindow that updates data in the main window when it is clicked:




...




Window mainWin = wCtrl.getWindow(Window.MAIN_WINDOW); // (2)

mainWin.update(); // (3)

context.setResponseBean("mainBody",new MainDataBean(),true); // (4)

context.setResponseBean("subBody",dataBean,true); // (5)

}


class. · (2) Specify the name of the main window by using the getWindow method of WindowController to

get the corresponding Window object. The defined Window.MAIN_WINDOW variable is "main" (the name of the main window).

· (3) Update the data in the main window using the update method of the Window class. · (4) Assign a data Bean to the area name allocated for the main window by using the

setResponseBean method. Set true as the third argument of setResponseBean. · (5) Assign a data Bean to the area name allocated for the subwindow by using the

setResponseBean method. Set true as the third argument of setResponseBean. The coding above allows the main window to update its data when execution of the business class ends

201

and the browser displays the next window.

Note the following when creating a business class: · For methods that are to be called while subwindows are being displayed, specify true as the third

argument of the setResponseBean method when it is called. Objects of the Window class are valid until the session ends. Therefore, you can temporarily store them in variables of a business class and use them when the business class is called. See the coding sample below:




...

// Variable used to store the Window object of the subwindow

Window subWin = null;


// Specify this business class for the session scope.

return true;

}

// Method to be called for the first access



((HttpDispatchContext)context).getWindowController();

// Create a Window object of the subwindow, then store it in a variable.

subWin = wCtrl.createWindow("subWindow");

...

}

// Method for opening the subwindow

public void openSubWindow(DispatchContext context, MyDataBean dataBean) {

subWin.open("sub.jsp","resizable=yes,width=300,height=300");

context.setResponseBean("subBody",new SubDataBean(),true);

...

}

// Method for closing the subwindow

public void openSubWindow(DispatchContext context, MyDataBean dataBean) {

subWin.close();

202

...

}

Checking the validity of requests

An application that uses subwindows can check the validity of requests by using the HttpControlStateProfile class and uji:controlState tag. For information about request validity, see Advanced Session Management.

For an application that uses subwindows, code the uji:controlState tag on each form displayed in the window. The validity is checked for each window. In each window, a request from the last screen displayed is handled as a "valid" one.

14.7 Frame Control

To divide a browser screen into frames, define the frames by using the uji:frame tag instead of the HTML FRAME tag.Use of the uji:frame tag provides the following advantages compared to the FRAME tag: · The JSP configuration is concise. · Business classes can indicate updating of a frame display. · The validity of requests is checked for each frame. · Reception of requests can be prevented during frame updating. To use frames with an application, create a screen as follows: · Create a control page that defines a frame set. The control page defines how to split a screen into frames,

using the FRAMESET and uji:frame tags. · Create a control page for each frame. This control page defines the name and layout of a display area

used with each frame. · In order to use a form on an input-output page displayed in a frame, use the uji:form tag instead of

HTML FORM tag. The following figure shows the association between frames and a control page:

Frames are managed with the com.fujitsu.uji.http.WindowController and com.fujitsu.uji.http.Window classes, in the same way as management of applications that use subwindows. A Window object is associated with each frame so that the frame to be displayed and so that it can be updated with the update method. For information on how to use subwindows, see Window Control.

203

Creating a JSP

Creating a control page that defines a frame set The FRAMESET and FRAME tags are generally used in HTML to define frames. However, Apcoordinator applications use the uji:frame tag instead of FRAME. Assign a name to each frame, and specify it in the name attribute of the uji:frame tag. Note the following when assigning a frame name:

· Specify a frame name so that it is unique in an application. For example, if multiple windows are split into frames, make sure that all frames including those in other windows have different names.

· A frame name must not be the same as the name of a window. "main", the name of the Main window, cannot be used as a frame name.

In the src attribute of the uji:frame tag, specify the URL of the control page to be used.Also, specify the uji:dispatch and uji:windowControl tags on the control page that defines a frame set. uji:include is not used. A coding example is shown below.

<%@ page contentType= "text/html; charset=iso-8859-1" %>

<%@ page errorPage="ErrorPage.jsp" %>


<HTML>

<HEAD>

<TITLE>Reserved system</TITLE>

<uji:dispatch />

<uji:windowControl/>

</HEAD>

<FRAMESET rows="50%,*">

<uji:frame src="mainFrm.jsp" name="mainFrame"/>

<uji:frame src="navFrm.jsp" name="navFrame"/>

<NOFRAMES>

Use a browser supporting frames.

</NOFRAMES>

</FRAMESET>

</HTML>

Specify uji:dispatch and uji:windowControl in this order in the content of the HEAD tag.

Creating a control page for each frame Code the uji:windowControl tag in addition to the uji:dispatch and uji:include tags, in the same way as that for ordinary control pages. A coding example is shown below.


<%@ page errorPage="ErrorPage.jsp" %>


<HTML>

<BODY>

<uji:dispatch />

<uji:include pane="mainHeader" />

<uji:include pane="mainBody" />

<uji:windowControl/>

</BODY>

</HTML>

204

Code uji:windowControl following uji:include and before </BODY>. To use the uji:frame tag, create an application so that requests are received by a JSP (control page) for updating a screen.If requests are received by a servlet and returned to the screen (JSP) as a response, the uji:frame tag cannot be used.

Displaying a frame

Splitting the Main window into frames Use the URL of the control page that defines a frame set, as an application URL.For example, create a control page that defines a frame set, using "main.jsp" as its name and http://yourHost/contextPath/main.jsp as the application URL. Methods of the business class called at the start of application execution assign a data Bean to the area used by each frame. In the following example, the screen is split into two frames, where one uses the mainHeader and mainBody areas, and the other uses the navBody area:


context.setResponseBean("mainHeader", new HeaderBean(), true);

context.setResponseBean("mainBody", new BodyBean(), true);

context.setResponseBean("navBody", new MenuBean(), true);

}

To assign a data Bean to a frame area, specify true in the third argument of setResponseBean.

Splitting a subwindow into frames If a subwindow uses a control page that defines a frame set, it is split into frames.Use the open method of the Window class to specify the control page used with the subwindow. For information about the open method, see Window Control.




...



((HttpDispatchContext)context).getWindowController();

Window subWin = wCtrl.createWindow("subWindow");

subWin.open("frame.jsp","resizable=yes,width=300,height=300"); // (1)

context.setResponseBean("subHead", new SubHeadBean(),true); // (2)

context.setResponseBean("subBody", new SubBodyBean(),true); // (2)

...

}

· (1) For opening of a subwindow, specify the URL of the control page that defines its

frame set. This URL is a relative path from the context root. · (2) Assign a data Bean to the area used by each frame. In this case, specify true in

the third argument of setResponseBean.

205

Updating a frame display

The frame displaying a form is usually updated when data input on the form is sent.There are two methods for updating other frames, as described below.

Using a business class to specify the frame to be updated The business class indicates updating of a frame display. This method uses the com.fujitsu.uji.http.WindowController and com.fujitsu.uji.http.Window classes.




...


WindowController wctrl=((HttpDispatchContext)context).getWindowContrller(); // (1)

Window frame=wctrl.getWindow("mainFrame"); // (2)

frame.update(); // (3)

context.setResponseBean("mainHeader",new HeaderBean(), true); // (4)

context.setResponseBean("mainBody",new BodyBean(), true); // (4)

}

· (1) Obtain the WindowController class from the HttpDispatchContext class. · (2) From the WindowController class, use the getWindow method to obtain the

Window object associated with the frame to be updated. Specify the name of the frame to be updated in the getWindow argument.

· (3) Call the update method of the Window object obtained in (2). · (4) If necessary, assign a data Bean to the area used by the frame to be updated. In

this event, specify true in the third argument of setResponseBean. This processing is unnecessary if the object of the data Bean to be assigned is the same as the one previously displayed.

In this method, the frame displaying a form is updated as well as the frame whose updating is specified with the update method.

Specifying the frame to be updated on a JSP In the targetWindow attribute of the uji:form tag, specify the name of the frame to be updated. Moreover, use the action attribute to specify the control page of the frame to be updated. As a result, when data of the form is sent, the frame displaying the form is not updated, and the frame specified in targetWindow is updated.

<uji:form name="updateForm" targetWindow="mainFrame" action="mainFrm.jsp">

...

</uji:form>

Assign a data Bean to the area of the frame to be updated, as required. This processing is performed by the method of the business class called when data of the form is sent. The following shows an example of coding such a business class method:


context.setResponseBean("mainHeader",new HeaderBean(),

206

true);

context.setResponseBean("mainBody",new BodyBean(), true);

}

Specify true in the third argument of setResponseBean. setResponseBean need not be called if the instance of the data Bean to be assigned is the same as the one previously displayed.

Updating the display of all frames Updating the display of a window split into frames updates the display of all frames in the frame set of the window.To update a window display, use the update method of the Window class.


WindowController wctrl=((HttpDispatchContext)context).getWindowContrller(); // (1)

Window win=wctrl.getWindow("main"); // (1)

win.update(); // (2)

context.setResponseBean("mainHeader",new HeaderBean(), true); // (3)

context.setResponseBean("navBody",new MenuBean(), true); // (3)

}

· (1) Obtain WindowController and obtain the Window object of the window split into

frames. Specify the window name in the getWindow argument. · (2) Call the update method of the window object obtained in step (1) to give an

instruction to update the display. · (3) If necessary, assign a data Bean to the area used by each frame to be updated. In

this case, specify true in the third argument of setResponseBean. This processing is unnecessary if the object of a data Bean to be assigned is the same as the one previously displayed.

Preventing reception of requests during frame updating

When a screen using the uji:frame tag is displayed, requests to display the contents of a frame can be as many as the number of frames. All frames are not re-displayed at the same time; the re-display of some frames may be delayed. Even in this state, a user can click buttons and links in displayed frames, so subsequent requests may be sent from screens whose display of some frames is incomplete. To prevent processing of such requests, specify true in the sync attribute of the uji:frame tag.

<FRAMESET rows="50%,*">

<uji:frame src="mainFrm.jsp" name="mainFrame" sync="true"/>

<uji:frame src="navFrm.jsp" name="navFrame" sync="true"/>

<NOFRAMES>

Use a browser supporting frames.

</NOFRAMES>

</FRAMESET>

In the above example, a null response (HTTP status code 204) is returned for requests sent from mainFrame and navFrame until mainFrm.jsp and navFrm.jsp are displayed. As a result, the business class is not called and no screen display is updated.This function is enabled only between frames for which sync="true" is specified. If sync="true" is not specified for frames, requests from the frames are always processed. Moreover, frames for which sync="true" is specified do not wait until frames for which sync="true" is not specified are displayed.

If frame display does not complete before the specified time elapses, a time-out occurs and this function is automatically cancelled. Requests are processed even if a frame has not yet been displayed. This prevents a

207

request from a frame from not being accepted even if the [Stop] button in a browser is pressed causing a frame display request to not be sent. The default time until a timeout occurs is 10 seconds. To change the default time, specify in the initialization parameter, uji.frameSyncTimeout, the number of seconds that elapse until a timeout occurs. If 0 is specified, no timeout occurs.

Checking the validity of requests

An application that uses frames can check the validity of requests by using the HttpControlStateProfile class and uji:controlState tag.For information about the validity of requests, see Advanced Session Management.

For an application that uses frames, specify the uji:controlState tag for each form displayed in a frame.The validity of requests is checked for each frame. In each frame, a request sent from the last screen displayed is handled as a "valid" request.

208

Chapter 15 Programming Using Application Program Interfaces (APIs)

This chapter explains the following:

Session management · Storing data managed by clients and data shared by all clients · Life cycle of objects making up an application · Exclusive control of method invocation · Detecting session disconnection caused by a timeout · Advanced session management, including: - Session management by URL rewriting - Detecting requests sent from unexpected pages - Disconnecting sessions explicitly - Preventing duplicate processing caused by repeated clicking of a button on a screen

Sending and receiving binary files · Receiving files uploaded from a browser · Sending files downloaded by a browser

Error processing · Displaying a JSP error page if an exception is thrown · Processing exceptions caused by a conversion from a character string to a numeric value when

data sent by an HTTP request is saved in a data Bean

15.1 Session Management

15.1.1 Webcoordinator Session Management

Webcoordinator provides session management functions. One session is created per client. If consecutive requests are sent from the same client, they are assumed to be for the same session. A request from another client is treated as a request for another session. Webcoordinator supports a session class as a class that indicates a session. Creating a user-defined session class allows users to store data for each client. Data shared by all clients can be stored in an application class.

If a single client uses multiple browsers, whether a session is processed as one session or is created for each browser depends on the browsers.

To manage data stored in units of sessions or application-level units in a Webcoordinator application, an user-defined session class or application class, respectively, is used.Create a session class as follows: 1) Create a session class that extends HttpSessionProfile.

package sample;

209

com.fujitsu.uji.http.HttpSessionProfile

{

}

Add data items used in a session, such as the login user name, to the session class. 2) Create a class imlpementing the Factory interface as a factory class.

Inheriting HttpFactory is easier than implementing the Factory interface. A factory class is used to generate an application class and a session class.

3) Create a session class from the factory class.

package sample;

import com.fujitsu.uji.SessionProfile;

public class SampleFactory extends com.fujitsu.uji.http.HttpFactory

{

public SessionProfile newSessionProfile() {

return new SampleSession();

}

}

Use newSessionProfile to generate a user-defined session class, and return it.The business class can collect SessionProfile using DispatchContext. This SessionProfile is used for the session class created here.


SampleSession session = (SampleSession)context.getSessionProfile();

}

4) Use the Web application environment definition file (web.xml) to specify a factory class name.

<context-param>

<param-name>factory</param-name>

<param-value>sample.SampleFactory</param-value>

</context-param>

For information about the Web application environment definition file, see Web Application Environment Definition File.

Follow the same procedure to create an application class. 1) An application class extends ApplicationProfile.

210

package sample;


{

}

2) Use the newApplicationProfile method of the factory class to generate an application class.

public ApplicationProfile newApplicationProfile()

{

return new SampleApplication();

}

In order to use the session recovery function provided by the application server, each object to be registered in the javax.sevlet.http.HttpSession class must be serializable. In this example, create a program so that the following objects become serializable:

· Session class instances (when creating a user-defined session class) · Instances of the business class specified in the session scope · Data Bean instances

15.1.2 Object Life Cycle

Each user object used by an Webcoordinator application has life cycles according to the request and session. Such an application is started when an HTTP request is sent from a client. The Web server creates a session for each client. If the client does not access the session within the specified time, a timeout occurs, and the session ends. When all sessions end and the specified time has elapsed, the application ends.

Application class An instance is created when an application is started.The same session is shared among separate sessions. The time at which an instance is deleted depends on the application server.

Session object After the session is started, the same instance is used until the session terminates due to a timeout.

Business class (session scope true) A business class that returns true in the init() method is generated when the class is first called. The same instance is used until the session terminates.

Business class (session scope false) A business class that returns false in the init() method can only be used while the request processing method is being called.

Data Bean (request=true) For a data Bean with request=true specified in the uji:useBean tag, the instance is stored until the next request is sent. When a data Bean having the same class is used in a subsequent request, the same instance is used.

Data Bean (request=false) A data Bean with request=false in the uji:useBean tag is discarded after a reply is sent to the client.

211

15.1.3 Exclusive Control Webcoordinator can have the following exclusive control of business class invocation:

Application exclusive control If javax.servlet.SingleThreadModel is implemented in an application class, only one business class is invoked at a time in the application. (javax.servlet.SingleThreadModel requiring no method is available only if it is declared.)

Same business class Different business class

Same session Exclusive Exclusive

Different session Exclusive Exclusive

Session exclusive control If javax.servlet.SingleThreadModel is implemented in a session, only one business class is invoked at a time in the session.

package sample;

public class SampleSession extends com.fujitsu.uji.http.HttpSessionProfile

implements javax.servlet.SingleThreadModel

{

}

212


Same session Exclusive Exclusive

Different session Free Free

Business class exclusive control If javax.servlet.SingleThreadModel is implemented in a business class, only one operation for the business class is invoked at a time in the application.


Same session Exclusive Free

Different session Exclusive Free

These functions exclusively control only the business logic part during invocation of the business class. Multithread operations are executed while a request is being analyzed or the screen display is being created. As well as the above methods, synchronized control can be used for exclusive control over any part.

15.1.4 Detecting a Session Disconnection

If a session is disconnected due to a timeout while a screen is displayed, the object associated with the session is initialized.

Executing specific processing when a session is started

A simple method of detection is to use a JSP to determine whether a session has started or has been disconnected. However, the JSP cannot distinguish between the start and disconnection of the initial session.A command is directly specified in an HTTP parameter of uji.verb.

<BODY>

<% if(session.isNew() && request.getParameter("uji.verb") == null) { %>

<jsp:forward page="main.jsp?uji.verb=login" />

<% } %>

<uji:dispatch />

Executing specific processing when a session is disconnected

If a session is disconnected due to a timeout, the data Bean specified with the setResponseBean method or uji:useBean tag is deleted.The notifyBeanLost method of the application class detects this operation.The return value of the notifyBeanLost method replaces the command when the session is disconnected.

package sample;


{

public String notifyBeanLost(String id) {

return("timeout");

}

213

}

In this event, the method of a business class without a Bean that corresponds to the command name "timeout" is called. The command map is used to associate the method with the command.

;timeout=sample.SampleHandler.timeout

The business class method determines the screen configuration and other processing.


{

public void timeout(DispatchContext context) {

// Specifies timeout processing.

...

}

}

To use the notifyBeanLost method, note the following about creating an input-output page: · Add the uji.id request parameter to the form. Specify request="true" with the uji:useBean tag for the data

Bean specified for uji.id. uji.id specifies the data Bean that receives the data input on the form.

<uji:useBean id="body" cls="sample.BodyBean" request="true" />


<INPUT name="uji.id" type="hidden" value="body">

....

</FORM>

· Do not add the uji.bean request parameter to the form.

Reexecuting processing that detected a session disconnection

After a session disconnection has been detected, create the following application to retry the session using interrupt processing, for example, such as by logging in:Add the uji.bean parameter so that the data Bean specified with the uji:useBean tag can be regenerated even if it is deleted.


<INPUT name="uji.bean" type="hidden" value="sample.SampleBean">

In session preprocessing, flag, etc., is set so that the current status can be checked to determine whether it is a new session.

214

package sample;

public class SampleSession extends com.fujitsu.uji.http.HttpSessionProfile

implements com.fujitsu.uji.Preprocessor

{

protected boolean loginFlag = false;

protected DispatchContext savedContext;

int preprocess(DispatchContext context) {

if(!loginFlag) {

// The context is saved if it is not the initial one.

if(context.getRequestBean() != null)

savedContext = context;

// context.setResponseBean configures a screen.

....

return Preprocessor.SKIP_ALL;

}


}

}

After login processing completes normally, reexecute processing.

public void login(DispatchContext context, LoginBean dataBean) {

// Login is executed.

....

// Normal execution

SampleSession sp = (SampleSession)context.getSessionProfile();

sp.loginFlag = true;

if(sp.savedContext != null) {

// When the context is stored, processing is reexecuted.

Dispatcher.redispatch(context, sp.savedContext);

sp.savedContext = null;

} else {

// Processing of the initial screen

....

}

}

215

15.1.5 Advanced Session Management (update)

Webcoordinator can use the following functions in addition to those of normal session management:

Using URL rewriting In general, a JSP uses Cookies for session management.For environments where cookies cannot be used, URL rewriting is used for session management.

Preventing duplicate processing If a button in a browser is clicked consecutively, the same request may be issued twice to a server.This function prevents duplicate processing of the same request in such cases.

Verifying the validity of a request A request from an unexpected page may be processed when the [Back] button is clicked in the browser or when a screen in cache is implemented.In Webcoordinator, detecting processing of such a request can cause an exception to be thrown.

Disconnecting a session explicitly You can disconnect a session before a timeout occurs.

There are two methods to prevent duplicate processing. The difference between them is the period in which duplicate processing is prevented.

Using the HttpControlStateProfile class as a session class Create a session class by inheriting the HttpControlStateProfile class. Using this method prevents duplicate processing during operation of the uji:dispatch tag. A business class is invoked while the uji:dispatch tag is running, so the method prevents duplicate processing while the business class is running.

Using the postOnce attribute of the uji:form tag. If true is specified in the postOnce attribute of the uji:form tag, a form is sent only once. Using this method prevents duplicate processing in the browser since no second or subsequent request is not sent to a server. However, this method is accomplished by using JavaScript, so it cannot be used in browsers in which JavaScript is not enabled.

The function for preventing duplicate processing with the uji:form tag is explained in Using the postOnce attribute of the uji:form tag.

Using the HttpControlStateProfile class

The following functions are provided for use with the HttpControlStateProfile class: · URL rewriting · Preventing duplicate processing · Verifying the validity of requests To use these functions, create an application by using the following procedure: 1) Add the uji:controlState tag to all HTML forms.

<FORM>

<uji:controlState />

...

</FORM>

2) Entend a session class from HttpControlStateProfile.

package sample;

public class SampleSession extends com.fujitsu.uji.http.HttpControlStateProfile

216

{

}

3) In the session class, override the method corresponding to the desired function in order to return the required parameters.

To use URL rewriting, override the getSessionMode method.

public int getSessionMode() {

return HttpControlStateProfile.URLREWRITING;

}

Dynamic switching between use of cookies and URL rewriting in response to a request is not supported. To add a parameter to the URL of the redirect destination, override the getRedirectURL method.

public String getRedirectURL(String defaultUrl) {

return defaultUrl + "?addparam";

}

To prevent duplicate processing, override the isDoublePostEnabled method.

public boolean isDoublePostEnabled() {

return false;

}

If a second request is received while the first one is being processed, the processing results of the first request are returned in response to the second request without processing of the second request.

To verify the validity of a request, override the isPageCheckEnabled method.

public boolean isPageCheckEnabled() {

return true;

}

If a server receives a request from a page other than the last page to which it sent data, ControlStateException is thrown.To judge whether this and other processing is executed, write it in the handleException method of the session class or application class.

Disconnecting a session explicitly

To disconnect a session, invoke the dispose method of the HttpSessionProfile class from a business class.

217

public void finalHandler(DispatchContext context, SomeBean dataBean) {

....


HttpSessionProfile sp =

(HttpSessionProfile)context.getSessionProfile();

sp.dispose();

}

When the dispose method is invoked, the session class is deleted from information of the session managed with a servlet container (javax.servlet.http.HttpSession).Because the session class stores information that Webcoordinator manages by associating it with the session, such information is deleted together with the session class.The session managed by the servlet container and HttpSession continues.After dispose is executed, a session class is created when the first request is received.

Using the postOnce attribute of the uji:form tag

The function for preventing duplicate processing with the postOnce attribute of the uji:form tag prevents data input for a form from being sent again from the same screen displayed. This function is enabled by setting a flag during setup of the form using JavaScript. This function is disabled in browsers in which JavaScript is not enabled.

To use the uji:form tag to prevent duplicate processing, create a form with the uji:form tag, and specify "true" in the postOnce attribute.

<uji:form name="order" method="post" postOnce="true" verbs="ok,cancel" beanId="body" beanCls="my.pkg.MyDataBean">

Commodity code: <INPUT NAME="code"><BR>

Quantity: <INPUT NAME="count"><BR>

<INPUT TYPE="SUBMIT" NAME="ok" VALUE="decision">

<INPUT TYPE="SUBMIT" NAME="cancel" VALUE="cancel">

</uji:form>

If postOnce="true" is specified, the duplicate processing prevention function is enabled even after browser reading is suspended. Therefore, no form is sent if the [Stop] button is clicked to suspend sending before the next screen is displayed and the transmitting button is then clicked. To handle such a state, create a transmitting button that enables a form to be sent regardless of whether postOnce="true" is specified. Create the transmitting button with the uji:pushButton tag, and specify skipScript="true".

<uji:form name="order" method="post" postOnce="true" verbs="ok,cancel" beanId="body" beanCls="my.pkg.MyDataBean">

Commodity code: <INPUT NAME="code"><BR>

Quantity: <INPUT NAME="count"><BR>

<INPUT TYPE="SUBMIT" NAME="ok" VALUE="decision">

<uji:pushButton type="submit" name="cancel" label="cancel"

218

skipScript="true" />

</uji:form>

Specifying skipScript="true" suppresses JavaScript execution when a form is sent. When a button with this specification is clicked, neither JavaScript for preventing duplicate processing nor JavaScript for checking input values is executed.

15.2 Sending and Receiving Binary Files

15.2.1 Uploading a File

Webcoordinator has functions for sending and receiving binary files. Therefore, file upload and download applications can easily be created.Create an application for uploading a file as follows:Define the com.fujitsu.uji.util.MimeSource type in a property of the Bean that receives the uploaded file.

import com.fujitsu.uji.util.MimeSource;

public class UpBean extends com.fujitsu.uji.DataBean {

protected MimeSource file;

public MimeSource getFile() {

return file;

}

public void setFile(MimeSource file) {

this.file = file;

}

}

Create an input-output page as follows:

Add enctype="multipart/form-data" to the form tag.

Specify type="file" in the input field of file name input. Delete the initial value.


<uji:useBean id="body" cls="updown.UpBean" request="true" />

<FORM method="post" enctype="multipart/form-data">

<INPUT name="uji.verbs" type="hidden" value="upload">

<INPUT name="uji.id" type="hidden" value="head">file-name:

<INPUT type="file" name="file" >

<BR>

<INPUT name="upload" type="submit" value="send">

</FORM>

219

The business class can fetch the stream and file from the Bean.To store them on a server, specify the absolute path to the server.

import java.io.InputStream;

import com.fujitsu.uji.util.MimeSource;

.....

public void upload(DispatchContext context, UpBean dataBean) {

MimeSource source = dataBean.getFile();

InputStream is = source.getInputStream();

String fname = source.getFileName();

....

}

.....

Use the application class to specify the file transfer parameter. Override the application class methods shown below, and specify the upper limits of transfer size and amount of memory used for transfers (if this amount of memory is exceeded, a work file is used). The default upper limit of transfer size is 16 megabytes, and the default amount of memory for transfers is one megabyte.

// Maximum file transfer size. The unit is bytes. 0 indicates "unlimited".

public long getMimeTransferSizeLimit() {

// Specify 32 megabytes as the upper limit of transfer size.

return 32*1024*1024;

}

// Amount of memory used for file transfers. The unit is bytes.

public int getMimeTransferMemorySize() {

// Specify one megabyte as the amount of memory used for transfers.

return 1024*1024;

}

The following quantitative restrictions are provided for uploading files: · The upload header length is up to 1024 bytes.

The upload header contains information about item and file names. A total of approximately 970 bytes can be specified for an item name length and file name length, but this depends on the browser used.

· The default upper limit of upload file size is 16 megabytes (16*1024*1024 bytes). As explained above, this size can be changed by overriding the getMimeTransferSizeLimit method with the application class.

If one of these quantitative restrictions is exceeded, the IOException exception is thrown.A generated exception is wrapped with the DispatchException class and posted to the handleException method implemented in the session class and to the handleException method implemented in the application class. To use the handleException method, the Postprocessor interface must be implemented in a session class or application class.For information on using the handleException method, see Error Processing.

220

15.2.2 Downloading a File

A JSP cannot be used to download a file because the JSP and output stream conflict. Therefore, create a servlet, and download the file by running the servlet. Create a servlet by inheriting UjiServlet.No method need be created, but in order for the class loader to be able to load a Java class of an application, the application must have the servlet class.

package updown;

public class DownloadServlet extends com.fujitsu.uji.http.UjiServlet {

public DownloadServlet() {

}

}

Add action="download" to the download input form. The download specified at this point can be specified with a servlet ID as an option. In this example shown below, the download file name is fixed and created using hidden items.The procedure for creating data Bean updown.DownloadParam is the same as that for general Webcoordinator applications. The description is omitted.

<FORM action="download">

<INPUT name="uji.verbs" type="hidden" value="download">

<INPUT name="uji.bean" type="hidden" value="updown.DownloadParam">

<INPUT name="file" type="hidden" value="downloadfilename">

<INPUT name="download" type="submit" value="download">

</FORM>

In the business class, return value Object is substituted for "void". The file to be downloaded is returned with the File class.Return values of "File", "InputStream", and "MimeSource" are each assumed to be a file, and download is started.The return value of "String" is assumed to be the name of a JSP file with a screen for displaying errors, etc. When processing such as setResponseBean is executed in the business class and the JSP file with uji:include specified (uji:dispatch cannot be specified) is returned, the Webcoordinator application can receive control.

....

//

public Object download(DispatchContext context, DownloadParam dataBean) {

name = "c:¥¥downloadarea¥¥" + dataBean.getFile();

return new File(name);

}

The command map is shared by general Webcoordinator applications.

221

updown.DownloadParam;download=updown.UploadHandler.download

To store the file on a server, edit web.xml and define servlet mapping. For details about web.xml, see Web Application Environment Definition File (web.xml).In the following example, servlet and servlet-mapping are added to define a download servlet:

<web-app>

<servlet>

<servlet-name>download</servlet-name>

<servlet-class>updown.DownloadServlet</servlet-class>

</servlet>

<servlet-mapping>


<url-pattern>/download</url-pattern>

</servlet-mapping>

</web-app>

15.3 Web Application Error Processing

15.3.1 JSP Error Page

A JSP error page is displayed if an exception occurs in a business class, a session class, or an application class, and the exception is not processed with the try-catch clause or the handleException method. For information on error processing using the handleException method, see Apcoordinator Core Function Error Processing.

The JSP error page can be specified at two locations.

@page directive

uji:dispatch The error page specified in uji:dispatch is used only for exceptions thrown during processing of a business class, and it takes precedence over the error page specified in the @page directive.The error page specified in the @page directive displays all application errors.

<%@ page errorPage="jspError.jsp" %>

<uji:dispatch errorPage="dispatchError.jsp" />

The JSP error page uses a JSP scriptlet to process an exception. The following is an example of a JSP error page:

<HTML>

<HEAD>

<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">


<%@ page isErrorPage="true" %>

222

<%@ page import="java.io.PrintWriter, com.fujitsu.uji.ApplicationProfile, com.fujitsu.uji.log.*" %>

</HEAD>

<BODY>

<PRE>

<%

if(exception != null) {

// Output to an HTML page.

Throwable ex;

// Note: A security problem is involved with output to an HTML page.

// Use the following source only for debugging:

/*

PrintWriter writer = new PrintWriter(out);

ex = exception;

while(ex instanceof NestedException) {

String msg = ex.getClass().getName() + " : " + ex.getMessage();

msg = msg.replace('<','[');

msg = msg.replace('>',']');

writer.println(msg);

ex = ((NestedException)ex).getRootCause();

}

ex.printStackTrace(writer);

*/

// Output to the application log.

ApplicationProfile ap = (ApplicationProfile)application.getAttribute(ApplicationProfile.APPLICATIONKEY);

if(ap != null) {

LogComposer lc = ap.getLogComposer();

if(lc != null) {

ex = exception;

while(ex instanceof NestedException) {

String msg = ex.getClass().getName() + " : " + ex.getMessage();

msg = msg.replace('<','[');

msg = msg.replace('>',']');

lc.println(msg);

ex = ((NestedException)ex).getRootCause();

}

lc.printStackTrace(ex);

}

}

223

}

%>

</PRE>

</BODY>

</HTML>

A security problem is involved with output to an HTML page.For use of the application, an appropriate screen must be created.

15.3.2 Data Bean Error Processing

When data sent with an HTTP request is specified in a data Bean, a character string specified incorrectly for a numeric item causes a numeric conversion error (NumberFormatException).In the event of such a numeric conversion error, Webcoordinator assumes that input has a default value of 0 and continues processing.To strictly determine that the data be subject to numeric conversion and execute special processing, implement UpdateExceptionListener in the data Bean.

public class SampleBean extends DataBean implements UpdateExceptionListener {

public void handleException(UpdateExceptionEvent uee) {

// Detects an exception.

Exception ex = uee.getException();

// Detects an item name.

String propertyName = uee.getName();

// Detects the value whose input was attempted.

Object value = uee.getValue();

// Executes alternative processing.

....

// Throws the exception again if it cannot be processed.

throw ex;

}

}

For example, when a null character string is sent for the BigInteger type item and null is specified, do as follows:

// Executes alternative processing.

if(propertyName.equals("someBigIntProp")

&& ex instanceof NumberFormatException) {

if(value instanceof String && ((String)value).length() == 0) {

setSomeBigIntProp(null);

224

return;

}

// For NumberFormatException, Webcoordinator

// specifies new BigInteger(0). Replace it with another exception.

ex = new IllegalArgumentException("Error in someIntProp");

}

225

226

Chapter 16 Linkage to Databases

16.1 Overview of the Database Linkage

Databases can be easily operated through the use of the component tag and database linkage class.Any database conforming to JDBC1.0 or JDBC2.0 can be used.

The database linkage has the following functions: · Displaying database contents on the screen using tables and combo boxes · Adding or updating database items entered in tables or record views · Automatically managing database connections The following component tags can be used for database linkage.By using the database linkage class as an item class in Data Bean, data retrieved from a database can be displayed on the screen.

Component tag Database linkage class Function uji:comboBox DBComboBox Selection items in combo box format

uji:listBox DBListBox Selection items in list box format uji:buttonList DBButtonList List of buttons

uji:recordView DBRecordView List of input items in record format uji:tableView DBTableView Table

uji:table DBTableModel Table tag of screen parts uji:list DBListModel List tag of screen parts

To use the database linkage function, you must have JDBC drivers.For details, see Required Software.For information on required files and settings for execution of the application,see Setting Up the Web Application Execution Environment.

16.2 Database Linked Applications

The procedure for creating a database linked application is shown below.

Defining the application class Create an application class by inheriting the DBApplicationProfile class.

public class MyApplication extends com.fujitsu.uji.database.DBApplicationProfile

{

}

Use the registDBConnectionInfo method to register connection information.Register the database connection information in the initDBApplication method.

public class MyApplication extends com.fujitsu.uji.database.DBApplicationProfile {

227

public MyApplication() {

}

public void initDBApplication(){

// If JDBC1.0 is used

registDBConnectionInfo("connection1", // Connection name

"username", // User name

"password", // Password

"fujitsu.symfoware.jdbc.RDADriver", // JDBC driver

"jdbc:symforda://host:2002/db_env");// Connected URL

/*

// If JDBC2.0 is used

registDBConnectionInfo("connection1", // Connection name

"username", // User name

"password", // Password

"com.fujitsu.symfoware.jdbc2.jndisp.SYMContextFactory",

// JNDI factory

"SYM://server", // Connected URL

"jdbc/Symfoware"); // JNDI name

*/

}

}

Use of the database linkage function requires the use of a user-defined application class.For details on how to define the application class, refer to Webcoordinator Session Management.

Defining Data Bean Create a database linkage class as a property of Data Bean.

import com.fujitsu.uji.database.*;

public class MyBean extends com.fujitsu.uji.DataBean

{

protected DBTableView dbView;

public DBTableView getDbView() {

228

return dbView;

}

public void setDbView(DBTableView dbView) {

this.dbView = dbView;

}

}

In the database linkage class, specify the connection and search method obtained from the application class.


DBApplicationProfile app = (DBApplicationProfile)context.getApplicationProfile();

DBConnectionInfo conn = app.getDBConnectionInfo("connection1");

DBTableView dbView = new DBTableView(conn);

try {

dbView.query("SELECT * FROM TABLE");

}catch(SQLException e) {

}

MyBean bean = new MyBean();

bean.setDbView(dbView);

context.setResponseBean("body", bean);

}

Creating an input-output page Use of the component tag to create an input-output page.

<uji:useBean id="body" />

<FORM>

<uji:tableView bean="body" property="dbView" />

...

</FORM>

Define the color and input fields as attributes of the component tags.

<uji:tableView bean="body" property="dbView"

headerBackground="yellow"

229

dataEditable="false;false;false;false;true"

/>

Updating data Use the update method of the database linkage class to register input data in the database.

DBTableView dbView = dataBean.getDbView();

try{

dbView.update();

}catch(SQLException e){

}

Lines can be added or deleted by specifying such lines and then executing the update method.

// Add

dbView.addRow(1);

... // Enter lines by displaying them on the screen

// Delete

dbView.removeRow(4);

// Registered in the database

try{

dbView.update();

}catch(SQLException e){

}

Controlling connections Specify the number of pool connections in the Web application environment definition file (web.xml).

<web-app>

<context-param>

<param-name>uji.database.connection.maxpoolsize</param-name>

<param-value>30</param-value>

</context-param>

<context-param>


<param-value>MyFactory</param-value>

</context-param>

230

<taglib>

<taglib-uri>uji-taglib</taglib-uri>

<taglib-location>/WEB-INF/ujiall.tld</taglib-location>

</taglib>

</web-app>

231

232

Chapter 17 Linkage to Applets

17.1 Overview

The applet linkage feature facilitates creation of Webcoordinator applications for which applets are used as front ends.

Applet linkage provides the following functions: · Servlets can distribute data sent from applets to methods of business classes. · APIs can be used to easily implement data transmission to and from applets

· This manual describes parts of a linkage between an applet and Webcoordinator

application and explains how to create Webcoordinator applications. For the method of creating applets, refer to the Apworks manuals.

· To use the Netscape as a client, use Java Plug-in.

17.2 Applications with Applet Linkage

An application with linkage to an applet sends and receives data as shown below.

233

1. The application sends a data Bean and command from an applet to a server by using the

com.fujitsu.uji.ext.UjiServletConnection class. 2. A servlet on the server receives the data Bean and command, and then passes them to business logic

according to the command map. 3. The business logic handles the received data Bean according to user-defined processing, and then returns

results with a data Bean. 4. The com.fujitsu.uji.ext.UjiServletConnection class receives the returned data Bean. As shown in the above figure, an application with linkage to an applet consists of a server application created as a servlet and a client applet created using an applet. The server application consists of the following files: · Servlet class · Data Bean · Business class · Command map You can use the functions listed below in the same way that they are used in general Webcoordinator applications. For details, see Major Components of Apcoordinator Applications. · Extensions of the factory class · Extensions of the application class · Extensions of the session class A client applet consists of the following files: · Applet class · Data Bean

17.2.1 Creating a Server Application

The procedure for creating a server application is given below. This section describes only the procedure specific to applet linkage. The overview of each file and explanation of how to create files are the same as those for general Webcoordinator applications. For details, see Major Components of Apcoordinator Applications.

Defining a servlet class Create a servlet class by inheriting the ObjectSerializeServlet class.

public class MainServlet extends com.fujitsu.uji.http.ObjectSerializeServlet {

234

public MainServlet() {

super();

}

}

Defining data Beans Data Beans must be serializable. The com.fujitsu.uji.DataBean class is serializable. All objects referred to by user-defined data Beans must be serializable. For details, refer to Java2 SDK documentation.

Defining a business class Methods in this business class must return the classes that inherit com.fujitsu.uji.DataBean.

public Object doSomething(com.fujitsu.uji.DispatchContext context, com.fujitsu.uji.DataBean dataBean){

// Code business logic.

return MyDataBean;

}

Defining a command map Define a command map in the same way as a command map for a general Webcoordinator application.

17.2.2 Creating a Client Applet

This section explains how to create a client applet.

Enabling communication between a client application and a server application To enable communication between a client application and a server application from the applet class, use com.fujitsu.uji.ext.UjiServletConnection. Use the following procedure:

1. Create the com.fujitsu.uji.ext.UjiServletConnection object by specifying the destination URL in an argument.

2. Create a data Bean to be sent. 3. Use the invoke method of the com.fujitsu.uji.ext.UjiServletConnection object to communicate with

the servlet. 4. Cast java.io.Object sent from the servlet to the user-defined data Bean.

The following is an example of coding according to the above procedure:

import java.net.URL;

import com.fujitsu.uji.ext.UjiServletConnection;

// Create the destination URL as a java.net.URL object.

URL url = new URL("http://somehost/myServlet");

// UjiServletConnection object

UjiServletConnection conn = null;

235

// Create a data Bean to be sent.

MyDataBean bean = new MyDataBean();

// Obtain data from the applet.

bean.setName(field.getText());

// Establish communication with the servlet, and obtain a return value.

try{

// Generate the UjiServletConnection object with the destination URL.

conn = new UjiServletConnection(url);

// Send the data Bean and command.

bean = (MyDataBean)conn.invoke(bean, "doSomething");

} catch(Exception e){

// Code communication error handling.

}

17.3 Session Management

17.3.1 Cookie Policy

The applet linkage function uses cookies to manage sessions. The function has some limitations even though cookies are supported in Java Plug-in 1.3 and Java Plug-in 1.4, both of which are supported by the function. For information on the cookie support function of Java Plug-in, refer to Java Plug-in documentation. For information on using JBK Plugin, refer to the appropriate JBK Plugin manuals.

17.3.2 Session Management When JBK Plugin is Used

When JBK Plugin is used, the life cycle of a session is the same as that of the UjiServletConnection object.To always maintain the same session in an applet, make the life cycle of UjiServletConnection the same as that of the applet. To maintain the same session during a transition from a JSP screen to an applet screen, it is necessary to obtain a cookie from a browser and to set it in UjiServletConnection.In this case, using the com.fujitsu.uji.ext.PluginUtility class allows cookies to be easily obtained from browsers. An example is shown below.



/*

* Initialization

*/

protected void initUser () {

try{

236

// Generate a UjiServletConnection object.

conn = new UjiServletConnection();

conn.setURL(new URL("http://somehost/myServlet"));

// Obtain a cookie from a browser, and set it in the UjiServletConnection object.

String cookie = com.fujitsu.uji.ext.PluginUtility.getCookieFromBrowser(this);

// Fetch the cookie to be set.

// Here, all cookies are set in UjiServletConnection.

if(cookie != null && cookie.length() != 0){

conn.setCookie(cookie);

}

// Generate the data to be sent.

MyBean reqBean = new MyBean();

MyBean resBean = (MyBean)conn.invoke(reqBean,"verb");



}

}

When a JBK Plugin is used, the session can be disconnected explicitly.To disconnect a session from an applet, use the clearCookie method of the UjiServletConnection class.



protected void method() {

try{

// Generate the UjiServletConnection object.

conn = new UjiServletConnection();

conn.setURL(new URL("http://somehost/myServlet"));

// Disconnect the session explicitly.

conn.clearCookie();

// Generate the data to be sent. A session is created.

MyBean reqBean = new MyBean();

MyBean resBean = (MyBean)conn.invoke(reqBean,"verb");



237

}

}

Explicit session disconnection is valid only for JBK Plugin. When Java Plug-in is used, a session using the UjiServletConnection class cannot be disconnected explicitly.

17.4 Setting Up the Execution Environment

Deploy a server application created using the applet linkage feature in the same way that a general Webcoordinator application is deployed. For more information on how to deploy a Webcoordinator application, see Setting up the Web Application Environment. This section is about the client applet execution environment. The following three files are required in order to run a client applet:

Applet class or jar file that includes an applet class Created applet class. If multiple class files are used, compress them and place them in a JAR file.

HTML file HTML file with tags for displaying an embedded applet For information on how to code such HTML files, refer to Java Plug-in documentation.

ujiapplet.jar Library to be distributed to clients. This library includes UjiServletConnection and DataBean. This library is installed in [apcoordinator-installation-folder]¥redist¥applet. ujiapplet.jar is a file that can be distributed again. It can be used by distributing it in the client environment.

To use JBK Plugin, do not include uji.jar in the classpath of the client. For information on how to define a client classpath, refer to the JBK Plugin manuals.

238

Chapter 18 Notes on Designing an Application

18.1 Specifying a Data Bean

To specify a data Bean that receives screen data using the JSP, either the uji.id request parameter or uji.bean request parameter be used. Use an appropriate parameter for the application.




<INPUT name="uji.bean" type="hidden" value="sample.BodyBean">

....

</FORM>

uji.id The uji.id tag is specified using the setResponseBean method of the DispatchContext class. It specifies data in the data Bean held by the server. uji.id has the following advantages:

· uji.id uses the existing data Bean and requires no excessive processing. This improves the application's efficiency.

· Data can be specified in a data Bean having a composite structure that uses a screen part. Note the following when using uji.id:

· When a timeout occurs or the Back button of the browser is used, the data Bean held by the server may fail to be associated with the screen. When the Back button is used, the command map is referenced using the type and screen button name of the data Bean held by the server. Therefore, the designated business class might not be called.

· When the uji:useBean tag is used to specify request="false", the data Bean held by the server is deleted. request="true" must be specified.

uji.bean The uji:bean tag generates a data Bean whenever an HTTP request is issued. uji:bean has the following advantage:

· Because uji:bean generates a data Bean for each request, it can operate for a timeout or the Back button of the browser being used.

Note the following when using uji:bean: · Any other classes inside Data Bean must be generated by the constructor of Data Bean. If screen

parts are used, classes must be generated by matching the number of repetitions. In a class that implements an interface (such as ComboBoxModel or TableViewModel) of item classes, classes inside it must also be generated by the constructor.

· A screen part class (class installing TableModel or ListModel) that has a value other than "String" cannot be used.

Concurrent use of uji.id and uji.bean When both uji.id and uji.bean are specified, the data Bean held by the server is searched for first. If the data Bean matches the class specified in uji.bean, the data Bean is used. If the data Bean held by the server cannot be found, a data Bean is generated. Concurrent use has the following advantages:

· When the data Bean held by the server is available, the uji.id advantages are effective. · Effective for a timeout or Back button of the browser.

Note the following point when concurrently using uji.id and uji.bean: · When a data Bean is generated for a request, the notes about uji.bean apply.

239

18.2 Character Encoding of Send Data

Webcoordinator enables explicit specification of which character encoding is used for data sent from the browser.

The following three methods can be used to specify character encoding:

Specify the character encoding for each form. The character encoding can be specified by adding a uji.encoding request parameter to each form. For details, refer to the uji.encoding request parameter tag reference.

Specify the encoding for all forms together (using API). The character encoding for all forms can be specified together by overriding the getRequestEncoding method of the ApplicationProfile class. For details, refer to the API Specification.

Specify the encoding for all forms together (using the Web application environment definition file). Using the uji.defaultEncoding parameter of the Web application environment definition file, the character encoding of all forms can be specified together. For details, refer to the Web application environment definition file.

If character encoding is specified by multiple methods, it is enabled according to the following order of priority: 1. uji.encoding request parameter 2. getRequestEncoding method of the ApplicationProfile class 3. uji.defaultEncoding initialization parameter in the Web application environment definition file

240

Chapter 19 Defining the Web Application Environment

19.1 Files Required at Execution

This section describes the files required for executing a Webcoordinator application. For JavaServer Faces application, refer to the "JavaServer Faces User's Guide".

Tag Library File

The tag library file defines the Webcoordinator UJI tags. The tag library file is in the lib folder under the Webcoordinator installation folder and must be copied to the environment (WEB-INF) of each application. The following table lists the names of the tag library files:

Tag library name Function

ujiall.tld Tag library file of the UJI tag

Execution-time Library

There are the libraries in the Webcoordinator application at the following. They are installed in the "lib" folder of the installation folder of Apcoordinator. The Webcoordinator execution-time library is available when Webcoordinator is installed. Specify the run-time library in the class path.

Library file name Function

uji.jar The library which is offered basic function of Apcoordinator core and Webcoordinator. Library of the general functions of Webcoordinator

ujidb.jar Library for the database linkage function

Web Application Environment Definition File (web.xml)

The Web application environment definition file defines the Web application environment. Specify the following information in this file:

Application context parameters

Initialization parameters

Tag library location

Servlet mapping An example of web.xml is given below.


<!DOCTYPE web-app

PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"

"http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>

<context-param>


241

<param-value>sample2.Sample2Factory</param-value>

</context-param>

<servlet>


<servlet-class>updown.DownloadServlet</servlet-class>

</servlet>

<servlet-mapping>


<url-pattern>/download</url-pattern>

</servlet-mapping>

<taglib>



</taglib>

</web-app>

The context parameter of the application is defined with the context-param tag. You can get the defined value in the getInitParameter method of the javax.servlet.ServletContext class. The application context parameter can be obtained using the getInitParameter method of the javax.servlet.ServletContext class.

The initialization parameter which Webcoordinator uses is defined with the context-param tag. Refer to the initialization parameters for the list of the initialization parameters. Use names other than the initialization parameters for the context parameter used by the application.

Files Required at Execution

When you use the following functions, you need the software separately.Refer to Files Required at Execution. · Linkage to Databases · XML Linkage Function · Invocation of Web Service

19.2 File Allocation at Execution

This section describes the general file allocation when a Webcoordinator application is executed.

JSP files Generally, allocate the JSP files to the application folder. These files can be allocated to a subfolder. In this case, consider the JSP file path used in a page map or other JSP files.

242

User files Static documents, for example, images can be allocated to the application folder or a subfolder.

Apcoordinator files Allocate the relationship definition file or tag library file to the WEB-INF folder. The WEB-INF folder is a special folder for allocating Web application information. This folder cannot be referenced directly from the client.

Web application environment definition file(web.xml) web.xml must be allocated to the WEB-INF folder.

User-defined class files Allocate the user-defined class files to the WEB-INF classes folder according to the package hierarchy. For example, allocate SampleHandler.class of the sample package to WEB-INF¥classes¥sample.

User-defined jar files Allocate the user-defined jar files to the WEB-INF lib folder.

19.3 Using Multiple Relationship Definition Files

Webcoordinator can use multiple relationship definition files. Create commands.map and pages.map folders. Allocate relationship definition files having other names to the folders. All files in the folders are used as the command map or page map.

This function facilitates addition of the relationship definition files when functions are added to the application.

243

244

Part 4 Developing EJB Applications

245

246

Chapter 20 Overview

The framework provided by Apcoordinator for EJB applications can be divided into the following two categories: · Functions for developing session Beans (Bccoordinator) · Functions for invoking EJBs (Apcoordinator core) Bccoordinator enables development of session Beans that use the framework provided by Apcoordinator.Use of Apcoordinator has the following advantages: · Session Beans can be developed using the same process as that used for Web applications. · Web applications and session Beans built using Apcoordinator are automatically capable of mutually

transferring information about individual sessions. · Data can be converted to the HashMap class before being sent to a Web application built using

Apcoordinator. During the conversion, properties can be filtered and selected so that only the properties required for the relevant session Beans are sent.

The Apcoordinator core provides functions for invoking EJBs from Web applications, session Beans, and SOAP server applications built using Apcoordinator. The Apcoordinator core provides the following functions: · Function for invoking session Beans developed using Apcoordinator: You can invoke a session Bean with a

data Bean and command name specified as arguments. Use APIs provided by Apcoordinator to invoke session Beans.

· Support function for invoking general EJBs: You can invoke EJBs by using home interfaces and remote interfaces. Apcoordinator provides APIs that implement the acquiring of home interfaces and remote interfaces by the use of simple coding.

Components of Session Beans

An Apcoordinator session Bean consists of the following components.

Business class

A Java class that performs processing on the session Bean. Command map

File that lists the relationships between the data Bean class and command name pairs and the names of the business class methods to be invoked.

Session Bean class The class that receives request from a client and requests Apcoordinator to process it.

Home interface An interface used to create and remove EJB objects. This is used by EJB clients.

247

Remote interface An interface used to invoke a method of an EJB object. This is used by EJB clients.

Develop also the following components if necessary. Data Bean

Java class that stores data input from a client or data to be output from a session Bean. Session class

A class used to retain data used by the session. To store data specific to an application in a session class, create a user-defined session class.

Application class A class used to store data shared by the objects of session Beans that operate on one JVM. To store data specific to an application in an application class, create a user-defined application class.

Factory class The factory class creates an instance of an application class or session class. To use a user-defined application class or session class, create a user-defined factory class.

Process of Invoking Session Beans

The following figure describes the process of invoking session Beans developed using Apcoordinator. Components that do not directly concern the process are omitted in the figure.

1. A client invoke a session Bean with a data Bean and a command as arguments. 2. The session Bean receives the data Bean and the command. 3. In the session Bean, the command map is searched for a business class method corresponding to the pair

of the data Bean and the command, and the method found in the command map is invoked. 4. The business class method performs a process, stores the result into a data Bean, and return the data

Bean. 5. The client receives the returned data Bean. To invoke a session Bean developed using Apcoordinator from an Apcoordinator application, you can use the following functions: · Session data synchronization: Automatically transfers data stored in the session class between the client

and the session Bean.

248

· Data Bean conversion: Converts a data Bean to the HashMap class before it is sent to the session Bean.

Item classes included in the data Bean are converted to basic data classes such as String and Integer or arrays of either. When you use data Bean conversion, you can also use filtering of properties. The filtering allows you to select and send only properties required for the session Bean. You can select and send data required for the session Bean without sending all properties included in the data Bean.

· Data I/O using the HashMap class: To input data from and output to the client, a session Bean can use

the HashMap class instead of a data Bean. The data Bean conversion described above requires this function.

· Local invocation: A local call allows a session Bean to be executed on the JVM of the client. This function facilitates debugging of applications.

Developing a Client

For information on developing a EJB client, see the following sections.

249

250

Type of client application Type of EJB Section to be referred to

A session Bean developed using Apcoordinator

Unified Remote Interface Calling Session Beans Developed Using Apcoordinator

Apcoordinator application

A general EJB Calling a General EJB

Non-Apcoordinator application

A session Bean developed using Apcoordinator

Linkage to Non-Apcoordinator Clients

Chapter 21 Developing Session Beans

21.1 Creating Session Beans

To develop a session Bean, create the following files: · Session Bean class · Home interface · Remote interface · Command map · Business class · Deployment descriptor (ejb-jar.xml) · ejb-jar Create the following classes, if necessary: · Data Bean · Factory class · Application class · Session class

21.1.1 Creating Java Source Files and Relationship Definition Files

Session Bean Class

Create a session Bean class by inheriting the com.fujitsu.uji.ejb.bean.UjiSessionBean class. You do not have to add any methods. The following is a coding sample of a session Bean class named ejboffice.ejb.OfficeEJB:

package ejboffice.ejb;

import com.fujitsu.uji.ejb.bean.UjiSessionBean;

public class OfficeEJB extends UjiSessionBean {

}

Home Interface

Create a home interface by inheriting the com.fujitsu.uji.ejb.UjiSessionHome interface. Create the create() method as follows:


import com.fujitsu.uji.ejb.UjiSessionHome;

public interface OfficeEJBHome extends UjiSessionHome {

public OfficeEJBRemote create()

throws java.rmi.RemoteException, javax.ejb.CreateException,

java.lang.reflect.InvocationTargetException;

}

Code the signature of the create() method as follows:

251

public [the name of the remote interface] create()

throws java.rmi.RemoteException, javax.ejb.CreateException, java.lang.reflect.InvocationTargetException;

In the above signature, replace [the name of the remote interface] with the name of your remote interface.

Remote Interface

Create a remote interface by inheriting the com.fujitsu.uji.ejb.UjiSession interface. You do not have to add or define any methods.


import com.fujitsu.uji.ejb.UjiSession;

public interface OfficeEJBRemote extends UjiSession {

}

Business Class

Set methods in which processing to be executed in the session Bean is coded in business classes. The following is a coding sample of a business class:


import ejboffice.*;


public class OfficeHandler extends com.fujitsu.uji.GenericHandler {

// Define a method to be invoked when the session Bean receives

// a request from the client.

// The second argument is a data Bean received from the client.

public Object search(DispatchContext context, ViewBean dataBean) {

// Describe the process

int index=dataBean.getIndex();

...

dataBean.putHeader(header);

252

// Specify the return object

return dataBean;

}

// Define other methods, if necessary

...

}

For information about how to create a business class, see Business Class.The following describes business classes specific to a session Bean: · The type of return values for the methods must be set to Object. Use the return statement of the method

for objects to be returned from the session Bean to the client. · Objects that the business class receives from the client and objects the business class returns must

comply with the rules for RMI over IIOP. For the rules, see Objects Usable as Arguments or Return Values of EJBs.

Command Map

In the command map, specify methods of the business classes that are to be invoked for data received from a client. The following is a coding sample:

ejboffice.ViewBean;getArea=ejboffice.ejb.OfficeHandler.getArea

ejboffice.ViewBean;search=ejboffice.ejb.OfficeHandler.search

ejboffice.RenewBean;find=ejboffice.ejb.OfficeHandler.find

ejboffice.RenewBean;update=ejboffice.ejb.OfficeHandler.update

The first line of the above sample means the following.

Invoke the getArea method of the ejboffice.ejb.OfficeHandler class, if a data Bean received from a client is the ejboffice.ViewBean class and the received command is "getArea".

For information about coding a command map, see Command Map.

Session Class

The session class is used to retain data used by the session. Data stored in a session class remains as long as an object of the session Bean exists even though execution of the business class has ended. To store data specific to an application in a session class, create a user-defined session class.For information about how to create a user-defined session class, see Session Class.

Application Class

The application class stores data shared by the objects of session Beans that operate on one JVM. Data stored in the application class is accessed by objects of other session Beans. To store data specific to an application in an application class, create a user-defined application class.For information about how to create a user-defined application class, see Application Class.

Factory Class

The factory class creates an instance of an application class or session class. To use a user-defined application class or session class, create a user-defined factory class, then specify the name of the class using initialization parameters.For information about how to create a factory class, see Factory Class. For information about how to set initialization parameters, see Setting Up Session Bean Initialization Parameters.

253

21.1.2 Setting Up Session Bean Initialization Parameters

Parameters that set up the operation of applications created using Apcoordinator are invoked initialization parameters. For a list of the initialization parameters, see Initialization Parameters. There are two ways to specify initialization parameters: · Use the deployment descriptor: The initialization parameters are defined as entries of the enterprise

Bean environment. Specify the name of an entry in uji/xxx format. "xxx" indicates the name of an initialization parameter. As the entry type, specify java.lang.String. The values of the entries can be changed when the session Bean is deployed in an EJB container. Fujitsu recommends using this method to specify initialization parameters, such as logLevel parameter (used for log output level setting), that might be changed after the program is compiled.

· Use a session Bean class: Override the getInitParameters method of the UjiSessionBean class, then store the initialization parameters in the Properties class as follows:

import com.fujitsu.uji.ejb.bean.*;

import java.util.Properties;


protected Properties getInitParameters() {

Properties p=new Properties();

// Specify a user-defined factory class.

p.setProperty("factory","ejboffice.ejb.OfficeFactory");

return p;

}

}

Fujitsu recommends using this method to specify initialization parameters, such as the factory parameter (for specifying a factory class), that are not likely to be changed once the program has been compiled.

21.1.3 Deployment Descriptor (ejb-jar.xml)

The deployment descriptor is an XML file in which the configuration and settings of an EJB are coded. Specify the following information in a deployment descriptor:

Setting item Deployment descriptor tag Value to be set

EJB name ejb-name Name assigned to the session Bean. When multiple EJBs are stored in one ejb-jar, assign an unique name to each EJB.

EJB class ejb-class Name of the session Bean class

Home interface home Name of the home interface

Remote interface remote Name of the remote interface

Session Bean type session-type Stateful or Stateless

Transaction management type

transaction-type Specify Bean for Bean-managed transaction demarcation. Specify Container for container-managed

254

Setting item Deployment descriptor tag Value to be set

transaction demarcation.

For information about how to create a deployment descriptor, see the manuals of the development environment, such as Apworks. The following is a coding sample of a deployment descriptor:


<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"

"http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

<ejb-jar>

<enterprise-beans>

<session>

<display-name>OfficeEJB</display-name>

<ejb-name>OfficeEJB</ejb-name>

<home>ejboffice.ejb.OfficeEJBHome</home>

<remote>ejboffice.ejb.OfficeEJBRemote</remote>

<ejb-class>ejboffice.ejb.OfficeEJB</ejb-class>

<session-type>Stateful</session-type>

<transaction-type>Container</transaction-type>

</session>

</enterprise-beans>

<assembly-descriptor>

<container-transaction>

<method>

<ejb-name>OfficeEJB</ejb-name>

<method-name>*</method-name>

</method>

<trans-attribute>NotSupported</trans-attribute>

</container-transaction>

</assembly-descriptor>

</ejb-jar>

21.1.4 EJB-JAR file

ejb-jar is a JAR file that stores files required for an EJB. Store the following files in ejb-jar: · Java class files. Place these in a folder under the directory for the package. - Session Bean class - Home interface - Remote interface - Business class - User-defined session class - User-defined application class - User-defined factory class - User-defined class used for the classes above · Configuration files. Place these in the configuration file folder described later.

255

- Command map - Command scripting - Remote map - Data Bean conversion map · Deployment descriptor (ejb-jar.xml). Place this in /META-INF. The configuration file folder is determined from the name of the session Bean class as follows:

/[package-directory]/[class-name]_inf

[package-directory] is a folder under the session Bean class package, and [class-name] is the name of the session Bean class. For example, when the session Bean class is ejboffice.ejb.OfficeEJB, the configuration file folder is /ejboffice/ejb/OfficeEJB_inf.

You can change the configuration file folder using the uji.infoPath initialization parameter.

For information about how to create ejb-jar, see the manuals of the development environment, such as Apworks.

21.2 Processing Specific to Session Beans

21.2.1 Exception Handling

The following two types of exceptions that occur during execution of EJBs have been defined in the specifications of EJBs: · Application exception, which is reported to the client. Every exception that satisfies all of the following

conditions is an application exception. - The exception is a subclass of java.lang.Exception. - The exception is not a subclass of java.lang.RuntimeException. - The exception is not a subclass of java.rmi.RemoteException. · System exception, which indicates an unrecoverable exception that prevents processing from continuing.

The EJB container receives a system exception, and the object of the EJB in which the system exception occurred is deleted. Every exception that satisfies both of the following conditions is a system exception:

- The exception is not an application exception. - The exception is not a subclass of java.rmi.RemoteException. Exceptions that occur in a business class are classified and handled as described above. · Application exceptions are reported to the client. · System exceptions are reported to the EJB container. Accordingly, the object of the session Bean is

deleted. However, when the business class is using a Postprocessor interface, exceptions are handled by the handleException method. If an exception occurs in the handleException method, the exception is classified and handled as described above. For information about the handleException method, see Error Processing.

To report system exceptions that occur in session Beans to the client for debugging purposes,set "client" for the uji.informSystemException initialization parameter. Under this configuration, system exceptions are reported to the client instead of to the container and the session Bean object is not removed when system exceptions occur.For normal operation, set "container" for uji.informSystemException so that system exceptions are reported to the EJB container.

21.2.2 Referencing the Enterprise Bean Environment

You can get the enterprise Bean environment (value defined by <env-entry> in the deployment descriptor) using the getEnvironment method of EJBDispatchContext.The following program is an example of a business class that uses the enterprise Bean environment.

import com.fujitsu.uji.ejb.bean.EJBDispatchContext;

...

public Object search(DispatchContext context, HashMap data) {

// / /

256

enterprise Bean environment

Integer i = (Integer)((EJBDispatchContext) context).getEnvironment("initialCount");

...

}

To use the EJBDispatchContext method, cast DispatchContext assigned to the first argument of the method of the business class to EJBDispatchContext.

As the argument of the getEnvironment method, specify the name of an entry, excluding java:comp/env/. In the example above, the value of java:comp/env/initialCount is obtained.If the specified name has not been defined, null is returned.

You can get the enterprise Bean environment using IniticalContext the same way as for a general EJB. The advantage of the getEnvironment method is that you can get the enterprise Bean environment even if it is invoked by a local invocation.

21.2.3 Getting SessionContext

EJB containers gives objects with the javax.ejb.SessionContext interface implemented to session Beans. To get SessionContext, use the getEJBContext method of EJBSessionProfile. The following is a coding sample for invoking the method using a business class:

import com.fujitsu.uji.ejb.bean.EJBSessionProfile;

import javax.ejb.SessionContext;

public Object search(DispatchContext context, HashMap data) {

EJBSessionProfile sp = (EJBSessionProfile)context.getSessionProfile();

SessionContext sessionContext = (SessionContext)sp.getEJBContext();

}

The type of the return values of the getEJBContext method is EJBContext, which is the super-interface of SessionContext. Cast it to SessionContext before using it.

To use the EJBSessionProfile method, get the session class using getSessionProfile of DispatchContext, then cast it to EJBSessionProfile.

21.2.4 Object Life Cycle

The following table shows the lifecycles for the application class, session class, and business class:

Class Its instance is created: The instance is valid: Remarks

Business class (when the init method returns true)

When the business class is first invoked with a invocation from a client after an object of the session Bean has been created

Until the session Bean object is deleted from the EJB container

257

Class Its instance is created: The instance is valid: Remarks

Business class (when the init method returns false)

When the business class is invoked with a invocation from a client

Until the invocation from the client ends.

An instance is created whenever a invocation to the business class is made from a client.

Session class

When an object of the session Bean is created (i.e., when the ejbCreate method of the session Bean is invoked)

Until the session Bean object is deleted from the EJB container

Application class

When an object of the session Bean is first created in the JVM (i.e., when the ejbCreate method of the session Bean is first invoked in the JVM)

Until all session Bean instances are deleted from the EJB container

One instance is shared by multiple session Bean objects existing in one JVM.

If you use a statefull session Bean, one session Bean corresponds with one client. Therefore one business class instance is invoked by one client.On the other hand, if you use a stateless session Bean, one session Bean can correspond with many clients.Therefore one business class instance can be invoked by two or more clients one by one.

21.2.5 Using a User-Defined Business Method

Session Beans created using Apcoordinator have one business method, whose name is exec.If you need to use another business method with a transaction and other attributes different from those in exec, do the following: · Add a user-defined business method to the session Bean class. · Add a remote interface to the additional business method. · Specify different transaction attributes for the exec method and a user-defined business method in the

deployment descriptor. · Specify the name of the method for each invocation to the session Bean from a client. Code a session Bean class with a user-defined business method added as follows:


import java.lang.reflect.InvocationTargetException;


public Object[] myExec(Object dataBean, String verb, Object syncData) throws InvocationTargetException {

return exec(dataBean,verb,syncData);

}

}

In the sample above, the business method myExec is added. Use the argument types of the method, the return value types, and the throws statement shown in the sample above in user-defined business methods. In addition, as shown in the example above, create user-defined business methods so that exec is invoked and values are returned. The exec method has been defined in the UjiSessionBean class.

To invoke a user-defined business method from a client, specify the name of the method as follows: · Invoke the session Bean using EJBCallFactory: Use the invokeMethod method instead of the invoke

method of the UjiSessionCall class. Specify the name of the method as the first argument.

258

UjiSessionCall call=...;

call.invokeMethod("myExec",dataBean,verb);

· Invoke the session Bean using the remote common interface: Cast the Call interface to the UjiSessionCall class, then invoke it in the same way as described above.

Call call=...;

((UjiSessionCall)call).invokeMethod("myExec",dataBean,verb);

For information about the basic procedure for invoking session Beans, see Calling EJBs.

21.3 Linkage between Session Bean and Client

21.3.1 Session Data Synchronization

The session synchronization feature enables the automatic exchange of data contained in the session class of a client with the data contained in the session class of a session Bean when a call is made to the session Bean from the client.

When a session Bean is called, the data contained in the session class of the client is transferred to the session Bean then set in its session class. When the call to the session Bean ends, data contained in the session class of the session Bean is transferred to the client then set in its session class.

To use the session synchronization feature, create a session class for the client and a session class for the session Bean as follows: · Session class for client

Create a user-defined session class. Set com.fujitsu.uji.ejb.SynchronizedDataHolder interface for the

259

session class, then create the getSynchronizedData method and setSynchronizedData method. Create the getSynchronizedData method so that objects are returned from the client to the session Bean. The setSynchronizedData method is called when an object received from the session Bean is set in the session class. Create the method so that the object in the argument is kept in the session class. The following is a coding sample:

import com.fujitsu.uji.ejb.SynchronizedDataHolder;

public class MyHttpSession extends HttpSessionProfile implements SynchronizedDataHolder {

protected MySyncObject syncData;

public Object getSynchronizedData() { return syncData; }

public void setSynchronizedData(Object data) { syncData = data; }

}

· Session class for session Bean Create a user-defined session class, then override and create the getSynchronizedData method and setSynchronizedData method in the same way for creating the session class for the client. Create the getSynchronizedData method so that objects are returned from the session Bean to the client. The setSynchronizedData method is called when an object received from the client is set in the session class. Create the method so that the object in the argument is kept in the session class. Because the com.fujitsu.uji.ejb.SynchronizedDataHolder interface has been declared in the implements statement of the session class for the session Bean EJBSessionProfile class, you do not have to add SynchronizedDataHolder to the implements statement in the user-defined class.

Data to be transferred between a client and session Bean must comply with the rules of RMI over IIOP. For information about the rules, see Objects Usable as Arguments or Return Values of EJBs.

21.3.2 Local Invocation

Although session Beans created using Apcoordinator usually operate in EJB containers, you can use them on a JVM on which the client operates. This function is called "local call".

When you use a local invocation when developing session Beans, you can debug the session Beans without placing them in EJB containers, increasing development efficiency.

To use a local invocation, create a program for client as follows: · Use the remote common interface to invoke a session Bean. · Define an alias of a session Bean to which a local invocation is made in the remote map using the local

tag.Specify the session Bean class for the class attribute. See the following coding sample:

<local name="MyLocalSessionBean" class="mypackage.MySessionBean"/>

· If the session Bean to be invoked uses the enterprise Bean environment, define the enterprise Bean environment in the content of the local tag. Do so using the following procedure:

- Copy all the env-entry tags and their content defined in the session Bean by the deployment descriptor to the local tag in the remote map.

- Each env-entry tag is used to represent an entry of the enterprise Bean environment, and the env-entry-name tag is used to indicate the name of the entry. To change the value that corresponds to the entry name, specify the value in the content of the env-entry-value tag. If there is no env-entry-value tag, add one.


260

<local name="MyLocalSessionBean" class="mypackage.MySessionBean">

<env-entry>




</env-entry>

</local>

To make switching between a local call and a general call easy, code the remote map as shown below. You can switch between them by specifying "ejb" for the name of the local tag or the other.

<local name="MyLocalSessionBean" application="java:comp/env/ejb/MySessionBean"

class="mypackage.MySessionBean">

<env-entry>




</env-entry>

</local>

When a local call to a session Bean is used, the following restrictions are placed on the session Bean: · No functions provided by the EJB container can be used. For example, the SessionContext object,

transaction control, and access restrictions on methods cannot be used. · InitialContext used for the client is also used for the session Bean. The operation of the following method when a local call is made is different from its when a general call is made: · The getEnvironment method of the EJBDispatchContext class. This method obtains the value of the

enterprise Bean environment. For general calls, it gets the value using the JNDI. For local calls, it gets the value defined in the remote map of the client.

21.3.3 Data Bean Conversion

Data Bean conversion changes a data Bean to the java.util.HashMap class when a call is made to a session Bean, then sends it. Item classes contained in the data Bean are converted to fundamental data classes, such as String and Integer or their arrays. When the session Bean returns HashMap, HashMap is automatically converted to a data Bean on the client.

261

Conversion from a data Bean to HashMap is called regular conversion. Conversion from HashMap to a data Bean is called reverse conversion.

Data Bean conversion enables a reduction of the amount of data to be transmitted because it deletes unnecessary data: · Data required only for display of Web page is removed from the data Bean and sent to the session Bean.

Item classes include data such as colors and fonts required to display a Web page. Such data can be automatically removed.

· Only those data Bean properties required for the session Bean need to be selected and sent. You can select the properties HashMap will contain after conversion.

When you use data Bean conversion, build a data Bean conversion map for an application invoking EJBs.Data Bean conversion map is a file used to customize the rule of data Bean conversion.If an application invoking EJBs does not have a data Bean conversion map, data Beans are not converted.

Conversion Rules of Data Beans

The tables below show how a data Bean is converted.

Data Bean to be converted

Property name Property class Property value

message String "Hello!"

info InfoBean (Data Bean)

Property name Property class Property value

count int 21

date Date 2002/4/1

choice ComboBox (item class of the combo box)

Choice No. Value Character string to be

displayed Color

1 chicago Chicago Red

2 roma Roma Green

3 helsinki Helsinki Orange

Choice 1 is being selected.

HashMap after conversion

262

HashMap key

Class of HashMap value HashMap value

message String "Hello!"

info HashMap

HashMap key

Class of HashMap value

HashMap value

count Integer 21

date Date 2002/4/1 choice Integer 1

choice.value String[] {"chicago","roma","helsinki"}

choice.text String[] {"Chicago","Roma","Helsinki"}

As shown in the tables above, data Bean conversion converts and stores properties of a data Bean in a HashMap.The properties are converted according to the rules described below. You can change the conversion rules by using the data Bean conversion map. · Primitive type: Converted to a wrapper class that corresponds to the primitive type. For example, int is

converted to java.lang.Integer. The keys used in the HashMap are the same as the names of the properties.

· Data Bean: The com.fujitsu.uji.DataBean class and its subclasses are recursively converted to the HashMap class. The keys used in the HashMap are the same as the names of the properties.

· Item class: Converted according to the rules specified by the item class. The following is a summary of the rules:

- For item classes of field tags such as FieldString (excluding CheckBox), data in the classes is stored in the HashMap. The keys used in the HashMap are the same as the names of the properties.

- For item classes of collection tags such as ComboBox and TableView and for the CheckBox class, multiple data items contained in classes are stored in the respective entries of the HashMap. The keys used in the HashMap are converted to a character string in "[property-name].[data-type]" format.

In either case, data included in the item classes regarding colors and fonts is not included in the HashMap after conversion.

· Screen part interface: ListModel and TableModel are converted to Object[] and Object[][], respectively. TreeNode is converted to a tree that consists of arrays. The elements of the list, the elements of the table, and the values of the nodes in the tree are recursively converted. For TreeModel, objects that represent a tree are retrieved from it and stored in the HashMap. In either case, the keys used in the HashMap are the same as the names of the properties.

· Array: Elements of each array are recursively converted to an array that consists of the elements. When all the resulting elements are of the HashMap class or a subclass, the converted array becomes HashMap[]. Otherwise, it becomes Object[]. The keys used in the HashMap are the same as the names of the properties.

· Other classes: Not converted and stored in the HashMapas is. The keys used in the HashMap are the same as the names of the properties.

For information about conversion of item classes and screen part interfaces, see the Data Bean Conversion Reference.

Data Type

A data type is assigned to each HashMap that is converted. The data type is a character string that indicates the type of data stored in the HashMap, and is used to do the following: · Determine a class to which a HashMap returned from a session Bean is to be converted during reverse

conversion to the data Bean. · Determine a business class to be called when a session Bean receives a HashMap. The data type is stored in the HashMap as the String value that corresponds to the key "uji.type".

Data Bean Conversion Map

The data Bean conversion map is a file used to specify how data Beans and item classes are to be converted. In a data Bean conversion map, you can do the following:

263

· Specify the data type of each class of data Beans after they are converted to HashMaps. · Select data Beans' properties to be sent to session Beans. · Select data to be sent to session Beans from the data included in item classes. For example, you can

specify whether choices of display character strings for TableView headers or for ComboBox are to be sent.

Code the data Bean conversion map in XML as shown below:


<convMap

xmlns="http://interstage.fujitsu.com/schemas/uji/convMap"


xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/convMap

http://interstage.fujitsu.com/schemas/uji/convmap.xsd">

<config>


</config>



<class name="mypackage.MyBean">

<beanConv target="my-Bean">

<property name="description" pass="false"/>

</beanConv>

</class>



<model name="ComboBox">

<comboBoxConv useIndex="true"/>

</model>

</convMap>

The following explains the coding sample of the data Bean conversion map above.

The root of the data Bean conversion map is convMap.Inside the convMap tag, first set the config tag, then set the version tag inside it. The version tag specifies the version of the syntax used in the data Bean conversion map. Specify 5.0.

264

<config>


</config>

After the config tag, how a data Bean and item class are to be converted is specified.

The class tag defines how a class specified with the name attribute is to be converted.



<property name="description" pass="false"/>

</beanConv>

</class>

This part specifies the following: · The mypackage.MyBean class is to be converted to a HashMap when the data Bean is sent, and its data

type is to be set to my-Bean. It also specifies that the HashMap is to be converted to mypackage.MyBean during reverse conversion to the data Bean if the data type of the HashMap is my-Bean.

· The property "description" of mypackage.MyBean is not to be sent, i.e., it is not to be stored in the resulting HashMap.

Inside the class tag, specify a tag for conversion. In this sample, the BeanConv tag is used. This tag specifies that the data Bean class specified with the class tag is to be converted to a HashMap. The data type of the HashMap is specified using the target attribute. If the target attribute is omitted, the class name specified with the class tag is used for the data type.

Inside the BeanConv tag, set the property tag if necessary. This tag specifies whether the property specified with the name attribute is to be sent using the pass attribute. Setting pass="false" does not send it.To send specific properties of a data Bean, set the BeanConv tag and property tag as follows:


<beanConv target="my-Bean" passByDefault="false">

<property name="userId" pass="true"/>

</beanConv>

</class>

To switch the conversion setting according to the name of a command used to call the session Bean, specify the command name in the verb attribute of the class tag to restrict the command to which the class tag is applied:

<class name="mypackage.MyBean" verb="update">

265

<beanConv target="my-Bean"/>

</class>



<property name="userId" pass="false"/>

</beanConv>

</class>

In the sample above, when the name of the command is "update", all the properties are sent. For another command name, all properties except the userId property are sent.

The coding sample below specifies the settings for conversion of the item class com.fujitsu.uji.compo.ComboBox:


<comboBoxConv useIndex="true"/>

</model>

The model tag specifies how item classes of the type specified with the name attribute are converted. name="ComboBox" specifies the com.fujitsu.uji.compo.ComboBox class and its subclasses. Inside the model tag, set a tag for conversion. In this sample, the comboBoxConv tag is used to specify that a ComboBox is to be converted to an array of choices and display character strings. useIndex="index" specifies that choices in the ComboBox are sent using index numbers. To send them using the values of the choices, specify useIndex="value".

The following is a coding sample for sending a ComboBox and its subclasses without conversion:


<noConv/>

</model>

For more information on the following, see Data Bean Conversion Reference. · The structure of data which item classes are converted to · Tags and attributes used in a data Bean conversion map

File Name of a Data Bean Conversion Map

By default, the name of the data Bean conversion map is conv.xml.For a Web application, the data Bean conversion map is placed in /WEB-INF. For a session Bean and a SOAP server application, it is placed in the configuration file folder. The name of the file and the location where it is placed can be changed using the uji.convMap initialization parameter. When the remote common interface is used, you can specify one data Bean conversion map for each session Bean to be called. To do this, specify the name of the file in the convMap

266

attribute of the ejb or local tag in the remote map.

If uji.convMap initialization parameter is not specified,and conv.xml is not placed in the default location, data Beans are not converted.

Because data Bean conversion is handled by a client, create data Bean conversion maps on the client. To call another session Bean from a session Bean, create data Bean conversion maps in the session Bean from which the other session Bean is called.

Data Bean Overwriting

When data Bean conversion is in progress, overwriting of the data Bean is allowed. Overwriting of the data Bean does not overwrite data returned from a session Bean as is, but does overwrite a data Bean provided as an argument when the session Bean is called.

Data Bean overwriting is allowed in the following case: · Data Bean conversion is enabled, · Data Bean overwriting is enabled, and · The class of a data Bean obtained by reverse-converting data returned from a session Bean is the same as

that of a data Bean that was used when the session Bean was called. Data Bean overwriting is enabled by default. To disable it, specify either of the following settings: · When using the UjiSessionCall class to call a session Bean, specify either of the following settings: - Specify false as the third argument of the invoke method. To temporarily disable data Bean

overwriting, do this:


call.invoke(dataBean,verb,false);

- Specify false in the setOverwriteMode method of UjiSessionCall. To disable data Bean overwriting whenever the same UjiSessionCall instance is used, do this:


call.setOverwriteMode(false);

call.invoke(dataBean,verb);

267

call.invoke(dataBean2,verb2);

· When using the Call interface to make a call to a session Bean: Cast a Call instance to UjiSessionCall, then follow the same procedure used for UjiSessionCall.

Call call=...;

UjiSessionCall uCall=(UjiSessionCall)call;

uCall.invoke(dataBean,verb,false);

Notes on Using Data Bean Conversion

· To use classes implementing ListModel, TableModel, TreeModel, or TreeNode for the values of data Bean properties, specify classes with these interfaces implemented as property types. Do not specify interfaces themselves. For example, to use MyListModel with ListModel implemented, develop a data Bean class as follows:

public class MyDataBean extends DataBean {

// Use MyListModel, not ListModel, as a type of a property "list"

protected MyListModel list;

public void setList(MyListModel list) {this.list=list;}

public MyListModel getList() {return list;}

...

}

· To specify classes with ListModel, TableModel, or TreeModel implemented as a property type of a data Bean, create constructors for the classes according to the following formats:

Interface Example of a constructor Description

ListModel public MyList(MyBean[] param)

Create a constructor by setting a one-dimensional array that stores the elements of a list as the argument.If elements of the list are restricted to a specific class and its subclasses, you can use classes of list elements as classes of elements of the array. The example provided at the left shows a case in which list elements are MyBean and its subclass. If the elements are not restricted to a specific class, specify Object[] as the argument.

TableModel public MyTable(MyBean[][] param)

Create a constructor by setting a two-dimensional array that stores the elements of a table as the argument.If the elements of the table are restricted to a specific class and its subclasses, you can use classes of table elements as classes of elements of the array. The example provided at the left shows a case in which table elements are MyBean and its subclass. If the elements are not restricted to a specific class, specify Object[][] as the argument.

TreeModel public MyTree(Object param)

Create a constructor by setting a root node as the argument. The root node is an object that can be obtained using the getRoot()

268

269

Interface Example of a constructor Description

method of TreeModel. Specify Object as the type of the constructor's argument.

If the constructors are not created with the formats stated above, an error occurs during reverse conversion.

21.3.4 Inputting Data Using HashMap

When a data Bean is converted to a HashMap using data Bean conversion, the session Bean receives the HashMap, not the data Bean. In such a case, a business class method that is to be called is determined by the data type specified in the HashMap. The data type is a character string that can be obtained with get ("uji.type") for HashMap.

To use a HashMap as input data, code a command map as follows:

# commands.map

$data-view;getArea=ejboffice.ejb.OfficeHandler.getArea

$data-view;search=ejboffice.ejb.OfficeHandler.search

$renew;find=ejboffice.ejb.OfficeHandler.find

$renew;update=ejboffice.ejb.OfficeHandler.update

Code each line of the command map in the following format:

$[data-type];[command-name]=[business-class-name].[method-name]

21.3.5 Linkage to Non-Apcoordinator Clients

This section showsthe way for non-Apcoordinator clients to invoke Apcoordinator session Beans.

Exception classes of Apcoordinator must be removed from exceptions thrown by the "exec" method of the session Bean.Develop a session Bean class in the following way. · Override the "exec" method of the session Bean class, and invoke the "exec" method of the super class (i.e.,

UjiSessionBean class) from the "exec" method of the session Bean class. · Catch an InvocationTargetException thrown by the "exec" method of the super class, and throw new

InvocationTargetException which does not include exception classes of Apcoordinator. The following program is an example of a session Bean class.


import java.lang.reflect.InvocationTargetException;


public Object[] exec(Object dataBean, String verb, Object syncData) throws InvocationTargetException {

try {

return super.exec(dataBean,verb,syncData);

} catch (InvocationTargetException e) {

270

Throwable rootCause=e.getTargetException();

Exception replaced=new Exception(rootCause.getMessage());

throw new InvocationTargetException(replaced);

}

}

}

If a client invoke session Beans developed by the above wayand an error occurs in the session Bean,the client will receive an exception which is newly created by the "exec" method of the session Bean class.The exception received by the client is not one thrown by the business class.In the above example, the client will receive an "Exception" class.

A non-Apcoordinator client invokes a session Bean in the following way. 1. Get a home interface using JNDI. 2. Invoke the create method of the home interface to get a remote interface.The create method has no

argument. 3. Invoke exec method of the remote interface. The method has the following three argument. - The first argument is a data Bean or a HashMap. The specified object is given to the second

argument of a business class of the session Bean. - The second argument is a command. - The third argument is an object which is sent to the session class of the session Bean. Specify this

argument if the session Bean uses session data synchronization. The specified object will be set to the session class by setSynchronizedData method. Specify null if the session Bean does not use session data synchronization.

A non-Apcoordinator client can not use data Bean conversion. If the client invoke a session Bean which uses a HashMap as an input data, give HashMap as the first argument of the exec method.

4. The return value of the exec method is Object[]. The array has the following elements. - Index 0: a return value of the business class. - Index 1: an object sent from the session class. This element is valid when the session Bean uses

session data synchronization. The object is a return value of the getSynchronizedData method of the session class. If the session Bean does not use session data synchronization, the object is the same object as is passed as the third object of exec method.

If an application exception occurs while a session Bean is running, the exec method throws java.lang.reflect.InvocationTargetException.

The following program is an example which invokes a session Bean.In the following program, a home interface class is SimpleBeanHome and a remote interface class is SimpleBeanRemote.

import javax.naming.InitialContext;

import javax.rmi.PortableRemoteObject;

...

HashMap syncData=new HashMap(); // An object sent to and received from a session class of the session Bean

syncData.put("userId","abc1234");

...

271

// Getting a home interface

InitialContext ctx=new InitialContext();

SimpleBeanHome home=(SimpleBeanHome)PortableRemoteObject.narrow(

ctx.lookup("java:comp/env/ejb/SimpleBean"),SimpleBeanHome.class);

// Getting a remote interface

SimpleBeanRemote remote=home.create();

// Invoking a session Bean

MessageBean bean=new MessageBean();

bean.setMessage("Hello!");

Object[] replyArray=remote.exec(bean,"echo",syncData);

// Receiving the return value

MessageBean reply=(MessageBean)replyArray[0];

syncData=(HashMap)replyArray[1];

A non-Apcoordinator client needs a JAR file ujiejbcl.jar.Copy the JAR file to the execution environment of the client and add it to the classpath.ujiejbcl.jar is installed in [Install folder of Apcoordinator]¥redist¥ejb folder.

ujiejbcl.jar provides classes necessary to use the following objects. · Home interfaces and remote interfaces of a session Bean developed using Apcoordinator · Data Beans (com.fujitsu.uji.DataBean class) ujiejbcl.jar is re-distributable. You can copy the JAR file to the execution environment of the client.

21.3.6 Objects Usable as Arguments or Return Values of EJBs

A data Bean to be provided when a session Bean is called must satisfy the following conditions: · When data Bean conversion is enabled, the HashMap that has been converted from a data Bean and

objects included in it comply with the rules for RMI over IIOP. · When data Bean conversion is disabled, the data Bean complies with the rules for RMI over IIOP. Objects returned by the session Bean must comply with the rules for RMI over IIOP.

RMI over IIOP allows the following types to be used as arguments or return values of EJBs: · Primitive types of Java (int, etc.) · Objects with java.io.Serializable implemented directly or indirectly and without java.io.Remote

implemented directly or indirectly · Remote interfaces that inherit the java.rmi.Remote interface and all of whose methods (including

inherited methods) throw superclasses of java.rmi.RemoteException or java.rmi.RemoteException as exceptions

· Arrays of types that can be used for communication If any of the conditions above is not satisfied, an error occurs in the following cases when a session Bean is called: · Although a setting in the conversion map specifies that the class MyDataBean is not to be converted,

Serializable has not been implemented for it. · Conversion of the class MyDataBean to a HashMap has been specified. MyDataBean has TableView as a

property and is using the MyCell class as data in the cells of the TableView's table. Serializable has not been implemented for MyCell. (In this case, Object[][], which indicates a table, is placed in the resulting HashMap, and MyCell is made an element of its two-dimensional array. The conditions are not fully satisfied.)

272

Chapter 22 Setting Up the Session Bean Execution Environment

22.1 Deploying a Session Bean

To run a session Bean, you need to deploy it to an EJB server using the EJB server deployment tools.For details of deploying session Beans, see the documentation for the EJB server being used.For information about deploying session Beans in an Interstage environment, see Setting up a session Bean environment for Interstage.

In general, the actions below are required to deploy a session Bean. Perform these actions using the deployment tools for EJB-JAR files.

Generation of code for the container and client Have the tool generate the source code required for the EJB container and EJB client.

Registration with the EJB container: Register the session Bean with the EJB container.

Modification of the values defined in the deployment statement Modify the values defined in the enterprise Bean environment as required. In addition, if the session Bean invokes other EJBs, associate the EJB references defined in the deployment statement with the EJBs running in the execution environment.

For deployment, you need to set classpaths so that, using the deployment tools, the following Apcoordinator libraries can be referenced: · uji.jar · ujiejb.jar

22.2 Setting Up Execution Classpaths

To run a session Bean on an EJB server, set classpaths so that the following Apcoordinator libraries can be referenced: · uji.jar · ujiejb.jar Some session Beans that use some special features may require JAR files other than those indicated above. For more information, see Apcoordinator JAR files required for applications.

To use Interstage as the EJB server and to use Fujitsu XML Processor, you need to set up Interstage for their use. For more information, see Setting Up the Interstage Session Bean Environment.

22.3 Setting Up the Interstage Session Bean Environment

Setup of the Interstage execution environment is described briefly below.

Deploying a session Bean

Deploy a session Bean from the Interstage Management Console as described below. 1. Specify the classpaths to the WorkUnit where the session Bean will be deployed. To do so, select the

WorkUnit, then click the [Settings] tab to display a window in which you can set up the WorkUnit environment. In this window, specify uji.jar and ujiejb.jar for [WorkUnit Settings]-[Classpath] on separate lines. If the WorkUnit is a "Use Different JavaVMs for Web Applications/EJB Applications" type of WorkUnit, specify the files for [WorkUnit Settings]-[EJB Container VM]-[Classpath]. The following is a coding sample.

C:¥Interstage¥APC¥lib¥uji.jar C:¥Interstage¥APC¥lib¥ujiejb.jar

If a new WorkUnit will be created, you can specify the classpaths when the WorkUnit is created.

273

2. Deploy the session Bean to the WorkUnit. To do so, select the WorkUnit to which the session Bean is to be deployed, then click the [Deployment] tab to display a window from which you can deploy applications. In this window, for the file to be deployed, specify the EAR file containing the EJB-JAR files or EJB-JAR files, then click [Deployment]. You have now completed the following operations.

- Generation of the server code and of the items for distribution to clients - Registration of the session Bean with the WorkUnit 3. Modifying the values defined in the deployment statement if necessary.Select [EJB Applications] for the

WorkUnit to which the session Bean has been deployed, then, from the list of EJB applications, select the application whose values are to be changed. In this window, click the [Deployment Descriptor] tab, then click [Detailed Settings] to display the values defined in the deployment statement. Any of the values can be changed.

If you are using Apdesigner supported by Apworks, you can perform the steps above in Apdesigner by starting the Interstage Management Console from IJServer View.

22.4 Setting Up Execution Classes for Execution at WorkUnit Startup

When you use a WorkUnit in Interstage, you can run a session Bean created with Apcoordinator when the WorkUnit is started and terminated.

Setting up a WorkUnit

To run a session Bean created with Apcoordinator when a WorkUnit is started, set the WorkUnit as follows. 1. From the Interstage Management Console, select the WorkUnit in which the session Bean is to be

executed, then click the [Startup/Shutdown] tab. 2. Specify the following items on the [Create a new Class] tab, then register the settings made for the items.

Item Startup Class Shutdown Class

Name Make the required setting, such as Initializer.

Make the required setting, such as Finalizer.

Class name com.fujitsu.uji.ejb.workunit.Initializer

com.fujitsu.uji.ejb.workunit.Finalizer

Start Order Specify an order of execution.

Arguments Specify the JNDI name of the session Bean in a form such as java:comp/env/ejb/SomeEJB.

Abort startup if error occurs in startup class?

Make the applicable setting. This item is not displayed.

Method of calling startup class when WorkUnit is running in multiple VMs

Select [Call in all VMs].

Application Container Select [EJB Container].

Creating an application for a specific operation

To use an application for a specific operation when the WorkUnit starts or terminates, create it as described below. If no such an application is needed, you can run the block for invoking the session Bean simply by setting up the WorkUnit without performing the steps below. 1. Adding startup and termination methods to a business class

Add a method for startup (and a method for termination) to a business class as follows. package somepackage; public class SomeHandler extends com.fujitsu.uji.GenericHandler

274

{ public void startEjb(DispatchContext context) { ... } ... }

2. Adding the method to the command map: Add the created method to the command map. This sample does not require a Bean to be specified, and the command is uji.initialize (or uji.finalize for termination).

;uji.initialize=somepackage.SomeHandler.startEjb

The first time that an application created as described above is executed, it may take some time to load setting files, load classes, and so on for initialization purposes. Running session Beans in the startup sequence of a WorkUnit enables such initialization processing to be done in advance. If the application does not require any special initialization, defining only the WorkUnit allows Apcoordinator setting files to be loaded and other initialization tasks to be performed.

Only EJBs in the WorkUnit can be used from the startup class of a WorkUnit.

275

276

Part 5 Developing Web Services

277

278

Chapter 23 Overview

Apcoordinator makes it easy to create SOAP server applications that transmit and receive XML data. SOAP server applications are based on the SOAP specifications, and the services provided are publicly available on networks. SOAP uses Hyper Text Transfer Protocol (HTTP) and Extensible Markup Language (XML), the standard protocol and language of the Internet, for its communication infrastructure. In addition, SOAP implements remote procedure calls to applications that are platform-independent in a distributed object environment.

Using Apcoordinator as the basis for SOAP server applications enables you to: · Develop SOAP server applications and Web applications in the same way, and · Send and receive XML data easily between Web applications and SOAP server applications constructed

with Apcoordinator. In addition, Apcoordinator supports Interstage SOAP and Apache SOAP. For differences between the functions of each type of SOAP, see Using Functions Specific to Servers.

Operation of a SOAP server application

This section gives an overview of operation of a SOAP server application as outlined by the following figure:

1. Call to a service from a client

An Apcoordinator application or a SOAP client calls a service on the SOAP server. 2. Call to a service class from the SOAP server

The SOAP server calls a service class based on registered information. 3. Call to Apcoordinator

The SOAP service class calls Apcoordinator. 4. Call to a business class

Apcoordinator calls a business class based on the XML data sent from the client and command data. 5. Return of XML data

Apcoordinator returns the XML data processed in a business class to the client.

Creating client applications

See the following table for the methods of creating programs that calls web services.

Client application Web service called Reference

Apcoordinator-based application

SOAP server application created for use with Apcoordinator

Unified Remote Interface Calling Apcoordinator-based Web Services

279

280

Client application Web service called Reference

General web service Calling General Web Services

Non-Apcoordinator-based application

SOAP server application created for use with Apcoordinator

Calling Services from a Non-Apcoordinator SOAP Client Application

Chapter 24 Developing SOAP Server Applications

24.1 Overview

This section explains how to develop a SOAP server application for use with Apcoordinator. The development flow consists of the following three steps: 1. Design of an XML document structure used for service data input-output 2. Development of service classes 3. Development of business logic

Apcoordinator-based web services can be used from SOAP client applications that have not been created for use with Apcoordinator.

24.2 Designing an XML Document Structure Used for Service Data input-output

Apcoordinator-based SOAP server applications input and output XML data. Before developing a SOAP server application, design an XML document structure for data input-output. 1. Designing an XML document structure for data input

In such a design of the XML document structure, the SOAP service application receives data as a parameter. This XML data is passed to an argument of a method in a business class as com.fujitsu.uji.xml.XmlDataBean. Apcoordinator checks whether the XML document design is valid for the methods of each business class.

2. Designing an XML document structure for data output In such a design of the XML document structure, the SOAP server application returns data as a return value. An XML document is returned to a client as a return value of a business class method in the form com.fujitsu.uji.xml.XmlDataBean.

For information about the XmlDataBean class, see XML Data Bean.

24.3 Developing Service Classes

A service class is a class that is available to the public as a SOAP server application. Each SOAP server application must have one service class. When a SOAP client calls a SOAP server application, the SOAP server calls a service class. The service class calls Apcoordinator, and Apcoordinator then calls a business class.

281

Create a service class by following the procedure given below. 1) Create a service class by extending a class provided by Apcoordinator. The class to be extended depends on the type of SOAP library to be used. Extend the com.fujitsu.uji.soap.service.JAXMService class if you use Interstage. Extend the com.fujitsu.uji.soap.service.SOAPService class if you use Apache.

// Example of use with Interstage

public class MyService extends com.fujitsu.uji.soap.service.JAXMService {

}

2) Override the getInitParameters method if necessary. Specify the initialization parameter required for Apcoordinator operation in getInitParameters. The following are typical parameters that can be specified:

· factory: Specify the name of an expanded factory class. · commandMap: Specify the path to the command map file. The initial value is

/SOAP-INF/commands.map. Use this to make changes.

import java.util.Properties;

public class MyService extends com.fujitsu.uji.soap.service.JAXMService {

public Properties getInitParameters(){

Properties p = new Properties();

p.setProperty("factory", "sample.SoapFactory");

282

"/SOAP-INF/commands.map");

return p;

}

}

If multiple SOAP server applications are created, the name of the folder that stores the command map and the application file names must be unique on the server.

24.4 Developing Business Classes

Develop business classes by using the same methods as those for general applications in an environment where Webcoordinator is used. However, note the following differences:

1) com.fujitsu.uji.xml.XmlDataBean is passed to a data Bean argument. 2) For the return values of methods, specify XmlDataBean to be returned to SOAP clients. 3) The setResponseBean method of the com.fujitsu.uji.DispatchContext class, which is used for Webcoordinator applications, cannot be used.


import com.fujitsu.uji.GenericHandler;


public class MyHandler extends com.fujitsu.uji.GenericHandler {

public Object myMethod(DispatchContext context, XmlDataBean dataBean){

// Processing for the XmlDataBean argument

String str = dataBean.getText("some/name");

...

// Creating a return value

XmlDataBean bean = new XmlDataBean();

...

return bean;

}

}

The DispatchContext entity that is passed to business logic is SOAPDispatchContext. To use the entity as SOAPDispatchContext, cast it.

24.5 Exception Handling in Business Classes

If an exception is generated in a business class, throw an appropriate exception or

283

com.fujitsu.uji.soap.service.SOAPHandlerException. Apcoordinator returns it to the client as the Fault object. 1. If an exception is thrown appropriately

If an exception is thrown appropriately, the following information is set in the Fault object. faultcode: uji.handlerException faultstring: Message specified for the exception detail/stacktrace: Stack trace for the location where the exception was generated

2. If a SOAPHandlerException is thrown appropriately If a SOAPHandlerException is thrown appropriately, the following information is set in the Fault object. faultcode: Code specified in SOAPHandlerException faultstring: Character string specified in SOAPHandlerException detail/stacktrace: Stack trace for the location where SOAPHandlerException was generated

For precise control of exceptions generated in business classes, use the try-catch block.




import com.fujitsu.uji.soap.service.SOAPHandlerException;


public Object myMethod(DispatchContext context, XmlDataBean dataBean) throws SOAPHandlerException {

try{

...

}catch(Exception e){

// Define the required information and generate an exception.

String faultcode = "xxx";

String faultstring = "yyy";

throw new SOAPHandlerException(faultstring, faultcode);

}

}

}

24.6 Life Cycle of Objects

For SOAP server applications created for use with Apcoordinator, the life cycle of a session class object depends on the scope of the service specified during registration of Web service information. Use an appropriate scope of service according to the characteristics of the Web service. · If request scope is specified for registration, an instance is generated for each request, together with a

session class and business class.

284

· If session scope is specified for registration, both instances of a session class and a business class of

session scope are generated for each session. In addition, an instance of a business class of a non-session scope is generated for each request. If Interstage SOAP is used, the session may be disconnected from a client application.

· If application scope is specified for registration, both instances of a session class and a business class of

session scope are maintained in the application. Also, an instance of a business class of a non-session scope is generated for each request.

24.7 Using Functions Specific to Servers

Apcoordinator provides methods to use functions specific to the respective SOAP servers explained in the following section.

24.7.1 Using Functions Specific to Interstage

When you use Interstage, you can program applications using the session management function. This section describes programming for a service that ends acceptance of requests.

285

To end acceptance of requests: 1. Cast com.fujitsu.uji.DispatchContext received by a method in business logic to

com.fujitsu.uji.soap.service.SOAPDispatchContext. 2. Disconnect the session by calling the release method of the SOAPDispatchContext class. In the following coding sample, acceptance of requests is ended after a business class method executes its processing 10 times.




import com.fujitsu.uji.soap.service.SOAPDispatchContext;


private int count = 0;

public Object myMethod(DispatchContext context, XmlDataBean dataBean){

count++;

if(count == 10){

// Disconnect the session.

SOAPDispatchContext soapContext = (SOAPDispatchContext)context;

soapContext.release();

}

}

}

24.7.2 Using Functions Specific to Apache SOAP

Apcoordinator provides functions specific to Apache SOAP for getting classes and information. To use this information, code the program as follows: 1. Cast com.fujitsu.uji.DispatchContext received by a method in business logic to

com.fujitsu.uji.soap.service.SOAPDispatchContext. 2. Get information by calling the getEnvironment method of the DispatchContext class. 3. Set any one of the following values in the getEnvironment method: - apache.SoapContext.request: Request parameter received as an org.apache.soap.rpc.SOAPContext

object - apache.SoapContext.response: Response parameter received as an

org.apache.soap.rpc.SOAPContext object - apache.Envelope: SOAP envelope received as an org.apache.soap.Envelope object

If Interstage is used for a SOAP server, getting information specific to Apache SOAP returns null.

286

24.8 Calling Services from a Non-Apcoordinator SOAP Client Application

Using the SOAP messaging API enables you to call a service from a SOAP client application that has not been created for use with Apcoordinator. You should know about the following before you use SOAP messaging API to call a SOAP server application created for use with Apcoordinator: · Basic knowledge about XML · Basic knowledge about SOAP

Send data

Code the SOAP Envelope body in the following format:

<soapenv:Body>

<dispatch xmlns="urn:fujitsu-apcoordinator-soap">

<verb>command</verb>

<root>

<data>data</data>

</root>

</dispatch>

</soapenv:Body>

Note: Specify "http://schemas.xmlsoap.org/soap/envelope/" for the URI whose namespace prefix is "soapenv" for the Body element. The SOAP library normally adds the prefix automatically.

· Insert the <dispatch> tag immediately below the Body element. Code xmlns for the attribute, and code the attribute value as follows depending on the environment of the SOAP server application:

1. For use with Interstage, code "urn:fujitsu-apcoordinator-soap". 2. For use with Apache, specify the value of the id attribute coded in the deploy information file. · Code the command to be sent immediately below the dispatch element. Specify "verb" for the element

name of the tag, and code the command name in the text node in the element. · In the element node following the "verb" element, code the XML data to be sent. In the coding sample

shown above, <root> is the root element of an XML data Bean.

In the above example, returns and indents are inserted so that it can be easily understood. In the SOAP messaging API that would actually be used, however, no return or indent is inserted.

Receive data

When you use a SOAP messaging API to call a SOAP server application created for use with Apcoordinator, the root element of the returned XML data Bean is inserted immediately below <Body> and returned.

<soapenv:Body>

<root>

<data>data</data>

</root>

</soapenv:Body>

In the above sample, <root> is the root element of the returned XML data Bean. If null is returned or an XML data Bean for which no XML data is set is returned, the following is returned:

287

If null is returned from a SOAP server application

<soapenv:Body>

<XmlDataBean_NULL/>

</soapenv:Body>

If an XML data Bean for which no XML data is set is returned from a SOAP server application

<soapenv:Body>

<XmlDataBean_NODATA/>

</soapenv:Body>

In the above example, returns and indents are inserted so that it can be easily understood. In the SOAP messaging API that would actually be used, however, no return or indent is inserted.

Sample of calling

This section shows a sample where Interstage is used for calling a service. For information on using Apache to call a service, refer to the Apache SOAP manuals.For information about Interstage SOAP APIs, refer to the Interstage Application Server SOAP Service User's Guide.

import javax.xml.soap.Name;

import javax.xml.soap.SOAPBody;

import javax.xml.soap.SOAPPart;

import javax.xml.soap.SOAPMessage;

import javax.xml.soap.SOAPEnvelope;

import javax.xml.soap.SOAPException;

import javax.xml.soap.SOAPConnection;

import javax.xml.soap.MessageFactory;

import javax.xml.soap.SOAPBodyElement;

import javax.xml.soap.SOAPConnectionFactory;

...

public void send() throws SOAPException{

// Generate SOAPConnection instance.

SOAPConnectionFactory connFactory = SOAPConnectionFactory.newInstance();

SOAPConnection conn = connFactory.createConnection();

// Generate SOAPBody.

MessageFactory mesgFactory = MessageFactory.newInstance();

SOAPMessage message = mesgFactory.createMessage();

288

SOAPPart part = message.getSOAPPart();

SOAPEnvelope env = part.getEnvelope();

SOAPBody body = env.getBody();

// Set send data in SOAPBody.

Name bodyRoot = env.createName("dispatch",null,"urn:fujitsu-apcoordinator-soap");

SOAPBodyElement elt = body.addBodyElement(bodyRoot);

Name verb = env.createName("verb");

Name xml = env.createName("root");

Name data = env.createName("data");

elt.addChildElement(verb).addTextNode("command");

elt.addChildElement(xml).addChildElement(data).addTextNode("text");

message.saveChanges();

// Send a message, and receive a response.

SOAPMessage resMessage = conn.call(message,"http://SoapHost/soap/servlet/WSContainer");

conn.close();

}

289

290

Chapter 25 Setting Up the SOAP Server Application Execution Environment

25.1 Environment for Interstage SOAP

To deploy a SOAP server application in Interstage, set up the environment as follows: 1) Construct an environment for Interstage SOAP services

Install Interstage Application Server to construct the environment for use of Interstage SOAP services. For information on constructing the environment for Interstage SOAP services, refer to the Interstage Application Server SOAP Service User's Guide.

2) Register Apcoordinator applications

Register the developed SOAP server application on a server.

· Only one SOAP server application can be registered per Web service container.

In order to run multiple SOAP server applications, create as many Web service containers as the number of such applications.

Registering Web service information with GUI

First, start the Web Service Information Edit Tool.To start the Web Service Information Edit Tool, click the [Tools] in [Interstage Management Console]. Then, click [Messaging Service] from the menu at the top-left of the screen.

Enter information for the following items on the [Register Messaging Service] screen.

Setting item Setting value

Web service identifier Specify an appropriate name.

Processed HeaderElement Select [No deletion].

Web service role (actor) name Do not enter anything.

291

Setting item Setting value

Web service application class name Specify the class name of the service class.

Web service application file name Do not enter anything.

Web service application life cycle Select [Request], [Session], or [Application]. For life-cycle information, see Life Cycle of Objects.

User authentication

Approval roll name

Decryption Request Receiving setup

SOAP signature verification

Specify an appropriate setting.

Encryption ID

SOAP signature generation

Destination role (actor) name

Specify an appropriate setting. Response Sending setup

mustUnderstand Select "No need of processing".

Finally, click the [OK] button to complete registration of service information.

Registering Web service information with commands

When you register Web service information with commands, you must code Web service information in an XML file. The XML file is referred to as the Web service information file. The Web service information file can be created automatically by Apdesigner of Apworks. If the Web service information file is not created automatically, create the Web service information file according to the format shown below. For the Web service information file, specify any file name with wsdd as its extension. Specify the name of a class including a package in [service-class-name]. [service-name] is a name given to a service to be registered. Specify any character string for it.

<deployment name="[service-class-name]" xmlns="urn:xmlns-fujitsu-com:soapx-wsdd-2002-10" xmlns:java="urn:xmlns-fujitsu-com:soapx-wsdd-providers-java-2002-10"> <service name="[service-name]" provider="java:MSG"> <parameter name="className" value="[service-class-name]"/> </service> </deployment>

Execute the soapmodifydd command to register Web service information. Sample input is shown below. For information about the soapmodifydd command, refer to the Interstage Application Server SOAP Service User's Guide.

soapmodifydd -set -url http://[host-name]:12000/soap_admin/servlet/WSContainer deploy.wsdd

At this point, registration of Web service information is completed. To access a Web service from a client, specify a URL, such as the one shown below. This example shows a case where the definition file of a sample provided by Interstage Application Server is used for settings of the servlet container. Depending on the setting of the servlet container, "/soap/services" may be different. In this case, change it.

292

http://[host-name]/soap/services/[service-name]

25.2 Environment for Apache SOAP

In an environment using Apache SOAP, deploy a SOAP server application as follows: 1) Place modules of the SOAP server application on the server.

Transfer the module of the developed SOAP server application to the server. In the example of environment setup used in this section, it is deployed in C:¥Project¥service.jar.

2) Environment settings for the Apache SOAP service

In order to use the Apache SOAP service, the environment of the Apache SOAP router must be set up. This section gives an example of setting up the environment for Tomcat. Refer to the appropriate Apache SOAP manual for information on setting up environments for other servers.

Environment variable settings

Specify the following paths in the CLASSPATH environment variable. · Library file of Apache SOAP (soap.jar)

The library file of Apache SOAP is in the "lib" folder of the Apache SOAP installation folder. · Library file for the XML linkage function

In the definition example, the Fujitsu XML processor (xmlpro.jar, xmltrans.jar) is specified. · Library file used during execution of the Apcoordinator server (uji.jar, ujisoap.jar, and others)

The server execution file of Apcoordinator is in the "lib" folder of the Apcoordinator installation folder.

· Created SOAP service file It is C:¥Project¥service.jar in the definition example.

You may require software other than Apcoordinator, depending on the function that the SOAP application uses. Add the library provided with the required software to classpath. The following is a definition example:

C:¥Apache-SOAP¥lib¥soap.jar;C:¥Program Files¥Common Files¥FujitsuXML¥xmlpro.jar;C:¥Program Files¥Common Files¥FujitsuXML¥xmltrans.jar;C:¥APC¥lib¥uji.jar;C:¥APC¥lib¥ujisoap.jar;C:¥Project¥service.jar

Deployment of an Apache SOAP router

Copy the soap.war file to webapps in the Tomcat installation folder to deploy the Apache SOAP router. The soap.war file is in the webapps folder of the Apache SOAP installation folder.

The URL of the SOAP router servlet defined in soap.war of the Apache SOAP router is soap. It is the URL of the SOAP service whose URL is open to the public for accessing this Apache SOAP router servlet. The Apache SOAP router has two kinds of URL, one for the RPC calling and one for the message calling. Both of them are open to the public. The URL for message calling is used for an Apcoordinator-based property. Define the message calling for the URL specified from a client. Each of the following examples is of a URL open to the public:

293

· Example of URL for RPC calling: "http://[host-name]:8080/soap/servlet/rpcrouter" · Example of URL for message calling:

"http://[host-name]:8080/soap/servlet/messagerouter"

Confirmation of environment setup

Restart Tomcat after changing the settings. Confirm whether the environment setup is correct by following the procedure given below.

· Specify the URL (e.g., http://soapserver:8080/soap) of Apache SOAP, and confirm that the following screen is displayed:

Apache-SOAP Hello! Welcome to Apache-SOAP.

What do you want to do today? · Run the admin client · Visit the SOAP RPC router URL for this SOAP server

· Specify the URL (e.g., http://[host-name]:8080/soap/servlet/messagerouter) for message calling, and confirm that the following screen is displayed:

SOAP Message Router

Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

3) Registration of SOAP applications

Use DeploymentDescriptor to register a SOAP server application with Apache SOAP. The procedure for registering a SOAP application is as follows:

Coding of DeploymentDescriptor.xml An example of coding DeploymentDescriptor.xml is shown below.

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:fujitsu-apcoordinator-soap" type="message"> <isd:provider type="java" scope="Session" methods="dispatch"> <isd:java class="sample.MyService" static="false"/> </isd:provider> <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener></isd:service>

Specify the following value for service.

· id: Specify a SOAP service identification name. This value must be the same as the service attribute specified for the soap tag of a remote map.

Specify either of the following values for provider.

· methods: Always specify dispatch. · scope: Specify the life cycle of SessionProfile. Normally, session is specified.

294

Specify the following value for java:

· class : Specify the class name of a service class developed as explained in Developing Service Classes. In the above coding example, the class name is sample.MyService.

Registering DeploymentDescriptor.xml Execute the following command to register DeploymentDescriptor:

java org.apache.soap.server.ServiceManagerClient http://[host-name]:8080/soap/servlet/rpcrouter deploy DeploymentDescriptor.xml

You can use the Apache SOAP URL (e.g., http://[host-name]:8080/soap) to refer to and delete the registered information. For the access URL of Apache SOAP, select [Run the admin client], and follow the instructions on the screen.

· Specify the classpath to the soap.jar library file of Apache SOAP in order to execute

this command. · DeploymentDescriptor.xml must be in the current directory from which this

command is executed. · The URL specified for the argument of the command is the Apache SOAP router

URL that is open to the public for RPC calling. (In the example, it is "http://[host-name]:8080/soap/servlet/rpcrouter".)

295

296

Appendix A Sample Application

The Sample Collection provides sample applications that use functions of Apcoordinator.This chapter describes two fundamental sample application.

A.1 Simple Sample

Application Overview

This sample is a simple application that adds and subtracts two items.

Control Page

main.jsp

<HTML>

<HEAD>

<TITLE>sample</TITLE>



</HEAD>

<BODY>

<uji:dispatch />

<uji:include pane="head" />

<uji:include pane="body" />

</BODY>

</HTML>

The application is started with main.jsp specified.The control page receives an HTTP request and starts

297

Apcoordinator.The taglib directive is a declaration to make the Apcoordinator UJI tag available.The uji:dispatch tag analyzes the HTTP request and calls the corresponding business class.The uji:include tag fetches the JSP to each screen area. In this sample, two areas, "head" and "body", are specified.

Data Bean

HeadBean.java

package sample;

public class HeadBean extends com.fujitsu.uji.DataBean

{

protected int count;

protected java.util.Date loginTime;

public int getCount() {

return count;

}

public void setCount(int count) {

this.count = count;

}

public java.util.Date getLoginTime() {

return loginTime;

}

public void setLoginTime(java.util.Date loginTime) {

this.loginTime = loginTime;

}

}

BodyBean.java

package sample;


{

protected String message;

protected double val1;

protected double val2;

protected double result;

public String getMessage() {

298

return message;

}

public void setMessage(String message) {

this.message = message;

}

public double getVal1() {

return val1;

}

public void setVal1(double val1) {

this.val1 = val1;

}

public double getVal2() {

return val2;

}

public void setVal2(double val2) {

this.val2 = val2;

}

public double getResult() {

return result;

}

public void setResult(double result) {

this.result = result;

}

}

The data Bean is a class having data to be transferred between a screen and logic.For the data items, the set and get methods are created in the JavaBean property format.In the sample, "count" and "loginTime" are created for HeadBean, "message", "val1", "val2", and "result" are created for BodyBean.

Input-output Page

header.jsp



<uji:useBean id="head" cls="sample.HeadBean" request="true" />

The execution count is

<jsp:getProperty name="head" property="count" /> . <BR>

The session start time is

299

<jsp:getProperty name="head" property="loginTime" /> . <BR>

<HR><BR>

request.jsp




In the sample program, addition and subtraction between two items are performed.


<INPUT name="uji.verbs" type="hidden" value="add,sub">


Input of value 1: <INPUT name="val1"> <BR>

Input of value 2: <INPUT name="val2"> <BR>

<INPUT name="add" type="submit" value="Addition">

<INPUT name="sub" type="submit" value="Subtraction">

</FORM>

response.jsp




<jsp:getProperty name="body" property="message" /><BR>

The calculation result between <jsp:getProperty name="body" property="val1" /> and

<jsp:getProperty name="body" property="val2" /> is<BR>

<jsp:getProperty name="body" property="result" />.<BR>


<INPUT name="uji.verbs" type="hidden" value="next">


<INPUT name="next" type="submit" value="Return to input">

</FORM>

This is a screen body. In the sample, header.jsp is a screen to be displayed in the header area and response.jsp is a screen to be displayed in the body area.The taglib directive is a declaration that makes the Apcoordinator UJI tag available.The uji:useBean tag declares the data Bean variable name. For simplification, the variable name consists of the display area name and "name".To reference the data Bean variable content, the jsp:getProperty tag is used. request.jsp declares two hidden items, uji.verbs and uji.id; two input items, val1 and val2; and two send buttons,

300

"add" and "sub" in the FORM INPUT tag.uji.verbs notifies Apcoordinator of the list of commands (button names) to be sent with this form.uji.id notifies Apcoordinator of the name of the variable of the data Bean that receives this form input. response.jsp defines the hidden items and send buttons of the form, but does not define the input items. The form destination (action) is omitted. In this case, the HTTP request is sent to the same control page, main.jsp. method="post" is specified to be able to send more data. Both the request.jsp and response.jsp screens correspond to BodyBean. To differentiate between them, the screen display mode is required. As appears later, "reqmode" and "resmode" are specified for the display mode.header.jsp is the only screen that corresponds to HeadBean. The screen mode is not required.

Business Class

SampleHandler.java

package sample;



{

public SampleHandler() {

}


return true;

}

public void add(DispatchContext context, BodyBean dataBean) {

double result = dataBean.getVal1() + dataBean.getVal2();

dataBean.setMessage("Addition was performed.");

dataBean.setResult(result);

dataBean.setVerb("resmode");


setHead(context);

}

public void sub(DispatchContext context, BodyBean dataBean) {

double result = dataBean.getVal1() - dataBean.getVal2();

dataBean.setMessage("Subtraction was performed.");

dataBean.setResult(result);

dataBean.setVerb("resmode");


setHead(context);

}

public void next(DispatchContext context, BodyBean dataBean) {

301



setHead(context);

}


BodyBean dataBean = new BodyBean();



setHead(context);

}

private HeadBean headBean;

private void setHead(DispatchContext context) {

if(headBean == null) {

headBean = new HeadBean();

headBean.setLoginTime(new java.util.Date());

}

headBean.setCount(headBean.getCount() + 1);


}

}

The business class specifies a processing logic.In the sample, the business class has the methods "add", "sub", and "next", which correspond to the send buttons and method startup for initial start. The add method performs addition as a business logic.Next, the result is specified in the data Bean. The data Bean that corresponds to the result screen is used. In this sample, because the data Bean is common, BodyBean received as a parameter is used without being changed.The setVerb method specifies the screen display modes. setResponseBean is used to associate the screen area with the data Bean and the associated value is specified in Apcoordinator.Because the head area is common, the setHead method is used to make the area subroutine. In the setHead method, a value is specified in headBean and associated with the head area.The init method returns "true". This specification makes this business class a session scope. This class has variable "headBean". The session scope assures that the same instance is used in the same session and the headBean value is held.

Relationship Definition File

commands.map

# commands.map

sample.BodyBean;add=sample.SampleHandler.add

sample.BodyBean;sub=sample.SampleHandler.sub

sample.BodyBean;next=sample.SampleHandler.next

;=sample.SampleHandler.startup

302

pages.map

# pages.map

sample.HeadBean;=header.jsp

sample.BodyBean;reqmode=request.jsp

sample.BodyBean;resmode=response.jsp

The command map file commands.map specifies the business class and method called in correspondence with the data Bean which is the screen input result and command (send button name). The page map file "pages.map" specifies the name of the input-output screen displayed using the processing result data Bean and display mode (specified using setVerb).

A.2 Sample Screen Parts

Application Overview

The screen part is used to display and input data in the table format.The summary mode uses the table.

The details mode uses the list and composite Bean.

Application Framework

See Appendix A.1 for details of the application framework. This section outlines the framework.

303

main.jsp

<HTML>

<HEAD>

<TITLE>model</TITLE>



</HEAD>

<BODY>

<uji:dispatch />

<uji:include pane="body" />

</BODY>

</HTML>

Only the body area is used.

DetailStBean.java

package model;

public class DetailStBean extends com.fujitsu.uji.DataBean

{

protected DataManager dm;

protected String slipNo;

protected String orderDate;

protected String productCode;

protected String productName;

protected String productCount;

protected String branch;

protected String deliveryDate;

protected String customerRegion;

protected String customerName;

protected String customerPhone;

public DetailStBean(DataManager dm, String[] data) {

this.dm = dm;

slipNo = data[0];

orderDate = data[1];

productCode = data[2];

productName = data[3];

304

productCount = data[4];

branch = data[5];

deliveryDate = data[6];

customerRegion = data[7];

customerName = data[8];

customerPhone = data[9];

}

public String getSlipNo() {

return slipNo;

}

public String getOrderDate() {

return orderDate;

}

public String getProductCode() {

return productCode;

}

public String getProductName() {

return productName;

}

public String getProductCount() {

return productCount;

}

public String getBranch() {

return branch;

}

public String getDeliveryDate() {

return deliveryDate;

}

public String getCustomerRegion() {

return customerRegion;

}

public String getCustomerName() {

return customerName;

}

public String getCustomerPhone() {

return customerPhone;

}

public void setDeliveryDate(String deliveryDate) {

if(this.deliveryDate != deliveryDate) {

dm.setDeliveryDate(this, deliveryDate);

305

}

}

}

This is the data Bean that indicates one data item. This data Bean is updated by calling the DataManager class. The set method of the property not to be updated is omitted.

DataManager.java

package model;

import java.util.Vector;

public class DataManager {

Vector data;

public DataManager() {

}

public int getDataCount() {

return data.size();

}

public DetailStBean getData(int index) {

return (DetailStBean)data.elementAt(index);

}

public void setDeliveryDate(DetailStBean bean, String value) {

// Corresponds to update processing of the database.

bean.deliveryDate = value;

}

public void prepareData() {

// Corresponds to the database read processing.

data = new Vector();

for(int i = 0; i < initialData.length; i++) {

DetailStBean bean = new DetailStBean(this, initialData[i]);

data.addElement(bean);

}

}

306

private static final String initialData[][] = {

{ "401791","20000214","AC106W","Television PD-F200V Black","1",

"U.S.A. Branch","20000216","District VS, Washington D.C.","Thomas Electric Store","044-999-9999" },

....(Omitted)....

};

}

This is a class that provides access to data.In this sample, the format of the default value is a character string. Memory data is only rewritten at data updating.

ModelBean.java

package model;

public class ModelBean extends com.fujitsu.uji.DataBean

{

protected SummaryModel summary;

protected DetailModel detail;

public SummaryModel getSummary() {

return summary;

}

public DetailModel getDetail() {

return detail;

}

public void initData(DataManager dm) {

summary = new SummaryModel(dm);

detail = new DetailModel(dm);

}

}

This is a data Bean. Properties "summary" and "detail" provide the screen part interfaces. Details of this class are described below.

ModelHandler.java

package model;


307

public class ModelHandler extends com.fujitsu.uji.GenericHandler

{

protected DataManager dm;

public ModelHandler() {

}


return true;

}

public void showDetail(DispatchContext context, ModelBean dataBean) {

dataBean.setVerb("detail");


}

public void showSummary(DispatchContext context, ModelBean dataBean) {

dataBean.setVerb("summary");


}


dm = new DataManager();

dm.prepareData();

ModelBean dataBean = new ModelBean();

dataBean.initData(dm);

dataBean.setVerb("summary");


}

}

showDetail and showSummary only switch the display mode (setVerb).The startup method initializes data and displays it in summary mode.

commands.map

# commands.map

model.ModelBean;showDetail=model.ModelHandler.showDetail

model.ModelBean;showSummary=model.ModelHandler.showSummary

;=model.ModelHandler.startup

308

pages.map

# pages.map

model.ModelBean;summary=summary.jsp

model.ModelBean;detail=detail.jsp

web.xml Same as Appendix A.1. Descriptions are omitted.

Summary (using the table screen part)

summary.jsp



<uji:useBean id="body" cls="model.ModelBean" request="true" />

<P>Specification of scheduled delivery date (summary mode) </P>

<uji:peTextMode/>


<INPUT name="uji.verbs" type="hidden" value="showDetail">


<uji:table bean="body" property="summary">

<uji:tableRenderer type="table" >

<TABLE border="2" width="100%"><uji:children/></TABLE>


<uji:tableRenderer type="column" cls="header" >

<TH bgcolor="#EEFFEE"><uji:value/></TH>


<uji:tableRenderer type="column" cls="editable" >

<TD><INPUT name="<uji:name/>" value="<uji:value/>"></TD>


</uji:table>

<INPUT name="showDetail" type="submit" value="Details">

</FORM>

This input-output page uses the uji:table tag.The attribute of the uji:table tag specifies "summary" for the name of the property that returns the TableModel interface.In uji:table, three uji:tableRenderer tags are

309

specified for renderers. A renderer specifies the format of a table or cell. The uji:table tag calls the renderers in units of table, row, and cell according to the information collected from the interface. This tag then outputs the contents to the screen. When the renderer is omitted, the default pattern is output. The first renderer specifies the format of the overall table (type="table"). In this sample, attributes "border" and "width" are added to the TABLE tag. The uji:children tag specifies the processing of the low-order renderer. The next renderer specifies the format of the cell (type="column") whose state is header (cls="header"). In this sample, the TH tag is used to specify the background color. uji:value specifies that the cell value is displayed. The last renderer specifies the format of the cell (type="column") whose state is editable (cls="editable"). Apcoordinator automatically reflects the data input using the INPUT tag on the data Bean. To enable this reflection, uji:name automatically generates the name at data updating. The uji:peTextMode tag specifies inhibition of screen editing by the Apworks page editor. This inhibition does not affect anything when the editor is executed.

SummaryModel.java

package model;

public class SummaryModel implements com.fujitsu.uji.model.table.TableModel {

DataManager dm;

public SummaryModel(DataManager dm) {

this.dm = dm;

}

public int getColumnCount() {

return 6;

}

public int getRowCount() {

return dm.getDataCount() + 1;

}

public java.lang.Object getValueAt(int row, int col) {

if(row == 0) {

switch(col) {

case 0: return "Slip number";

case 1: return "Order data";

case 2: return "Product number";

case 3: return "Quantity";

case 4: return "Branch";

case 5: return "Scheduled delivery date";

}

} else {

DetailStBean bean = dm.getData(row - 1);

switch(col) {

310

case 0:return bean.getSlipNo();

case 1:return bean.getOrderDate();

case 2:return bean.getProductCode();

case 3:return bean.getProductCount();

case 4:return bean.getBranch();

case 5:return bean.getDeliveryDate();

}

}

throw new ArrayIndexOutOfBoundsException();

}

public java.lang.String getColumnClass(int row, int col) {

if(row == 0)

return "header";

else if(col == 5)

return "editable";

return null;

}

public java.lang.String getRowClass(int row) {

return null;

}

public void setValueAt(java.lang.Object val, int row, int col) {

if(row == 0 || col != 5 || !(val instanceof String))

throw new IllegalStateException();

DetailStBean bean = dm.getData(row - 1);

bean.setDeliveryDate((String)val);

}

}

This is a class installing the table interface. The getColumnCount method returns the number of columns in the table, and the getRowCount method returns the number of rows. The getValueAt method returns the data of the cell in the table. In this sample, row 0 is used for the header. The data row selects only the summary target and returns it. The getColumnClass method returns the cell data state using an arbitrary character string. In this sample, row 0 returns "header", and column 5 returns "editable". Other rows and columns return "null" so that the default renderer is used. The getRowClass method returns the data state of the row. In this sample, however, the default is used. The setValueAt method is called to update data. After a simple check, the Bean update is called. In this sample, the header character string is reported by the class. Alternatively, the header character string can be written in JSP and the class only returns data. In "Details" below, the header is written in JSP using a fixed character string.

311

Details (using the list and composite Bean screen parts)

detail.jsp



<uji:useBean id="body" cls="model.ModelBean" request="true" />

<P>Specification of scheduled delivery date (details mode) </P>

<uji:peTextMode/>


<INPUT name="uji.verbs" type="hidden" value="showSummary">


<uji:list bean="body" property="detail">

<uji:listRenderer type="list">

<TABLE border="2" width="100%">

<TR>

<TH bgcolor="#EEFFEE" rowspan="2">Slip number</TH>

<TH bgcolor="#EEFFEE">Order date</TH>

<TH bgcolor="#EEFFEE">Product number</TH>

<TH bgcolor="#EEFFEE">Quantity</TH>

<TH bgcolor="#EEFFEE" colspan="2">Customer region</TH>

<TH bgcolor="#EEFFEE">Scheduled delivery date</TH>

</TR>

<TR>

<TH bgcolor="#EEFFEE" colspan="3">Product name</TH>

<TH bgcolor="#EEFFEE">Branch</TH>

<TH bgcolor="#EEFFEE">Customer name</TH>

<TH bgcolor="#EEFFEE">Customer telephone number</TH>

</TR>

<uji:children/>

</TABLE>

</uji:listRenderer>

<uji:listRenderer type="element">

<uji:composite>


<TR>

<TD rowspan="2"><uji:getProperty property="slipNo" /></TD>

<TD><uji:getProperty property="orderDate" /></TD>

<TD><uji:getProperty property="productCode" /></TD>

<TD><uji:getProperty property="productCount" /></TD>

312

property="customerRegion" /></TD>

<TD><input name="<uji:compositeName property='deliveryDate' />"

value="<uji:getProperty property='deliveryDate' />" ></TD>

</TR>

<TR>

<TD colspan="3"><uji:getProperty property="productName" /></TD>

<TD><uji:getProperty property="branch" /></TD>

<TD><uji:getProperty property="customerName" /></TD>

<TD><uji:getProperty property="customerPhone" /></TD>

</TR>


</uji:composite>

</uji:listRenderer>

</uji:list>

<INPUT name="showSummary" type="submit" value="Summary">

</FORM>

This input-output page uses the uji:list and uji:composite tags. The attribute of the uji:list tag specifies "detail" for the name of the property that returns the ListModel interface. Two renderers are used. The first one is the renderer of the overall list. The TABLE tag is used to specify the header area.The last one is the renderer of the list element (each row). In this sample, the list element is not simple data, but a data Bean. To reference the content of the data Bean, the uji:composite tag is used. The uji:composite tag does not specify a data Bean. This is because the data Bean is received from the high-order screen part (in this sample, uji:list). In this sample, the value returned as the list element is DetailStBean class and is used for the data Bean in the uji:composite tag. A single renderer having no attribute is specified in the uji:composite tag. In compositeRenderer, the uji:getProperty tag is specified to reference a value and the uji:compositeName tag is specified to specify the name at data updating. In this sample, data is formatted in two ways and the scheduled delivery date can be updated.

DetailModel.java

package model;

public class DetailModel implements com.fujitsu.uji.model.list.ListModel {

DataManager dm;

public DetailModel(DataManager dm) {

this.dm = dm;

}

313

314

public int getSize() {

return dm.getDataCount();

}

public java.lang.Object getElementAt(int pos) {

return dm.getData(pos);

}

public java.lang.String getElementClass(int pos) {

return null;

}

public void setElementAt(java.lang.Object obj, int pos) {

throw new IllegalStateException();

}

}

This is a class installing the list interface. The getSize method returns the number of list elements. The getElementAt method returns the data of the list element. In this sample, the DetailStBean object received from the DataManager class is returned without being changed. The getElementClass method returns the data state. In this sample, default values are used for all the states. In this sample, the setElementAt method is not called. When the list element is simple data including a character string and the input field is specified using the uji:name tag, setElementAt is used to receive data. In this case, the input field is specified through the uji:composite tag. The set method of DetailStBean is directly called.

Appendix B Overview of Apcoordinator Operations

An overview of the internal operations of Apcoordinator is given below. Refer to this section to find out about debugging Apcoordinator applications and to get a better understanding of frameworks.

Outline of Web front-end operations

The figure below outlines Apcoordinator Web front-end operations. · When the uji:dispatch tag (or UjiServlet) is implemented, the data Bean containing the contents of the

analyzed request is sent to the Apcoordinator core. · When JSP is displayed, the data Bean specified by setResponseBean in a business class is referenced

from the UJI tag. · The correspondence table created at this time is used to analyze the next request.

315

Outline of Apcoordinator core operations

The figure below outlines Apcoordinator core operations. · In the Web front-end system, the data Bean created from the analyzed request serves as input. In EJB

and SOAP, the data Bean for parameters serves as input. · Preprocessing and postprocessing are performed before and after logic execution. · When command scripting is used, a script is executed instead of an ordinary class being called. · When a class is called, preprocessing and postprocessing of a business class are performed before and

after logic execution.

316

If an exception is thrown, control is passed to the handleException method.

317

318

Appendix C Compatibility with Earlier Versions of Apcoordinator (update)

This section covers compatibility with earlier versions of Apcoordinator as well as provides information about compatibility with earlier versions of Interstage Application Server.

C.1 Information Common to All Types of Applications

About the XML-described data specification version to be specified

The XML-described data specification has been updated to version 6.0, which is now the recommended version. Because version 5.0 still applies, version 5.0 applications need not be updated to version 6.0. For differences between the two XML-described data specification versions, see the XML-described Data Specification Reference. In addition, the command scripting version has been upgraded to version 6.0, and is now the current recommendation. The command scripting version indicates the version of an XML-described data specification in a specSection tag.Command scripting operation has not been changed.

C.2 Web Application

Update for use of new UJI tag features

To use the new UJI tag features in applications that run on old version of Apcoordinator, you need to replace the old ujiall.tld tag library file with the new one.To do so, copy the Apcoordinator ujiall.tld tag library file to the Web application's WEB-INF folder, overwriting the former file.Sources that have not been updated need not be recompiled.

Update for the HTML code generated by UJI tags

With the upgrade of Apcoordinator, some changes have been made to HTML code patterns generated by UJI tags because function extension and optimization.Those changes include adding and removing HTML tags, and modifying request parameters.In an automatic test tool that makes HTML code comparisons, the changes will appear as differences.

In order to make an application work correctly with a future version of Apcoordinator,an application program codes should not depend on HTML code patterns generated by UJI tags,except when HTML tags generated by UJI tags are defined by the UJI Tag Reference.

Fix of attributes of the uji:tableView and uji:treeView tags

The following problems of the uji:tableView and uji:treeView tags have been fixed. 1. The default value may not be applied to omitted attributes,when two or more uji:tableView and

uji:treeView tags are used in one JSP file, and some attribute values are omitted for the second or later tag of those tags.In this condition, the value specified by formerly executed tag may be applied to the omitted attribute.This problem may occur when the following attribute of the uji:tableView and uji:treeView tags are specified, the specified attribute value is a semi-colon delimited value, and some of the delimited values are omitted.

columnWidth columnInputWidth columnInputHeight indentIcon indentIconUseImage header headerInsets headerBackground headerForeground

319

320

headerFontStyle headerFontWeight headerFontSize headerTextDecoration headerAlignmentHorizontal headerAlignmentVertical headerRuleWidth headerRuleColor headerRuleType headerNoWrap headerUseImage dataInsets dataBackground dataForeground dataFontStyle dataFontWeight dataFontSize dataTextDecoration dataAlignmentHorizontal dataAlignmentVertical dataRuleWidth dataRuleColor dataRuleType dataNoWrap dataUseImage dataStripeBackground dataEmpty dataEditable dataCellType

2. When two or more uji:tableView and uji:treeView tags are used in one JSP file, and the multiRow attribute is specified,the second or later tags may use the multiRow attribute value of formerly executed tags, not its own multiRow attribute value.

These problems are fixed in this version,but the following products have these problems.Therefore behavior of the uji:tableView and uji:treeView tags used in an application will be changedwhen the following products are replaced by this version of the productif the application running on the following products has been affected by the above problems. · Windows platform - Interstage Application Server Enterprise Edition V6.0 - Interstage Application Server Plus V5.0.1, V6.0 - Interstage Apworks Modelers-J Edition V6.0 - Interstage Application Server Plus Developer V5.0.1, V6.0 · Solaris OE platform - Interstage Application Server Enterprise Edition 5.0.1, 6.0 · Linux platform - Interstage Application Server Enterprise Edition V6.0 Not to change the behavior of an applicationwhen the above product is replaced to this version of Apcoordinator,modify JSP files as follows. · To specify a semi-colon delimited value, specify all delimited values, and do not omit delimited values. · Specify multirow record to the multiRow attribute explicitly. Do not assume that formerly specified

multiRow value is applied. For more detail on how to specify attribute values,see description of the uji:tableView and uji:treeView tags in the UJI Tag Reference.

Appendix D Linkage with Struts

D.1 Summary

Struts is an open source framework for Web applications developed by Apache Jakarta Project. This page describes how to use Apcoordinator in an existing Struts application and how to use a Struts application together with an Apcoordinator application. In Struts applications, UJI tags and the remote common interface can be used.

D.2 Programming That Uses UJI Tags

Use UJI tags in a Struts application to dynamically change the colors or sizes of displayed items or to easily create selections or entries repeated many time in lists or tables.The coding sample below shows a case of declaring use of a data Bean using uji:useBean and of using uji:tableView in the html:form tag.

<uji:useBean id="myDataBean" cls="mypkg.MyDataBean" scope="request" request="true" />

<html:form name="myForm" action="myAction" type="mypkg.MyFormBean">

<input type="hidden" name="uji.id" value="myDataBean" />

<uji:tableView bean="myDataBean" property="table"

borderWidth="1" ruleWidth="1" dataEditable=";;true" />

<html:submit value="Submit" />

</html:form>

321

See below to see how the application works. The values set in the table, such as "Hamburger", are not indicated in the JSP above because they are set by the data Bean.

To use UJI tags in a Struts application as shown above, edit the related files using the following procedure: 1. Setting the data Bean

In the action class, set request or session for the data Bean as the data Bean's scope. 2. Editing the JSP

Write UJI tags in the JSP. Note that some UJI tags are cannot be used in some locations. In uji:form:

You can use all UJI tags that can be used in uji:form content. In html:form:

You can use component tags in content directly under html:form. Outside a form:

With the exception of some basic tags, you can use all UJI tags that can be used outside a form. 3. Getting data

To be used for a data Bean, get a data that is input to the form with the action class. Supplement: List of usable UJI tags

UJI tags that can be used in Struts applications are provided in a list.

D.2.1 Setting the Data Bean

Set the data Bean for display in the Struts action class. This sample assumes that the following data Bean is used for uji:tableView:

package mypkg;

import com.fujitsu.uji.DataBean;


public class MyDataBean extends com.fujitsu.uji.DataBean

{

protected TableView table = new TableView();

public MyDataBean() {

table.addRow(new Object[]{"Hamburger","$3.00","2"});

table.addRow(new Object[]{"Hot dog","$2.50","2"});

table.addRow(new Object[]{"Potato","$2.50","3"});

table.addRow(new Object[]{"Cola","$3.00","4"});

}

public TableView getTable() {

return table;

322

}

}

To set a data Bean from an action class, set it up as an object whose scope is either request or session. That is, use the setAttribute method of the javax.servlet.http.HttpServletRequest or javax.servlet.http.HttpSession interface. In the following coding sample, request is specified for setting the data Bean:

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import org.apache.struts.action.Action;

import org.apache.struts.action.ActionForm;

import org.apache.struts.action.ActionMapping;

...

public class MyAction extends Action {

public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest request,

HttpServletResponse response) throws Exception {

MyDataBean dataBean = new MyDataBean();

request.setAttribute("myDateBean", dataBean);

...

}

}

D.2.2 Editing the JSP

To use UJI tags, first edit web.xml that is a Web application environment definition file. As shown in the following sample, specify the location of the tag library descriptor file for UJI tags (ujiall.tld) using the taglib element:


<!DOCTYPE web-app

PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

...

<taglib>

323



</taglib>

...

</web-app>

Edit the JSP. First, set the taglib directive to declare the use of UJI tags by means of the prefix "uji:". Next, to reference the properties of the data Bean, use the uji:useBean tag. Be sure to specify the scope attribute and request attribute in it. For the scope attribute, specify the scope you designated for the data Bean. For the request attribute, specify "true".


...


Preparations for using UJI tags are now complete.Some UJI tags cannot be used in some locations in a Struts application. This information is provided below.

UJI tags usable in uji:form

You can use all UJI tags that can be specified for uji:form content in uji:form.However, you cannot use Struts tags. In addition, for the beanId attribute of uji:form, use the value specified in the id attribute of uji:useBean. See the following coding sample:


<uji:form name="myform" beanId="myDataBean" action="MyAction.do" >



<input name="submit" type="submit" value="submit">

</uji:form>

In the action attribute of the uji:form tag, specify the URL of the servlet.

324

Do not specify the name specified in the action tag in struts-config.xml.

UJI tags usable in html:form

As UJI tags that can be used in html:form, you can use component tags in content directly under html:form. However, you cannot use any attributes in the UJI Tag Reference that are described as valid only when they are used in the content of the uji:form tag. To use such an attribute, use uji:form.

In addition, to update the values, you need to send the hidden parameter uji.id by using the INPUT tag of the HTML. For uji.id, set the value specified in the id attribute of uji:useBean. See the following coding sample:


<html:form name="myForm" action="myAction" type="mypkg.MyFormBean">

<input type="hidden" name="uji.id" value="myDataBean" />



<html:submit value="Submit" />

</html:form>

To use the uji:anchor tag in html:form, set form-specified mode.

UJI tags that can be used outside a form

You can use the following UJI tags outside a form (for example, uji:form or html:form): · uji:include · uji:includedBody · uji:useBean · uji:getProperty · uji:resourceText · Page parts tag · Component tag However, except for the html:html tag, Struts tags and UJI tags cannot be nested.

Notes on using uji:include

Note the following about using uji:include: · Creating a page map.

A page map that matches the JSP to be included with uji:include must be created. In the following example, HeaderBean is associated with header.jsp:

325

mypkg.HeaderBean;=header.jsp

· Coding uji:useBean. You must code uji:useBean in the JSP that uses uji:include. Specify the scope attribute and request attribute in uji:useBean.In the scope attribute, specify the scope that is specified for the data Bean. In the request attribute, specify "true". In addition, specify the key that is specified to set the data Bean in the id attribute of uji:useBean and the pane attribute of uji:include.

...

<uji:useBean id="header" cls="mypkg.HeaderBean" scope="session" request="true" />

<uji:include pane="header" />

...

D.2.3 Getting the Data Bean

To use the sent form data in the action class as a data Bean, use com.fujitsu.uji.http.HttpBeanUpdater: 1. Create an instance of HttpBeanUpdater. 2. Invoke the getRequestBean() method to get the data Bean. See the following example:

import javax.servlet.ServletContext;






import com.fujitsu.uji.http.HttpBeanUpdater;

...




326

request.getSession().getServletContext();

ClassLoader loader = this.getClass().getClassLoader();

HttpBeanUpdater beanUpdater = new HttpBeanUpdater(context, request, loader);

MyDataBean dataBean = (MyDataBean)beanUpdater.getRequestBean();

...

}

}

D.2.4 List of Usable UJI Tags

The table below lists the UJI tags that can be used in a Struts application.

Tag Description In uji:form

In html:form

Out of

form

uji:action Specifies a JavaScript statement executed for an event coded in HTML.

- - -

uji:anchor Provides an anchor. O O(*1)(*2) O

uji:borderLayout Sets four areas, one each at the top, bottom, right, and left.

O O(*1) O

uji:borderLayoutRenderer Represents the content of the area created with uji:borderLayout.

O O(*1) O

uji:buttonList Displays selections in button form. O O(*1) -

uji:case

Specifies how a page is to be expanded only when there are other pages expanded under different conditions.

O - O

uji:checkBox Provides a check box. O O(*1) -

uji:children Expands the lower-level structure according to the expansion format in the page parts tag.

O - O

uji:colorMap Defines the names of colors used in component tags.

O O(*1) O

uji:comboBox Selects the form of a combo box. O O(*1) -

uji:composite Handles a data Bean in complex Bean format. O - O

uji:compositeName Generates the names of items input in uji:compositeRenderer tags.

O - O

327


In html:form

Out of

form

uji:compositeRenderer Specifies how a data Bean in complex Bean format is to be expanded.

O - O

uji:controlState Manages sessions. - - - uji:dispatch Invokes business classes. - - -

uji:fieldBigDecimal Sets a decimal point number input field. O O(*1) -

uji:fieldBigInteger Sets a decimal integer input field. O O(*1) -

uji:fieldDate Sets a date/time input field. O O(*1) -

uji:fieldDouble Sets a real number input field. O O(*1) -

uji:fieldLong Sets an integer value input field. O O(*1) -

uji:fieldString Sets a character string input field. O O(*1) -

uji:fieldTextArea Sets a multiple-line text input field. O O(*1) -

uji:form Sets a form. - - O

uji:frame Divides a page into frames. - - -

uji:getProperty Outputs the values in data Bean properties to the page.

O - O

uji:gridLayout Aligns items to the grid. O O(*1) O

uji:gridLayoutRenderer Represents the content of each area specified by uji:gridLayout.

O O(*1) O

uji:include Loads input/output pages. O - O

uji:includedBody Outputs the input/output pages associated with the uji:include tag.

- - O

uji:input Applies a client script. (This is equivalent to the INPUT tag.)

- - -

uji:label Sets a label. O O(*1) O

uji:list Expands data in the form of a list. O - O

uji:listBox Represents selections in the form of a list box. O O(*1) -

uji:listRenderer Specifies how data in list form is expanded. O - O

uji:name Generates the names of input items used to update current objects.

O - O

uji:peTextMode Prohibits editing in page - - O

328


In html:form

Out of

form mode using Apworks Page Editor.

uji:pushButton Represents a push button. O O(*1) O

uji:radioButton Represents a radio button. O O(*1) -

uji:recordView Represents a set of input items in the record format. O O(*1) -

uji:resourceText Outputs character strings defined in the resource file.

O - O

uji:saveSession Re-register sessions having associated data. O - O

uji:select Uses a client script. (This is equivalent to the SELECT tag.)

- - -

uji:switch Expands a different page depending on the condition.

O - O

uji:tabbedLayout Creates a tabbed layout. O O(*1) O

uji:tabbedLayoutRenderer Represents the content of each pane obtained with uji:tabbedLayoutRenderer.

O O(*1) O

uji:table Expands data in the form of a table. O - O

uji:tableRenderer Specifies how data is to be expanded if it is expanded in table form.

O - O

uji:tableView Displays data in the form of a table. O O(*1) -

uji:textarea Uses a client script. (This is equivalent to the TEXTAREA tag.)

- - -

uji:tree Expands data in a tree structure. O - O

uji:treeRenderer Specify how data is to be expanded if it is in tree structure.

O - O

uji:treeView Represents a table with a tree. O O(*1) -

uji:useBean Names a data Bean. - - O

uji:validate Checks items when an HTML event occurs and runs JavaScripts.

- - -

uji:value Represents the value of the current object. O - O

uji:windowControl Provides window control. - - -

*1 If the UJI Tag Reference imposes restrictions on uji:form or the HTML FORM tag, observe those restrictions. *2 Use in form-specified mode.

329

D.3 Using the Remote Common Interface

Use the remote common interface to call general EJBs/Web services or EJBs/Web services developed with Apcoordinator from the same interface. For details, see Remote Common Interface.

To use the remote common interface in a Struts application, use the com.fujitsu.uji.ext.InitialCallFactory class to get the CallFactory object.







import com.fujitsu.uji.ext.InitialCallFactory;




...

try{

CallFactory factory = (CallFactory)InitialCallFactory.createFactory(servlet);

Call call = factory.createCall("myejb");

ResponseBean responseBean = (ResponseBean)call.invoke(dataBean, "verb");

} catch(Throwable e){

...

}

...

}

}

To synchronize EJB session information, you need to set the object to be synchronized in the session scope in advance. To do so, after the java.io.Serializable interface has been implemented in the object, use com.fujitsu.uji.SessionProfile.SYNCDATAHOLDERKEY as the name that will be associated with the object.

The coding sample below shows a class set in the session scope. In this sample, the user ID is used as the data to be stored in a session.

330

public class SynchronizedData implements java.io.Serializable {

protected String userId = null;

public String getUserId(){

return userId;

}

public void setUserId(String userId){

this.userId = userId;

}

}

The coding sample below is an example of the remote common interface used for synchronization of session information. To generate a CallFactory object, use InitialCallFactory#createFactory(Servlet, HttpSession).







import com.fujitsu.uji.ext.InitialCallFactory;




...

SynchronizedData syncData = new SynchronizedData();

HttpSession session = request.getSession();

session.setAttribute(SessionProfile.SYNCDATAHOLDERKEY, syncData);

try{

CallFactory factory = (CallFactory)InitialCallFactory.createFactory(servlet, session);

Call call = factory.createCall("myejb");

331

ResponseBean responseBean = (ResponseBean)call.invoke(dataBean, "verb");

} catch(Throwable e){

...

}

...

}

}

D.4 Using Struts Applications Together with Apcoordinator Applications

You can use Struts applications together with Apcoordinator applications without modifying the applications' business logic.For example, if you create frequently used components for login sessions or similar activities in advance and use them with an Apcoordinator application and a Struts application, you can reduce the time required to develop applications as well as improve their quality.Using the two types of applications in this way allows them to share objects in the session scope.

Integrating common resources

When two types of Web applications are combined, their web.xml files (Web application environment definition files) must be integrated. If the applications have initialization parameters or servlets which have the same name but of which use is different, correct the names in advance to make them unique. The coding sample below shows a Web application environment definition file in which that for Apcoordinator application and that for Struts application are integrated.


<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

<servlet>

<servlet-name>action</servlet-name>

<servlet-class>org.apache.struts.action.ActionServlet</servlet-class>

<init-param>

<param-name>config</param-name>

<param-value>/WEB-INF/struts-config.xml</param-value>

</init-param>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>action</servlet-name>

<url-pattern>*.do</url-pattern>

</servlet-mapping>

332



<taglib>

<taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>

<taglib-location>/WEB-INF/struts-bean.tld</taglib-location>

</taglib>

<taglib>

<taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>

<taglib-location>/WEB-INF/struts-html.tld</taglib-location>

</taglib>

<taglib>

<taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>

<taglib-location>/WEB-INF/struts-logic.tld</taglib-location>

</taglib>



<taglib>



</taglib>

</web-app>

Transition from a Struts application to an Apcoordinator application

To transit from a Struts application to an Apcoordinator application, create a form that allows transition to the Apcoordinator's control page. The following coding sample shows an example of not sending a data Bean or command:

<uji:form name="myForm" action="main.jsp" >

<input type="submit" value="Submit" >

</uji:form>

The coding sample below shows an example of sending a data Bean and a command. In the sample, the verbs attribute and beanCls attribute are used in the uji:form tag:

<uji:form name="myForm" action="main.jsp" verbs="myverb" beanCls="mypkg.MyDataBean" >

<input type="submit" value="Submit" >

</uji:form>

333

Transition from an Apcoordinator application to a Struts application

To transit from an Apcoordinator application to a Struts application, you must shift control to the JSP or logic (servlet). To shift to the JSP, specify the JSP to which control is to be shifted in the action of the form:

<uji:form name="myForm" action="index.jsp">

<input type="submit" value="Submit">

</uji:form>

To shift to the logic, specify the URL of the servlet to which control is to be shifted in the action of the form:

<uji:form name="myForm" action="index.do">

<input type="submit" value="Submit">

</uji:form>

334

Terms

Apache SOAP

Apache SOAP is an open source API that supports the SOAP 1.1 and SOAP Messages with Attachments specifications.Apache SOAP is provided by the Apache Software Foundation.

Apcoordinator

The Apcoordinator product provides frameworks for constructing applications that conform to JavaTM 2 Platform, Enterprise Edition (J2EE).

Apcoordinator Core

Apcoordinator core is a framework that specifies the structure of an application. It provides Web applications, EJB session Beans, and SOAP server applications, created using Apcoordinator with functions commonly used by them.

Applet

Applets are programs that are embedded in HTML code and operate in Web browsers.

Application Log

The output of internal information at execution. Apcoordinator can output logs by queuing them regardless of the application's response.

Apworks

Software provided by Fujitsu. Apworks offers an integrated development environment to efficiently develop a business application.

Area Name

When creating a screen by linking input-output pages, Apcoordinator determines the layout of the input-output pages according to the area name. The control page creates an area using the uji:include tag.Data Bean is associated with the area by the setResponseBean method of the DispatchContext class.

Attribute

Tag attribute. In the following example, id and cls are called the attribute names and "body" and

335

"somePackage.someBean" are called the attribute values.

<uji:useBean id="body" cls="somePackage.someBean" />

Bccoordinator

Bccoordinator provides functions that support creation of EJB session Beans and SOAP server applications.

Business Class

A Java class in which a business logic is specified.

Client Script

This function specifies the JavaScript operating on the client browser in the Web application.

Collection Tag

The collection tag is a kind of component tag and a generic name for tags that represent multiple data items. Examples are selection items and tables.

Command

When a client calls an Apcoordinator application, the client sends a command in order to select a process the application performs.Apcoordinator selects the business class method to be called for a request according to the command.

Command Map

The command map associates a pair of a data Bean that holds input data from the client and a command with a business class method.

Command Scripting

Command scripting enables processing flows to be coded in XML, then executes them.Command scripting allows you to code only the minimum required portions of business classes with Java.

Component Tag

The component tag enables easy creation of screen items. The component tags are classified as field tags,

336

collection tags, and layout tags.

Control Page

A JSP page that receives an HTTP request and sends instructions to Apcoordinator using the uji:dispatch tag.

Cookie

Mechanism for communication of user information and session management information between Web browsers and Web servers.

Data Bean

A JavaBean-format class that sends and receives data between a client and a business class.

Data Bean Conversion

Data Bean conversion converts data Beans of a called EJB session Bean created using Apcoordinator to the java.util.HashMap class, after which the data is sent. For session Beans, you can use data Bean conversion to remove unnecessary data to reduce the amount of data that needs to be transmitted.

Data Bean Conversion Map

The data Bean conversion map is a file for specifying how data Beans are to be converted in Data Bean conversion.

Data Class

A data attribute used to select one of the expansion formats of the screen part.

Data Type (data Bean conversion)

The data type is a label attached to a HashMap converted by data Bean conversion from a data Bean. The data type indicates the type of data stored in the HashMap.

Deployment Descriptor

The deployment descriptor is a file containing information required to install an application into an operating environment.

337

Directive(JSP)

Specify the information used when JSP is changed into Java in directive.There are directives, such as page, taglib, and include.Directive is surrounded by <%@ and %> .

Display Mode

When a data Bean is associated with multiple input-output pages, the display mode allows Apcoordinator to select the input-output page to be displayed. The business class specifies the display mode using the setVerb method of the data Bean.

Enterprise Bean Environment

The enterprise Bean environment enables applications to be customized without modifications to the source code by setting constants required for EJB programs in a deployment descriptor.

Enterprise JavaBeans (EJB)

Enterprise JavaBeans are models of components used to create applications on the server side in Java.

Factory

A function to indirectly create a Java class used by the application. The factory class allows the user to use the classes created by the user.

Field Tag

The field tag is a kind of component tag and a generic name for tags that represent a single data input item. Examples are a string input fields and check boxes.

HTTP Request

A request for processing and operation from the browser to the Web server. An HTTP request is sent according to the HTTP protocol.

HTTP Response

The processing result of a request sent from the Web server to the browser.

338

Initialization Parameter

Initialization parameters specify the operation of an application created using Apcoordinator. Initialization parameters are used to designate the name of a user-defined factory class, log level, and other settings.

Input-output Page

A JSP page that has input-output items. The overall screen does not indicate a single input-output page. A screen consists of several input-output pages.

Interstage

Interstage is the name of a Fujitsu application server product family.

Item Class

Class storing the data input and displayed in the field tag and collection tag. Attributes (such as the color and fonts) to be used for display can also be set. Item classes are provided for each tag with data.

Java Plug-in

Java Plug-in is a tool that supports execution of Applets on Web browsers. Java Plug-in is provided by Sun Microsystems.

JBK Plug-in

The JBK plug-in supports execution of Applets on Web browsers.It is included in Apworks

JDBC

Java standard library for connecting to relational databases

JSP(JavaServer Pages)

Java dynamic Web page. The JSP specifies the server operation with the JSP tags and JSP scriptlets.

Layout Tag

The layout tag is a kind of component tag and a generic name for tags that make it easier to position items.

339

Log Level

Log significance. The smaller the number, the more significant the log. Apcoordinator can suppress unneeded logs with a specification to output only logs whose level is below a specified level.

Page Map

The page map associates the input-output page with the data Bean which is the processing result of the business class and the display mode of the data Bean.

Relationship Definition File

Apcoordinator indirectly specifies a business class name and JSP file name in an application by using the relationship definition files instead of directly specifying them. There are two kinds of the relationship definition files: the command map and page map.

Remote Common Interface

The remote common interface is used to call EJB session Beans and SOAP server applications created using Apcoordinator. The remote common interface allows common APIs to be used to call an EJB session Bean or SOAP server application.

Remote Map

The remote map is a file used to define the names of applications to be called using the remote common interface.

Renderer

A tag that specifies an expansion format of the screen part.

RMI-IIOP

RMI-IIOP allows an object being executed on a JVM to call an object being executed on another JVM. Communication between the objects is implemented with protocols used by a CORBA distributed object model. RMI-IIOP is used for Enterprise JavaBeans.

Screen Part Interface

The screen part tag asks a data Bean for the number of repetitions or data through the screen part interface. The table uses the TableModel interface. The tree uses the TreeNode or TreeModel interface. The list uses the ListModel interface.

340

Screen Part Tag

This function supports expansion of repetitive data to a screen or parting of the screen. There are five screen part tags: table, tree, list, condition, and composite Bean.

Servlet

A servlet is a Java application that operates on a Web server. A servlet is suitable for development of applications that return the results of dynamic processing.

Session

A connection between the server and client. A session is created for each client.

Session Bean

A session Bean is a component defined for Enterprise JavaBeans. Session Beans are created by the client and exist only while one client-server session is being executed.

SOAP

SOAP stands for the Simple Object Access Protocol. It is a light protocol standardized by the World Wide Web Consortium (W3C). Its communication infrastructure consists of the Hyper Text Transfer Protocol (HTTP) and Extensible Markup Language (XML), both of which are commonly used on the Internet.

SOAP Service Class

The SOAP service class is publicly available as a SOAP server application.One SOAP service class is required in each SOAP server application.

Tag Library File

A file that defines an extension tag.

UJI(Unified JSP Interface)

See Unified JSP Interface.

Unified JSP Interface (UJI)

An interface that calls Apcoordinator from JSP files of Web application. This interface is specified in a JSP extension tag.

341

URL Rewriting

One of the session management methods. A character string that identifies the session is appended to the end of the URL. Generally, this method is used with browsers that cannot use Cookie.

Web Application Environment Definition File (web.xml)

A file that defines the Web application environment, including the application parameters and tag library locations.

Webcoordinator

Webcoordinator provides functions that support creation of Web applications .

Web Service

Web services are service components that can be used on the Internet.

XML Data Bean

Data Bean used in the XML linkage function. Internally retains XML data. Using XML data Bean enables the UJI tag and XML data to be linked.

XML-described Data Specification

An XML-described data specification enables data item transfer or scope check processing to be coded in an external file in XML and the processing to be performed. The XML file includes specifications of each data item such as data scope and character string patterns.

XPath

Coding method for specifying certain elements and attributes in XML data.

342

Documents

Apcoordinator User's Guide - Fujitsu€¦ · Part 4 Developing EJB Applicat ions ... 21.1.4 EJB-JAR file.....255 . v 21.2 Processing Specific to Session Beans .....256 21.2.1 Exception