Embed Size (px)
Citation preview
Apcoordinator User's Guide
i
Using the Online Manual
Browser
Use a web browser (such as MicrosoftR Internet Explorer 3.0 or later, Netscape NavigatorTM 3.0 or later, and
NetscapeR Communicator 4.0 or later) that supports HTML 3.2. If you use the HotJava browser, characters may
not be displayed correctly.
If you use MicrosoftR Internet Explorer 5.0 or later or another newer browser, characters may not be displayed
correctly depending on the page. In order to display characters correctly, select the [View] menu, click
[Encoding]-[Auto-Select], and uncheck [Auto-Select].
Using "Favorites" in MicrosoftR Internet Explorer
To add a page of text in this manual to the [Favorites] menu, right-click the frame containing the
text, and then click [Add to Favorites] in the popup menu. The page is then added to the [Favorites]
menu. No frames are displayed when you select the added item on the [Favorites] menu to jump directly
to the page of text.
Using "Bookmarks" in Netscape NavigatorTM or NetscapeR Communicator
To add a page of text in this manual to the [Bookmarks] menu, right-click the frame containing the
text, and then click [Add Bookmark] in the popup menu. A bookmark to the page is then added to the
[Bookmarks] menu. No frames are displayed when you select the bookmark on the [Bookmarks] menu to jump
directly to the page of text.
When text is not displayed in frames...
To restore the use of frames, click "Contents" in the top or bottom right corner.
File path names
In this manual, the file paths are written in the Windows format. If you use the Solaris platform or Linux
platform, change the format of the paths as shown below.
C:¥Interstage¥F3FMjs2¥conf¥jscontainer_wco.xml
/opt/FJSVjs2/conf/jscontainer_wco.xml
For the paths represented as "Apcoordinator installation folder", refer to "11.2 Required Software for
Execution," and change their names accordingly.
Product names
Product names are abbreviated as follows in this manual:
Interstage Apcoordinator
-> Apcoordinator
Interstage Apworks
-> Apworks
Interstage Application Server
-> Interstage
Interstage Application Server JServlet
-> JServlet
Interstage Application Server InfoProvider Pro
-> IPP
Solaris(TM) Operating Environment
-> Solaris OE
Trademarks
· Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States and/or other countries.
· Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries.
ii
· Java and all Java-related trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
· Sun, Sun Microsystems, Sun logos, Solaris, and all Solaris-related trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
· Apworks is a registered trademark of FUJITSU LIMITED. · Interstage is a registered trademark of FUJITSU LIMITED. · Other company and product names in this document are trademarks or registered trademarks of their
respective owners.
1
Part 1 Frameworks Provided by Apcoordinator
2
3
Chapter 1 Product Overview
1.1 About Apcoordinator
Apcoordinator provides 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.
4
- Apcoordinator provides functions for communicating with applets. · Enterprise JavaBeans (EJB) - Apcoordinator provides frameworks that improve compatibility between EJB and Web 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
5
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
6
Find the Manual for a Function
Purpose: To Manual Sample
Common functions
Understand the basics of frameworks
Chapter 2 Overview of the
Frameworks Provided by
Apcoordinator
Code a processing flow in XML
Chapter 9 Command
Scripting
Command Scripting
Reference
commandMap
Code the specifications of data in XML
Chapter 10 XML-Described
Data Specification
XML-Described Data
Specification Reference
eSpecCalc,
carrent
Read and save XML files and use XML
data Chapter 5 Using XML Data
Specify string data for use by an
application, in an XML file 4.6 Resource Files meetingroom
Call business services created by
Apcoordinator
Chapter 6 Developing
EJB/SOAP Clients ejbOffice, soap
Outputs application logs 4.2 Application Logs logTest
Control calls to business classes 4.5 Hook for Business
Class Calls
Use events 4.4 User-Defined Events
Create a Java source from an
XML-described data specification
Chapter 10 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
Chapter 13
Webcoordinator
Application Framework
simpleForm,
sample
Use UJI tags
Chapter 14 Programming
Using the UJI Tags
UJI Tag Reference
board, catalog,
address,
script, model,
include
Use browser subwindows 14.6 Window Control subwin
Divide a screen into frames 14.7 Frame Control frame
Manage data at the session level 15.1.1 Webcoordinator
Session Management
Send and receive binary files 15.2 Sending and
Receiving a Binary File updown, browse
Display XML data
14.5 Using XML Data with
Tags
Tag reference
xmlAddress
7
Display data in a database Chapter 16 Linkage to
Databases office
Link an application with an applet Chapter 17 Linkage to
Applet applet
Create combo boxes on a screen
14.4.3 Using Collection
Tags
UJI Tag Reference
board, comboBox
Create tables on a screen
14.4.3 Using Collection
Tags
UJI Tag Reference
address,
scrollTable,
model
Detect disconnection of a session 15.1.4 Detecting a
Session Disconnection timeout
Prevent double processing 15.1.5 Advanced Session
Management click
Prevent requests from unexpected
screens
15.1.5 Advanced Session
Management sessionControl
EJB
Understand the configuration of an EJB Chapter 20 Overview
Create EJB session Beans Chapter 21 Developing
Session Beans ejbOffice
Call EJBs created using Apcoordinator
7.1 Calling Session
Beans Developed Using
Apcoordinator
ejbOffice
To call a general EJB 7.2 Calling a General EJB
Web service
Understand the configuration of a Web
service Chapter 23 Overview
Create SOAP server applications Chapter 24 Developing
SOAP Server Applications soap
Call Web services created using
Apcoordinator
8.1 Calling Web Services
Developed Using
Apcoordinator
soap
Call a general Web service 8.2 Calling a General Web
Service
Find the Manual for a Component
Component Manual Sample
Apcoordinator core
Functions common to all frameworks Part 2 Functions of
Apcoordinator Core
commandMap,
eSpecCalc,
logTest, and so
forth (* 1)
Webcoordinator
Web application Part 3 Developing Web
Applications
simpleForm,
sample, board,
etc. (* 1)
Bccoordinator
8
EJB session Bean Part 4 Developing EJB
Applications ejbOffice
SOAP server application Part 5 Developing Web
Services soap
JICK
Use of groupware (mail, directories,
etc.)
J Internet Communication
Kit Online Manual
sendMail,
ldapLogin
*1 Other samples are also available. For the other samples, see Find the manual for a function or see the
Samples.
9
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:
10
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
11
successful user registration and shows the user ID.
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.
12
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,
13
[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.
· 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 "Part 3 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.
14
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.
15
For more information on how to develop session Beans using Apcoordinator, see "Part 4 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.
16
For more information on how to develop Web services using Apcoordinator, see "Part 5 Developing Web Services."
2.4 Linkage between Applications Developed Using Apcoordin
ator
Applications developed using Apcoordinator link to one another and operate as shown in the following figure:
17
Part 2 Functions of Apcoordinator Core
18
19
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 Appendix B 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) {
20
double result = dataBean.getVal1() - dataBean.getVal2(); 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 3.2 Data
Bean.
o o -
XML data Bean
(com.fujitsu.uji.xml.XmlData
Bean class)
Class that holds data
in the XML format. For
details, see Chapter
5 Making Use of XML
Data.
o o o
21
Type of application(*1) Type Description
Web EJB SOAP
HashMap (java.util.HashMap
class)
Used in EJB session
Beans. For details,
see 21.3.4 Inputting
Data Using HashMap.
- o -
*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: 13.3 Files for a Webcoordinator Application. · EJB session Bean: Chapter 21 Creating a Java Source File and Relationship Definition File. · SOAP server application: 24.4 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: 13.3 Files for a Webcoordinator Application · EJB session Bean: Chapter 21 Creating a Java Source File and Relationship Definition File · SOAP server application: 24.4 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
22
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.
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 15.1.5 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 3.5 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
23
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:
· 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 3.5 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: Chapter 19 Setting Up the Web Application Execution Environment - EJB session Bean: 21.1.2 Setting Up Initialization Parameters for a Session Bean - SOAP server application: 24.3 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.
24
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.
3.6.1 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
for a Web application.
13.3 Files for a
Webcoordinator
Application
Resource file Defines data about character strings
used in the application. 4.6 Resource File
Remote map
Defines the name of an application to
be invoked through the remote common
interface.
6.2 Remote Map
XML file for command
scripting
Writes the processing flow for
command scripting.
Chapter 9 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.
Chapter 10
XML-described Data
Specification
Business class
configuration file
Specifies business class settings
for the business class retry function
and the transaction management.
4.7 Business Class
Retry Function
4.8 Transaction
Management
Function
Data Bean conversion
map
Specifies how the data Bean converter
converts data Beans when EJBs are
invoked.
21.3.3 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 Chapter 5 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]
25
Data input by HashMap is used for EJB session Beans. For details, see 21.3.4 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.
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 Chapter 9 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.search /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
26
Type of
application Default location
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 11.3 Initialization
Parameters.
27
Chapter 4 Programming Using the Application
Program Interface (API)
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 class The
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 class SampleHandler extends com.fujitsu.uji.GenericHandler { .... 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
28
from GenericHandler class. For more information on the handleException method, see 4.3 Error Processing.
4.2 Application Logs
4.2.1 Log Functions
Apcoordinator has a facility for collecting application logs. The Apcoordinator application log functions
can output logs without being affected by the application response because it queues the log output. Specifying
a log level can control whether the log is displayed according to the status.
Basic Log Output Operations
Use the LogComposer object to output logs. This object can be referenced from the application class.
import com.fujitsu.uji.log.*; public class SampleHandler extends com.fujitsu.uji.GenericHandler { .... public void startup(DispatchContext context) { .... LogComposer lc = context.getApplicationProfile().getLogComposer(); lc.println("Starts processing."); } }
Customizing the Log Output Functions
The LogComposer object can be specified optionally by the application class. newLogComposer of the
ApplicationProfile class is overridden, and the LogComposer object is returned to change the log format and
output destination. At default, the queue is valid and a dated message is 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")); } catch(IOException e) { return null; // The default is used. } lc.setQueueSize(1000); lc.enableQueue(); lc.setLogLevel(9);
29
return lc; } }
To invalidate the log output, the null LogComposer object is returned.
public LogComposer newLogComposer() { return new LogComposer(); }
Log Level
The significance level can be specified in the Apcoordinator log. The greater the number, the less significant
the level. Log level 0 is the most significant. The level can be specified optionally; Apcoordinator uses
the following levels:
0: Most significant log
3: Apcoordinator error log level
5: Initial default level of messages with an unspecified log level
10: Apcoordinator information log level
Specify the log level during log display.
LogComposer lc = context.getApplicationProfile().getLogComposer(); lc.println(7, "Starts processing.");
When the level is not specified, the default level is used. The initial value of the default level is 5, but
this value can be changed using the setDefaultLevel method.
lc.setDefaultLevel(7); lc.println("Starts processing.");
Specifying the log output level can suppress unnecessary log output. The default level is 9 (only logs under
level 9 are output).
lc.setLogLevel(5); // Logs under level 5 are output.
The log output level can also be specified using an initialization parameter. However, the log output level
specified in the setLogLevel method has a higher priority. For more information on initialization parameters,
see 11.3 Initialization Parameters. The following is an example specifying the log output level in web.xml
file of a Web application.
<web-app> <context-param>
30
<param-name>logLevel</param-name> <param-value>5</param-value> </context-param> </web-app>
When making log character strings to output logs, the log level can be determined beforehand to exclude
unnecessary processing.
int level = 5; if(lc.isLogged(level)) { String message = "character-string" + a + "operation is" + b + "costly." lc.println(level, message); }
Specifying the Format
The LineLogFormat object specifies the log output format. Any format can be specified at creation of the
LogComposer object.
lc = LogComposer.getFileOutputInstance("c:¥¥myapp¥¥mylog.txt", true, new LineLogFormat("%d %m"));
System information can be displayed with the following specification:
%m Message text
%d Time
%t Thread name
%s Method name
%l Log level
%% Displays the % symbol.
For example, with specification "%d %m," the following log is output:
2001/01/05 16:47:49 uji:no entry in commands.map for TestUseBean.dataBean1;submit
4.2.2 Log Queuing
While application logs are being output, application processing is interrupted. Log queuing can output logs
at an appropriate timing after completion of application processing. This function allows the user to output
logs without being affected by the application response. The Apcoordinator log feature validates log queuing
at default.
Validating and Invalidating the Queue
To limit the message order in the application, temporarily invalidate the queue. The queued messages wait
31
to be output.
LogComposer lc = context.getApplicationProfile().getLogComposer(); synchronized(lc) { lc.disableQueue(true); lc.println(3, "Significant message"); lc.enableQueue(); }
Specifying the Queue Size
Specifying the queue size (number of messages to be queued) can prevent the message from running short due
to log messages. If an attempt is made to output more messages than the upper limit, the excess messages must
wait until other messages are output and sufficient free space becomes available.
lc.setQueueSize(1000);
Specifying the Queue in the Customized Log Feature
When using the customized log feature, the queue is suppressed immediately after the log feature is made
available. Queue start must be executed.
public class SampleApplication extends com.fujitsu.uji.ApplicationProfile { LogComposer newLogComposer() { LogComposer lc; lc = LogComposer.getFileOutputInstance("c:¥¥myapp¥¥mylog.txt", true, new LineLogFormat("%d %m")); lc.setQueueSize(1000); lc.enableQueue(); lc.setLogLevel(9); return lc; } }
4.3 Error Processing
To subtly control exceptions that occur in the business class, use the try-catch block.
public void startup(DispatchContext context) { dm = new DataManager(); try {
32
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.
public class SampleHandler extends com.fujitsu.uji.GenericHandler 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; .... public Object handleException(DispatchContext context,
33
Throwable th) { 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. 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; }
34
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 && ((MyEvent)evt).getType()==MyEvent.TYPE1) { file.delete(); } } }
In the business class, use the event listener and event as follows:
public void startup(DispatchContext context) { context.addUjiEventListener(new MyListener(new File("foo")); .... } public Object postprocess(DispatchContext context,Object result) { .... if (failed) { context.fireUjiEvent(new MyEvent(MyEvent.TYPE1,this)); }
35
}
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:
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 4.1 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 {
36
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); } }
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 {
37
// 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 3.5 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 xmlns="http://interstage.fujitsu.com/schemas/uji/ujiResource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/ujiResource http://interstage.fujitsu.com/schemas/uji/ujiresource.xsd"> <config> <version>5.1</version> </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">
38
<elem>192.168.96</elem> <elem>192.168.97</elem> </array> <map id="rooms"> <elem key="room101">Meeting room 101</elem> <elem key="room102">Meeting room 102</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:
<?xml version="1.0" encoding="ISO-8859-1"?> <ujiResource xmlns="http://interstage.fujitsu.com/schemas/uji/ujiResource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/ujiResource http://interstage.fujitsu.com/schemas/uji/ujiresource.xsd"> <config> <version>5.1</version> </config> <!-- Write the tags (e.g., text, array, and map) used to define character strings in any sequence here.--> </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>
39
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"> <elem key="room101">Meeting room 101</elem> <elem key="room102">Meeting room 102</elem> </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 11.3 Initialization
Parameters.
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
40
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 com.fujitsu.uji.DispatchContext; import java.util.Map; ... public void startup(DispatchContext context) { 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"); ... }
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.DispatchContext;
41
import com.fujitsu.uji.util.UjiResource; import java.util.Map; ... public void startup(DispatchContext context) { // 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 · 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(); ....
42
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
<?xml version="1.0" encoding="ISO-8859-1"?> <ujiResource xmlns="http://interstage.fujitsu.com/schemas/uji/ujiResource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/ujiResource http://interstage.fujitsu.com/schemas/uji/ujiresource.xsd"> <config> <version>5.1</version> </config> <map id="rooms"> <elem key="room101">Meeting room 101</elem> <elem key="room102">Meeting room 102</elem> </map> </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.DispatchContext; import com.fujitsu.uji.compo.ButtonList; import com.fujitsu.uji.util.UjiResource; ... public void startup(DispatchContext context) { MyDataBean bean = new MyDataBean(); ... ButtonList blRoom = bean.getBlRoom();
43
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>
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; }
44
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.
import com.fujitsu.uji.DispatchContext; import com.fujitsu.uji.util.UjiResource; ... public void startup(DispatchContext context) { 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:
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 13.3.1 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 Chapter 10 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"/>
45
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.
<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 "4.6.2 Referring to a Character String from a Java Program" Getting a character string by
using the UjiResource class.
4.7 Retrying Business Classes (new)
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.
46
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 4.8 Transaction Management,
see 4.8.3 Using the Transaction Management Function Together with the Business Class Retry Function.
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 exe
cuted
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.
47
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 3.6.2 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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/handlerConfig http://interstage.fujitsu.com/schemas/uji/handlerconfig.xsd"> <config> <version>6.0</version> </config> <handler name="sample.SampleHandler"> <!-- (1) --> <method name="doUpdate"> <!-- (2) --> <retry enabled="true" retryInterval="200" retryCount="1" /> <!-- (3) --> </method> <method name="*"> <!-- (4) --> <retry enabled="false"/> <!-- (5) --> </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
48
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. - 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
49
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 applicatio
n 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.DispatchContext; import com.fujitsu.uji.GenericRetriableHandler; ... 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) {
50
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 (new)
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.
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:
51
- 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 4.7 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 4.8.4 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 4.8.4 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)
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
52
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. · 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 3.6.2 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):
<?xml version="1.0" encoding="iso-8859-1"?> <handlerConfig
53
xmlns="http://interstage.fujitsu.com/schemas/uji/handlerConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/handlerConfig http://interstage.fujitsu.com/schemas/uji/handlerconfig.xsd"> <config> <version>6.0</version> </config> <handler name="sample.SampleHandler"> <!-- (1) --> <method name="doUpdate"> <!-- (2) --> <transaction enabled="true"> <!-- (3) --> <rollbackException class="some.pkg.MyException"> <!-- (4) --> </transaction> </method> <method name="*"> <!-- (5) --> <transaction enabled="false"/> <!-- (6) --> </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 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.
54
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.
Whether subsequent processing executed or skipped Processing in
which exception
occurs
before
Transaction
Begin
Start of a
transaction
Business
method
before
Transaction
Completion
End of a
transacti
on
after
Transaction
Completion
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.
55
4.8.3 Using the Transaction Management Function Together with the Business Cla
ss Retry Function
To use the transaction management function together with the 4.7 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:
<?xml version="1.0" encoding="iso-8859-1"?> <handlerConfig xmlns="http://interstage.fujitsu.com/schemas/uji/handlerConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/handlerConfig http://interstage.fujitsu.com/schemas/uji/handlerconfig.xsd"> <config> <version>6.0</version> </config> <handler name="sample.SampleHandler"> <method name="doUpdate"> <transaction enabled="true"/> <!-- (1) --> <retry enabled="true" retryInterval="200" retryCount="1" /> <!-- (2) --> </method> <method name="search"> <retry enabled="true" retryInterval="200" retryCount="1" /> <!-- (3) --> </method> <method name="*"> <transaction enabled="false"/> <!-- (4) --> <retry enabled="false"/> <!-- (5) --> </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
56
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.
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.
57
Subsequent processing executed or skipped
Processing
in which
exception
occurs
before
Transaction
Begin
Start of a
transaction
Business
method
before
Transactio
n
Completion
before
Method
Completion
End of a
transact
ion
after
Transacti
on
Completio
n
handle
Exception (*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.
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.DispatchContext; import com.fujitsu.uji.Preprocessor; public class SampleHandler extends GenericTransactionHandler { Connection connection = null; public int preprocess(DispatchContext context) {
58
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) // 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) { ... } return Preprocessor.EVAL; } ... public Object postprocess(DispatchContext context, Object result) { closeConnection(); return result; } public Object handleException(DispatchContext context, Throwable th) { closeConnection(); return null; } private void closeConnection() { if (connection != null) {
59
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 are used to disconnect the database connection.
When you use the processing in the coding sample above 4.8.3 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.
60
61
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 11.2 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 14.5 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.
62
The element corresponding to the root of the XML tree maintained in an XML data Bean is referred to as the
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.
public void startup(DispatchContext context) { 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.
63
For an explanation of XPath with examples, see 5.3 Summary of XPath.
An XML data element can be referenced as a string or XML data Bean.
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
elementAttribute 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.
64
<doc> <header> <title>XML Linkage Function Manual</title> <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
65
XML data below is specified with XPath "/book/publisher/name".
<?xml version="1.0" encoding="UTF-8" ?> <book> <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" ?>
66
<book xmlns:fj="urn:fj-touch-communications"> <title>Introduction to Apcoordinator</title> <date>2001/4/1</date> <fj:publisher lang="ja"> <fj:name>Fujitsu Touch Communications</fj:name> <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.
XmlDataBean xmlBean = new XmlDataBean(); ... 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.
67
This automatic search for declared namespaces is valid for the following methods:
· getText(String xpath) · getElement(String xpath) · getNodeSet(String xpath) · getSubBean(String xpath)
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
<?xml version="1.0" encoding="ISO-8859-1" ?> <book> <title>Introduction to Apcoordinator</title> </book>
Adding a namespace declaration
xmlBean.addNamespaceDeclaration("fj","urn:fj-touch-communications")xmlBean.addNamespacesToNode()
XML data after addition of a namespace declaration
<?xml version="1.0" encoding="ISO-8859-1" ?> <book xmlns:fj="urn:fj-touch-communications"> <title>Introduction to Apcoordinator</title> </book>
68
69
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:
· 7.2 Calling General EJBs · 8.2 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"); //
70
Specifying the SOAP server application to be called 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:
<?xml version="1.0" encoding="ISO-8859-1"?> <remoteMap xmlns="http://interstage.fujitsu.com/schemas/uji/remoteMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/remoteMap http://interstage.fujitsu.com/schemas/uji/remotemap.xsd"> <config> <version>5.0</version> <defaultSoapApi>Interstage_JAXM</defaultSoapApi> </config> <!-- Define session Bean calling.--> <ejb name="MySessionBean" application="java:comp/env/ejb/MySessionBean"/> <!-- Define session Bean local calling.--> <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> <!-- Define SOAP service calling.--> <soap name="myService" url="http://somehost/soap/services/someservice"/> </remoteMap>
71
The remote map root is remoteMap. Write the config tag inside the remoteMap tag, and then specify the 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 21.3.2 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, see7.5 EJB Session Beans Grouping function and 7.6 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 Chapter 25 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 Interf
ace
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; public Object doSomething(DispatchContext context, DataBean dataBean){ CallFactory factory = context.getCallFactory(); try {
72
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 ... } 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.
73
For an explanation of operations specific to session Beans, see Chapter 7 Calling EJBs. For an explanation
of operations specific to SOAP server applications, see Chapter 8 Calling Web Services.
74
75
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 21.3 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 Chapter 6 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 7.4
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 21.3 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 21.2.1
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.
76
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:
import com.fujitsu.uji.ejb.EJBCallFactory; import com.fujitsu.uji.ext.CallFactory; 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 21.3 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 21.2.1 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 7.4 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
77
- 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.
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 Cla
ss
The following is a coding sample:
import com.fujitsu.uji.ejb.EJBCallFactory; import com.fujitsu.uji.ext.CallFactory; public void someMethod(DispatchContext context, MyDataBean dataBean) { EJBCallFactory callFactory=(EJBCallFactory)context.getCallFactory(CallFactory.EJB); 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 7.4 Automatic Deletion of Session
Bean Object.
7.2.2 Coding Sample for Getting a Home Interface from the EJBCallFactory Class
The following is a coding sample:
import com.fujitsu.uji.ejb.EJBCallFactory; import com.fujitsu.uji.ext.CallFactory; public void someMethod(DispatchContext context, MyDataBean dataBean) {
78
EJBCallFactory callFactory=(EJBCallFactory)context.getCallFactory(CallFactory.EJB); SomeEntityHome home=(SomeEntityHome)callFactory.getHome("java:comp/env/ejb/someSessionBean"); SomeEntity remote=home.findByPrimaryKey(...); 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.
79
7.5 EJB Session Beans Grouping Function (new)
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 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 Chapter 6 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.
80
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 Part 4 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.
<?xml version="1.0" encoding="iso-8859-1"?> <remoteMap xmlns="http://interstage.fujitsu.com/schemas/uji/remoteMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/remoteMap http://interstage.fujitsu.com/schemas/uji/remotemap.xsd"> <config> <version>5.0</version> <defaultSoapApi>Interstage_JAXM</defaultSoapApi> </config> <!-- Define a group of session Beans to be called with EJB session Beans grouping.--> <ejbExt name="MySessionBeans" type="proxy" recoverTime="10" > <application name="java:comp/env/ejb/MySessionBean1" /> <application name="java:comp/env/ejb/MySessionBean2" /> <application name="java:comp/env/ejb/MySessionBean3" /> </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:
81
public Object doSomething(DispatchContext context, DataBean dataBean){ CallFactory factory = context.getCallFactory(); // 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
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:
82
· 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 Operation Guide or Interstage Management Console Help.
· 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
EJBs. If the name of an EJB application is foo, the JNDI lookup name is "java:comp/env/ejb/foo."
7.6 Retrying EJBs (new)
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.
83
Note that the EJB retry function allows you to call only session Beans that were created with Apcoordinator.
Use the Chapter 6 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 Part 4 Developing an EJB Application.
For notes on creating session Beans to be called by the EJB retry function, see 7.6.3 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 21.2.1 Exception Handling in Part 4
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 Chapter
6 Remote Common Interface. For details of the remote map, see 6.2 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:
<?xml version="1.0" encoding="iso-8859-1"?> <remoteMap xmlns="http://interstage.fujitsu.com/schemas/uji/remoteMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
84
xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/remoteMap http://interstage.fujitsu.com/schemas/uji/remotemap.xsd"> <config> <version>5.0</version> </config> <!-- Specify a session Bean to be called using the EJB retry function.--> <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 interfaces are used to call applications through the Chapter 6 Remote Common Interface. For details, see Calling
with the 6.3 Calling Using the CallFactory Interface and Call Interface. This section describes how to use these interfaces with the EJB retry function.
85
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.DispatchContext; import com.fujitsu.uji.ext.CallFactory; import com.fujitsu.uji.ext.Call; import com.fujitsu.uji.ext.UjiCreateException; import com.fujitsu.uji.ext.UjiRemoteException; import com.fujitsu.uji.ext.UjiTargetException; ... public Object doSomething(DispatchContext context, SomeBean dataBean) { // Get the CallFactory interface. CallFactory factory = context.getCallFactory(); 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. 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.
86
Using the EJB retry function together with the EJB session Beans grouping fun
ction
The EJB retry function can operate together with the 7.5 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:
<?xml version="1.0" encoding="iso-8859-1"?> <remoteMap xmlns="http://interstage.fujitsu.com/schemas/uji/remoteMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/remoteMap http://interstage.fujitsu.com/schemas/uji/remotemap.xsd"> <config> <version>5.0</version> </config> <!-- Define a group of session Beans to be called with EJB session Beans grouping. --> <!-- Also define retry exceptions. --> <ejbExt name="MySessionBeans" type="proxy" > <application name="java:comp/env/ejb/MySessionBean1" /> <application name="java:comp/env/ejb/MySessionBean2" /> <application name="java:comp/env/ejb/MySessionBean3" /> <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 session Bean object is created whenever the invoke method of the Call object is called. Specifying true
87
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 applicatio
n 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.
88
89
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 8.4 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 Chapter 6 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 Chapter 25 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);
90
// Getting of UjiServiceCall 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
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 String url = new String("http://some.host/service"); UjiServiceCall call = callFactory.createUjiServiceCall(url,"urn:foobar", SOAPCallFactory.APACHE); // Service calling XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
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
91
import com.fujitsu.uji.soap.SOAPCallFactory; import javax.xml.rpc.Call; public void someMethod(DispatchContext context, MyDataBean dataBean) { ... // Getting of CallFactory SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP); 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.SOAPCallFactory; import com.fujitsu.uji.soap.ServiceCall; import com.fujitsu.uji.soap.Response; import com.fujitsu.uji.soap.Parameter; import com.fujitsu.uji.soap.Parameters; public void someMethod(DispatchContext context, MyDataBean dataBean) { ... // Return value type setting Class[] paramTypes = new Class[]{String.class}; // Method parameter type setting Parameters params = new Parameters(); params.add("param1", String.class, "add"); // Getting of CallFactory SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP);
92
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.SOAPCallFactory; 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; public void someMethod(DispatchContext context, MyDataBean dataBean) { ... // 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, beanSer);
93
// Getting of CallFactory String url = new String("http://some.host/service"); SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP); 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.SOAPCallFactory; import com.fujitsu.uji.soap.UjiServiceCall; import com.fujitsu.uji.ext.UjiRemoteException; import com.fujitsu.uji.ext.UjiTargetException; import com.fujitsu.uji.soap.UjiSoapException; public void someMethod(DispatchContext context, XMLDataBean dataBean) { ... // Getting of CallFactory SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP); // Getting of UjiServiceCall String url = new String("http://some.host/service");
94
UjiServiceCall call =callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM); // Service calling try { XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); } 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.
95
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:
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 String url = new String("http://some.host/service"); UjiServiceCall call =callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM); call.setUserName("username"); call.setPassword("password"); // Service calling XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
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
96
- Specify the host name and port number of the proxy in setProxy. · 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
import com.fujitsu.uji.soap.SOAPCallFactory; import com.fujitsu.uji.soap.UjiServiceCall; public void someMethod(DispatchContext context, XmlDataBean dataBean) throws Exception { ... // Getting of CallFactory SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP); // Getting of UjiServiceCall String url = new String("http://some.host/service"); UjiServiceCall call =callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM); call.setProxy("proxyaddress", port); // Service calling XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
Example of calling a Web service when the proxy for the Basic authentication is set
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 String url = new String("http://some.host/service"); UjiServiceCall call =callFactory.createUjiServiceCall(url,"urn:foobar", SOAPCallFactory.INTERSTAGE);
97
call.setProxy("proxyaddress", port, "username", "password"); // Service calling XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
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:
import com.fujitsu.uji.soap.SOAPCallFactory; import com.fujitsu.uji.soap.UjiServiceCall; public void someMethod(DispatchContext context, XmlDataBean dataBean) { private UjiServiceCall call; ... // Getting of CallFactory SOAPCallFactory callFactory=(SOAPCallFactory)context.getCallFactory(CallFactory.SOAP); // Getting of UjiServiceCall String url = new String("http://some.host/service"); if(call == null) { call=callFactory.createUjiServiceCall(url,null, SOAPCallFactory.INTERSTAGE_JAXM); call.setMaintainSession(true); } // Service calling XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
98
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:
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 String url = new String("http://some.host/service"); 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 XmlDataBean response=(XmlDataBean)call.invoke(dataBean,verb); ... }
99
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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/commandMap http://interstage.fujitsu.com/schemas/uji/commandmap.xsd"> <config> <version>5.0</version> </config> <!-- Add sample1.BodyBean;add --> <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> <!-- Initialization ; --> <entry> <!-- Create a BodyBean instance --> <newBean cls="sample1.BodyBean" /> <setResponseBean pane="body" verb="reqmode" /> <invoke name="setHead"/> </entry> <!-- Subroutine setHead --> <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>
100
</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>
101
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.
102
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.
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 {
103
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(); } }
104
105
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
106
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
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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec http://interstage.fujitsu.com/schemas/uji/espec.xsd"> <config> <version>6.0</version> </config> <specification name="sampleCheck" > <section name="sect1" > <!-- Check the property sampleNumber is in the range of 0 or more and 10 or less. --> <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".
107
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.
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.
108
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
<?xml version="1.0" encoding="iso-8859-1" ?> <eSpec xmlns="http://interstage.fujitsu.com/schemas/uji/espec" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec http://interstage.fujitsu.com/schemas/uji/espec.xsd"> <config> <version>6.0</version> </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="#10 or less" /> </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:
<verify property="sampleNumber" op="GE" operand="#0" exception="#ERR01" info="#0 or more" />
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).
109
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 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.
110
<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 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.
111
· 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; } }
import com.fujitsu.uji.xscript.ESpecValidator; 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:
<!-- Unconditionally assign sample1 to targetProp1 --> <term property="sample1" target="targetProp1" /> <!-- When the string length of sample2 is 0, assign the character string "none" to targetProp2 --> <term property="sample2" function="stringLength" op="EQ" operand="#0" value="#none" target="targetProp2" /> <!-- Add 1 to sample3, then assign the result to targetProp3 -->
112
<term property="sample3" op="ADD" operand="#1" target="targetProp3" /> <!-- Assign the result of sample4 with myFormat applied to targetProp4 --> <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 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.
113
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" /> <verify property="sampleNumber" op="LE" operand="#10" exception="#ERR01" info="#10 or less" /> </block>
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:
114
<value seq="1" property="flight" op="EQ" operand="#101" /> <value seq="2" property="flight" op="EQ" operand="#103" /> <value seq="3" property="flight" op="EQ" operand="#105" /> <value seq="4" property="flight" op="EQ" operand="#107" /> <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" /> <status seq="5" require="true" /> </decision> <decision exception="#ERR02" info="#Special discount not specified" > <status seq="2" require="true" /> <status seq="7" require="true" /> </decision> <decision exception="#ERR03" info="#First class seats not specified" > <status seq="3" require="true" /> <status seq="6" require="true" /> </decision> <decision exception="#ERR02" info="#Special discount not specified" > <status seq="4" require="true" /> <status seq="7" require="true" /> </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.
115
· 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.
<?xml version="1.0" encoding="iso-8859-1" ?> <eSpec xmlns="http://interstage.fujitsu.com/schemas/uji/espec" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec http://interstage.fujitsu.com/schemas/uji/espec.xsd"> <config> <version>6.0</version> </config> <specification name="sampleCheck" > <control> <validate section="sect1" /> <validate section="^nextSection" /> </control> <section name="sect1" > ... <term property="#true" value="#sect2" target="^nextSection" /> </section> <section name="sect2" > ... </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
116
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.
<?xml version="1.0" encoding="iso-8859-1" ?> <eSpec xmlns="http://interstage.fujitsu.com/schemas/uji/espec" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec http://interstage.fujitsu.com/schemas/uji/espec.xsd"> <config> <version>6.0</version> </config> <specification name="sampleCheck" > <control> <validate section="sect1" node="subBean" targetNode="subTarget" /> <validate section="sect2" node="*detail" /> </control> <section name="sect1" > ... </section> <section name="sect2" > ... </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,
117
"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" />
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.
<?xml version="1.0" encoding="iso-8859-1" ?> <eSpec xmlns="http://interstage.fujitsu.com/schemas/uji/espec" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/espec http://interstage.fujitsu.com/schemas/uji/espec.xsd"> <config> <version>6.0</version> <debug>trace</debug> </config> <specification name="sampleCheck" > ... </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.
118
· 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:
import com.fujitsu.uji.DispatchContext; import com.fujitsu.uji.xscript.ESpecValidator; import com.fujitsu.uji.xscript.ESpecResultException; 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) } catch(ESpecResultException e) { ... // (5) } catch(Exception e) { throw e; // (6) } ... }
(1) Create an instance of the ESpecValidator class. To call user-defined methods, specify ClassLoader as an argument.
119
(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
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.
<?xml version="1.0" encoding="iso-8859-1"?> <commandMap xmlns="http://interstage.fujitsu.com/schemas/uji/commandMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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>
120
· 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 Chapter 9 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:
java com.fujitsu.uji.xscript.compiler.ESpecCompiler 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.
121
· 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.
import com.fujitsu.uji.DispatchContext; import com.fujitsu.uji.xscript.ESpecValidator; import com.fujitsu.uji.xscript.ESpecResultException; 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); } catch(ESpecResultException e) { ... } catch(Exception e) { throw e; } ... }
getInstance Takes the character string argument "package-name.class-name." In the sample above, the
122
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.
XML-described data specification
<verify property="prop1" op="GE" operand="#0" error="#ERR01" info="#prop1" /> <verify property="prop2" op="GE" operand="#0" error="#ERR02" info="#prop2" /> <verify property="prop3" op="LE" operand="#10" error="#ERR03" info="#prop3,#10" />
Business class methods
try { validator.validate("checkValue", bean); } catch(ESpecResultException e) { 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) ... } ... } catch(Exception e) { throw e;
123
} ... } catch(Exception e) { 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.
(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.
XML-described data specification
<verify property="prop1" op="GE" operand="#0" error="#ERR01" info="#prop1" /> <verify property="prop2" op="GE" operand="#0" error="#ERR02" info="#prop2" /> <verify property="prop3" op="LE" operand="#10" error="#ERR03" info="#prop3,#10" />
Resource file code
<?xml version="1.0" encoding="iso-8859-1"?> <ujiResource xmlns="http://interstage.fujitsu.com/schemas/uji/ujiResource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/ujiResource http://interstage.fujitsu.com/schemas/uji/ujiresource.xsd"> <config>
124
<version>5.1</version> </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 { validator.validate("checkValue", bean); } catch(ESpecResultException e) { 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]); ... } ... } catch(Exception e) { 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.
125
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: Chapter 19 Setting Up a Web Application Execution Environment · EJB session Bean: Chapter 22 Setting Up a Session Bean Execution Environment · SOAP server application: Chapter 25 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 -
126
*1 Each of the following products supplies jick.jar from the Interstage Apworks server runtime
that is in the product. The default installation folder is C:¥Interstage¥APW¥JICK¥V4¥lib.
· Interstage Application Server Plus · Interstage Application Server
The following products install jick.jar in C:¥Interstage¥APW¥JICK¥V4¥lib 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
16.1 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.
Chapter 5 XML linkage Any
of: - Apache Xerces
- Apache Xalan -
Application server provided
by any of the following
products:
- Interstage Application
Framework Suite Standard
Edition
- Interstage Application
Framework Suite Enterprise
Edition
- Interstage Application
Server Plus
- Interstage Application
Server Plus Developer
- Interstage Application
Server Standard Edition
- 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)
Chapter 8 Web service
call
Part 5 SOAP server
application
Any
of: - Apache Xerces
- Apache Xalan -
(*1) Modify the isj2ee.properties file to enable Fujitsu XML Processor to be used.
127
11.3 Initialization Parameters
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. o o o
logLevel
Specifies the log output level.
Specify this parameter to change
the level.
o o o
commandMap
Specifies the name of a command map
file. Specify this parameter to
change the name. (*1)
o o o
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.
o - -
uji.remoteMap
Specifies the name of a remote map
file. Specify this parameter to
change the name. (*1)
o o o
uji.convMap
Specifies the name of a data Bean
conversion map file. Specify this
parameter to change the name. (*1)
o o o
uji.database.connection.minpoolsize
Specifies the number of pool
connections in database linkage.
The specified number of
connections is always acquired.
o - -
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.
o - -
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.
o - -
uji.doubleClick.DelayedFlush
Specifies when to flush the buffer
used to output responses when a
uji:controlSection tag is used.Specify true or false. The
default is false. Specifying false
flushes the buffer before
execution of a business class.
Specifying true flushes the buffer
after execution of a business
o - -
128
Application
type Parameter Description
Web EJB SOAP
class. Although specifying true
displays an exception generated
during execution of the business
class in a browser, the scope of
the validity of the function
preventing duplicate processing
narrrows. Therefore, for
debugging of a business class,
specify true.
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.
o - -
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.
o - -
uji.backupResponseBeans
Specifies the size of the stack for
backing up response beans. If the
number of backups exceeds the
number specified by this
parameter, backups exceeding the
limit are deleted. The default
value is 5.
o - -
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.
- o o
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
- o -
129
Application
type Parameter Description
Web EJB SOAP
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.
o - -
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 .
o - -
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, Object,
boolean) method.
o - -
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.
o - -
uji.handleException.wrap Specifies how a reported exception
is thrown. If true is specified,
the parent class of the business
o o o
130
Application
type Parameter Description
Web EJB SOAP
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".
o o o
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.
o o o
uji.handlerConfig
Specifies the name of a file to be
used as a business class
configuration file. The default is
handlerconfig.xml.
o o o
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 (/).
For information about how to set initialization parameters, see the following pages:
· Web application: Chapter 19 Setting Up a Web Application Execution Environment · EJB session Bean: 21.1.2 Setting Session Bean Initialization Parameters · SOAP server application: 24.3 Developing a Service Class
131
Part 3 Development of Web Application
132
133
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.
134
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.
135
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
136
names. Rewriting the relationship definition files can replace the input-output pages and methods.
137
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.
138
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.
139
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 classMethod
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
140
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.
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
A.1 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 Appendix B 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 A.1 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:
141
;=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:
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:
public void startup(DispatchContext context) { 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); context.setResponseBean("head", headBean); }
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.
142
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.
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 A.1 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 3.6.1 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) { ....
143
}
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.
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. 14.2 Screen Part Tags contains a description of how to do this.
144
145
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: 13.3 Webcoordinator Application Files · Tags used for session management: 15.1.5 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. A.2 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
146
creating tables or selection items, they can easily be written by using the 14.4.1 component
tag.
Before using a screen part tag, prepare a data Bean that installs the interface determined for each part.
The 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>
147
</uji:tableRenderer>
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> <uji:tableRenderer type="column" cls="editable" > <TD><INPUT name="<uji:name/>" value="<uji:value/>"></TD> </uji:tableRenderer>
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
148
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.
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.
149
The tree has the following data structure:
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>
150
<FONT color="black" ><uji:getProperty property="value" /></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:
151
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:compositeRenderer> .... </uji:compositeRenderer> </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"> <uji:validate event="blur" type="int" minInclusive="10" maxInclusive="20" >
152
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 14.4.1 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.
Because of the above, use the client script or JavaScript under the following conditions:
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:
153
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"> 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:
154
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) {"; } }
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() {
155
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.
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:
156
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
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.
157
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 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 {
158
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; public class BodyBean extends com.fujitsu.uji.DataBean { protected String strData; public String getStrData() { return strData; } public void setStrData(String strData) { this.strData = strData; } ... }
JSP definitions are the same as those for item classes.
159
<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" /> ... </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>
160
<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.*; import com.fujitsu.uji.compo.*; 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(); } catch(Exception e) { return "0000/01/01"; // Error value } } }
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 }
161
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.
uji:recordView
Input item with a label
uji:tableView
Item in a table
162
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:
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; import com.fujitsu.uji.compo.*; public class BodyBean extends com.fujitsu.uji.DataBean { protected ComboBox comboData = new ComboBox(); public ComboBox getComboData() { return comboData;
163
} ... }
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
4.6 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.
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:
164
Setting data
Create a TableView class as a property in a data Bean.
package sample; import com.fujitsu.uji.compo.*; public class BodyBean extends com.fujitsu.uji.DataBean { 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.
<FORM> <uji:tableView bean="body" property="tableView" width="400" background="yellow" /> </FORM>
Creating a header row
A header row can be added to tables.
... TableView table = dataBean.getTableView(); table.setHeader(new Object[] { "product-name", "price", "quantity" } );
165
...
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> <uji:tableView bean="body" property="tableView" 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> <uji:tableView bean="body" property="tableView" 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> <uji:tableView bean="body" property="tableView" 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> <uji:tableView bean="body" property="tableView" 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>
166
<uji:tableView bean="body" property="tableView" 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> <uji:tableView bean="body" property="tableView" 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"); TableView table = dataBean.getTableView(); table.setAttributeAt(attr, 0, 0); ...
Concatenating cells
Tag attributes can be used to concatenate cells for display.
<FORM> <uji:tableView bean="body" property="tableView" 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 com.fujitsu.uji.compo.*; import java.text.*; public class NumberFormatCell implements CellModel {
167
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(); } catch(Exception e) { try { // 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.
... TableView table = dataBean.getTableView(); 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.
168
package sample; import com.fujitsu.uji.compo.*; public class BodyBean extends com.fujitsu.uji.DataBean { 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.
public void startup(DispatchContext context) { 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, ....">
169
<uji:tableView bean="body" property="tableView" 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.
· 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.
<FORM method="post"> <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:
170
· 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; import com.fujitsu.uji.compo.*; public class BodyBean extends com.fujitsu.uji.DataBean { protected TreeView treeView = new TreeView(); public TreeView getTreeView() { return treeView; } ... }
Add data lines to the TreeView class.
... TreeNodeRow root = new TreeNodeRow(new Object[] { "root" }); TreeNodeRow child1 = new TreeNodeRow(new Object[] { "child1" }); TreeNodeRow child2 = new TreeNodeRow(new Object[] { "child2" }); TreeNodeRow child3 = new TreeNodeRow(new Object[] { "child3" }); root.addChild(child1); root.addChild(child2); root.addChild(child3); TreeNodeRow grandchild11 = new TreeNodeRow(new Object[] { "grandchild1" }); TreeNodeRow grandchild12 = new TreeNodeRow(new Object[] { "grandchild2" });
171
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.
<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.
172
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. </uji:borderLayoutRenderer> <uji:borderLayoutRenderer place="west"> ... Define HTML coding as being on the left side of the screen. </uji:borderLayoutRenderer> <uji:borderLayoutRenderer place="center"> ... Define HTML coding as being in the center of the screen. </uji:borderLayoutRenderer> <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.
173
<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" > ... Define HTML coding to be located according to the grid coordinates. </uji:gridLayoutRenderer> <uji:gridLayoutRenderer gridX="0" gridY="1" > ... Define HTML coding to be located according to the grid coordinates. </uji:gridLayoutRenderer> <uji:gridLayout>
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>
174
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 Chapter 5 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 11.2 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:
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
175
Tag Function
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)
<?xml version="1.0" encoding="ISO-8859-1" ?> <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; .... public void startup(DispatchContext context) { 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");
176
// Create an XML data Bean. XmlDataBean xmlBean = new XmlDataBean(); // 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(); } } ....
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.
177
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:
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)
<?xml version="1.0" encoding="ISO-8859-1" ?> <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,
178
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"
:
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.
179
Tag Description
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>
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.
180
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>
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>
181
<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 14.5.2 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]).
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
182
Tag XML item class(*)
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)
<?xml version="1.0" encoding="ISO-8859-1" ?> <root> <member> <name>David</name> <hobby1>Baseball</hobby1> </member> <sports> <data>Baseball</data>
183
<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.XmlDataBean; 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: 12: public void startup(DispatchContext context) { 13: try { 14: // Create the File object that indicates a file to be loaded. 15: ServletContext sc =
184
((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
<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
185
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: 29: // Specify an XML data Bean to be displayed 30: context.setResponseBean("body",dataBean); 31: }
186
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:
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
187
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; import com.fujitsu.uji.http.HttpDispatchContext;
188
... 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:
import com.fujitsu.uji.http.Window; import com.fujitsu.uji.http.WindowController; import com.fujitsu.uji.http.HttpDispatchContext; ... public void someHandler(DispatchContext context, MyDataBean dataBean) { WindowController wCtrl = ((HttpDispatchContext)context).getWindowController(); // (1) Window subWin = wCtrl.getWindow("subWindow"); // (2) subWin.close();
189
// (3) context.setResponseBean("mainBody",dataBean,true); // (4) }
· (1) Get WindowController by using the getWindowController method of the HttpDispatchContext 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:
import com.fujitsu.uji.http.Window; import com.fujitsu.uji.http.WindowController; import com.fujitsu.uji.http.HttpDispatchContext; ... public void someHandler(DispatchContext context, MyDataBean dataBean) { WindowController wCtrl = ((HttpDispatchContext)context).getWindowController(); // (1) Window mainWin = wCtrl.getWindow(Window.MAIN_WINDOW); // (2) mainWin.update(); // (3) context.setResponseBean("mainBody",new MainDataBean(),true); // (4) context.setResponseBean("subBody",dataBean,true); // (5) }
· (1) Get WindowController by using the getWindowController method of the HttpDispatchContext 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
190
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:
import com.fujitsu.uji.http.Window; import com.fujitsu.uji.http.WindowController; import com.fujitsu.uji.http.HttpDispatchContext; ... // Variable used to store the Window object of the subwindow Window subWin = null; public boolean init() { // Specify this business class for the session scope. return true; } // Method to be called for the first access public void startup(DispatchContext context) { WindowController wCtrl = ((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();
191
... }
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 15.1.5 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
192
on how to use subwindows, see 14.6 Window Control.
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" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <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 contentType= "text/html; charset=iso-8859-1" %> <%@ page errorPage="ErrorPage.jsp" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <HTML> <BODY> <uji:dispatch /> <uji:include pane="mainHeader" /> <uji:include pane="mainBody" /> <uji:windowControl/> </BODY>
193
</HTML>
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:
public void startup(DispatchContext context) { 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 14.6 Window Control.
import com.fujitsu.uji.http.Window; import com.fujitsu.uji.http.WindowController; import com.fujitsu.uji.http.HttpDispatchContext; ... public void someHandler(DispatchContext context, MyDataBean dataBean) { WindowController wCtrl = ((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) ... }
194
· (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.
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.
import com.fujitsu.uji.http.Window; import com.fujitsu.uji.http.WindowController; import com.fujitsu.uji.http.HttpDispatchContext; ... public void someMethod(DispatchContext context, MyDataBean dataBean) { 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>
195
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:
public void someMethod(DispatchContext context, MyDataBean dataBean) { context.setResponseBean("mainHeader",new HeaderBean(), 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.
public void someMethod(DispatchContext context, MyDataBean dataBean) { 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>
196
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 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 15.1.5 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.
197
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:
198
1) Create a session class that extends HttpSessionProfile.
package sample; public class SampleSession extends 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.
public void startup(DispatchContext context) { 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 "19.1 Files Required at
Execution" Web Application Environment Definition File.
199
Follow the same procedure to create an application class.
1) An application class extends ApplicationProfile.
package sample; public class SampleApplication extends com.fujitsu.uji.ApplicationProfile { }
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 WWW 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.
200
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.
.
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.
201
package sample; public class SampleSession extends com.fujitsu.uji.http.HttpSessionProfile implements javax.servlet.SingleThreadModel { }
Same business class Different business class
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 business class Different business class
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.
202
package sample; public class SampleApplication extends com.fujitsu.uji.ApplicationProfile { public String notifyBeanLost(String id) { return("timeout"); } }
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 class SampleHandler extends com.fujitsu.uji.GenericHandler { 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" /> <FORM method="post"> <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
203
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.id" type="hidden" value="body"> <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.
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; } return Preprocessor.EVAL; } }
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) {
204
// When the context is stored, processing is reexecuted. Dispatcher.redispatch(context, sp.savedContext); sp.savedContext = null; } else { // Processing of the initial screen .... } }
15.1.5 Advanced Session Management
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.
205
<FORM> <uji:controlState /> ... </FORM>
2) Entend a session class from HttpControlStateProfile.
package sample; public class SampleSession extends com.fujitsu.uji.http.HttpControlStateProfile { }
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.
206
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.
public void finalHandler(DispatchContext context, SomeBean dataBean) { .... context.setResponseBean("body", 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>
207
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" 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:
208
Add enctype="multipart/form-data" to the form tag. Specify type="file" in the input field of file name input. Delete the initial value.
<%@ taglib uri="uji-taglib" prefix="uji" %> <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>
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.
209
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 4.3 Error Processing.
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>
210
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.
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 "19.1
Files Required at Execution" 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> <servlet-name>download</servlet-name> <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 4.3 Apcoordinator Core Function Error
Processing.
The JSP error page can be specified at two locations.
211
@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 contentType= "text/html; charset=iso-8859-1" %> <%@ page isErrorPage="true" %> <%@ 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); */
212
// 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); } } } %> </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();
213
// 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); return; } // For NumberFormatException, Webcoordinator // specifies new BigInteger(0). Replace it with another exception. ex = new IllegalArgumentException("Error in someIntProp"); }
214
215
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 11.2 Required Software.
For information on required files and settings for execution of the application, see Chapter 19 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 {
216
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 15.1.1 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() { return dbView; }
217
public void setDbView(DBTableView dbView) { this.dbView = dbView; } }
In the database linkage class, specify the connection and search method obtained from the application
class.
public void startup(DispatchContext context) { 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" dataEditable="false;false;false;false;true" />
Updating data
Use the update method of the database linkage class to register input data in the database.
218
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 "19.1 Files Required at Execution" 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-name>factory</param-name> <param-value>MyFactory</param-value> </context-param> <taglib> <taglib-uri>uji-taglib</taglib-uri> <taglib-location>/WEB-INF/ujiall.tld</taglib-location> </taglib> </web-app>
219
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 The applet linkage feature of the Apcoordinator supports the following plug-ins:
· JBK Plugin provided by any of the following: - Interstage Application Server Plus V5.0.1 - Interstage Application Server Plus Developer V5.0.1 · Java Plug-in 1.3.1 and Java Plug-in 1.4.1
· 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.
220
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 Chapter 3 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 Chapter 3 Major Components of Apcoordinator Applications.
Defining a servlet class
Create a servlet class by inheriting the ObjectSerializeServlet class.
public class MainServlet extends
221
com.fujitsu.uji.http.ObjectSerializeServlet { 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
222
UjiServletConnection conn = null; // 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.
import java.net.URL; import com.fujitsu.uji.ext.UjiServletConnection; /* * Initialization */ protected void initUser () {
223
try{ // 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"); } catch(Exception e){ // Code communication error handling. } }
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.
import java.net.URL; import com.fujitsu.uji.ext.UjiServletConnection; 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.
224
MyBean reqBean = new MyBean(); MyBean resBean = (MyBean)conn.invoke(reqBean,"verb"); } catch(Exception e){ // Code communication error handling. } }
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 Chapter 19 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.
225
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.
<uji:useBean id="body" cls="sample.BodyBean" request="true" /> <FORM method="post"> <INPUT name="uji.id" type="hidden" value="body"> <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.
226
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 "19.1 Files Required
at Execution" 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
227
Chapter 19 Defining the Web Application
Environment
19.1 Files Required at Execution
This section describes the files required for executing a Webcoordinator application.
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.
<?xml version="1.0" encoding="UTF-8"?> <!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> <param-name>factory</param-name>
228
<param-value>sample2.Sample2Factory</param-value> </context-param> <servlet> <servlet-name>download</servlet-name> <servlet-class>updown.DownloadServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>download</servlet-name> <url-pattern>/download</url-pattern> </servlet-mapping> <taglib> <taglib-uri>uji-taglib</taglib-uri> <taglib-location>/WEB-INF/ujiall.tld</taglib-location> </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
11.3 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 11.2 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.
229
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.
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.
230
231
Part 4 Developing EJB Applications
232
233
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.
234
Home interface
An interface used to create and remove EJB objects. This is used by EJB clients.
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.
235
· 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.
236
Developing a Client
For information on developing a EJB client, see the following sections.
Type of client
application Type of EJB Section to be referred to
A session Bean developed
using Apcoordinator
Chapter 6 Unified Remote
Interface
7.1 Calling Session Beans
Developed Using Apcoordinator
Apcoordinator
application
A general EJB 7.2 Calling a General EJB
Non-Apcoordinator
application
A session Bean developed
using Apcoordinator
21.3.5 Linkage to
Non-Apcoordinator Clients
237
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:
package ejboffice.ejb; 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; }
238
Code the signature of the create() method as follows:
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.
package ejboffice.ejb; 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:
package ejboffice.ejb; import ejboffice.*; import com.fujitsu.uji.DispatchContext; 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) {
239
// Describe the process int index=dataBean.getIndex(); ... dataBean.putHeader(header); // Specify the return object return dataBean; } // Define other methods, if necessary ... }
For information about how to create a business class, see 3.1 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 21.3.6 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 3.6.1 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 3.3 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
240
user-defined application class, see 3.4 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 3.5 Factory Class. For
information about how to set initialization parameters, see 21.1.2 Setting Up Session Bean Initialization
Parameters.
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 11.3 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; public class OfficeEJB extends UjiSessionBean { 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.
241
Setting item Deployment
descriptor tag Value to be set
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 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:
<?xml version="1.0" encoding="UTF-8"?> <!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>
242
</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. - 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
243
and handled as described above. For information about the handleException method, see 4.3 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) { // Getting the value of java:comp/env/initialCount from the 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 =
244
(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
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:
245
import com.fujitsu.uji.ejb.bean.UjiSessionBean; import java.lang.reflect.InvocationTargetException; public class OfficeEJB extends UjiSessionBean { 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.
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 Chapter 7 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.
246
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
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
247
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 21.3.6 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.
The following is a coding sample:
<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>
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"
248
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>
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.
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.
249
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
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]"
250
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:
· 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:
<?xml version="1.0" encoding="UTF-8"?> <convMap xmlns="http://interstage.fujitsu.com/schemas/uji/convMap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://interstage.fujitsu.com/schemas/uji/convMap http://interstage.fujitsu.com/schemas/uji/convmap.xsd"> <config> <version>5.0</version> </config> <!-- Specify how mypackage.MyBean is to be converted -->
251
<class name="mypackage.MyBean"> <beanConv target="my-Bean"> <property name="description" pass="false"/> </beanConv> </class> <!-- Send ComboBox (including subclasses) choices using index numbers --> <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.
<config> <version>5.0</version> </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.
<class name="mypackage.MyBean"> <beanConv target="my-Bean"> <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
252
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:
<class name="mypackage.MyBean"> <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"> <beanConv target="my-Bean"/> </class> <class name="mypackage.MyBean"> <beanConv target="my-Bean"> <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:
<model name="ComboBox">
253
<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:
<model name="ComboBox"> <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 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.
254
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:
UjiSessionCall call=...; 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:
UjiSessionCall call=...; call.setOverwriteMode(false); call.invoke(dataBean,verb); 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);
255
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()
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:
256
# 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 shows the 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 com.fujitsu.uji.ejb.bean.UjiSessionBean; import java.lang.reflect.InvocationTargetException; public class OfficeEJB extends UjiSessionBean { public Object[] exec(Object dataBean, String verb, Object syncData) throws InvocationTargetException { try { return super.exec(dataBean,verb,syncData); } catch (InvocationTargetException e) { Throwable rootCause=e.getTargetException(); Exception replaced=new Exception(rootCause.getMessage()); throw new InvocationTargetException(replaced); } } }
If a client invoke session Beans developed by the above way and an error occurs in the session Bean, the client
257
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"); ... // 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();
258
// 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.)
259
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 22.3 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 11.1 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 22.3 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. For details, see Interstage
Management Console Help.
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
260
C:¥Interstage¥APC¥lib¥ujiejb.jar
If a new WorkUnit will be created, you can specify the classpaths when the WorkUnit is created.
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 WorkUni
t Startup (new)
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 Classes] tab.
2. Specify the following items on the [Create a new Class] tab, then register the settings made for the
items.
Item Startup Termination
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.
261
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 { 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.
262
263
Part 5 Developing Web Services
264
265
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 24.7 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.
266
Client application Web service called Reference
SOAP server
application created
for use with
Apcoordinator
Chapter 6 Unified Remote
Interface
8.1 Calling
Apcoordinator-based Web
Services
Apcoordinator-based
application
General web service 8.2 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
267
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 5.2 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.
268
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 {
269
public Properties getInitParameters(){ Properties p = new Properties(); p.setProperty("factory", "sample.SoapFactory"); p.setProperty("commandMap", "/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.DispatchContext; import com.fujitsu.uji.GenericHandler; import com.fujitsu.uji.xml.XmlDataBean; 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; } }
270
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
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.DispatchContext; import com.fujitsu.uji.GenericHandler; import com.fujitsu.uji.xml.XmlDataBean; import com.fujitsu.uji.soap.service.SOAPHandlerException; public class MyHandler extends com.fujitsu.uji.GenericHandler { 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.
271
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.
· 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.
272
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.
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.DispatchContext; import com.fujitsu.uji.GenericHandler; import com.fujitsu.uji.xml.XmlDataBean; import com.fujitsu.uji.soap.service.SOAPDispatchContext; public class MyHandler extends com.fujitsu.uji.GenericHandler { 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
273
- 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.
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>
274
<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:
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{
275
// Generate SOAPConnection instance. SOAPConnectionFactory connFactory = SOAPConnectionFactory.newInstance(); SOAPConnection conn = connFactory.createConnection(); // Generate SOAPBody. MessageFactory mesgFactory = MessageFactory.newInstance(); SOAPMessage message = mesgFactory.createMessage(); 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(); }
276
277
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.
278
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.
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 24.6 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.
279
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.
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
280
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:
· 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:
281
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.
Specify the following value for java:
· class : Specify the class name of a service class developed as explained in 24.3 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.
282
· 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".)
283
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> <%@ page contentType= "text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> </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
284
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; public class BodyBean extends com.fujitsu.uji.DataBean { protected String message; protected double val1; protected double val2; protected double result; public String getMessage() { return message; }
285
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
<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <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 <jsp:getProperty name="head" property="loginTime" /> . <BR> <HR><BR>
286
request.jsp
<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <uji:useBean id="body" cls="sample.BodyBean" request="true" /> In the sample program, addition and subtraction between two items are performed. <FORM method="post"> <INPUT name="uji.verbs" type="hidden" value="add,sub"> <INPUT name="uji.id" type="hidden" value="body"> 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
<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <uji:useBean id="body" cls="sample.BodyBean" request="true" /> <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> <FORM method="post"> <INPUT name="uji.verbs" type="hidden" value="next"> <INPUT name="uji.id" type="hidden" value="body"> <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, "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.
287
header.jsp is the only screen that corresponds to HeadBean. The screen mode is not required.
Business Class
SampleHandler.java
package sample; import com.fujitsu.uji.DispatchContext; public class SampleHandler extends com.fujitsu.uji.GenericHandler { public SampleHandler() { } public boolean init() { 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"); context.setResponseBean("body", dataBean); 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"); context.setResponseBean("body", dataBean); setHead(context); } public void next(DispatchContext context, BodyBean dataBean) { dataBean.setVerb("reqmode"); context.setResponseBean("body", dataBean); setHead(context); } public void startup(DispatchContext context) {
288
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); context.setResponseBean("head", headBean); } }
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
pages.map
# pages.map sample.HeadBean;=header.jsp sample.BodyBean;reqmode=request.jsp
289
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.
main.jsp
<HTML>
290
<HEAD> <TITLE>model</TITLE> <%@ page contentType= "text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> </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]; productCount = data[4]; branch = data[5]; deliveryDate = data[6]; customerRegion = data[7];
291
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); } } }
292
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); } } 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).... };
293
}
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; import com.fujitsu.uji.DispatchContext; public class ModelHandler extends com.fujitsu.uji.GenericHandler { protected DataManager dm; public ModelHandler() { } public boolean init() {
294
return true; } public void showDetail(DispatchContext context, ModelBean dataBean) { dataBean.setVerb("detail"); context.setResponseBean("body", dataBean); } public void showSummary(DispatchContext context, ModelBean dataBean) { dataBean.setVerb("summary"); context.setResponseBean("body", dataBean); } public void startup(DispatchContext context) { dm = new DataManager(); dm.prepareData(); ModelBean dataBean = new ModelBean(); dataBean.initData(dm); dataBean.setVerb("summary"); context.setResponseBean("body", dataBean); } }
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
pages.map
# pages.map model.ModelBean;summary=summary.jsp model.ModelBean;detail=detail.jsp
web.xml
295
Same as Appendix A.1. Descriptions are omitted.
Summary (using the table screen part)
summary.jsp
<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <uji:useBean id="body" cls="model.ModelBean" request="true" /> <P>Specification of scheduled delivery date (summary mode) </P> <uji:peTextMode/> <FORM method="post"> <INPUT name="uji.verbs" type="hidden" value="showDetail"> <INPUT name="uji.id" type="hidden" value="body"> <uji:table bean="body" property="summary"> <uji:tableRenderer type="table" > <TABLE border="2" width="100%"><uji:children/></TABLE> </uji:tableRenderer> <uji:tableRenderer type="column" cls="header" > <TH bgcolor="#EEFFEE"><uji:value/></TH> </uji:tableRenderer> <uji:tableRenderer type="column" cls="editable" > <TD><INPUT name="<uji:name/>" value="<uji:value/>"></TD> </uji:tableRenderer> </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 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
296
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) { 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(); }
297
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.
Details (using the list and composite Bean screen parts)
detail.jsp
<%@ page contentType="text/html; charset=iso-8859-1" %> <%@ taglib uri="uji-taglib" prefix="uji" %> <uji:useBean id="body" cls="model.ModelBean" request="true" /> <P>Specification of scheduled delivery date (details mode) </P> <uji:peTextMode/> <FORM method="post"> <INPUT name="uji.verbs" type="hidden" value="showSummary">
298
<INPUT name="uji.id" type="hidden" value="body"> <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> <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>
299
</TR> </uji:compositeRenderer> </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; } 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; }
300
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.
301
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.
302
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
303
after logic execution.
If an exception is thrown, control is passed to the handleException method.
304
305
Appendix C Compatibility with Earlier Versions
of Apcoordinator (new)
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. In an automatic test tool that makes HTML code comparisons, the
changes will appear as differences.
306
307
Appendix D Linkage with Struts (new)
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>
308
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. D.2.1 Setting the data Bean
In the action class, set request or session for the data Bean as the data Bean's scope.
2. D.2.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. D.2.3 Getting data
To be used for a data Bean, get a data that is input to the form with the action class.
Supplement: D.2.4 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; import com.fujitsu.uji.compo.*; 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"}); }
309
public TableView getTable() { return table; } }
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: <?xml version="1.0" encoding="UTF-8"?> <!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>
310
... <taglib> <taglib-uri>uji-taglib</taglib-uri> <taglib-location>/WEB-INF/ujiall.tld</taglib-location> </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."
<%@ taglib uri="uji-taglib" prefix="uji" %> ... <uji:useBean id="myDataBean" cls="mypkg.MyDataBean" scope="request" request="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:useBean id="myDataBean" cls="mypkg.MyDataBean" scope="request" request="true" /> <uji:form name="myform" beanId="myDataBean" action="MyAction.do" > <uji:tableView bean="myDataBean" property="table" borderWidth="1" ruleWidth="1" dataEditable=";;true" /> <input name="submit" type="submit" value="submit"> </uji:form>
311
In the action attribute of the uji:form tag, specify the URL of the servlet. 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 14.4 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:
<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>
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:
312
· 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:
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 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; import com.fujitsu.uji.http.HttpBeanUpdater; ... public class MyAction extends Action { public ActionForward execute(ActionMapping mapping, ActionForm
313
form, HttpServletRequest request, HttpServletResponse response) throws Exception { ServletContext context = 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 O O(*1) -
314
Tag Description In
uji:form
In
html:form
Out
of
form
box.
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
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 O - O
315
Tag Description In
uji:form
In
html:form
Out
of
form
a list.
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
mode using Apworks Page
Editor.
- - O
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
316
Tag Description In
uji:form
In
html:form
Out
of
form
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.
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 Chapter 6 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 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; import com.fujitsu.uji.ext.CallFactory; import com.fujitsu.uji.ext.InitialCallFactory; public class MyAction extends Action { public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception { ... try{ CallFactory factory = (CallFactory)InitialCallFactory.createFactory(servlet); Call call = factory.createCall("myejb"); ResponseBean responseBean = (ResponseBean)call.invoke(dataBean, "verb"); } catch(Throwable e){ ...
317
} ... } }
To 21.3.1 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.
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 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; import com.fujitsu.uji.ext.CallFactory; import com.fujitsu.uji.ext.InitialCallFactory; public class MyAction extends Action {
318
public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception { ... 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"); 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.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
319
"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> <!-- Struts Tag Library Descriptors --> <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> <!-- UJI Tag Library Descriptor --> <taglib> <taglib-uri>uji-taglib</taglib-uri> <taglib-location>/WEB-INF/ujiall.tld</taglib-location> </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
320
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>
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>
321
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.
322
Attribute
Tag attribute. In the following example, id and cls are called the attribute names and "body" and
"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
323
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,
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.
324
Deployment Descriptor
The deployment descriptor is a file containing information required to install an application into an operating
environment.
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 WWW server. An HTTP request is sent according
to the HTTP protocol.
325
HTTP Response
The processing result of a request sent from the WWW server to the browser.
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
326
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.
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.
327
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.
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.
328
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.
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.
329
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.
