null  null

uCosminexus Application Server

Common Container Functionality Guide

3020-3-Y07-10(E)

■ Relevant program products

See the manual

uCosminexus Application Server Overview

.

■ Export restrictions

If you export this product, please check all restrictions (for example, Japan's Foreign Exchange and Foreign Trade Law, and USA export control laws and regulations), and carry out all required procedures.

If you require more information or clarification, please contact your Hitachi sales representative.

■ Trademarks

Active Directory is either a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.

AIX is a trademark of International Business Machines Corporation in the United States, other countries, or both.

AX2000 is a product name of A10 Networks, Inc.

F5, F5 Networks, BIG-IP and iControl are trademarks or registered trademarks of F5 Networks, Inc. in the U.S. and certain other countries.

All Borland brand and product names are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.

BSAFE is a registered trademark or a trademark of EMC Corporation in the United States and/or other countries.

CORBA is a registered trademark of Object Management Group, Inc. in the United States.

HP-UX is a product name of Hewlett-Packard Development Company, L.P. in the U.S. and other countries.

IIOP is a trademark of Object Management Group, Inc. in the United States.

Linux(R) is the registered trademark of Linus Torvalds in the U.S. and other countries.

Microsoft is either a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries.

OMG, CORBA, IIOP, UML, Unified Modeling Language, MDA and Model Driven Architecture are either registered trademarks or trademarks of Object Management Group, Inc. in the United States and/or other countries.

Oracle and Java are registered trademarks of Oracle Corporation and/or its affiliates.

Red Hat is a trademark or a registered trademark of Red Hat Inc. in the United States and other countries.

RSA is a registered trademark or a trademark of EMC Corporation in the United States and/or other countries.

SOAP is an XML-based protocol for sending messages and making remote procedure calls in a distributed environment.

UNIX is a registered trademark of The Open Group in the United States and other countries.

VisiBroker is a trademark or registered trademark of Micro Focus IP Development Limited or its subsidiaries or affiliated companies in the

United Kingdom, United States and other countries.

Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

X/Open is a registered trademark of The Open Group in the U.K. and other countries.

Eclipse is an open development platform for tools integration provided by Eclipse Foundation, Inc., an open source community for development tool providers.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

The other company names and product names are either trademarks or registered trademarks of the respective companies. Throughout this document Hitachi has attempted to distinguish trademarks from descriptive terms by writing the name with the capitalization used by the manufacturer, or by writing the name with initial capital letters. Hitachi cannot attest to the accuracy of this information. Use of a trademark in this document should not be regarded as affecting the validity of the trademark.

■ Microsoft product name abbreviations

This manual uses the following abbreviations for Microsoft product names:

Abbreviation

Active Directory

Microsoft IIS

SQL Server

Microsoft IIS 7.0

Microsoft IIS 7.5

SQL Server 2005

SQL Server 2008

Full name or meaning

Microsoft(R) Active Directory(R)

Microsoft(R) Internet Information Services 7.0

Microsoft(R) Internet Information Services 7.5

Microsoft(R) SQL Server 2005

Microsoft(R) SQL Server 2008

SQL Server

JDBC driver for

SQL Server

Windows

Abbreviation

SQL Server 2008

SQL Server 2012

SQL Server JDBC Driver

Windows Server

2008

Windows Server

2008 x86

Full name or meaning

Microsoft(R) SQL Server 2008 R2

Microsoft(R) SQL Server 2012

Microsoft(R) SQL Server JDBC Driver 3.0

Microsoft(R) JDBC Driver 4.0 for SQL Server

Microsoft(R) Windows Server(R) 2008 Standard 32-bit

Microsoft(R) Windows Server(R) 2008 Enterprise 32-bit

Windows Server

2008 x64

Windows Server

2008 R2

Microsoft(R) Windows Server(R) 2008 Standard

Microsoft(R) Windows Server(R) 2008 Enterprise

Microsoft(R) Windows Server(R) 2008 R2 Standard

Microsoft(R) Windows Server(R) 2008 R2 Enterprise

Microsoft(R) Windows Server(R) 2008 R2 Datacenter

Microsoft(R) Windows Server(R) 2012 Standard Windows Server

2012

Windows Server

2012 Standard

Windows Server

2012 Datacenter

Microsoft(R) Windows Server(R) 2012 Datacenter

Windows XP

Windows Vista Windows Vista

Business

Windows Vista

Enterprise

Windows Vista

Ultimate

Windows 7 x86

Microsoft(R) Windows(R) XP Professional Operating System

Microsoft(R) Windows Vista(R) Business (32-bit)

Microsoft(R) Windows Vista(R) Enterprise (32-bit)

Microsoft(R) Windows Vista(R) Ultimate (32-bit)

Windows 7 Microsoft(R) Windows(R) 7 Professional (32-bit)

Microsoft(R) Windows(R) 7 Enterprise (32-bit)

Windows 8

Windows 7 x64

Windows 8 x86

Microsoft(R) Windows(R) 7 Ultimate (32-bit)

Microsoft(R) Windows(R) 7 Professional (64-bit)

Microsoft(R) Windows(R) 7 Enterprise (64-bit)

Microsoft(R) Windows(R) 7 Ultimate (64-bit)

Windows(R) 8 Pro (32-bit)

Windows(R) 8 Enterprise (32-bit)

Windows(R) 8 Pro (64-bit) Windows 8 x64

Windows(R) 8 Enterprise (64-bit)

Note that Windows 32 bit and Windows 64 bit are sometimes respectively referred to as Windows x86 and Windows x64.

■ Restrictions

Information in this document is subject to change without notice and does not represent a commitment on the part of Hitachi. The software described in this manual is furnished according to a license agreement with Hitachi. The license agreement contains all of the terms and conditions governing your use of the software and documentation, including all warranty rights, limitations of liability, and disclaimers of warranty.

Material contained in this document may describe Hitachi products not available or features not available in your country.

No part of this material may be reproduced in any form or by any means without permission in writing from the publisher.

Printed in Japan.

■ Issued

Aug. 2013: 3020-3-Y07-10(E)

■ Copyright

All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.

Summary of amendments

The following table lists changes in the manual 3020-3-Y07-10(E) for uCosminexus Application Server 09-50, uCosminexus Application Server(64) 09-50, uCosminexus Client 09-50, uCosminexus Developer 09-50, uCosminexus Service Architect 09-50, uCosminexus Service Platform 09-50, uCosminexus Service Platform(64)

09-50 and product changes related to the manual:

Changes Location

A description is added for the Bean Validation functionality, and implementation methods and actions to be taken when an error occurs are specified.

The functionality is added for deploying WAR applications, configured only with WAR files, on

J2EE servers.

1.2.9

,

Chapter 10

2.4.3

,

11.3.3

,

11.3.4

,

11.3.6

,

11.4.6

,

12.3

,

12.5.2

,

13.2

,

13.4.4

,

13.9

2.4.3

3.3.2

,

3.4.3

,

3.6.4

,

3.6.7

The characters that can be used with the Portable Global JNDI name are added.

The RAR file for DB Connector, common to the SQL Server versions and JDBC driver for SQL

Server, are added.

RAR file for DB Connector:

DBConnector_SQLServer_CP.rar

JDBC driver for SQL Server: SQL Server JDBC Driver

With this, the description for the RAR file for DB Connector and JDBC driver for SQL Server is changed or deleted corresponding to the version.

A description is added for the J2EE components and functionality available for database connection.

HiRDB Type4 JDBC Driver and SQL Server JDBC driver compliant with the JDBC 4.0

specifications are now supported with DB Connector, and the JDBC 2.0 specifications are no longer supported.

SQL Server 2012 is now supported. Accordingly, the notes for each SQL Server version are added.

The SMTPS provider is added to the providers available with JavaMail. Also, the property to output a message when the javax.mail.Transport

object is obtained is added to the session properties specific to the SMTP provider and SMTPS provider.

Whether to read the library JAR annotations can now be selected with an option.

The annotations that cannot be updated with the reload functionality are added:

@WebEndpoint

@WebServiceRef

The description of notes has been moved from Release Notes.

3.6.2

3.6.3

3.6.7

8.1

,

8.2

,

8.2.1

,

8.3

12.3

12.6.1

3.3.13

,

3.6.3

,

3.6.6

,

3.6.7

,

3.14.4

,

3.16.10

,

4.4

,

4.14.1

,

4.15.2

,

7.8.2

,

7.10.1

,

7.19

,

8.3

,

12.5.1

,

13.2

,

13.4.4

,

13.8.13

,

14.6

,

15.2.1

,

15.2.2

,

15.2.3

,

15.3

,

Appendix E

In addition to the above changes, minor editorial corrections have been made.

Preface

For details on the prerequisites before reading this manual, see the

uCosminexus Application Server Overview

.

■ Non-supported functionality

Some functionality described in this manual is not supported. Non-supported functionality includes:

Audit log functionality

Compatibility functionality

Cosminexus Component Transaction Monitor

Cosminexus DABroker Library

Cosminexus Reliable Messaging

Cosminexus TPBroker and VisiBroker

Cosminexus Web Service - Security

Cosminexus XML Security - Core functionality

JP1 linkage functionality

Management portal functionality

Migration functionality

SOAP applications complying with specifications other than JAX-WS 2.1

uCosminexus OpenTP1 linkage functionality

Virtualized system functionality

XML Processor high-speed parse support functionality

■ Non-supported compatibility functionality

"Compatibility functionality" in the above list refers to the following functionality:

Basic mode

Check of JSP source compliance (cjjsp2java) with JSP1.1 and JSP1.2 specifications

Database connection using Cosminexus DABroker Library

EJB client application log subdirectory exclusive mode

J2EE application test functionality

Memory session failover functionality

Servlet engine mode

Simple Web server functionality

Switching multiple existing execution environments

Using EJB 2.1 and Servlet 2.4 annotation

I

Contents

1

Application Server Functionality

1.1 Classification of functionality

1.1.1 Functionality serving as an execution platform for applications

1.1.2 Functionality for operating and maintaining the execution platform of applications

1.1.3 Correspondence between the functionality and manuals

1.2 Correspondence between the purpose of a system and the functionality

1.2.1 Naming management functionality

1.2.2 Functionality for managing resource connections and transactions

1.2.3 Functionality for invoking Application Server from OpenTP1 (TP1 inbound integrated functionality)

1.2.4 JPA functionality used with Application Server

1.2.5 Cosminexus JPA Provider functionality

1.2.6 Cosminexus JMS Provider functionality

1.2.7 JavaMail functionality

1.2.8 CDI functionality used with Application Server

1.2.9 Bean Validation functionality used with Application Server

1.2.10 Managing application attributes

1.2.11 Annotation functionality

1.2.12 Functionality for formatting and deploying J2EE applications

1.2.13 Container extension library functionality

1.3 Description of the functionality mentioned in this manual

1.3.1 Meaning of the classification

1.3.2 Examples of tables describing the classification

1.4 Main functionality changes in Application Server 09-50

2

Naming Management

2.1 Organization of this chapter

2.2 Overview of naming management

2.2.1 Naming management functionality

2.2.2 Naming services

2.3 Binding and looking up objects in the JNDI name space

2.3.1 Types of names used for lookup

2.3.2 Mapping and looking up the JNDI name space

2.3.3 How to check the JNDI name space

2.3.4 Definitions in cosminexus.xml

2.3.5 Execution environment settings

2.4 Looking up with the Portable Global JNDI names

2.4.1 Types of JNDI name spaces

2.4.2 Automatically bound objects

1

8

9

5

8

12

2

4

5

13

13

14

15

15

15

19

19

21

16

16

17

17

19

25

32

35

36

36

38

38

39

26

27

27

28

29

29

i

Contents

2.4.3 Naming rules for the Portable Global JNDI names

2.4.4 Controlling the registration of Portable Global JNDI names

2.4.5 Looking up with the Portable Global JNDI names when the CTM is used

2.4.6 Resource reference names

2.4.7 Specifying the Portable Global JNDI names in annotations

2.4.8 Definitions in the DD

2.4.9 Execution environment settings

2.5 Looking up with names beginning with HITACHI_EJB

2.6 Assigning an optional name to Enterprise Beans or J2EE resources (User-specified name space functionality)

2.6.1 Objects that can be assigned an optional name

2.6.2 Rules for assigning the optional names

2.6.3 Timing for registering or deleting the optional name

2.6.4 Searching from the client

2.6.5 Setting the optional names for the Enterprise Beans

2.6.6 Setting the optional names for the J2EE resources

2.6.7 Execution environment settings

2.6.8 Precautions for using the user-specified name space functionality

2.7 Searching the CORBA Naming Service by using the round-robin policy

2.7.1 Scope of round-robin search

2.7.2 Operations when performing a round-robin search

2.7.3 Settings required for performing a round-robin search

2.7.4 Settings recommended for using the round-robin search functionality

2.7.5 Notes on performing a round-robin search

2.8 Caching with the naming management functionality

2.8.1 Procedure of caching

2.8.2 Clearing the Cache Used in Naming

2.8.3 Settings for using the caching functionality

2.8.4 Notes on caching in naming

2.9 Detecting errors in a naming service

2.9.1 What is the naming service error detection functionality

2.9.2 Concurrent use of the round-robin search functionality

2.9.3 Behavior of the naming service error detection functionality

2.9.4 Execution environment settings (When the Error Detection functionality is used)

2.9.5 Notes on the naming service error detection functionality

2.10 Switching the CORBA Naming Services

2.11 Re-using the EJB home object references (Functionality for re-connecting to the EJB home objects)

2.11.1 Execution environment settings (J2EE server settings)

2.11.2 Notes on re-using the EJB home object references

84

84

84

40

45

45

46

49

50

51

52

79

80

81

82

83

75

76

77

78

78

68

72

72

74

74

64

66

66

67

55

60

62

62

55

56

58

59

ii

Contents

3

Resource Connections and Transaction Management

3.1 Organization of this chapter

3.2 Overview of resource connections and transaction management

3.3 Resource connections

3.3.1 How to connect to resources

3.3.2 Types of resource adapters

3.3.3 How to use the resource adapters

3.3.4 Resource adapter functionality

3.3.5 Functionality other than the resource adapter functionality

3.3.6 Implementation for connecting to the resources

3.3.7 How to set up resource adapters

3.3.8 Procedure for resource adapter settings (To deploy and use the resource adapter as a J2EE resource adapter)

3.3.9 Procedure for resource adapter settings (To include and use the resource adapter in the J2EE application)

3.3.10 Procedure for resource adapter settings (To use the resource adapter with Inbound)

3.3.11 Procedure for resource adapter settings (To use connection pool clustering)

3.3.12 Connection settings for using components other than the resource adapters

3.3.13 Notes on the resource adapters

3.4 Managing transactions

3.4.1 Transaction management methods for the resource connections

3.4.2 Local transaction and global transaction

3.4.3 Transaction types available for each resource

3.4.4 Functionality provided with the transaction services

3.4.5 Transaction operations during system exceptions

3.4.6 Obtaining the transaction manager

3.4.7 Overview of processing and the points to remember when using the container-managed transactions

(CMT)

3.4.8 Overview of processing and the points to remember when using the UserTransaction interface

3.4.9 Overview of processing and the points to remember when using the resource adapter-specific transaction management interface

3.4.10 Overview of processing and the points to remember when transactions are not used

3.4.11 Notes on the JTA-based transaction implementation

3.4.12 Settings in the execution environment

3.5 Resource sign-on method

3.6 Connecting to a database

3.6.1 Overview of DB Connector-based connections

3.6.2 Available J2EE components and functionality

3.6.3 Connectable databases

3.6.4 Types of DB Connectors (RAR file)

3.6.5 Preconditions and notes on connecting to HiRDB

3.6.6 Preconditions and notes on connecting to Oracle

100

111

113

113

114

115

103

107

109

111

117

118

119

120

121

122

123

124

124

127

128

128

129

130

132

132

134

87

88

89

90

90

91

95

96

98

99

99

iii

Contents

3.6.7 Preconditions and notes on connecting to SQL Server

3.6.8 Preconditions and notes on connecting to XDM/RD E2

3.6.9 Settings in the execution environment (resource adapter settings)

3.7 Connecting to a database queue

3.7.1 Overview of connections using DB Connector for Cosminexus RM and Cosminexus RM

3.7.2 Features of connections using DB Connector for Cosminexus RM and Cosminexus RM

3.7.3 Available functionality

3.7.4 Connectable databases

3.7.5 Types of DB Connector for Cosminexus RM (RAR file)

3.7.6 Preconditions for connecting to a HiRDB queue

3.7.7 Preconditions for connecting to an Oracle queue

3.7.8 Settings for connecting to a database queue

3.8 Outbound connection with OpenTP1 (SPP or TP1/Message Queue)

3.8.1 Connections using uCosminexus TP1 Connector

3.8.2 Connections using TP1/Message Queue - Access

3.8.3 Connection settings for OpenTP1 and Outbound

3.9 Inbound connection with OpenTP1

3.10 Connection with Cosminexus JMS Provider

3.11 Connecting to the SMTP server

3.12 Using the JavaBeans resources

3.12.1 JavaBeans resource functionality

3.12.2 Procedure for starting the JavaBeans resources

3.12.3 Implementing the JavaBeans resources

3.12.4 Setting up the JavaBeans resources

3.12.5 Replacing the JavaBeans resources

3.13 Connection with other resources

3.13.1 Resource adapters used for connection with other resources

3.13.2 Functionality available for other resource connections

3.14 Functionality for performance tuning

3.14.1 Connection pooling

3.14.2 Functionality available with connection pooling

3.14.3 Connection sharing or association

3.14.4 Statement pooling

3.14.5 Light transaction

3.14.6 In-process transaction service

3.14.7 Caching the DataSource objects

3.14.8 Optimizing the container-managed sign-on for DB Connector

3.14.9 Definitions in cosminexus.xml

3.14.10 Settings in the execution environment

3.15 Functionality for fault tolerance

3.15.1 Detecting the connection errors

155

155

155

156

158

161

163

163

150

150

151

151

152

153

154

173

176

176

176

177

178

163

165

165

168

169

178

181

181

136

140

140

141

141

142

145

146

147

147

148

149

iv

Contents

3.15.2 Waiting for a connection when connections deplete

3.15.3 Retrying to obtain a connection

3.15.4 Displaying the connection pool information

3.15.5 Clearing the connection pool

3.15.6 Automatically closing the connections

3.15.7 Connection sweeper

3.15.8 Transaction timeout and statement cancellation

3.15.9 Transaction recovery

3.15.10 Output of the SQL statement for troubleshooting

3.15.11 Automatically closing the objects

3.15.12 Definitions in cosminexus.xml

3.15.13 Settings in the execution environment

3.16 Other resource adapter functionality (For the resource adapters conforming to the Connector

1.5 specifications)

3.16.1 Managing the resource adapter lifecycle

3.16.2 Managing the resource adapter work

3.16.3 Message inflow

3.16.4 Transaction inflow

3.16.5 Looking up Administered objects

3.16.6 Specifying multiple connection definitions

3.16.7 Application Server-specific Connector 1.5 API specifications

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

3.16.9 Examples of property file specification

3.16.10 Notes on using the resource adapters conforming to the Connector 1.5 specifications

3.17 Functionality for connection pool clustering

3.17.1 Connecting to Oracle using Oracle RAC

3.17.2 Overview of connection pool clustering

3.17.3 Resource adapters used

3.17.4 Connection pool clustering operations

3.17.5 Procedure for stopping or starting a connection pool manually

3.17.6 Settings required for clustering a connection pool

3.18 Connection test for resources

3.19 Functionality for operations in the firewall environment

3.19.1 Communication port for transaction recovery

3.19.2 Communication port used by Smart Agent

3.19.3 Settings for operations in the firewall environment

3.20 Notes on starting a transaction with the EJB client applications

3.20.1 Notes on application development

3.20.2 Notes on system setup

3.20.3 Notes on system operations

248

249

252

252

252

252

254

234

234

236

238

241

246

254

254

256

198

198

202

211

215

216

217

220

222

227

233

184

185

186

187

187

189

189

190

193

195

195

195

v

vi

Contents

5

4

Invoking Application Server from OpenTP1 (TP1 Inbound Integrated Function)

(INTENTIONALLY DELETED)

4.1 INTENTIONALLY DELETED

How to Use JPA with Application Server

5.1 Organization of this chapter

5.2 Features of JPA

5.2.1 Advantages of applications using JPA

5.2.2 Entity class

5.2.3 JPA provider

5.3 JPA functionality that can be used with Application Server

5.3.1 Available JPA providers

5.3.2 Available components

5.3.3 Supported application formats

5.3.4 Supported class loader configuration

5.3.5 available resource adapters

5.4 EntityManager

5.4.1 Methods provided with EntityManager

5.4.2 Types of EntityManager

5.4.3 Transaction control and EntityManager

5.4.4 Persistence unit

5.5 Persistence context

5.5.1 EntityManager and persistence context

5.5.2 Persistence context when the container-managed EntityManager is used

5.5.3 Persistence context when the application-managed EntityManager is used

5.6 How to obtain the container-managed EntityManager

5.6.1 Method of injecting EntityManager in the application

5.6.2 Method of looking up EntityManager from the application

5.6.3 Overriding the @PersistenceContext definition using the DD

5.7 How to obtain the application-managed EntityManager

5.7.1 Method of injecting EntityManagerFactory in the application

5.7.2 Method of looking up EntityManagerFactory from the application

5.7.3 Overriding the @PersistenceUnit definition using the DD

5.8 Definitions in persistence.xml

5.8.1 Attributes specified in the <persistence-unit> tag

5.8.2 Tags specified under the <persistence-unit> tag

5.9 Allocating persistence.xml

5.10 JPA interfaces

5.10.1 javax.persistence.EntityManager interface

5.10.2 javax.persistence.EntityManagerFactory interface

257

258

259

280

282

283

283

283

288

289

289

293

276

278

279

279

270

271

272

274

274

268

268

269

269

270

266

266

267

268

260

261

261

262

262

264

264

265

5.11 Notes on setting up applications

5.11.1 Notes on allocating the entity classes

5.11.2 Reference scope of the persistence unit name

5.11.3 Items checked when the application is deployed

5.11.4 Notes on using the JPA with Application Server

5.11.5 Notes when the Cosminexus JPA functionality is not used

6

Cosminexus JPA Provider

6.1 Organization of this chapter

6.2 Cosminexus JPA Provider

6.2.1 Processing in Cosminexus JPA Provider

6.2.2 Functionality provided by Cosminexus JPA Provider

6.2.3 Preconditions for using Cosminexus JPA Provider

6.2.4 Estimating the number of DB Connector connections

6.3 Updating a database using entities

6.4 Entity operations by EntityManager

6.4.1 Transition of entity states

6.4.2 persist operation for the entities

6.4.3 remove operation for the entities

6.4.4 Obtaining the entities from the database

6.4.5 Synchronization with the database

6.4.6 Separate and merge operations of an entity from the persistence context

6.4.7 managed entity

6.5 Defining the mapping information between the database and Java objects

6.6 Entity relationships

6.6.1 Relationship types

6.6.2 Annotations for relationships

6.6.3 Direction of relationships

6.6.4 Default mapping (bi-directional relationship)

6.6.5 Default mapping (unidirectional relationship)

6.7 Cache functionality of the entity objects

6.7.1 Processing of the cache functionality

6.7.2 Cache reference forms and cache types

6.7.3 Scope of the cache functionality

6.7.4 Notes on using the cache functionality

6.8 Auto-numbering of the primary key values

6.9 Database operations based on the query language

6.10 Optimistic lock

6.10.1 Optimistic lock processing

6.10.2 Exception processing when optimistic lock fails

6.10.3 Notes on using the optimistic lock

Contents

301

308

309

309

311

312

312

313

315

316

302

303

303

304

305

307

329

331

334

334

337

338

339

318

319

319

319

320

321

324

329

339

340

340

296

296

296

297

299

299

vii

Contents

6.11 Pessimistic lock in JPQL

6.12 Creating an entity class

6.12.1 Defining the mapping between an entity class and database

6.12.2 Requirements for creating entity classes

6.12.3 Specifying the access methods for the entity class fields

6.12.4 Creating the accessor method

6.12.5 Types of persistence fields and persistence properties of the entities

6.12.6 Specifying the primary key in the entities

6.12.7 Default mapping rules for the persistence fields and persistence properties

6.13 Procedure for inheriting an entity class

6.13.1 Inheritance class types

6.13.2 Inheritance mapping strategy

6.14 Procedure for using EntityManager and EntityManagerFactory

6.14.1 Entity lifecycle management with EntityManager

6.14.2 How to set up EntityManager and EntityManagerFactory

6.14.3 Notes on the API functions of EntityManager

6.15 Procedure for specifying the callback method

6.15.1 Location for specifying the callback method

6.15.2 Implementing the callback methods

6.15.3 Order of invoking the callback methods

6.16 Procedure for referencing and updating the database with the query language

6.16.1 Procedure for referencing and updating the database with JPQL

6.16.2 Procedure for referencing and updating the database with the native query

6.16.3 Specifying the range of query result items

6.16.4 Specifying the flush mode

6.16.5 Specifying a query hint

6.16.6 Notes on executing a query

6.17 JPQL coding method

6.17.1 JPQL syntax

6.17.2 SELECT statement

6.17.3 SELECT clause

6.17.4 FROM clause

6.17.5 WHERE clause

6.17.6 GROUP BY clause and HAVING clause

6.17.7 ORDER BY clause

6.17.8 Bulk UPDATE statement and Bulk DELETE statement

6.17.9 Notes on using JPQL

6.17.10 Exceptions thrown when queries are used

6.18 Defining persistence.xml

6.19 Settings in the execution environment

viii

354

354

354

356

356

351

351

352

354

344

345

345

346

349

342

343

343

343

361

365

366

366

366

367

357

358

359

359

376

376

377

379

380

381

367

367

368

369

372

375

Contents

7

Cosminexus JMS Provider

7.1 Organization of this chapter

7.2 Overview of Cosminexus JMS Provider

7.2.1 Cosminexus JMS Provider

7.2.2 Location of Cosminexus JMS Provider within Application Server

7.2.3 Overview of the Cosminexus JMS Provider functionality

7.3 Allocating the CJMSP resource adapters and CJMSP Broker

7.3.1 Configuration in which one CJMSP Broker is allocated to one CJMSP resource adapter

7.3.2 Configuration in which one CJMSP Broker is allocated to multiple CJMSP resource adapters

7.4 Types of messaging models

7.4.1 PTP messaging model

7.4.2 Pub/Sub messaging model

7.5 Configuration of messages

7.6 Selecting the received messages using Message Selector

7.7 Mechanism for ensuring a highly-reliable message delivery

7.7.1 Types of problems occurring during message delivery and how to ensure reliability

7.7.2 Using transactions

7.7.3 Controlling the message flow rate

7.8 CJMSP Broker functionality

7.8.1 Connection services

7.8.2 Destination management and routing services

7.8.3 CJMSP Broker performance monitoring

7.8.4 Management information and message persistence services

7.9 CJMSP resource adapter functionality

7.10 Invoking a Message-driven Bean

7.10.1 Features of message processing using the Message-driven Beans

7.10.2 Procedure of invoking the Message-driven Beans

7.10.3 Settings required in the Message-driven Beans

7.10.4 Setting up the transaction context

7.11 Restrictions on implementing applications

7.12 Definitions in the DD

7.13 Flow of execution environment setup

7.14 CJMSP Broker settings

7.14.1 Setting up the common properties and the management command properties of CJMSP Broker

7.14.2 Creating CJMSP Broker

7.14.3 Setting up the individual properties of CJMSP Brokers

7.14.4 Starting CJMSP Broker

7.14.5 Creating destinations

7.15 CJMSP resource adapter settings

7.16 J2EE application settings

7.17 Starting and stopping the system when Cosminexus JMS Provider is used

383

409

409

409

410

411

412

413

415

417

400

401

404

404

408

397

397

397

398

400

418

418

418

419

419

420

422

423

388

390

390

391

395

396

384

385

385

385

386

388

388

ix

x

Contents

7.17.1 System starting procedure

7.17.2 System stopping procedure

7.17.3 Checking the CJMSP Broker status

7.18 Checking the troubleshooting information

7.19 Notes on using Cosminexus JMS Provider

8

Using JavaMail

8.1 Organization of this chapter

8.2 Session properties

8.2.1 Session properties for connecting to the SMTP server

8.2.2 Session properties for connecting to the POP3 server

8.3 Notes on using JavaMail

9

Using CDI with Application Server

9.1 Organization of this chapter

9.2 Overview of the CDI

9.3 Application development using the CDI

9.3.1 CDI-target applications

9.3.2 Injective relationship of the CDI-target J2EE modules

9.3.3 Notes on development

9.4 Setting up the class path (Development environment settings)

9.4.1 File storage destinations

9.4.2 Class path settings

9.5 Settings for using the CDI (Changing the security settings)

9.6 Using the debug log (check development log)

9.7 Setting up the execution environment

9.8 Notes on using the CDI

10

Using Bean Validation with Application Server

10.1 Organization of this chapter

10.2 Overview of Bean Validation

10.3 Applicable scope of Bean Validation

10.4 Bean Validation functionality and Bean Validation operations

10.5 Procedures for using Bean Validation

10.5.1 Procedures for using Bean Validation from JSF

10.5.2 Procedures for using Bean Validation from CDI

10.6 Using the debug log (check development log)

10.7 Output of information when the validation.xml contents are invalid

10.8 Notes on the implementation of Bean Validation

439

440

441

442

445

445

446

447

442

442

444

445

448

449

431

432

433

433

436

438

423

424

425

427

429

451

452

453

454

455

459

459

460

462

463

464

11

Managing Application Attributes

11.1 Organization of this chapter

11.2 Managing attributes

11.3 Applications containing cosminexus.xml

11.3.1 cosminexus.xml

11.3.2 Advantages of using the applications containing cosminexus.xml

11.3.3 Creating the applications containing cosminexus.xml

11.3.4 Creating cosminexus.xml

11.3.5 Example of creating cosminexus.xml

11.3.6 Operations of the applications containing cosminexus.xml

11.3.7 Procedure of migrating from the applications not containing cosminexus.xml

11.4 Omitting the DD

11.4.1 Configuration of applications that can be executed with Application Server

11.4.2 Differences in functionality depending on the presence of application.xml

11.4.3 Rules for determining the modules when application.xml exists

11.4.4 Rules for determining the modules when application.xml does not exist

11.4.5 Operations for Web applications in which web.xml is omitted

11.4.6 Display name specified when the DD is omitted

11.4.7 Operations for creating application.xml when application.xml is omitted

11.4.8 Notes on adding resources in the J2EE applications when application.xml is omitted

12

Using Annotations

12.1 Organization of this chapter

12.2 Specifying annotations

12.2.1 Merits of using annotations and the annotations that can be specified

12.2.2 Using the library JAR class with a declared annotation

12.2.3 Implementing the Enterprise Beans when an annotation is specified

12.3 Classes to be loaded and the class path required for loading

12.4 Using the DI

12.4.1 Types of resources that can be specified in the @Resource annotation

12.4.2 Resolving the resource references using the @Resource annotation

12.4.3 Operations during DI failure

12.4.4 Notes

12.5 Controlling the annotation references

12.5.1 Purpose and scope of the functionality for controlling the annotation references

12.5.2 Timing for referencing annotations

12.5.3 Definitions in the DD (module settings)

12.5.4 Changing the settings for the functionality for controlling the annotation references

12.6 Updating the contents defined in the annotations

12.6.1 Updating the annotations

Contents

465

483

485

486

488

489

490

474

476

481

482

482

491

466

467

469

469

470

472

472

493

498

501

501

502

505

506

507

507

509

510

511

512

512

494

495

495

496

497

xi

xii

Contents

12.6.2 Overwriting the annotations using the DD

12.6.3 Referencing and updating the definitions with the server management commands

12.7 Notes on using annotations

13

Formats and Deployment of J2EE Applications

13.1 Organization of this chapter

13.2 Executable J2EE application formats

13.3 Archive-format J2EE applications

13.4 Exploded archive-format J2EE applications

13.4.1 Overview of the exploded archive format

13.4.2 Configuration of the application directory

13.4.3 Settings for using the exploded archive-format J2EE applications (changing the security settings)

13.4.4 Notes on using the exploded archive format

13.5 Deploying and un-deploying J2EE applications

13.5.1 Deploying and un-deploying J2EE applications in the archive format

13.5.2 Deploying and un-deploying J2EE applications in the exploded archive-format

13.5.3 Deploying the EAR files and ZIP files in the exploded archive format

13.5.4 Setting up the J2EE application properties

13.6 Replacing J2EE applications

13.7 Redeploying J2EE applications

13.7.1 Replacing J2EE applications by redeploying

13.7.2 Statuses and replacement of J2EE applications

13.7.3 Notes on replacing J2EE applications by redeploying

13.8 Detecting updates and reloading the J2EE applications

13.8.1 How to reload the J2EE applications

13.8.2 Scope of reloading

13.8.3 Class loader configuration used for reloading

13.8.4 Operations when an error occurs

13.8.5 Files for update detection

13.8.6 Update detection interval for J2EE applications

13.8.7 Interval for updating the J2EE application configuration file

13.8.8 Reloading the Web applications

13.8.9 Reloading the JSPs

13.8.10 Relationship with the other functionality

13.8.11 Reloading the J2EE applications using commands

13.8.12 Settings for detecting updates and reloading the J2EE applications

13.8.13 Notes and restrictions related to reloading

13.9 WAR applications

13.9.1 Support range of the operation commands for WAR applications

13.9.2 Executable WAR application formats

13.9.3 Replacing WAR applications

514

519

521

525

540

541

543

545

531

537

538

540

540

526

527

528

529

529

550

550

555

556

557

557

546

546

548

548

570

574

581

581

582

583

561

562

564

566

567

570

Contents

13.9.4 Names of WAR applications

13.9.5 Determining the context root

13.9.6 Reading the cosminexus.xml file

583

584

584

14

Container Extension Library

585

14.1 Organization of this chapter

14.2 Using the container extension library

14.3 Container extension library functionality

14.3.1 Determining the usage of the container extension library

14.3.2 Procedure of creating and using the container extension library

14.3.3 Settings for using the container extension library functionality

14.4 Server start and stop hook functionality

14.4.1 Invocation order of the server start and stop hook processing

14.4.2 Implementing the server start and stop hook functionality

14.4.3 Specifying the class path for using the server start and stop hook functionality

14.5 Invoking the CORBA objects through Smart Agent

592

593

594

595

595

14.5.1 Notes on the implementation of the CORBA object invocation processing

14.5.2 Notes on the packaging of the CORBA object invocation processing

595

14.6 Constraints on using the container extension library and server start and stop hook functionality 596

586

587

588

588

589

589

592

15

Notes on Implementation of Applications

15.1 Notes on using the thread-local variables

15.2 Notes on Developer's Kit for Java

15.2.1 Notes common to Application Server versions

15.2.2 Notes related to the differences in specifications with JDK 1.4.2 provided in Application Server

Version 6

15.2.3 Notes related to the differences in specifications with JDK 5.0 provided in Application Server Version

7 and Version 8

15.3 Notes on using loggers beginning with sun.rmi

606

609

611

597

598

599

599

Appendix

A. Character Codes

A.1 Character codes handled in an application

A.2 Character code conversion between the browser and application

B. Configuration of the Class Loader

B.1 Default class loader configuration

B.2 Class loader configuration for local call optimization

B.3 Class path set in the class loader

C. Contract Between the JPA Provider and EJB Container

C.1 Runtime-related contract

613

614

614

616

618

618

620

621

623

623

xiii

Contents

C.2 Deployment-related contract

D. BNF for JPQL

E. Use Cases for Cosminexus JMS Provider

E.1 Preconditions common to all the use cases

E.2 Prerequisite process model

E.3 Environment setup for using Cosminexus JMS Provider

E.4 Adding applications that use Cosminexus JMS Provider

E.5 Deleting applications that use Cosminexus JMS Provider

E.6 Starting the Cosminexus JMS Provider services (for the initial startup)

E.7 Starting the Cosminexus JMS Provider services (for restarting a running system)

E.8 Checking the state of the CJMSP resource adapters and CJMSP Broker

E.9 Checking the message delivery status and the action to be taken for accumulated messages

(Procedure for pausing CJMSP Broker)

E.10 Checking the message delivery status and the action to be taken for accumulated messages

(Procedure for stopping an application)

E.11 Terminating the Cosminexus JMS Provider services

E.12 Compressing the destinations

E.13 Changing the destination size

E.14 Deleting the persistence subscribers

E.15 Monitoring the CJMSP Broker status

E.16 Checking the CJMSP Broker details

E.17 Checking the destination status

E.18 Checking the persistence subscriber status

E.19 Analysis of errors in the CJMSP resource adapters

E.20 Analysis when CJMSP Broker stops due to an error

E.21 Analysis when there is no response from a Cosminexus JMS Provider service

E.22 Recovery when an error occurs in a CJMSP resource adapter

E.23 Recovery when CJMSP Broker stops due to an error

E.24 Recovery when there is no response from a Cosminexus JMS Provider service

E.25 Deleting the Cosminexus JMS Provider service instances

F. Main Functionality Changes in Each Version

F.1 Main functionality changes in 09-00

F.2 Main functionality changes in 08-70

F.3 Main functionality changes in 08-53

F.4 Main functionality changes in 08-50

F.5 Main functionality changes in 08-00

G. Glossary

Index

635

636

642

647

649

653

655

627

631

634

635

656

667

668

669

669

670

671

673

659

660

661

663

664

666

683

685

686

689

693

674

676

678

680

680

695

xiv

1

Application Server Functionality

This chapter describes the classification and purpose of the Application Server functionality and the correspondence between the functionality and manuals. This chapter also describes the functionality that is changed in this version.

1

2

1. Application Server Functionality

1.1 Classification of functionality

Application Server

is a product used for setting up an execution environment for the applications focusing on a J2EE server compliant with Java EE 6 and for developing the applications to be operated on the execution environment.

You can use various functionality such as the functionality compliant with the Java EE standard specifications and the functionality independently extended on Application Server. By selecting and using the functionality according to the purpose and intended use, you can set up and operate a highly reliable system with an excellent processing performance.

The Application Server functionality can be broadly classified as follows:

Functionality serving as an execution platform of applications

Functionality used for operating and maintaining the execution platform of the applications

The above functionality can be further classified according to the positioning and the intended use of the functionality.

The Application Server manuals have been provided as per the classification of the functionality.

The following figure shows the classification of the Application Server functionality and the set of manuals corresponding to the functionality.

1. Application Server Functionality

Figure 1

1: Classification of the Application Server functionality and the set of manuals corresponding to each functionality

#1

Application Server

has been omitted from the manual names.

#2

You can execute SOAP Web Services and RESTful Web Services with Application Server. Depending on the purpose, see the following manuals in addition to the

uCosminexus Application Server Web Service Development

Guide

.

To develop and execute SOAP applications:

uCosminexus Application Server SOAP Application Development Guide

To ensure the security for SOAP Web Services and SOAP applications:

uCosminexus Application Server XML Security - Core User Guide

uCosminexus Application Server Web Service Security Users Guide

3

1. Application Server Functionality

To learn about XML processing in detail:

uCosminexus Application Server XML Processor User Guide

The following subsections describe the classification of the functionality and the correspondence of the manuals to the functionality.

1.1.1 Functionality serving as an execution platform for applications

The functionality forms a base for executing online businesses and batch businesses implemented as applications. You choose the functionality you want to use according to the intended use of a system and requirements.

You need to determine whether to use the functionality serving as the execution platform for applications, even before you set up a system and develop applications.

The following points provide the classification-wise description of the functionality serving as the execution platform for applications:

(1) Basic functionality to operate applications (basic development functionality)

This functionality includes the basic functionality for operating the applications (J2EE applications). This functionality mainly includes the J2EE server functionality.

Application Server provides a Java EE 6-compliant J2EE server. The J2EE server provides the functionality unique to

Application Server apart from the functionality compliant with the standard specifications.

The basic development functionality can be further classified into three types based on the form of the J2EE application using the functionality. The manuals of the Application Server functionality have been divided according to this classification.

The following subsections give an overview of the classification:

• Functionality for executing Web applications (Web container)

This includes the Web container functionality that serves as an execution platform for Web applications and the functionality that is executed by integrating Web containers and Web servers.

• Functionality for executing Enterprise Beans (EJB container)

This includes the EJB container functionality that serves as an execution platform for Enterprise Beans. This also includes the EJB client functionality for invoking Enterprise Beans.

• Functionality used in both Web applications and Enterprise Beans (Common container functionality)

This includes the functionality that can be used in the Web applications operating on Web containers and the

Enterprise Beans operating on EJB containers.

(2) Functionality for developing Web Services

This includes the functionality for the execution and development environment of Web Service.

Application Server provides the following engines:

JAX-WS engine that binds the SOAP messages in accordance with the JAX-WS specifications

JAX-RS engine that binds the RESTful HTTP messages in accordance with the JAX-RS specifications

(3) Application server-specific functionality expanded for improving the reliability and performance (Expansion functionality)

This includes the functionality expanded uniquely on Application Server. This also includes the functionality implemented by using non-J2EE server processes, such as a batch server, CTM, and database.

With Application Server, various functionality are expanded to improve the reliability of the system and to implement stable operations. Furthermore, the functionality is also expanded to operate applications other than the J2EE applications (batch applications) in the Java environment.

4

1. Application Server Functionality

(4) Functionality to ensure system security (Security management functionality)

This includes the functionality used for ensuring the security of Application Server-based systems. This includes the authentication functionality for preventing unauthorized access and the encryption functionality for preventing information leakage through a communication path.

1.1.2 Functionality for operating and maintaining the execution platform of applications

This functionality is used to efficiently operate and maintain the execution platform for the applications. You use this functionality as and when required after starting system operations. However, depending on the functionality, you need to implement some settings and applications in advance.

The following points classification-wise describe the functionality used for operating and maintaining the execution platform of applications:

(1) Functionality used for daily operations such as system start and stop (Operation functionality)

This classification includes the functionality used in daily operations, such as starting or stopping systems, starting or stopping applications, and replacing the applications.

(2) Functionality for monitoring system usage (Watch functionality)

This includes the functionality used for monitoring system operations and resource depletion. This also includes the functionality to output the information used in monitoring the system operation history.

(3) Functionality for operating the systems by integrating with other products (Linkage functionality)

This includes the functionality to be integrated and implemented with other products, such as JP1 and cluster software.

(4) Functionality for troubleshooting (Maintenance functionality)

This includes the functionality used for troubleshooting. This also includes the functionality used to output the information that is referenced for troubleshooting.

(5) Functionality for migrating from products of older versions (Migration functionality)

This includes the functionality used for migrating from old Application Server to a new Application Server.

(6) Functionality for compatibility with products of older versions (Compatibility functionality)

This includes the functionality used for compatibility with older versions of Application Server. We recommend you to migrate the compatibility functionality to the corresponding recommended functionality.

1.1.3 Correspondence between the functionality and manuals

The functionality guides for Application Server have been divided according to the classification of the functionality.

The following table describes the classification of the functionality and the manuals corresponding to the respective functionality.

Table 1

1: Classification of functionality and corresponding functionality guides

Classification Functionality

Manual

#1

Basic development functionality

Web container

Web Container Functionality

Guide

5

1. Application Server Functionality

Classification

Basic development functionality

Expansion functionality

Security management functionality

Functionality

Using JSF and JSTL

Integrating with Web server

In-process HTTP server

Implementing servlets and JSPs

EJB container

EJB client

Notes on implementing Enterprise Beans

Naming management

Managing resource connections and transactions

Invoking Application Server from OpenTP1 (TP1 inbound integrated function)

Using JPA with Application Server

Cosminexus JPA Provider

Cosminexus JMS Provider

Using JavaMail

Using CDI with Application Server

Using Bean Validation with Application Server

Managing application attributes

Using annotations

Formatting and deploying J2EE applications

Container extension library

Executing applications by using batch servers

Scheduling and load balancing requests using CTM

Scheduling batch applications

Inheriting the session information between J2EE servers (Session failover functionality)

Database session failover functionality

EADs session failover functionality

Controlling the full garbage collection by using the Explicit

Memory Management functionality

Output of application user logs

Asynchronous parallel processing of threads

Authentication using integrated user management

Authentication using the application settings

Using the TLSv1.2 for the SSL/TLS communication

Controlling access with the management functionality for load balancers using API-based direct connections

Manual

#1

Web Container Functionality

Guide

EJB Container Functionality

Guide

Common Container

Functionality Guide

#2

Expansion Guide

Security Management Guide

6

1. Application Server Functionality

Classification Functionality

Operation functionality

Monitoring functionality

Linkage functionality

Maintenance functionality

Starting and stopping a system

Operating J2EE applications

Monitoring the operation information (Statistics collection functionality)

Monitoring resource depletion

Audit log output functionality

Database audit trail integration functionality

Output of the operation information by using management commands

Automatic execution of processing by using Management event reporting and Management action

Collecting the statistical information of CTM

Output of console logs

Operating a JP1-integrated system

Centralized monitoring of systems (Integrating with JP1/IM)

Automatic system operations by using jobs (Integrating with JP1/

AJS)

Collecting and consolidating audit logs (Integrating with JP1/Audit

Management - Manager)

Integration with cluster software

1-to-1 node switching systems (Integrating with cluster software)

Mutual node switching systems (Integrating with cluster software)

N-to-1 recovery systems (Integrating with cluster software)

Node switching system for the host unit management model

(Integrating with cluster software)

Troubleshooting-related functionality

Performance analysis by using the trace-based performance analysis

JavaVM functionality of the product (referred to as JavaVM hereafter)

Migrating from old Application Server Migration functionality

Compatibility functionality

Migrating to the recommended functionality

Basic mode

Servlet engine mode

Functionality for compatibility with the basic development functionality

Functionality for compatibility with the extension functionality

#1:

uCosminexus Application Server

has been omitted from the manual names.

#2: This manual.

Manual

#1

Operation, Monitoring, and

Linkage Guide

Maintenance and Migration

Guide

Compatibility Guide

7

8

1. Application Server Functionality

1.2 Correspondence between the purpose of a system and the functionality

With Application Server, you need to choose the applicable functionality according to the purpose of the system to be set up and operated.

This subsection describes the types of systems for the functionality that can be used in common by Web and EJB containers. The functionality-wise correspondence with the following items is described here:

• Reliability

This functionality is best used for the systems that require high reliability.

This functionality includes the functionality for enhancing the system availability (stable operations) and fault tolerance, and the functionality for enhancing the security, such as user authentication.

• Performance

This functionality is best used for the systems that emphasize performance.

This functionality includes the functionality used for system performance tuning.

• Operation and maintenance

This functionality is best used when you want efficient operations and maintenance.

• Extendibility

This functionality is best used when you need to expand or reduce the system scale and for flexible response for the changes in the configuration.

• Others

The functionality is used for supporting other individual purposes.

Furthermore, the functionality that can be used in common by Web containers and EJB containers includes the Java

EE standard functionality and the functionality independently extended by Application Server. When you select the functionality, check the compliance with the Java EE standards, as and when required.

1.2.1 Naming management functionality

The following table describes the naming management functionality. Select the functionality according to the purpose of the system. For details about the functionality, see the

reference location

.

Table 1

2: Correspondence between the naming management functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

N N N Y N Y Y

2.3

Binding and looking up objects in the

JNDI name space

Looking up with the

Portable

Global JNDI names

Looking up with names beginning with

N

N

N

N

N

N

Y

Y

N

N

Y

Y

Y

Y

2.4

2.5

1. Application Server Functionality

Purpose of a system

Compliance with Java

EE standards

Functionality

Reliability Performance

N

Operation and maintenance

N

Expan sion

Y

Others Standard Expanded

Reference location

HITACHI_E

JB

Assigning an optional name to the

Enterprise

Beans or

J2EE resources

(userspecified name space functionality)

Searching the

CORBA

Naming

Service by using the round-robin policy

Caching with the naming management functionality

Detecting errors in a naming service

Switching the

CORBA

Naming

Service

Re-using the

EJB home object references

(functionality for reconnecting to the EJB home objects)

N

N

N

N

Y

N

N

N

N

Y

N

N

N

N

N

N

N

N

N

Y

Y

N

N

Y

Y

N

N

N

N

N

N

N

Y

N

N

N

N

N

Y

Y

Y

Y

Y

Y

Y

Y

2.5

2.6

2.7

2.8

2.9

2.10

2.11

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality. The functionality for which

Y

is specified only in the

Expanded

column indicates the Application Server-specific functionality.

1.2.2 Functionality for managing resource connections and transactions

The following table describes the functionality for managing resource connections and transactions. Select the functionality according to the purpose of the system. For details about the functionality, see the

reference location

.

9

1. Application Server Functionality

Table 1

3: Correspondence between the functionality for managing the resource connections and transactions and the purpose of a system

Purpose of the system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

In-process transaction service

DataSource object caching

Optimizing container management sign-on in DB

Connector

Detecting connection errors

Waiting to acquire connections in the case of connection depletion

Retrying to acquire connections

Displaying the connection pool information

Clearing the connection pool

Automatically closing a connection

Connection pooling

Functionality available with connection pooling

Connection sharing and association

Statement pooling

Light transaction

N

N

N

N

N

N

N

N

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

Y

N

Y

N

N

Y

N

N

Y

#1

N

N

N

N

Y

Y

Y

N

Y

Y

N

Y

Y

Y

#1

Y

Y

Y

Y

N

3.14.1

3.14.2

3.14.3

3.14.4

3.14.5

3.14.6

3.14.7

3.14.8

3.15.1

3.15.2

3.15.3

3.15.4

3.15.5

3.15.6

10

1. Application Server Functionality

Functionality name

Connection sweeper

Transaction timeout and statement cancellation

Transaction recovery

Issuing of

SQL statements for troubleshooti ng

Automatic closing of objects

Managing the resource adapter life cycle

#2

Managing the resource adapter work

#2

Message inflow

#2

Transaction in-flow

#3

Looking up

Administered objects

#2

Specifying multiple connection definitions

#2

Connection pool clustering functionality

(temporary stop, restart, and status display of the connection pool)

Resource connection test

Purpose of the system

Reliability

Y

Performance

N

Operation and maintenance

N

Expan sion

N

Y

Y

N

Y

N

N

N

N

N

N

Y

N

N

N

N

N

N

N

N

N

N

N

N

N

N

N

Y

N

N

N

N

N

N

N

N

Y

N

N

N

N

N

N

N

N

N

N

N

N

Compliance with Java

EE standards

Others Standard Expanded

N

N

N

N

N

N

N

N

N

N

N

N

N

N

Y

Y

N

Y

Y

Y

Y

Y

Y

Y

N

N

Y

N

N

Y

N

N

N

N

N

N

N

Y

Y

Reference location

3.15.7

3.15.8

3.15.9

3.15.10

3.15.11

3.16.1

3.16.2

3.16.3

3.16.4

3.16.5

3.16.6

3.17

3.18

11

1. Application Server Functionality

Purpose of the system

Compliance with Java

EE standards

Functionality name

Reliability

N

Performance

N

Operation and maintenance

Y

Expan sion

N

Others Standard Expanded

Reference location

Functionality for operations in a firewall environment

N N Y

3.19

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality. The functionality for which Y is specified only in the

Expanded

column indicates the Application Server-specific functionality.

#1: In the case of Connector 1.0,

Expanded

. In the case of Connector 1.5,

Java EE standards

.

#2: This functionality can be used only when you use a resource adapter compliant with the Connector 1.5 specifications.

#3: This functionality can be used only when you use the TP1 inbound adapter from the resource adapters compliant with the

Connector 1.5 specifications.

1.2.3 Functionality for invoking Application Server from OpenTP1 (TP1 inbound integrated functionality)

The following table describes the TP1 inbound integrated functionality used for invoking Application Server from

OpenTP1. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

4: Correspondence between Application Server invocation from OpenTP1 (TP1 inbound integrated functionality) and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Connection management functionality

RPC

Connection functionality

Scheduling function

Transaction integration functionality

N

N

N

N

N

N

N

N

Y

Y

Y

Y

N

N

N

N

Y

Y

Y

Y

N

N

N

N

Y

Y

Y

Y

4.6

4.7

4.8

4.9

Legend:

Y: Supported

N: Not supported

Note: The functionality for which Y is specified only in the

Expanded

column indicates the Application Server-specific functionality.

12

1. Application Server Functionality

1.2.4 JPA functionality used with Application Server

The following table describes the JPA functionality used with Application Server. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

5: Correspondence between the JPA functionality used with Application Server and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reference location

JPA

Reliability

Y

Performance

N

Operation and maintenance

Y

Expan sion

N

Others

N

Standard

Y

Expanded

Y

Chapter 5

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been extended to the Java EE standard functionality.

1.2.5 Cosminexus JPA Provider functionality

The following table describes the Cosminexus JPA Provider functionality. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

6: Correspondence between the Cosminexus JPA Provider functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Updating the database using entities r

Entity operations by

EntityManage

Defining the mapping information between a database and

Java objects

Entity relationship

Functionality for caching entity objects

Autonumbering of primary key values

Y

N

N

N

N

N

Y

N

N

Y

Y

N

N

N

N

N

N

N

N

N

N

N

N

N

N

Y

Y

N

N

Y

Y

Y

Y

Y

N

Y

Y

Y

Y

Y

Y

Y

6.3

6.4

6.5

6.6

6.7

6.8

13

1. Application Server Functionality

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability

N

Performance

N

Operation and maintenance

Y

Expan sion

N

Others Standard Expanded

Reference location

Database operations based on query language

Optimistic lock

Pessimistic lock in the

JPQL

Y

Y

N

N

N

N

N

N

N

N

N

Y

Y

N

Y

Y

Y

6.9

6.10

6.11

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality. The functionality for which Y is specified only in the

Expanded

column indicates the Application Server-specific functionality.

1.2.6 Cosminexus JMS Provider functionality

The following table describes the Cosminexus JMS Provider functionality. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

7: Correspondence between the Cosminexus JMS Provider functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Sending and receiving the messages compliant with the JMS specifications

System for ensuring highly reliable message delivery

CJMSP

Broker functionality

CJMSP resource adapter functionality

N

Y

N

N

N

N

N

N

N

N

Y

N

N

N

N

N

Y

N

N

Y

Y

Y

Y

Y

N

N

N

N

7.4

,

7.5

,

7.6

7.7

7.8

7.9

14

1. Application Server Functionality

Purpose of a system

Functionality name

Reliability Performance

N

Operation and maintenance

N

Expan sion

N Invoking the

Messagedriven Beans

N

Legend:

Y: Supported

N: Not supported

Compliance with Java

EE standards

Others Standard Expanded

Y Y N

7.10

Reference location

1.2.7 JavaMail functionality

The following table describes the JavaMail functionality. Select the functionality according to the purpose of a system.

For details about the functionality, see the

reference location

.

Table 1

8: Correspondence between the JavaMail functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

JavaMail N N N N Y Y N

Chapter 8

Legend:

Y: Supported

N: Not supported

1.2.8 CDI functionality used with Application Server

The following table describes the CDI functionality used with Application Server. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

9: Correspondence between the CDI functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

CDI N N N N Y Y N

Chapter 9

Legend:

Y: Supported

N: Not supported

1.2.9 Bean Validation functionality used with Application Server

The following table describes the Bean Validation functionality used with Application Server. Select the functionality according to the purpose of a system. For details on the functionality, see the

Reference location

column.

15

1. Application Server Functionality

Table 1

10: Correspondence between the Bean Validation functionality and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Bean

Validation

----Y Y --

Chapter 10

Legend:

Y: Supported

--: Not supported

1.2.10 Managing application attributes

The following table describes the functionality for managing application attributes. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

11: Correspondence between the functionality for managing the application attributes and the purpose of a system

Purpose of a system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Applications containing cosminexu s.xml

Omitting a

DD

N

N

N

N

N

N

Y

Y

N

N

N

Y

Y

Y

11.3

11.4

Legend:

Y: Supported

N: Not supported

Note: The functionality for which Y is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality. The functionality for which

Y

is specified only in the

Expanded

column indicates the Application Server-specific functionality.

1.2.11 Annotation functionality

The following table describes the annotation functionality. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

Table 1

12: Correspondence between the annotation functionality and the purpose of a system

Purpose of the system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Annotation N N N Y N Y Y

Chapter 12

16

1. Application Server Functionality

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality.

1.2.12 Functionality for formatting and deploying J2EE applications

The following table describes the functionality for formatting and deploying J2EE applications. Select the functionality according to the purpose of the system. For details about the functionality, see the

reference location

.

Table 1

13: Correspondence between the functionality for formatting and deploying J2EE applications and the purpose of a system

Purpose of the system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Deploying and undeploying

J2EE applications

Replacing

J2EE applications

Redeploying

J2EE applications

Detecting updates and reloading

J2EE applications

N

N

N

N

N

N

N

N

N

N

Y

Y

N

N

N

N

N

N

N

N

Y

Y

N

N

Y

N

Y

Y

13.5

13.6

13.7

13.8

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified in both

Standard

and

Expanded

columns of the

Compliance with Java EE standards

column indicates that the Application Server-specific functionality has been expanded to the Java EE standard functionality. The functionality for which

Y

is specified only in the

Expanded

column indicates the Application Server-specific functionality.

1.2.13 Container extension library functionality

The following table describes the container extension library functionality. Select the functionality according to the purpose of a system. For details about the functionality, see the

reference location

.

17

1. Application Server Functionality

Table 1

14: Correspondence between the container extension library functionality and the purpose of a system

Purpose of the system

Compliance with Java

EE standards

Functionality name

Reliability Performance

Operation and maintenance

Expan sion

Others Standard Expanded

Reference location

Container extension library functionality

Server start/ stop hook functionality

Invoking the

CORBA objects through Smart

Agent

N

N

N

N

N

N

N

N

N

Y

Y

Y

N

N

N

N

N

N

Y

Y

Y

14.3

14.4

14.5

Legend:

Y: Supported

N: Not supported

Note: The functionality for which

Y

is specified only in the

Expanded

column indicates the Application Server-specific functionality.

18

1. Application Server Functionality

1.3 Description of the functionality mentioned in this manual

This subsection describes the meaning of the classification used in the description of the functionality in this manual and the examples of the tables describing the classification.

1.3.1 Meaning of the classification

The description of the functionality in this manual is classified into the following five points. You can select and read the required location depending on the purpose of referencing the manual.

Explanation

This is the explanation about the functionality. This section explains the purpose, features, and mechanism of the functionality. Read this section if you want an overview of the functionality.

Implementation

This section describes the methods such as the coding method and the DD writing method. Read this section when developing applications.

Settings

This section describes the required property settings for the system setup. Read this section when setting up the system.

Operations

This section describes operation methods. This section describes the operating procedures and the execution examples of the commands to be used. Read this section when operating the system.

Notes

This section describes the general precautions for using the functionality. Make sure that you read the notes.

1.3.2 Examples of tables describing the classification

The following table lists the classification of the functionality description. The title of the table is "organization of this chapter" or "organization of this section".

The following is an example of a table describing the classification of the functionality.

Category

Explanation

Implementation

Settings

Operations

Notes

Example of a table describing the classification of the functionality

Table X-1: Organization of this chapter (YY functionality)

What is the

YY

functionality

Title

Implementation of applications

Definitions in the DD and cosminexus.xml

#

Settings in the execution environment

Operations using the

YY

functionality

Notes on using the

YY

functionality

X.1

X.2

X.3

X.4

X.5

X.6

Reference location

#

Tip

For details on cosminexus.xml

, see

11. Managing Application Attributes

.

Property settings for applications that do not contain cosminexus.xml

19

1. Application Server Functionality

With the applications that do not contain cosminexus.xml

, you set up or change the properties after importing the applications into the execution environment. You can also change the specified properties in the execution environment.

You specify the application settings in the execution environment using the server management commands and the property files. For details on the application settings with the server management commands and the property files, see

3.5.2 How to set up the J2EE application properties

in the

uCosminexus Application Server Application Setup

Guide

.

The tags specified in the property files correspond to a DD or cosminexus.xml

. For details on the correspondence between the DD or cosminexus.xml

and the property file tags, see

2.2 Details of attributes specified in the Cosminexus application property file (cosminexus.xml)

in the

uCosminexus Application Server

Application and Resource Definition Reference Guide

.

Note that the properties specified with each property file can also be specified with the HITACHI Application

Integrated Property File.

20

1. Application Server Functionality

1.4 Main functionality changes in Application Server

09-50

This section describes the main changes in the functionality of Application Server 09-50 and the purpose of each change.

The contents described in this section are as follows:

This section gives an overview and describes the changes in the main functionality of Application Server 09-50.

For details on the functionality, see the description in the reference location. The

Reference manual

and

Reference section

columns describe the main locations where that functionality has been described.

uCosminexus Application Server is omitted from the manual names mentioned in the

Reference manual

column.

(1) Improving development productivity

The following table describes the items that are changed to improve development productivity.

Table 1

15: Changes made for improving development productivity

Item Overview of changes Reference manual

Simplification of Eclipse setup

Supporting debug using the user-extended trace-based performance analysis

GUI can now be used to set up the Eclipse environment.

The user-extended trace-based performance analysis setup file can now be created in the development environment.

Application

Development Guide

Application

Development Guide

Reference section

1.1.5

,

2.4

1.1.3

,

6.5

(2) Simplifying installation and setup

The following table describes the items that are changed to simplify installation and setup.

Table 1

16: Changes made for simplifying installation and setup

Item Overview of changes Reference manual

Expanding the system configuration patterns in the virtual environment

More tier types are now available in the virtual environment ( http-tier

, j2ee-tier

, and ctmtier

). Accordingly, the following system configuration patterns can now be set up:

Pattern of allocating the Web server and J2EE server on different hosts

Pattern of allocating the front end (servlets or JSPs) and back end (EJBs) separately

Pattern of using the CTM

Virtual System Setup and Operation Guide

Reference section

1.1.2

(3) Supporting standard and existing functionality

The following table describes the items that are changed to support standard and existing functionality.

Table 1

17: Changes made for supporting standard and existing functionality

Item Overview of changes Reference manual

Supporting the JDBC 4.0

specifications

HiRDB Type4 JDBC Driver and SQL Server JDBC driver complying with the JDBC 4.0 specifications are now supported with DB Connector.

This manual

Reference section

3.6.3

21

1. Application Server Functionality

Item

Relaxation of the naming rules for the Portable Global JNDI names

Supporting the Servlet 3.0

specifications

Extended use of applications that can be integrated with

Bean Validation

Supporting JavaMail

Extended use of the OS that can use the javacore command

Overview of changes

Characters that can be used in the Portable Global JNDI names are added.

The changes in the HTTP Cookie name, and URL path parameter name in Servlet 3.0 can now also be used in

Servlet 2.5 or earlier.

Bean Validation can now be used for validation in the CDI and user applications as well.

Web Container

Functionality Guide

This manual

The mail sending and receiving functionality using

JavaMail 1.4-compliant APIs is now available.

The javacore command can now be used to obtain the

Windows thread dump.

Reference manual

This manual

This manual

Command Reference

Guide

Reference section

2.4.3

2.7

Chapter 10

Chapter 8

javacore

(Obtaining the thread dump/in

Windows)

(4) Maintaining and improving reliability

The following table describes the items that are changed for maintaining and improving reliability.

Table 1

18: Changes made for maintaining and improving reliability

Item Overview of changes Reference manual

Avoiding the depletion of the code cache area

Supporting the efficient application of the Explicit

Memory Management functionality

Expanding the range of the class-wise statistical information that is output

The size of the code cache area used in the system can now be checked, and the threshold value can be changed to avoid the depletion of area before the area is depleted.

System Design Guide

Maintenance and

Migration Guide

Definition Reference

Guide

System Design Guide

Expansion Guide

The functionality that can control the objects transferred to the Explicit heap is added as the functionality for reducing the automatic release processing time and applying the

Explicit Memory Management functionality efficiently.

Functionality for controlling the transfer of objects to the Explicit memory block

Functionality for specifying the classes to be excluded from the Explicit Memory Management functionality

Output of the object release rate information in the

Explicit heap information

The static

field-based reference relationships can now be output to the extended thread dump containing classwise statistical information.

Maintenance and

Migration Guide

Maintenance and

Migration Guide

9.6

Reference section

7.1.2

5.7.2

,

5.7.3

16.1

,

16.2

,

16.4

7.13.6

8.2.2

,

8.6.5

,

8.10

,

8.13.1

,

8.13.3

5.5

(5) Maintaining and improving operability

The following table describes the items that are changed with the purpose of maintaining and improving operability.

22

1. Application Server Functionality

Table 1

19: Changes made for maintaining and improving operability

Item Overview of changes

Supporting the EADs session failover functionality

Operations using the WAR files

The EADs session failover functionality that implements the session failover functionality by integrating with the

EADs is now supported.

The WAR applications configured only with WAR files can now be deployed on J2EE servers.

Reference manual

Expansion Guide

Web Container

Functionality Guide

This manual

Command Reference

Guide

Reference section

Chapter 5

,

Chapter 7

2.2.1

Starting and stopping the management functionality using synchronous execution

A synchronous execution option is added for starting and stopping the management functionality (Management

Server and Administration Agent).

Releasing the Explicit memory block forcefully with the

Explicit Memory Management functionality

The release processing of the Explicit memory block can now be executed at any time with the javagc command.

Operation, Monitoring, and Linkage Guide

Command Reference

Guide

Expansion Guide

Command Reference

Guide

13.9

cjimportwa r

(Importing

WAR application s)

2.6.1

,

2.6.2

,

2.6.3

,

2.6.4

adminagent ctl (Starting and stopping

Administrat ion Agent)

,

mngautorun

(Setting up and cancelling the settings for autostart and autorestart)

,

mngsvrctl

(Starting, stopping, and setting up

Manageme nt Server)

8.6.1

,

8.9

javagc

(Forced garbage collection)

(6) Other purposes

The following table describes the items that are changed for other purposes.

Table 1

20: Changes made for other purposes

Item Overview of changes

Obtaining definition information

The snapshot

(collecting the snapshot log) command can now be used to collect only definition files.

Reference manual

Maintenance and

Migration Guide

Command Reference

Guide

Reference section

2.3

snapshotlog

(Collecting the

23

1. Application Server Functionality

Item

Obtaining definition information

Output of the cjenvsetup command log

Overview of changes Reference manual

The snapshot

(collecting the snapshot log) command can now be used to collect only definition files.

The execution information for the Component Container

Administrator setup (the cjenvsetup

command) is now output to the message log.

Command Reference

Guide

System Setup and

Operation Guide

Maintenance and

Migration Guide

Command Reference

Guide

Supporting BIG-IP v11

Output of the CPU time to the event log of the Explicit

Memory Management functionality

Extending the functionality of the user-extended trace-based performance analysis

BIG-IP v11 is now added to the available load balancer types.

The CPU time taken for the Explicit memory block release processing is now output to the event log of the Explicit

Memory Management functionality.

System Setup and

Operation Guide

Virtual System Setup and Operation Guide

Maintenance and

Migration Guide

Improving the analysis of information when asynchronous Session Bean invocation is used

The following functionality is added in the user-extended trace-based performance analysis:

The trace target specification method can now be specified for packages or classes in addition to the usual trace target specification method for methods.

The range of available event IDs is expanded.

The restrictions on the number of lines that can be specified in the user-extended trace-based performance analysis setup file are relaxed.

The trace collection level can now be specified in the user-extended trace based performance analysis setup file.

The root application information of the PRF trace can now be used to compare the invocation source and the invocation destination requests.

Maintenance and

Migration Guide

EJB Container

Functionality Guide

Reference section

snapshot log)

4.1.4

4.20

cjenvsetup

(Setting up

Component

Container

Administrat or)

4.7.2

2.1

5.11.3

7.5.2

,

8.28.1

2.17.3

7.5.3

,

24

2

Naming Management

This chapter describes the naming management functionality. The naming management is one of the functionality provided with the J2EE services. You use the naming management functionality to resolve the names for the Enterprise Bean references or the resource references.

25

2. Naming Management

2.1 Organization of this chapter

The

naming management

is one of the functionality provided with the J2EE services. A J2EE service is a component functionality of the J2EE container.

The following table describes the naming management functionality and the reference locations.

Table 2

1: Naming management functionality and reference locations

Functionality

Reference location

Overview of naming management

Binding and looking up objects in the JNDI name space

#

Looking up with the Portable Global JNDI names

Looking up with names beginning with

HITACHI_EJB

Assigning an optional name to the Enterprise Beans or J2EE resources (user-specified name space functionality)

Searching the CORBA Naming Service by using the round-robin policy

Caching with the naming management functionality

Naming service error detection

2.2

2.3

2.4

2.5

2.6

2.7

2.8

2.9

Switching the CORBA Naming Services

Re-using the EJB home object references (functionality for re-connecting to the EJB home objects)

2.10

2.11

#: There are various types of lookup methods. For details on the lookup names and methods, see

2.3.1 Types of names used for lookup

.

26

2. Naming Management

2.2 Overview of naming management

This section describes the naming management functionality and the naming services used for naming management.

2.2.1 Naming management functionality

The naming management manages the name and storage location of an object (EJB home objects, business interface references, and J2EE resources corresponding to the Enterprise Beans). By using the naming management functionality, the EJB client is able to use the necessary objects from the names of the Enterprise Beans or resources to be invoked, without knowing their storage locations.

Also, when you use a resources adapter compliant with the Connector 1.5 specifications, the objects to be managed are also managed by the naming management. The objects to be managed are the objects used for sending and simultaneously receiving messages from within the J2EE application. For details on the objects to be managed, see

3.16.5 Looking up Administered objects

.

In the JNDI of the naming management functionality, the objects other than the CORBA object references (RMI-IIOP remote objects and JDBC data source objects) are handled as follows:

The objects other than the CORBA object references are registered by converting the target objects into CORBA objects and by registering the CORBA object references into the CORBA Naming Service.

To search for objects other than the CORBA objects, the functionality searches for the CORBA object references, reversely convert the CORBA objects into the original objects, and acquire the original objects.

The naming management functionality provided with Application Server includes the functionality provided in J2EE with Application Server-specific enhancements and the functionality that is unique to Application Server. To

determine whether the functionality is unique to Application Server, see

1. Application Server Functionality

.

The following table describes the relation between the naming management functionality provided by Application

Server and the target objects.

Table 2

2: Relation between the naming management functionality provided by Application Server and the target objects

Functionality

Enterprise Bean

EJB home object Business interface

J2EE resource

Binding and looking up objects in the JNDI name space Y Y

Looking up with the Portable Global JNDI names

Looking up with names beginning with HITACHI_EJB

Assigning an optional name to the Enterprise Beans or J2EE resources (user-specified name space functionality)

Searching the CORBA Naming Service by using the roundrobin policy

Caching objects with the naming management functionality

Switching the CORBA Naming Service

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

#2

N

Y

#1

Y

N

Y

N

N

N

Legend:

Y: Available

N: Not available

#1: The names beginning with HITACHI_EJB cannot be looked up.

#2: If the J2EE server is restarted by setting the ejbserver.jndi.cache

property to "on" while a business interface is being used, a javax.ejb.EJBException

might occur when the business method is executed.

27

2. Naming Management

!

Important note

When a custom error page is set up in a Web application, you cannot use the JNDI from the set error page.

2.2.2 Naming services

When using the naming management functionality, the name and storage location of the object is managed by the

naming service

.

Application Server supports the JNDI that uses the

CORBA Naming Service

as the naming management functionality.

When the JNDI interfaces, such as object registration, deletion, or search, are invoked, the interface of the corresponding CORBA Naming Service is invoked. Consequently, to use the naming management functionality, you must specify the protocol, host name, and port number to connect to the CORBA Naming Service.

Reference note

You can start the CORBA Naming Service as an in-process of the J2EE server. By starting the CORBA Naming Service as an in-process, a separate start and stop process becomes redundant, thereby enhancing the operability.

28

2. Naming Management

2.3 Binding and looking up objects in the JNDI name space

The objects to be looked up are associated with the names in the JNDI name space and managed.

To reference the objects, such as the resource manager you want to use and the Enterprise Bean you want to invoke, execute a search (lookup) in the JNDI name space with the application to be executed in the J2EE server.

This section describes the types of names used for lookup, rules for bound names, and the lookup mechanism. This section also describes how to check the JNDI name space.

The following table describes the organization of this section.

Table 2

3: Organization of this section (Binding and looking up objects in the JNDI name space)

Category Title Reference location

Explanation Types of names used for lookup

Mapping and looking up the JNDI name space

How to check the JNDI name space

Implementation

Settings

Definitions in cosminexus.xml

Execution environment settings

Note: The functionality-specific explanation is not available for "Operations".

2.3.1

2.3.2

2.3.3

2.3.4

2.3.5

2.3.1 Types of names used for lookup

With Application Server, you can use the following four types of names for lookup:

Looking up with the Portable Global JNDI names

A lookup method for which you specify a name beginning with java:global

, java:app

, or java:module

(Portable Global JNDI name) defined in Java EE. You can use this method to look up the Enterprise Beans or

J2EE resources.

Looking up with names using java:comp/env

A lookup method for which you specify a name that uses java:comp/env

defined in Java EE. You can use this method to look up the Enterprise Beans or J2EE resources.

Looking up with names beginning with

HITACHI_EJB

A lookup method for which you specify a name that is automatically bound using the Application Server-specific naming rules. You can use this method to look up Enterprise Beans.

Looking up with the optional names assigned by the user-specified name space functionality

A lookup method for which you specify the optional name registered by using an Application Server-specific functionality (user-specified name space functionality). You can use this method to look up the Enterprise Beans or J2EE resources.

The following table describes the lookup method that can be used and the recommended lookup method for each form of EJB client.

Table 2

4: Types of lookup methods

Lookup methods

Form of EJB Client

Looking up with the

Portable Global JNDI names

Looking up with names using java:comp/env

Looking up with names beginning with

HITACHI_EJB

Looking up with the optional names assigned by the userspecified name space functionality

EJB client applications R N Y Y

29

2. Naming Management

Lookup methods

Form of EJB Client

Looking up with the

Portable Global JNDI names

Looking up with names using java:comp/env

Looking up with names beginning with

HITACHI_EJB

JSPs, servlets

EJBs

Y

Y

R

R

Y

Y

Legend:

R: Usage is recommended

Y: Available

N: Not available

The following points describe the lookup names and the methods of lookup using those names:

Looking up with the optional names assigned by the userspecified name space functionality

Y

Y

(1) Looking up with the Portable Global JNDI names

The following points describe how to define the names, the lookup range, and features for looking up with the

Portable Global JNDI names:

Definition method

A lookup using the Portable Global JNDI names includes lookup with automatically bound names and lookup with names specified in the resource reference definitions.

To look up automatically bound names

A name is automatically assigned to the object reference when a J2EE application is deployed on Application

Server. This name is defined using the naming rules provided in Java EE and begins with java:global , java:app

, or java:module

. This name is called the

Portable Global JNDI name

.

To look up names specified in the resource reference definitions

You specify the Portable Global JNDI name in the resource reference definition for the DD.

Range that can be looked up

You can look up the Enterprise Beans or J2EE resources in all the J2EE servers or EJB client applications that use the same CORBA Naming Service.

Features

When a J2EE application is deployed, the EJB home object reference corresponding to the Enterprise Bean, and the business interface reference are automatically bound to names beginning with java:global

, java:app

, or java:module

. A name space conflict can be avoided because the standard application name or standard module name is assigned to the bound name. Also, the Portable Global JNDI names are common to Application

Servers created by different companies, so you need not amend the source code and the DD when the J2EE applications are migrated between Application Servers.

For details on looking up with the Portable Global JNDI names, see

2.4 Looking up with the Portable Global JNDI names

. Also, for details on the standard application name and standard module name, see

2.4.2 Automatically bound objects

.

(2) Looking up with names using java:comp/env

The following points describe how to define the names, the lookup range, and features for looking up names using java:comp/env

:

Definition method

Defines the mapping of the links between the reference names defined in Java EE using java:comp/env

and the actual names in the DD resource references. This resolves the link between the reference names and the actual names during deployment.

Range that can be looked up

30

2. Naming Management

You can look up in one component. However, in the case of Web applications, you can look up in one Web application.

Features java:comp/env

is the context root of the name space defined in Java EE. You can use java:comp/env

to look up between different EJB-JAR and Web applications in a J2EE application and to look up J2EE resources.

The specifications for looking up names using java:comp/env

follow the Java EE provisions.

(3) Looking up with names beginning with HITACHI_EJB

The following points describe how to define the names, the lookup range, and features for looking up names beginning with

HITACHI_EJB

:

Definition method

A name is automatically assigned to the object reference when a J2EE application is deployed on Application

Server. This name is defined using the Application Server-specific naming rules.

Range that can be looked up

You can look up the Enterprise Beans in all the J2EE servers or EJB applications that use the same CORBA

Naming Service.

Features

When a J2EE application is deployed, the EJB home object reference corresponding to the Enterprise Bean, and the business interface reference are automatically bound to names beginning with

HITACHI_EJB

. A name space conflict can be avoided because the server name and application name of the J2EE application is assigned to the bound name.

For details on looking up with names beginning with

HITACHI_EJB

, see

2.5 Looking up with names beginning with

HITACHI_EJB

.

(4) Looking up with the optional names assigned by the user-specified Name Space functionality

The following points describe how to define the names, the lookup range, and features for looking up with the optional names assigned by the user-specified Name Space functionality:

Definition method

Uses the

user-specified name space functionality

of Application Server to define an optional name for the

Enterprise Beans or J2EE resources.

Range that can be looked up

You can look up the Enterprise Beans or J2EE resources in all the J2EE servers that use the same CORBA

Naming Service.

Features

In the case of the Enterprise Beans, if you use the user-specified Name Space functionality, you can register the optional names for the EJB home object references or business interface references combined with binding the name to the JNDI name. You can also register the optional names for the J2EE resources (resource adapter, mail configuration, and JavaBeans resource).

By registering an optional name, you can look up the Enterprise Beans and J2EE resources with any user-specified name.

For details on assigning optional names for the Enterprise Beans or J2EE resources, see

2.6 Assigning an optional name to the Enterprise Beans or J2EE resources (User-specified name space functionality)

.

Reference note

The Java EE specifications recommend looking up with the names using java:comp/env

.

31

2. Naming Management

2.3.2 Mapping and looking up the JNDI name space

This subsection describes the mechanism of JNDI name space mapping, and the relationship of the name specified for lookup with the JNDI name space and DD.

(1) Mechanism for referencing the Enterprise Beans and the method of usage (ejb-ref)

To invoke the Enterprise Beans with the applications executed in J2EE servers, you need to resolve the names of the

Enterprise Bean references. To be precise, you resolve the names such as the names of the EJB home interface, EJB local home interface, and business interface corresponding to the Enterprise Beans.

The following two types of operations are required for resolving the names of the EJB home interfaces or business interfaces:

• Operations for creating the referencing applications

You decide the reference name when you create the application and specify that reference name in the lookup argument of the programs such as Enterprise Beans and servlets. Also, when using java:comp/env , you specify the decided reference name in

<ejb-ref>

of the DD.

• Operations for deploying the referencing applications

When you deploy the created application on a J2EE server, customize the Enterprise Beans and link the reference name and the actual name with linked-to

.

You can use the server management commands to execute this operation.

The mapping mechanism differs based on whether the referencing J2EE application is the same as or differs from the referenced J2EE application. The examples of resolving the names of the EJB home interface when you reference the

Enterprise Bean of a different J2EE application and when you reference the Enterprise Bean of the same J2EE application are as follows:

(a) When referencing the Enterprise Beans of a different J2EE application

The following figure shows an example of referencing the Enterprise Beans included in a J2EE application from a different J2EE application.

32

2. Naming Management

Figure 2

1: Example of referencing the Enterprise Beans included in a J2EE application from a different

J2EE application

When using java:comp/env

, the reference name in java:comp/env

that is specified in the lookup

argument of the referencing program, and the lookup

name that is actually registered in the JNDI Name Space are linked by default ( linked-to ). Note that to specify a lookup name that is different from the name registered in the JNDI

Name Space, you must use the server management commands for customization. The above figure shows a case of customization for invoking

PetShopEB

as ejb/PetShopBean

.

When using the user-specified name space functionality, you can specify the optional name in the lookup

argument of the referencing program. You need not define

<ejb-ref>

.

(b) When referencing the Enterprise Beans of the same J2EE application

The following figure shows an example of referencing the Enterprise Beans included in a J2EE application from the same J2EE application.

33

2. Naming Management

Figure 2

2: Example of referencing the Enterprise Beans included in the same J2EE application

To invoke the Enterprise Beans of the same application, resolve the references by linking ( linked-to

)

<ejbref-name> and ejb-name instead of resolving the references with the lookup name. Note that for the same

J2EE applications, the information required for referencing is identified when the application is developed, so you can directly write ejb-name

in the

<ejb-link>

tag of the DD.

(2) Mechanism for referencing the resources and the method of usage (resource-ref)

To use a resource adapter in the applications executed on a J2EE server, you need to use lookup to resolve the names of the resource references. To be precise, you resolve the name of the factory that creates a connection to the resource manager.

The following two types of operations are required for resolving the names of the factory that creates the connection to the resource manager:

• Operations for creating the referencing applications

34

2. Naming Management

You decide the reference name when you create the application and specify that reference name in the lookup argument of the programs such as Enterprise Beans and servlets. Also, specify the decided reference name in

<resource-ref>

of the DD.

• Operations for deploying the referencing applications

When you deploy the created application on a J2EE server, you customize the resource and use linked-to to link the reference name and the resource registered on the J2EE server.

You can use the server management commands to execute this operation.

The following figure shows an example of accessing the database via DB Connector.

Figure 2

3: Example of accessing the database via DB Connector

In this example, the reference name and the display name of the resource are linked.

2.3.3 How to check the JNDI name space

You can use commands to display and check the name identified by the CORBA Naming Service. Note that you cannot check the optional names of the J2EE resources and the registered information of the EJB local home object references. The nsutil command is used. For details on the usage method and the usage conditions of the nsutil command, see the

Borland(R) Enterprise Server VisiBroker(R) Developers Guide

.

The following is an example of execution when the list of contents in the JNDI name space HITACHI_EJB/

SERVERS/MyServer/EJB

is displayed:

35

2. Naming Management

# nsutil -VBJprop ORBInitRef=NameService=corbaname::localhost:900 list HITACHI_EJB/SERVERS/

MyServer/EJB

Bindings in HITACHI_EJB/SERVERS/MyServer/EJB

Context: App1

Context: App2

Context: App3

2.3.4 Definitions in cosminexus.xml

Define the naming management functionality in the

<ejb-jar>

tag of cosminexus.xml

. The following table describes the definitions used for naming management in cosminexus.xml

.

Table 2

5: Definition of the naming management functionality in cosminexus.xml

Specified tags Settings

<session>-<lookup-name>

tag

<entity>-<lookup-name>

tag

Specifies the lookup name.

For details on cosminexus.xml

, see

2. Application Property File (cosminexus.xml)

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

2.3.5 Execution environment settings

When you use the naming management functionality, you must set up the J2EE server and the J2EE applications and customize the server management commands.

(1) Setting up the J2EE server

You specify the J2EE server settings with the Easy Setup definition file. You define the naming management functionality in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy Setup definition file. The following table describes the definition of the naming management functionality in the Easy Setup definition file.

Table 2

6: Definition of the naming management functionality in the Easy Setup definition file

Items Specified parameters Settings

Basic settings ejbserver.naming.host

# ejbserver.naming.port

# ejbserver.naming.startupMode

Specifies the host name of the CORBA

Naming Service.

Specifies the port number of the CORBA

Naming Service.

Specifies the startup mode of the CORBA

Naming Service.

Specifies the timeout value for the communication with the naming service.

Timeout in the communication with the naming service ejbserver.jndi.request.timeout

# By default, the J2EE server automatically starts and uses the CORBA Naming Service with the host name localhost and port number

900

as an in-process. Change these settings as needed.

For details on the Easy Setup definition file and parameters, see

4.6 Easy Setup definition file

in the

uCosminexus

Application Server Definition Reference Guide

.

(2) Customizing the server management commands

You can customize the settings for operating the server management commands. This point describes the settings for the CORBA Naming Service used by the server management commands.

36

2. Naming Management

To customize the server management commands for using the naming management functionality, specify the settings in usrconf.properties

(system property file for the server management commands). The settings are as follows. For details on the keys and the description of the keys not listed here, see

5. Files Used with the Server

Management Commands

in the

uCosminexus Application Server Definition Reference Guide

.

Table 2

7: Customizing the server management commands for using the naming management functionality

Items Specified keys Settings

Name of the host on which the CORBA

Naming Service is operated

Port number of the

CORBA Naming

Service

Access protocol for the

CORBA Naming

Service ejbserver.naming.host

ejbserver.naming.port

ejbserver.naming.protocol

Specifies the host on which the CORBA

Naming Service used by the server management commands is operated.

Specifies the port number of the CORBA

Naming Service used by the server management commands.

Specifies the access protocol for the CORBA

Naming Service used by the server management commands.

(3) Setting up the J2EE applications

You implement the J2EE application settings for the execution environment using the server management commands and property files. To define the naming management functionality, use the Session Bean property file or Entity Bean property file.

The tags specified in these property files correspond to cosminexus.xml

. For details about the definitions in cosminexus.xml

, see

2.3.4 Definitions in cosminexus.xml

.

37

2. Naming Management

2.4 Looking up with the Portable Global JNDI names

When you deploy a J2EE application, Portable Global JNDI names are automatically bound to the JNDI names of the

EJB home object reference and business interface reference. The bound names are used for lookup.

This section describes the name spaces defined in Java EE, objects bound by the Portable Global JNDI names, naming rules, definitions in the DD, and the execution environment settings.

The following table describes the organization of this section.

Table 2

8: Organization of this section (Looking up with the Portable Global JNDI names)

Category Title Reference location

Explanation

Implementation

Settings

Types of JNDI name spaces

Automatically bound objects

Naming rules for the Portable Global JNDI names

Controlling the registration of Portable Global JNDI names

Looking up the Portable Global JNDI names when the CTM is used

Resource reference names

Specifying the Portable Global JNDI names in annotations

Definitions in the DD

Execution environment settings

2.4.1

2.4.2

2.4.3

2.4.4

2.4.5

2.4.6

2.4.7

2.4.8

2.4.9

Note: The functionality-specific explanation is not available for "Operations" and "Notes".

2.4.1 Types of JNDI name spaces

This subsection describes the types of JNDI name spaces defined in Java EE and the range that can be looked up.

The following figure shows the range of the JNDI name space.

Figure 2

4: Range of the JNDI name space

38

java:global

This name space is shared by all the J2EE applications. With Application Server, all the J2EE servers or EJB client applications using the same CORBA Naming Service share this name space.

java:app

This name space is shared within a J2EE application. The name space is shared by all the components in one J2EE application (Enterprise Beans, servlets, JSPs, filters, and resource adapters).

java:module

2. Naming Management

3

4

5

1

2

This name space is shared among various modules (EJB-JARs, Web applications, or resource adapters). The name space is shared by all the components in one module (Enterprise Beans, servlets, JSPs, filters, and resource adapters).

java:comp

This name space is shared among various components (Enterprise Beans, servlets, JSPs, filters, or resource adapters). The name space is shared within one component only. However, in the case of a Web application, the name space is shared by all the servlets or JSPs in the Web application.

No.

The name space that can be used depends on whether the component to be looked up is included in the same process, application, module, or component as the lookup source. The following table describes the relationship with the components to be looked up, and the possibility of lookup in each name space.

Table 2

9: Possibility of lookup in each name space

Relationship with the component to be looked up Name space to be looked up

Server

(Process)

Application Module Component java:global java:app java:module java:comp

Same

Same

Same

Same

Different

#2

Same

Same

Same

Different

Different

Same

Same

Different

Different

Different

Same

Different

Different

Different

Different

Y

Y

Y

Y

Y

#3

Y

N

N

Y

Y

N

N

N

Y

Y

Y

C

#1

N

N

N

Legend:

Y: Can be looked up.

C: Can be looked up depending on the component type.

N: Cannot be looked up.

#1

Can be looked up in the case of components in the Web application (servlets, JSPs, or filters).

#2

Indicates that the server (process) is different, but the same CORBA Naming Service is used. Includes the lookup of J2EE applications in a J2EE server from the EJB client application.

#3

Only the automatically bound EJB references can be looked up (Application Server-specific specifications).

2.4.2 Automatically bound objects

With Application Server, the standard application name, standard module name, and EJB reference are automatically bound to the names defined in Java EE. Note that the standard application name and standard module name are defined on Application Server as follows:

Standard application name

This name uniquely identifies the J2EE application introduced in Java EE 6. With Application Server, the name is called

standard application name

to distinguish from the "J2EE application name" or "application display name" specified in <display-name> in application.xml

.

Standard module name

This name uniquely identifies various modules in a J2EE application introduced in Java EE 6 (EJB-JAR, Web application, or resource adapter). With Application Server, the name is called

standard module name

to distinguish from the "module name" indicating the names of the EJB-JAR files or WAR files.

The following table describes the automatically bound objects and names.

39

2. Naming Management

Table 2

10: Automatically bound objects and names

Bound objects java:app/AppName

#1 Standard application name

( java.lang.String

type)

Standard module name

( java.lang.String

type)

EJB reference

#2

Session Bean home object java:module/ModuleName

#1

Session Bean business interface

Bound names java:global[/

standard-application-name

]/

standard-module-name

/

Enterprise-Beanname

[!

fully-qualified-class-name

] java:app/

standard-module-name

/

Enterprise-Bean-name

[!

fully-qualified-class-name

] java:module/

Enterprise-Bean-name

[!

fully-qualified-class-name

] java:global[/

standard-application-name

]/

standard-module-name

/

Enterprise-Beanname

[!

fully-qualified-class-name

] java:app/

standard-module-name

/

Enterprise-Bean-name

[!

fully-qualified-class-name

] java:module/

Enterprise-Bean-name

[!

fully-qualified-class-name

]

#1

Can be looked up only from an EJB-JAR or Web application.

#2

With the EJB 3.1 specifications, the class name omission format in which the fully-qualified class name is omitted can be used for lookup when there is one EJB reference (home object and business interface) for one Enterprise Bean.

Furthermore, with Application Server, the reference registered first can be looked up using the class name omission format in the following order of priority even if there are multiple references:

1. Remote home object

2. Local home object

3. Local business interface (including when the business interface is omitted)

4. Remote business interface

However, we do not recommend lookup in the class name omission format because the specifications related to the class name omission format for multiple references are not provided in Java EE.

If an object that can be looked up with a name beginning with

HITACHI_EJB

exists in an application, you can also use the Portable Global JNDI name for lookup.

Note that when the application starts, the Portable Global JNDI name is output to message KDJE47701-I for each bound EJB reference. When the class name or application name omission format of the Enterprise Bean is enabled, all the formats that can be looked up are enumerated using comma and space delimiters (,).

2.4.3 Naming rules for the Portable Global JNDI names

The Portable Global JNDI name includes the standard application name, standard module name, and Enterprise Bean name. Java EE defines the naming rules and characters that can be used for these names.

This subsection describes the naming rules for the standard application name, standard module name, and Enterprise

Bean name used in the Portable Global JNDI name, and the characters that can be used.

(1) Naming rules for the standard application name

The following table describes the rules for setting up the standard application name.

Table 2

11: Naming rules for the standard application name

Preconditions for the application

J2EE application

(EAR file) application.xml

exists.

The <application-name> tag exists.

The value exists.

Standard application name

Value of the <applicationname>

tag

#1

40

2. Naming Management

J2EE application

(EAR file)

Preconditions for the application application.xml

exists.

The <application-name> tag exists.

The value is null

#2

.

-The

<application-name> tag does not exist.

application.xml

does not exist.

---

A value is specified in the

-name

option of the cjimportwar

command

Standard application name

Default standard application name

#3

WAR application

(WAR file)

No value is specified in the -name option of the cjimportwar command

Value of the

-name

option of the cjimportwar command

#1

Default standard application name

#3

Legend:

--: Not applicable.

#1

The space characters before and after the value (single-byte spaces, tabs, and linefeeds) are removed. The space characters between the words are not removed.

#2

Indicates a zero length string. A value consisting of only a space character is also determined to be null.

#3

The default standard application name differs depending on the J2EE application format. The following table describes the naming rules for the default standard application name.

Table 2

12: Naming rules for the default standard application name

Precondition for applications Default standard application name

J2EE application

(EAR file)

Archive format

WAR application

(WAR file)

Exploded archive format

Archive format

Exploded archive format

String obtained by removing the extension from the name of the EAR file.

However, the extension is not removed if a period "." exists only at the beginning of the file name.

If application.xml

exists

J2EE application name (value of the <display-name> tag).

If application.xml

does not exist

Name of the application directory.

String obtained by removing the extension from the name of the WAR file.

However, the extension is not removed if a period "." exists only at the beginning of the file name.

WAR directory name.

The values that can be specified in the standard application name are as follows:

Standard application name specified in the

<application-name>

tag

The standard application name is registered if the name contains single-byte alphanumeric characters (0 to 9, A to

Z, and a to z) and the following special characters:

Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period

(.), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark

(@), square brackets ([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)

However, the following names are not registered:

Names that begin or end with a period (.)

Names containing a period (.) only

Names with a string length of 256 characters or more

41

2. Naming Management

Names matching with env

Standard application name specified in the <display-name> tag

The standard application name (value of the

<display-name>

tag) is registered if the name contains singlebyte alphanumeric characters (0 to 9, A to Z, and a to z), plus (+), hyphen (-), period (.), underscore (_), and caret

(^).

However, the following names are not registered:

Names that begin or end with a period (.)

Names containing a period (.) only

Names with a string length of less than 1 character

Names with a string length of 256 characters or more

Names matching with env

Examples of names that are not registered foo/bar

,

.foo

,

.foobar.

, env

In the case of names for which the standard application name cannot be registered, KDJE47710-W is output when the application starts and the start processing of the application continues. However, the Portable Global JNDI names are not registered for all the objects included in that application, so the Portable Global JNDI names cannot be used for lookup. To look up with the Portable Global JNDI names, as and when required, change the name of the DD or EAR file, or the name of the application directory according to the naming rules.

(2) Naming rules for the standard module name

The following table describes the rules for setting up the standard module name.

Table 2

13: Naming rules for the standard module name

Preconditions for the module

EJB-JAR module

(EJB-JAR file) ejb-jar.xml

exists The <module-name> tag exists.

The value exists.

The value is null

#2

.

-The

<module-name

> tag does not exist.

---

Web module (WAR file) ejb-jar.xml

does not exist web.xml

exists The <module-name> tag exists.

The value exists.

The value is null

#2

.

-web.xml

does not exist

The

<module-name>

tag does not exist.

---

Resource adapter module (RAR file)

--

Standard module name

Value of the <module-name> tag

#1

Default standard module name

#3

Value of the <module-name> tag

#1

Default standard module name

#3

Default standard module name

#3

Legend:

--: Not applicable.

#1

The space characters before and after the value (single-byte spaces, tabs, and linefeeds) are removed. The space characters between the words are not removed.

42

2. Naming Management

#2

Indicates a zero length string. A value consisting of only a space character is also determined to be null.

#3

The default standard module name differs depending on the module and J2EE application format. The following table describes the naming rules for the default standard module name.

Table 2

14: Naming rules for the default standard module name

Module J2EE application format Default standard module name

EJB-JAR module

(EJB-JAR file)

Archive format

Web module

(WAR file)

Resource adapter module

Exploded archive format

Archive format

Exploded archive format

Archive format

String obtained when you remove the extension from the relative path from the root directory of the application package up to the EJB-JAR file.

However, the extension is not removed if a period "." exists only at the beginning of the EJB-JAR file name.

If the path delimiter is

\

, the character is converted to

/

.

If application.xml

exists

The path specified in the

<module>/<ejb>

tag of application.xml

.

If application.xml

does not exist

String obtained when you remove the last

_jar

from the relative path from the application directory up to the EJB-JAR directory.

If the path delimiter is \ , the character is converted to / .

String obtained when you remove the extension from the relative path from the root directory of the application package up to the WAR file.

However, the extension is not removed if a period "." exists only at the beginning of the WAR file name.

If the path delimiter is

\

, the character is converted to

/

.

If application.xml

exists

The path specified in the <module>/<web>/<web-uri> tag of application.xml

.

If application.xml

does not exist

String obtained when you remove the last

_war

from the relative path from the application directory up to the WAR directory.

If the path delimiter is

\

, the character is converted to

/

.

String obtained when you remove the extension from the relative path from the root directory of the application package up to the RAR file.

However, the extension is not removed if a period "." exists only at the beginning of the RAR file name.

If the path delimiter is \ , the character is converted to / .

Note that the standard module name (value of the <module-name> tag) is registered if the name contains singlebyte alphanumeric characters (0 to 9, A to Z, and a to z) and the following special characters:

Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand

(&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), forward slash as a delimiter (/), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark (@), square brackets ([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)

However, the following names are not registered:

Names that begin or end with a forward slash (/)

Names containing a forward slash (/) only

Names with a series of forward slashes (/)

Names that begins or ends with a period (.)

Names containing a period (.) only

43

2. Naming Management

Names with a series of forward slashes (/) and periods (.)

Names with a string length of 256 characters or more

Names matching with env

Names beginning with env/

Names matching with

AppName

Names beginning with

AppName/

Examples of names that are not registered

/foo , /foobar/ , / , foo//bar , bar.

, .foobar.

, foo/.bar

, AppName , AppName/foo , env/foo/bar

In the case of names for which the standard module name cannot be registered, KDJE47711-W is output for each module when the application starts and the start processing of the application continues. However, the Portable Global

JNDI names are not registered for all the objects included in that module, so the Portable Global JNDI names cannot be used for lookup. To look up with the Portable Global JNDI names, as and when required, change the name of the

DD or the name of the application directory according to the naming rules.

(3) Naming rules for the Enterprise Bean name

A name is registered as the Enterprise Bean name if the name contains single-byte alphanumeric characters (0 to 9, A to Z, and a to z) and the following special characters:

Space ( ), exclamation mark (!), double quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand

(&), single quotation mark ('), barren (() ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), colon (:), semicolon (;), less-than sign (<), equal sign (=), greater-than sign (>), question mark (?), at mark (@), square brackets

([) (]), backslash (\), caret (^), underscore (_), grave accent mark (`), curly brackets ({) (}), vertical bar (|), and tilde (~)

However, the following names are not registered:

Names that begin or end with a period (.)

Names containing a period (.) only

Names with a string length of 256 characters or more

Names matching with ModuleName

Names matching with env

Examples of names that are not registered

.foo

, .foobar.

, ModuleName , env

In the case of names for which the Enterprise Bean name cannot be registered, KDJE47712-W is output for each

Enterprise Bean when the application starts and the start processing of the application continues. However, the registration to the Portable Global JNDI names is not performed for all the objects included in that Enterprise Bean.

Note that the names for which the Enterprise Bean name cannot be registered cannot be looked up with the Portable

Global JNDI names, but all the other application functionality operate as before.

Furthermore, the specifiable string length is checked for each Enterprise Bean interface (home interface or business interface) as well. For example, if the following string length is 256 characters or more, KDJE47713-W is output for each interface, and the name is not registered in the Portable Global JNDI name with the format specifying that interface name.

Length-of-Enterprise-Bean-name

+

length-of-interface-class-name

#

+ 1

# Fully-qualified class name containing the package name

Note that in EJB 3.1, if the interface is omitted, the Enterprise Bean class name is applicable instead of the interface class name.

44

2. Naming Management

(4) Operations when the standard application name or standard module name are duplicated

With Application Server, if the same standard application name is already registered for a name space when an application starts, KDJE47720-W is output, and the name is not registered for the name space. Similarly, if the same standard module name is already registered for a name space in the same application, the following message is output and the name is not registered for the name space. However, the start processing of the application continues.

For an EJB-JAR: KDJE47721-W

For a Web application: KDJE47722-W

For a resource adapter: KDJE47723-W

Note that the modules are registered in the following order with Application Server:

1. Resource adapter

2. EJB-JAR

3. Web application

If the registered object and name match in the hierarchy demarcated with forward slashes (/), even if the name does not exactly match the registered standard application name or standard module name, the name might be determined to be a duplicate. The examples are as follows:

Example 1

If the applications are started in the following order, the standard application name is determined to be duplicated:

1. An application with the standard application name foo/bar is started

2. An application with the standard application name foo is started

Example 2

If the applications are started in the following order, the standard application name is determined to be duplicated:

1. An application with the standard application name foo

and the standard module name bar

is started

2. An application with the standard application name foo/bar

is started

2.4.4 Controlling the registration of Portable Global JNDI names

In Application Server version 09-00 and later, if you do not want to look up with the Portable Global JNDI names, specify the following settings in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the

Easy Setup definition file. When you specify these settings, the Portable Global JNDI name is not registered when the application starts. Furthermore, the information and warnings related to the Portable Global JNDI name are also not displayed.

Specify false in the ejbserver.jndi.global.enabled

parameter.

2.4.5 Looking up with the Portable Global JNDI names when the CTM is used

If the system configuration uses the CTM, you can acquire the EJB remote home object by looking up the CORBA

Naming Service that is connected to the CTM daemon from the EJB client application. When you look up the EJB, you can use the names beginning with HITACHI_EJB , the Portable Global JNDI name, and the optional name assigned by using the user-specified name space functionality.

During EJB lookup when the CTM is used, the optional name is used if the optional name is specified for the EJB. If the optional name is not specified, the default lookup name is used. The default lookup name is switched using the ejbserver.ctm.useGlobalJNDI

parameter in the

<configuration>

tag of the logical J2EE server

( j2ee-server

) in the Easy Setup definition file.

The following table describes the names used for EJB lookup when the CTM is used.

45

2. Naming Management

Table 2

15: Names used for EJB lookup when the CTM is used

Preconditions

Specificati on of the optional name for

EJB

Value of the ejbserver.jndi.global.ena

bled parameter

#1

Value of the ejbserver.ctm.useGlobal

JNDI parameter

#2

Can the Portable Global

JNDI name be registered

#3

Yes

No

-true

(default) false true

-false

(default)

--

--

Can be registered

Cannot be registered

--

--

Lookup name

Optional name for the EJB

Portable Global JNDI name

Name beginning with

HITACHI_EJB

Legend:

--: Not applicable

#1

Indicates the value specified in the ejbserver.jndi.global.enabled

parameter of the Easy Setup definition file. If the value is true

, the Portable Global JNDI name is registered when the application starts. If the value is false

, the Portable

Global JNDI name is not registered.

#2

Indicates the value specified in the ejbserver.ctm.useGlobalJNDI

parameter of the Easy Setup definition file. If the value is true

, the Portable Global JNDI name is used for EJB lookup in a system configuration where the CTM is used. If the value is false , a name beginning with HITACHI_EJB is used.

#3

Indicates whether the EJB can be registered with the Portable Global JNDI name. If the standard application name or standard module name is duplicated, or if the string cannot be registered, the Portable Global JNDI name cannot be registered.

2.4.6 Resource reference names

In Java EE 6 and later, apart from the names using java:comp/env

, you can specify the fully qualified JNDI name in the resource reference name. By specifying the fully qualified JNDI name in the resource reference name, you can define the resource reference shared by all the components in one application (Enterprise Beans, servlets, JSPs, filters, and resource adapters) and the resource reference shared by all the components in the EJB-JAR or Web application.

Also, you can look up the other resource references with the fully qualified JNDI name by specifying the

<lookupname>

tag in the DD ( web.xml

), or the lookup

attribute of the

@Resource

and

@EJB

annotations.

This subsection describes the specification of the fully qualified JNDI name for the resource reference name, and the look up of the other resource references.

!

Important note

If the registration of the Portable Global JNDI names is controlled by specifying false in the ejbserver.jndi.global.enabled

parameter, do not specify a name beginning with java:

in the resource reference name.

(1) Specifying the fully qualified JNDI name for the resource reference name

With Application Server, if you specify a name beginning with java:

in the resource reference name when the registration of the Portable Global JNDI name is enabled, the fully qualified JNDI name is determined to have been specified and the specified name is handled as the JNDI name as is.

If the registration of the Portable Global JNDI name is disabled, or if you specify a name beginning with a string other than java: , the name is handled as a name beginning with java:comp/env or as an optional name of the resource adapter.

46

2. Naming Management

1

2

No

.

5

6

3

4

Resource reference types

Environment entry

Resource reference

Resource environment variable reference

Remote EJB reference

Local EJB reference

Persistence context reference

7

The following table describes the resource reference types for which you can specify the fully qualified JNDI name as the resource reference name in the DD ( web.xml

).

Table 2

16: Resource reference types for which you can specify the fully qualified JNDI name (DD)

Persistence unit reference

Tags specifying the resource reference name

<env-entry> - <env-entry-name>

<resource-ref> - <res-ref-name>

<resource-env-ref> - <resource-env-ref-name>

<ejb-ref> - <ejb-ref-name>

<ejb-local-ref> - <ejb-local-ref-name>

<persistence-context-ref> - <persistence-context-refname>

<persistence-unit-ref> - <persistence-unit-ref-name>

The following table describes the resource reference annotations for which you can specify the fully qualified JNDI name in the name

attribute.

Table 2

17: Resource reference types for which you can specify the fully qualified JNDI name

(Annotations)

5

6

3

4

7

1

2

No

.

Resource reference types

Environment entry

Resource reference

Resource environment variable reference

Remote EJB reference

Local EJB reference

Persistence context reference

Persistence unit reference

Annotations specifying the resource reference name name

attribute of

@Resource name attribute of @EJB name

attribute of

@PersistenceContext name

attribute of

@PersistenceUnit

If you specify the fully qualified JNDI name in the resource reference name when the registration of the Portable

Global JNDI name is enabled, depending on the combination of whether the specified name space, and standard application name and standard module name violate the naming rules, KDJE47730-E is output when the application is starting and the application fails to start.

The following table describes the specified name space of the fully qualified JNDI name and whether the application can be started. Note that even if you specify a name that begins with java: , but without a specifiable name space,

KDJE47730-E is output when the application is starting and the application fails to start.

Table 2

18: Specified name space of the fully qualified JNDI name and can the application be started

Preconditions Specified name space

Standard application name of the application defining the resource reference

Standard module name of the EJB-JAR or Web application defining the resource reference java:comp java:module java:app java:global

Invalid value or duplication

-Y N N Y

47

2. Naming Management

Preconditions

Standard application name of the application defining the resource reference

Standard module name of the EJB-JAR or Web application defining the resource reference

Normal Invalid value or duplication

Normal java:comp

Y

Y

Specified name space java:module

N

Y java:app

Y

Y java:global

Y

Y

Legend:

Y: The application can be started.

N: The application cannot be started.

--: Not applicable.

With Application Server, there are no constraints on the sub-context name when you specify the resource reference name for the fully qualified JNDI name. However, if a context or object is already registered with the same name,

KDJE47721-W is output when the application is starting and the application fails to start.

Note that even when you define the Portable Global JNDI name in the resource reference name, that resource reference cannot be looked up from the J2EE server or EJB client application of another process. If you look up a resource reference on another process in which the Portable Global JNDI name is defined, the

NameNotFoundException exception occurs.

(2) Looking up the other resource references

With Application Server, by specifying the <lookup-name> tag in web.xml

, or the lookup attribute in the

@Resource

and

@EJB

annotations, in addition to specifying the resource references that have been registered using the names beginning with java:comp/env

, you can look up the resources shared by the EJB-JAR or Web applications and the resources shared by an application through the DI functionality and resource references.

For example, the DI functionality can also be executed for the environment entry defined in the java:app

name space in web.xml

within a Web application from the EJB in the EJB-JAR that is a separate module.

You can use the resource adapter name and the EJB optional name in the names that can be looked up from the resource references.

The following table describes the names that can be looked up from the resource references.

Table 2

19: Names that can be looked up from the resource references

Lookup source resource reference

Name that can be looked up

Annotation DD (web.xml) lookup

attribute of

@Resource

#1

<env-entry> - <lookup-name>

#2 lookup

attribute of

@EJB

<resource-ref> - <lookup-name>

#1

<resource-env-ref> - <lookup-name>

#1

<ejb-ref> - <lookup-name>

Environment entry name (fully qualified

JNDI name)

Resource reference name (fully qualified

JNDI name)

Optional name of the resource adapter

Resource environment variable reference name (fully qualified JNDI name)

EJB remote reference name (fully qualified

JNDI name)

Portable Global JNDI name of the EJB remote object

Optional name of the EJB remote object

48

2. Naming Management

Annotation lookup

attribute of

@EJB

Lookup source resource reference

DD (web.xml)

<ejb-local-ref> - <lookup-name>

Name that can be looked up

Local EJB reference name (fully qualified

JNDI name)

Portable Global JNDI name of the local EJB object

Optional name of the local EJB object

#1

According to the Java EE specifications, if the data type in the injection destination or the data type set in the

<resourceref-type>

tag and

<resource-env-ref-type>

tag of web.xml

is one of the following types, the settings in the lookup

attribute of the

@Resource

annotation or the

<lookup-name>

tag are ignored (the operation is the same as when the settings are not specified): org.omg.CORBA.ORB

org.omg.CORBA_2_3.ORB

javax.ejb.EJBContext

javax.ejb.SessionContext

javax.ejb.TimerService

javax.transaction.UserTransaction

javax.validation.Validator

javax.validation.ValidatorFactory

javax.enterprise.inject.spi.BeanManager

#2

According to the Java EE specifications, if a value is set in the

<env-entry-value>

tag, the settings in the lookup

attribute of the

@Resource

annotation or the

<lookup-name>

tag are ignored (the operation is the same as when the settings are not specified).

Note that if the <linked-to> tag, <linked-queue> tag, or <linked-adminobject> tag is specified in the property file, and the mappedName attribute is specified in the @Resource annotation, the settings in the lookup attribute of the

@Resource

annotation and the

<lookup-name>

tag in web.xml

are ignored.

!

Important note

Do not set the lookup destination resource reference as the lookup source and do not set a circular reference. If you define the resource references so that they form a circular reference, an infinite recursive call occurs when you look up from an application or when you execute the DI functionality, the java.lang.StackOverflowError

exception occurs, and the application does not return a response.

An example of a circular reference is as follows:

<env-entry>

<env-entry-name>java:app/env/sample1</env-entry>

<lookup-name>java:app/env/sample2</env-entry>

</env-entry>

<env-entry>

<env-entry-name>java:app/env/sample2</env-entry>

<lookup-name>java:app/env/sample1</env-entry>

</env-entry>

For this definition, if you look up java:app/env/sample1

from the application, an infinite recursive call occurs, and the java.lang.StackOverflowError

exception is thrown.

2.4.7 Specifying the Portable Global JNDI names in annotations

With Application Server, you can specify the Portable Global JNDI name in the lookup

and mapped

attributes of the

@EJB

annotation, according to the Java EE specifications. Due to this, you can directly inject the EJB business interface reference or home object reference.

49

2. Naming Management

If you specify settings matching the following conditions in the

@EJB

annotation, regardless of the injected Session

Bean type, the DI functionality is implemented every time a business method is invoked, or the timeout callback method is invoked.

If the format

<module-name>/<bean-name>

is specified in the beanName

attribute

If the Portable Global JNDI name is specified in the lookup attribute

If the Portable Global JNDI name is specified in the mappedName attribute

2.4.8 Definitions in the DD

This subsection describes the necessary DD definitions when you use the Portable Global JNDI names for look up.

You specify the definitions for look up with the Portable Global JNDI names in application.xml

, ejbjar.xml

, and web.xml

.

The following table describes the definitions in the DD related to looking up with the Portable Global JNDI names.

Table 2

20: Definitions in the DD for looking up with the Portable Global JNDI names

DD type Tag name Settings application.xml

<application> - <application-name> ejb-jar.xml

web.xml

<ejb-jar> - <module-name>

<web-app> - <module-name>

<web-app> - <env-entry> - <lookup-name>

<web-app> - <resource-ref> - <lookup-name>

<web-app> - <resource-env-ref> - <lookup-name>

<web-app> - <ejb-ref> - <lookup-name>

<web-app> - <ejb-local-ref> - <lookup-name>

Specifies the standard application name.

Specifies the standard module name.

Specifies the standard module name.

If the tag is specified multiple times, the value set in the tag specified first is applied, and the values set in the second and subsequent tags are ignored.

Specifies the Portable Global JNDI name that references another enventry

.

Specifies the Portable Global JNDI name that references another resource-ref

.

Specifies the Portable Global JNDI name that references another resource-env-ref

.

Specifies the Portable Global JNDI name that references another ejbref , or the Portable Global JNDI name that binds the remote business interfaces.

Specifies the Portable Global JNDI name that references another ejblocal-ref

, or the Portable Global

JNDI name that binds the local business interfaces.

!

Important note

The contents specified in the

<module-name>

tag and

<lookup-name>

tag existing in cosminexus.xml

and

HITACHI Application Integrated Property File differ from the contents specified in the

<module-name>

tag and

<lookup-name> tag set in the above ejb-jar.xml

or web.xml

.

50

2. Naming Management

2.4.9 Execution environment settings

To look up with the Portable Global JNDI names, you must specify the J2EE server settings.

You implement the J2EE server settings using the Easy Setup definition file. You specify the definition for looking up with the Portable Global JNDI names in the <configuration> tag of the logical J2EE server ( j2ee-server ) in the Easy Setup definition file. The following table describes the settings in the Easy Setup definition file.

Table 2

21: Definitions in the Easy Setup definition file for looking up with the Portable Global JNDI names

Item Specified parameter Settings

Registering the Portable Global

JNDI name

Default lookup name when the

CTM is used ejbserver.jndi.global.ena

bled ejbserver.ctm.useGlobalJN

DI

Specifies whether to register the Portable Global JNDI name for the naming service when the application starts.

Specifies the default lookup name to be used when the optional name is not specified in the EJB, when the CTM is used.

Reference note

If you specify the settings to register the Portable Global JNDI name, the information about the registered name and the warnings, such as the duplication of the standard application name, are displayed on the console when the application starts.

For details on the Easy Setup definition file and parameters, see

4.6 Easy Setup definition file

in the

uCosminexus

Application Server Definition Reference Guide

.

51

2. Naming Management

2.5 Looking up with names beginning with

HITACHI_EJB

This section describes the names beginning with

HITACHI_EJB

. When you deploy a J2EE application, a name beginning with

HITACHI_EJB

is automatically bound to the JNDI name of the EJB home object reference and business interface reference. The bound name is used for lookup.

For details on the mapping mechanism and usage of the JNDI name space, see

2.3.2 Mapping and looking up the

JNDI name space

.

!

Important note

The names beginning with HITACHI_EJB are not bound when a local interface is used. Use another method for lookup.

(1) Name that automatically binds the EJB home object reference

When you start (deploy) a J2EE application, the EJB home object reference of the Enterprise Bean is bound to the

JNDI name with the following name:

HITACHI_EJB/SERVERS/

server-name

/EJB/

J2EE-application-name

/

Enterprise-Bean-name server-name

Name of the J2EE server

J2EE-application-name

Lookup name of the J2EE application

Enterprise-Bean-name

Lookup name of the Enterprise Bean

When Enterprise Beans are invoked between the J2EE applications, or Enterprise Beans are invoked from the EJB client application, the client looks up the EJB home object reference with the bound JNDI name.

The following figure shows that when a J2EE application is started with the below-mentioned conditions, an EJB home object implementing the "CartHome" interface is generated, and that reference is bound to the JNDI name

"

HITACHI_EJB/SERVERS/MyServer/EJB/CartApp/CartEB

".

Conditions

Enterprise Bean: "CartBean"

Remote interface name: "Cart"

Home interface: "CartHome"

Server name: "MyServer"

Lookup name of the J2EE application: "CartApp"

Lookup name of the Enterprise Bean: "CartEB"

52

Figure 2

5: Binding the EJB home object reference to the JNDI name space

2. Naming Management

The following figure shows the procedure of lookup and obtaining of objects when the EJB home object reference is looked up using a name beginning with

HITACHI_EJB

.

Figure 2

6: Procedure of lookup and obtaining of objects using a name beginning with HITACHI_EJB

(2) Name that automatically binds the business interface reference

When you start (deploy) a J2EE application, the business interface reference is bound to the JNDI name with the following name:

HITACHI_EJB/SERVERS/

server-name

/EJBBI/

J2EE-application-name

/

Enterprise-Bean-name server-name

Name of the J2EE server

53

2. Naming Management

J2EE-application-name

Lookup name of the J2EE application

Enterprise-Bean-name

Lookup name of the Enterprise Bean

When Enterprise Beans are invoked between the J2EE applications, or Enterprise Beans are invoked from the EJB client application, the client looks up the business interface reference with the bound JNDI name.

54

2. Naming Management

2.6 Assigning an optional name to Enterprise Beans or

J2EE resources (User-specified name space functionality)

The functionality with which the user assigns an optional name and registers the Enterprise Beans or J2EE resources in JNDI name space is called the

user-specified name space functionality

. This functionality enables you to lookup the

Enterprise Beans or J2EE resources using any specified name.

Note that you must customize the settings for operating the server management commands to assign an optional name.

For details on how to specify the settings, see

2.6.7 Execution environment settings

.

!

Important note

In the Java EE specifications, we recommend that you perform lookup with the name using java:comp/env .

The following table describes the organization of this section.

Table 2

22: Organization of this section (User-specified name space functionality)

Category Title

Explanation

Implementation

Objects that can be assigned an optional name

Rules for assigning the optional names

Timing for registering or deleting the optional name

Searching from the client

Setting the optional names for the Enterprise Beans

Setting the optional names for the J2EE resources

Execution environment settings Settings

Notes Precautions for using the user-specified name space functionality

Note: the function-specific explanation is not available for "Operations".

2.6.1

2.6.2

2.6.3

2.6.4

2.6.5

2.6.6

2.6.7

2.6.8

Reference location

2.6.1 Objects that can be assigned an optional name

This subsection describes the objects that can be assigned an optional name.

You assign optional names to the Enterprise Beans or J2EE resources.

(1) Optional names for Enterprise Beans

An optional name is assigned to Enterprise Beans with the following interfaces:

Remote home interface

Local home interface

Remote business interface

Local business interface

Hereafter, the remote home interface and remote business interface are together called the

remote interface

. Also, the local home interface and local business interface are together called the

local interface

.

Reference note

The optional names for the remote interface and local interface are set as different attributes. For details, see

2.6.5 Setting the optional names for the Enterprise Beans

.

55

2. Naming Management

(2) Optional names for J2EE resources

The following table describes the J2EE resources to which you can assign optional names.

Table 2

23: J2EE resources for which optional names can be assigned

Types of J2EE resources

Possibility of assigning an optional name

Resource adapter DB Connector

Mail configuration

JavaBeans resource

DB Connector for Cosminexus RM

Cosminexus RM uCosminexus TP1 Connector

TP1/Message Queue - Access

Other resources adapters

Y

#1

Y

Y

#2

Y

Y

#2

Y

#3

Y

Y

Legend:

Y: Optional name is assigned

#1 When the connection pool clustering functionality is used, optional names are not assigned to the member resource adapters.

#2 An optional name is assigned to the javax.jms.ConnectionFactory

object specified in

<resource-env-ref>

of the property file. An optional name is not assigned to the javax.jms.Destination

object specified in <resource-env-ref> .

#3 For the resource adapters compliant with the Connector 1.5 specifications, you cannot assign an optional name to an administered object.

2.6.2 Rules for assigning the optional names

This subsection describes the rules for assigning the optional names to Enterprise Beans and J2EE resources.

(1) Specifiable names

This subsection describes the characters that can be specified as the optional name and the specification constraints.

(a) Characters that can be specified in an optional name

You can specify a name containing the following characters as an optional name:

Alphanumeric characters (A-Z, a-z, 0-9)

Underscore (_)

Forward slash (/)

Period (.)

Hyphen (-)

However, you can use the forward slash (/) in the name only when the forward slash is used as a delimiter.

(b) Constraints on optional name specification

You cannot specify the following names as optional names. If you specify the following names, the J2EE applications or J2EE resources cannot be started:

Name that begins or ends with a forward slash (/) or period (.).

Name that only contains a forward slash (/) or period (.).

Name with a series of forward slashes (/).

56

2. Naming Management

Name with a series of forward slashes (/) and periods (.).

Name that begins with HITACHI_EJB (case-sensitive).

Name with a string length longer than 255 bytes.

Apart from the above, for the J2EE resources, the definition specified later becomes valid when the same name is specified.

(2) Duplication of optional names

The following table describes whether the duplication of the optional name is allowed when the optional names are assigned to Enterprise Beans and J2EE resources.

Table 2

24: Duplication of the optional names for Enterprise Beans and J2EE resources

Target for assigning the optional name

Enterprise Beans with remote interface

Enterprise Beans with local interface

Resource adapters included in the J2EE application

J2EE resources

#1

N

Y

#2

N N Enterprise Beans with remote interface

Enterprise Beans with local interface

Resource adapters included in the J2EE application

J2EE resources

#1

Y

#2

N

N

C

C

N

C

C

N

N

N

N

Legend:

Y: Can be duplicated

C: Can be duplicated if the J2EE application is different

N: Cannot be duplicated

#1 Excluding the resource adapters included in the J2EE application.

#2 Can be duplicated regardless of whether the local call optimization functionality is used.

Note that for the combinations in which the optional names cannot be duplicated, the specification of the optional name might be disallowed even if the name does not match completely.

This is described with the following example:

Example

The naming management functionality manages the objects registered in the CORBA Naming Service by names.

The name assigned to the object analyzes the forward slash (/) as a delimiter of the hierarchical structure and is managed in a tree structure. In the tree structure, you can register a new object below the nodes that have child nodes.

In the following figure, nodes A, B, C, and F have child nodes. Therefore, new objects can be registered below these nodes.

57

2. Naming Management

Figure 2

7: Example wherein the optional name cannot be specified although the name does not match completely

In such a case, if the optional name 'A/B/D' is already in use, you can specify the optional name 'A/B/I'.

However, new objects cannot be registered in nodes such as D, E, G, and H. Therefore, the optional name

'A/B/D/I' cannot be specified.

If an optional name that cannot be duplicated is specified, an error occurs at the following timings in each object where the optional name is specified:

In the case of the Enterprise Beans, the J2EE application fails to start.

In the case of J2EE resources other than mail configuration, the resource fails to start.

In the case of mail configuration, an error occurs during attribute settings.

2.6.3 Timing for registering or deleting the optional name

This subsection describes how to set the optional names for the Enterprise Beans or J2EE resources, the timing for registering the optional name, and the timing for deleting the optional name.

(1) Timing for registering or deleting the optional names of Enterprise Beans

The optional name specified in the Enterprise Bean object is registered in the name space when the J2EE application is started or when the J2EE server is started.

The optional name specified in the Enterprise Bean object is deleted from the name space when the J2EE application is stopped or when the J2EE server is stopped.

Reference note

When the log level is set to "Warning", you can check whether the optional name is registered or deleted in the message log.

When the optional name is registered: KDJE47605-I is output.

When the optional name is deleted: KDJE47606-I is output.

However, these messages are not output in the default log level settings. For details on the log level settings, see

3.3.6 Log collection settings for J2EE servers

in the

uCosminexus Application Server Maintenance and Migration Guide

.

(2) Timing for registering or deleting the optional names of the J2EE resources

The optional name for a J2EE resource is registered in the name space when the J2EE resource is started.

The optional name for the J2EE resource is deleted from the name space when the J2EE resource is stopped.

Reference note

You can check whether the optional name was registered or deleted through the message log.

When the optional name is registered: KDJE47602-I is output.

58

2. Naming Management

When the optional name is deleted: KDJE47603-I is output.

2.6.4 Searching from the client

This subsection describes how to search the Enterprise Beans or J2EE resources that are assigned optional names, from the client.

(1) Relation between the settings for the client source and the search destination object

This subsection describes the specification method in the client source and the settings in the search destination object when an Enterprise Bean or J2EE resource that is assigned an optional name is searched.

In the client source, you specify the optional name of the search destination object as the name to be looked up. In the search destination object, you use the annotation or property file to set up the corresponding optional name.

The following figure shows the relation between the coding of the source at the search source and the settings in the search destination object.

Figure 2

8: Relation between the settings for the client source and the search destination object

(2) Searching the Enterprise Beans

The following is an example of coding in the client when an optional name is used to search an Enterprise Bean. In this example, an EJB home object specifying an optional name "MyCart" is searched.

...

javax.naming.Context ctx = new javax.naming.InitialContext();

Object obj = ctx.lookup("MyCart");

SampleHome home =

(SampleHome)javax.rmi.PortableRemoteObject.narrow(obj, SampleHome.class);

Sample mybean = home.create(); // Generating a remote object

String name = mybean.ping(); //Executing the business method

...

The operations after acquiring the EJB home objects are similar to the operations for the EJB home objects acquired without using the optional names.

The following figure shows the procedure of lookup and acquisition of objects when you look up the EJB home object references.

59

2. Naming Management

Figure 2

9: Procedure of lookup and acquisition of objects for the EJB home object references

(3) Searching the J2EE resources

The following is an example of coding in the client when an optional name is used to search a J2EE resource. In this example, a J2EE resource specifying an optional name "jdbc/DBOpt" is searched.

Context initCtx = new InitialContext();

DataSource ds = (DataSource) initCtx.lookup("jdbc/DBOpt");

Note that the same operations are executed after acquiring the J2EE resource objects that are executed for the objects acquired without using the optional names.

!

Important note

You cannot search the J2EE resources from the EJB client applications. If you perform such a search, the exception javax.naming.NameNotFoundException

occurs.

2.6.5 Setting the optional names for the Enterprise Beans

This section describes how to set up an optional name for Enterprise Beans.

You can set up an optional name for the Enterprise Beans using the following methods:

Method of specifying the settings in cosminexus.xml

Method of specifying the settings in annotations

This subsection describes the respective methods.

Note that when you use this functionality, you must first specify whether you want to use the optional name, in usrconf.properties

of the server management commands. For details on the settings, see

2.6.7 Execution environment settings

.

(1) Method of specifying the settings in cosminexus.xml

To set up the optional name for an Enterprise Bean, you specify the settings in the <ejb-jar> tag of cosminexus.xml

. The following table describes the optional name settings for the Enterprise Beans in cosminexus.xml

.

60

2. Naming Management

Table 2

25: Setting the optional names for the Enterprise Beans in cosminexus.xml

Items Specified tags Settings

Remote interface

<session> - <optional-name>

tag

Local interface

<entity> - <optional-name>

tag

<session> - <local-optional-name>

tag

<entity> - <local-optional-name> tag

Specifies the optional name for the remote interface of the Session Bean.

Specifies the optional name for the remote interface of the Entity Bean.

Specifies the optional name for the local interface of the Session Bean.

Specifies the optional name for the local interface of the Entity Bean.

For details on the specified tags, see

2.2 Details of attributes specified in the Cosminexus application property file

(cosminexus.xml)

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

Reference note

You can also specify the optional name for the Enterprise Beans using annotations. If the optional name is specified using the annotations and if a different optional name is set up using the server management commands, the value set up with the server management commands becomes valid.

For details, see

(3) When an optional name is specified in both server management commands and annotations

.

(2) Method of specifying the settings in annotations

You specify the optional name in the mappedName

attribute of

@Stateless

,

@Stateful

, or

@Singleton

.

The following is an example of coding when the optional name is specified using annotations. In this example, the optional name

"MyFoo"

of the Stateless Session Bean is specified in the mappedName

attribute of

@Stateless

.

@Stateless(mappedName="MyFoo") public class FooEB implements FooIF {

...

} public interface FooIF {

...

}

The optional name specified in the mappedName

attribute of

@Stateless

,

@Stateful

, or

@Singleton

is set up in the <hitachi-session-bean-property><mapped-name> tag of the Session Bean property file.

(3) When an optional name is specified in both server management commands and annotations

If the optional name is specified by specifying the mappedName

attribute of

@Stateless

,

@Stateful

, or

@Singleton

, and if the optional name is specified in the

<optional-name>

tag or

<local-optionalname> tag in cosminexus.xml

, the specification in the <optional-name> tag and <local-optionalname>

tag becomes valid.

The following table lists the tags that become valid when the optional name is specified in both server management commands and annotations.

61

2. Naming Management

Table 2

26: Tags that become valid when the optional name is specified in both server management commands and annotations

Target for setting up the optional name

Only the mappedName attribute of

@Stateless,

@Stateful, or

@Singleton is specified

Only the <optional-name> tag or

<local-optional-name> tag is specified

When both mappedName attribute of

@Stateless, @Stateful, or @Singleton, and the <optional-name> tag or <localoptional-name> tag are specified

Remote interface

<mapped-name> tag

#

<optional-name> tag <optional-name> tag

Local interface

<mapped-name>

tag

#

<local-optional-name>

tag

<local-optional-name>

tag

#: The tag in which the value specified in the mappedName

attribute of

@Stateless

,

@Stateful

, or

@Singleton

is set up.

2.6.6 Setting the optional names for the J2EE resources

This subsection describes how to set an optional name for a J2EE resource.

You can set the optional name for a J2EE resource in cosminexus.xml

.

Note that when you use this functionality, you must first specify whether you want to use the optional name, in usrconf.properties

of the server management commands. For details about the settings, see

2.6.7 Execution environment settings

.

To set up the optional names for the J2EE resources, specify the settings in the <rar> tag of cosminexus.xml

.

The following table describes the optional name settings for the J2EE resources in cosminexus.xml

.

Table 2

27: Setting the optional names for the J2EE resources in cosminexus.xml

Items Specified tags Settings

Resource adapter <resource-external-property> -

<optional-name>

tag

Specifies the optional name for the resource adapter.

Note: You specify the optional name for the mail configuration and JavaBeans resources using the property files. For details on the settings, see

2.6.7 Execution environment settings

.

For details about the specified tags, see

2.2 Details of attributes specified in the Cosminexus application property file

(cosminexus.xml)

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

2.6.7 Execution environment settings

To use the user-specified name space functionality, you must customize the server management commands and set up the J2EE applications.

(1) Customizing the server management commands

You can customize the settings for operating the server management commands. This subsection describes the settings for the user-specified name space functionality used by the server management commands.

You customize the server management commands using usrconf.properties

(system property file for the server management commands). The following table describes the settings.

Table 2

28: Customizing the server management commands for using the user-specified name space functionality

Items Specified keys Settings

Assigning the optional names to the EJB home ejbserver.cui.optionalname.enabled

Specifies whether to set up the optional names for the EJB home objects.

62

2. Naming Management

Items Specified keys Settings object references (Userspecified name space functionality)

Assigning the optional names to the J2EE resources (User-specified name space functionality) ejbserver.cui.optionalname.enabled

ejbserver.cui.optionalname.enabled

Also, for assigning an optional name to an

EJB home object, in addition to specifying this key, you must also specify the optional name

#

for the EJB home object.

Specifies whether to set up the optional names for the J2EE resources.

Also, for assigning an optional name to a

J2EE resource, in addition to specifying this key, you must also specify the optional name

#

for the J2EE resource.

#: You specify an optional name, when you define the J2EE application properties by using the server management commands. For details about referencing and changing the name registered in the JNDI name space, see

9.13 Referencing and changing the names registered in the JNDI name space

in the

uCosminexus Application Server Application Setup Guide

.

(2) Setting up the J2EE applications

You implement the J2EE application settings in the execution environment using the server management commands and property files. This subsection describes the settings for specifying the optional name for the Enterprise Beans and

J2EE resources separately. Note that the tags described here correspond to cosminexus.xml

. For details about the

definitions in cosminexus.xml, see

2.6.5 Setting the optional names for the Enterprise Beans

or

2.6.6 Setting the optional names for the J2EE resources

.

(a) Setting the optional names for the Enterprise Beans

To set up an optional name for an Enterprise Bean, use the Session Bean property file or Entity Bean property file.

The tag names differ depending on the interface type. The property files and tags used for each interface type are as follows:

Optional name for the remote interface

You specify the optional name in the Session Bean property file for the Session Bean and in the

<optionalname>

tag of the Entity Bean property file for the Entity Bean.

Optional name for the local interface

You specify the optional name in the Session Bean property file for the Session Bean and in the <localoptional-name>

tag of the Entity Bean property file for the Entity Bean.

An example of specification of an optional name in a property file is as follows. In this example, the SessionBean property file is used to set up an optional name for the Stateful Session Beans.

<hitachi-session-bean-property>

<display-name>MyAdder</display-name>

<session-type>Stateful</session-type>

<transaction-type>Container</transaction-type>

<runtime>

<lookup-name>MyAdder</lookup-name>

<optional-name>user/Adder</optional-name>

<local-optional-name>user/localAdder</local-optional-name>

<maximum-sessions>0</maximum-sessions>

<stateful>

<maximum-active-sessions>0</maximum-active-sessions>

<inactivity-timeout>0</inactivity-timeout>

<removal-timeout>0</removal-timeout>

In this example,

"user/Adder"

is set as the optional name for the remote interface and

"user/localAdder"

is set up as the optional name for the local interface.

(b) Setting the optional names for the J2EE resources

To set up an optional name for a J2EE resource, specify the name as an attribute of the DB Connector, mail configuration, or JavaBeans resource. The commands and property files used in the settings differ for each resource type. The following table lists the resource types and the commands and property files for setting the optional names.

63

2. Naming Management

Table 2

29: Resource types and the commands and property files for setting the optional names

Types of resource adapters

Commands Property file Specified tags

Resource adapter

Mail configuration cjsetrarprop command cjsetresprop command cjsetjbprop

command

Connector property file

Mail property file

<resource-external-property>

- <optional-name> tag

JavaBeans resource JavaBeans resource property file

<resource-env-externalproperty> - <optional-name> tag

Note: You cannot set up the optional names for the mail configuration and JavaBeans resources in cosminexus.xml

. You specify the optional name in a property file.

The following is an example of specification of an optional name in a property file. In this example, the Connector property file is used to set up the optional name for the resource adapters.

<hitachi-connector-property>

<description></description>

<display-name>DB_Connector_for_Oracle</display-name>

<icon />

<vendor-name>Hitachi, Ltd.</vendor-name>

:

<connector-runtime>

<resource-external-property>

<description></description>

<optional-name>jdbc/TestDB1</optional-name>

<res-auth>Container</res-auth>

<res-sharing-scope>Shareable</res-sharing-scope>

</resource-external-property>

</connector-runtime>

</hitachi-connector-property>

In this example, "jdbc/TestDB1" is set as the optional name for DB Connector.

2.6.8 Precautions for using the user-specified name space functionality

This subsection describes the precautions for using the user-specified name space functionality.

(1) Notes on executing a search using an optional name

An Enterprise Bean with a local interface cannot be searched from outside the J2EE application.

The optional name of the Enterprise Bean with a local interface cannot be searched for the naming contexts.

You can set up the same optional name for the Enterprise Bean with a remote interface and the Enterprise Bean with a local interface. However, if you look up the optional name that is duplicated in such a case, the Enterprise

Bean with a local interface will necessarily be looked up.

(2) Notes on the naming service

When one CORBA Naming Service is shared by multiple J2EE servers, you cannot use the user-specified name space functionality.

Specify settings so that the J2EE server and the CORBA Naming Service start and stop at the same time.

If either the J2EE server or the CORBA Naming Service is down, restart the J2EE server and the CORBA Naming

Service together.

If the CORBA Naming Service is shared, you cannot use 'Cosminexus' as the optional name to be set up in the user-specified name space functionality.

64

2. Naming Management

(3) Notes on specifying the optional names for the J2EE resources

When you stop, delete, or change the attributes (for a JavaMail session) of the J2EE resource for which the optional name is registered, first stop all the J2EE applications running on the J2EE server.

When using the user-specified name space functionality of a J2EE resource, specify the same string as the host name of the provider URL ( java.naming.provider.url

), specified in

InitialContext

generated by the J2EE application and the value of the ejbserver.naming.host

key specified in the J2EE server definition. Note that if this condition holds true, you need not specify the provider URL for InitialContext that is generated by the J2EE application.

Specify localhost

(default value) in the ejbserver.naming.host

key of the user property file for

J2EE servers.

Connect to the naming service on the same J2EE server.

If localhost

is specified in the ejbserver.naming.host

key, and if you want to specify the provider

URL for

InitialContext

generated by the J2EE application, specify the value that can be acquired using the following API in the host name of the provider URL: java.net.InetAddress.getLocalHost().getHostName();

Even if the optional name in the user-specified name space functionality of a J2EE resource contains a forward slash (/), you cannot perform a naming context search. Only the specified optional name can be used as the lookup name.

The examples of JNDI lookup names that can and cannot be used for the J2EE resources (DB Connector) that are deployed and started with "jdbc/TestDB" assigned as an optional name are as follows:

Example of a lookup name that can be used

DataSource ds = (DataSource) initCtx.lookup("jdbc/TestDB");

Example of a lookup name that cannot be used

Context ctx = (Context) initCtx.lookup("jdbc");

65

2. Naming Management

2.7 Searching the CORBA Naming Service by using the round-robin policy

You can look up the EJB home objects or business interface references with the same names (optional name) registered in multiple CORBA Naming Services by following the round-robin policy. This is called the

round-robin search

.

When you perform a round-robin search for the EJB home objects or business interface references using the relevant names from the JNDI name space, the client application can acquire the EJB home objects or business interface references selected by the round-robin policy from the EJB home objects or business interface references that exist in multiple CORBA Naming Services. As a result, you can distribute the load out by starting the J2EE server in a cluster configuration. Furthermore, you can invoke the Enterprise Beans of the J2EE server from the EJB client regardless of the cluster configuration.

The following table describes the organization of this section.

Table 2

30: Organization of this section (Searching the CORBA Naming Service by using the round-robin policy)

Category

Explanation

Settings

Notes

Title

Scope of round-robin search

Operations when performing a round-robin search

Settings required for performing a round-robin search

Settings recommended for using the round-robin search functionality

Notes on performing a round-robin search

2.7.1

2.7.2

2.7.3

2.7.4

2.7.5

Reference location

Note: The function-specific explanation is not available for "Implementation" and "Operations".

Tip

Note that to perform a round-robin search, the EJB home objects or business interface references to be searched must be registered with the same names in the CORBA Naming Service. Therefore, use the user-specified name space functionality to specify the same names for the EJB home objects or business interface references.

2.7.1 Scope of round-robin search

The scope of round-robin search using the JNDI includes groups within a

logical naming service

.

The logical naming service is made up of one or more groups. Each group contains one or more CORBA Naming

Services. The following figure shows the configuration of a logical naming service.

66

Figure 2

10: Configuration of a logical naming service

2. Naming Management

You can specify the same CORBA Naming Service for the group members in multiple groups.

2.7.2 Operations when performing a round-robin search

The following figure shows the operations in a round-robin search when performed from a client program.

You assume that the EJB home object to be searched using the round-robin search is registered with the name

"MyBean" in each of the CORBA Naming Services shown in the figure. The same name is set up using the userspecified name space functionality in the multiple EJB home objects to be searched.

Figure 2

11: Operations during the round-robin search

The following is a description of the figure:

67

2. Naming Management

1. The client application uses the group name of the logical naming services to be searched, as an argument, and generates the

InitialContext

instance for round robin.

2. The client application specifies the name

"My Bean"

and requests a search to the generated

InitialContext

instance for round robin.

3. The round-robin Search functionality uses the round-robin policy to determine the search destination of the

CORBA Naming Services belonging to the group to be searched.

4. If the search is successful, the result is returned to the client application.

Note that if the search fails, another CORBA Naming Service belonging to that group is searched.

5. The client application accesses the searched EJB home objects.

!

Important note

When

InitialContext

is issued for the first time, an attempt is made to connect to the provider URLs of all the groups. Therefore, if a non-connectable provider URL is mentioned, the processing might be delayed.

2.7.3 Settings required for performing a round-robin search

This subsection describes the settings required for performing a round-robin search and the naming rules of the group names.

The following settings are required when performing a round-robin search:

Logical naming service group for which the round-robin search will be performed

Root position of the CORBA Naming Services that belong to each group

Class to which the implementation of

InitialContextFactory

is delegated

To use the round-robin search functionality, you specify the settings in the system properties. Note that in addition to the system property settings, you can also specify the classes to which the implementation of

InitialContextFactory

is delegated, as arguments when generating

InitialContext

of each application.

In the arguments used for generating InitialContext , you can select and specify a specific naming service from the group of logical naming services specified in the system properties.

Note that when the settings are only specified in the system properties, you cannot perform a round-robin search specifying a specific group. The naming services of all the groups existing on the logical naming service are included in the scope of search.

The following is an overview of each setting method:

(1) Identifying the groups from the system property settings and the root position of the

CORBA Naming Service belonging to that group

When executing the round-robin search, you specify the group of logical naming services to be searched by a roundrobin search and the root position of the naming services belonging to the group, in the system properties. Also, you must specify java.naming.factory.initial=com.hitachi.software.ejb.jndi.GroupContextFactory

as the class to which the implementation of InitialContextFactory is delegated.

The method of setting up the system properties differs at the following locations for the various types of applications that use the round-robin search functionality.

(2) For the J2EE applications (Enterprise Beans or servlets) running on the J2EE server

You customize and set up the J2EE server properties. Specify the settings in the user properties for J2EE servers in the

Easy Setup definition file.

You specify the definition for the round-robin search in the

<configuration>

tag of the logical J2EE server

( j2ee-server

) in the Easy Setup definition file. The following table describes the definitions for performing a round-robin search in the Easy Setup definition file.

68

2. Naming Management

Table 2

31: Definition for performing a round-robin search in the Easy Setup definition file

Specified parameters Settings ejbserver.jndi.namingservice.group.list

ejbserver.jndi.namingservice.group.

Specify-groupname

.providerurls

java.naming.factory.initial

Specify the CORBA Naming Service group.

Specify the root position of the CORBA Naming Services belonging to each group.

Specify the class to which the implementation of

InitialContextFactory is delegated.

Note that the round-robin search presumes the use of the user-specified name space functionality. When you use the user-specified name space functionality, you need to customize the settings for operating the server management

commands and define the J2EE application properties. For details on the settings, see

2.6.7 Execution environment settings

and

2.6.5 Setting the optional names for the Enterprise Beans

.

(3) For the EJB client applications running on servers other than the J2EE server

You use one of the following methods to specify the settings:

Specify the settings as properties when starting the EJB client application.

Specify the settings in the application by using the

System.setProperty

method.

Note that the method of setting the EJB client application properties differs depending on the commands used for starting the EJB client application. This subsection describes how to set the EJB client application properties and the examples of specification.

(a) Methods of setting the EJB client application properties

The method of setting the properties differs when the cjclstartap

command is used and when the vbj

command is used.

• For the cjclstartap command

When the cjclstartap command is used, you set the properties in the EJB client application properties file

( usrconf.properties

). For properties that can be specified, see

(2) For the J2EE applications (Enterprise

Beans or servlets) running on the J2EE server

.

• For the vbj command

When the vbj command is used, you set the properties in the batch file/ shell script file, or in the command arguments.

(b) Example of specifying the properties

An example of specification is as follows. This is an example of specifying the properties in usrconf.properties

. For details on each key, see

14.3 usrconf.properties (User property file for Java applications)

in the

uCosminexus Application Server Definition Reference Guide

.

# Define the logical naming service configuration ejbserver.jndi.namingservice.group.list=g1;g2;g3 ejbserver.jndi.namingservice.group.g1.providerurls=corbaname::hostA:900;corbaname::hostB:900 ejbserver.jndi.namingservice.group.g2.providerurls=corbaname::hostD:700;corbaname::hostE:700 ejbserver.jndi.namingservice.group.g3.providerurls=corbaname::hostF:800;corbaname::hostG:800

# Specify the class to which the implementation of InitialContextFactory is delegated java.naming.factory.initial=com.hitachi.software.ejb.jndi.GroupContextFactory

:

The following contents are specified in the ejbserver.jndi.namingservice.group.list

key, ejbserver.jndi.namingservice.group.

Specify-group-name

.providerurls

key, and java.naming.factory.initial

key respectively in the example of specification: ejbserver.jndi.namingservice.group.list

key

When performing a round-robin search, define the group of the logical naming services that is to be searched.

Specify each group name so that it can be uniquely identified in logical naming.

69

2. Naming Management ejbserver.jndi.namingservice.group.

Specify-group-name

.providerurls

key

You specify the root position of the naming service belonging to each group in the provider URL. In

Specifygroup-name

, you specify the group name specified in ejbserver.jndi.namingservice.group.list

.

java.naming.factory.initial

key

You specify the class to which the implementation of

InitialContextFactory

is delegated.

If you specify com.hitachi.software.ejb.jndi.GroupContextFactory

in the java.naming.factory.initial

key, a round-robin search is implemented. If you do not specify com.hitachi.software.ejb.jndi.GroupContextFactory

in the java.naming.factory.initial

key, the CORBA Naming Service used by the J2EE server is searched.

Note that if you specify the java.naming.factory.initial

key as an argument when generating

InitialContext in the method described in

(4) Selecting the group to be searched based on the argument specified for generating InitialContext

, you need not specify a value for this key in the system properties.

(4) Selecting the group to be searched based on the argument specified for generating

InitialContext

When settings are specified for executing a round-robin search, you can select a specific group to be looked up in the round-robin search targets by specifying the group as an argument for generating

InitialContext

in the client application. Note that the specification of an argument for generating

InitialContext

is optional.

An example of specification is as follows:

:

Hashtable env = new Hashtable(); env.put("ejbserver.jndi.namingservice.groupname", "g1"); env.put("java.naming.factory.initial",

"com.hitachi.software.ejb.jndi.GroupContextFactory");

InitialContext ic = new InitialContext(env);

:

The following contents are specified in the ejbserver.jndi.namingservice.groupname

key and the java.naming.factory.initial

key respectively in the example of specification: ejbserver.jndi.namingservice.groupname

key

You specify the group name to be searched in the '

gl

' portion. Specify the group name that is already defined in system properties ( ejbserver.jndi.namingservice.group.list

key of usrconf.properties

).

Note that ejbserver.jndi.namingservice.groupname

key does not have a default value. When you do not specify a group name, all the groups set in the system properties are searched.

java.naming.factory.initial

key

You specify the class to which the implementation of

InitialContextFactory

is delegated. If you specify com.hitachi.software.ejb.jndi.GroupContextFactory

in the java.naming.factory.initial

key, a round-robin search is implemented. When you omit the specification in the java.naming.factory.initial

key of the system properties and if you do not specify this key in the argument, the group specified in the ejbserver.jndi.namingservice.groupname

key is not searched and the CORBA Naming Service used by the J2EE server is searched.

(5) Naming rules for the group names

You can use the following characters in a group name:

Alphanumeric characters (A-Z, a-z, 0-9)

Underscore (_)

Make sure to specify a group name that is unique in the logical naming service.

70

2. Naming Management

(6) Settings in the properties

The EJB client application properties are used when the Enterprise Beans are invoked from the Java application. Set the required properties according to the contents of the J2EE application. For details on the properties that can be set, see the

uCosminexus Application Server Definition Reference Guide

.

Example of contents that can be set in the properties

• Log settings for the EJB client applications

You use the keys beginning with ejbserver.client.log

and the keys beginning with ejbserver.logger

to change the output destination and the log level of the system log output by the system and the user log output by the EJB client applications. For details on the system log, see

3.8 System log output by the EJB client applications

in the

uCosminexus Application Server EJB Container Functionality

Guide

, and for details on the user log, see

9. User log output by the applications

in the

uCosminexus

Application Server Expansion Guide

.

• Transactions settings for the EJB client applications

You use the keys beginning with ejbserver.client.transaction

to specify whether to use transactions with the EJB client applications and to specify the client name to be used by the transaction service. Note that when you use uCosminexus Client to set up the EJB client environment, you cannot use the

EJB client application transactions. For details, see

3.20 Notes on starting a transaction with the EJB client applications

.

• EJB client operations in the case of communication error in the EJB remote interface

In the ejbserver.container.rebindpolicy

key, you can specify the re-connect operation for the connections and the re-send operation for the requests in the EJB client.

• Settings for executing the round-robin search from the EJB client applications

In the ejbserver.jndi.namingservice.group.list

key, ejbserver.jndi.namingservice.group.

specify-group-name

.providerurls

key, and java.naming.factory.initial

key, you can specify the CORBA Naming Service group, the root position of the CORBA Naming Service belonging to each group, and the class to which the implementation of InitialContextFactory is delegated. Note that the round-robin search is enabled when you specify the user-specified name space functionality during the customization of the server management commands for the J2EE server.

• Setting the priority of requests from the EJB client applications to the CTM

In the ejbserver.client.ctm.RequestPriority

key, you can set the priority for the requests to be sent from the EJB client applications to the CTM.

(7) Properties with different specification requirements depending on the commands (for the

EJB client applications)

This subsection describes the properties with different specification requirements depending on the EJB client application commands ( vbj command). The following table lists the property keys with different specification requirements depending on the EJB client application commands.

Table 2

32: Property keys with different specification requirements depending on the EJB client application commands

Property keys Type cjclstartap

Commands vbj org.omg.CORBA.ORBClass

org.omg.CORBA.ORBSingletonClass

javax.rmi.CORBA.UtilClass

javax.rmi.CORBA.StubClass

javax.rmi.CORBA.PortableRemoteObjectClass

java.endorsed.dirs

Fixed

Fixed

Fixed

Fixed

Fixed

Variable

N

N

N

N

N

N

Y

N

N

N

Y

N

71

2. Naming Management

Legend:

Fixed: Value for the applicable key is fixed and must be specified

Variable: Value must be specified according to the system execution environment

Y: Key must be specified for the command

N: Key need not be specified for the command

2.7.4 Settings recommended for using the round-robin search functionality

When you use the round-robin search functionality, we recommend that you also use the naming service error detection functionality.

For the example of settings when the round-robin search functionality is combined with the naming service error

detection functionality, see

2.9.4 Execution environment settings (When the error detection functionality is used)

.

2.7.5 Notes on performing a round-robin search

This subsection describes the notes on performing a round-robin search.

The context acquired for a round-robin search only supports the lookup method. You cannot use the other APIs defined in javax.naming.Context

.

If you execute a round-robin search using an optional name, the Enterprise Beans are searched in the following order:

1. An Enterprise Bean with a local interface is searched from the name space of the J2EE server executing the search.

2. If the Enterprise Bean is not found in 1, an Enterprise Bean with a remote interface is searched by the roundrobin search.

The following table describes whether the Enterprise Beans can be searched for each class to which the processing of

InitialContextFactory

is delegated.

Table 2

33: Searchability of the Enterprise Beans for each class to which the processing of

InitialContextFactory is delegated

Search target InsContextFactory

Enterprise Bean with a remote interface

Enterprise Bean with a remote interface

(search by optional name)

GroupContextFactory

Y

#

Y

Y

Y

Enterprise Bean with a local interface

Enterprise Bean with a local interface

(search by optional name)

Y

#

Y

Y

Y

J2EE resource

J2EE resource

(search by optional name)

Y

#

N

Y

Y

Legend:

Y: Can be searched

N: Cannot be searched

# When you perform a lookup in java:comp/env , the round-robin search is not executed. java:comp/env is searched only from the J2EE server executing the lookup.

You use the following methods to specify the class to which the implementation of

InitialContextFactory

will be delegated. If both the methods are specified, the method specified in the argument is enabled.

72

2. Naming Management

Specify the class in the java.naming.factory.initial

key of usrconf.properties

.

Specify the class in the java.naming.factory.initial

key with the argument ( Hashtable ) used when

InitialContext

is generated.

73

2. Naming Management

2.8 Caching with the naming management functionality

The naming management functionality of the J2EE services has a caching functionality. The caching functionality is a functionality whereby when you search an EJB home object reference through the JNDI, the relevant object is temporarily stored in the cache and returned in the subsequent searches for the same object.

This section describes the procedure of caching and the clearing of the cache area.

You specify the settings for caching with the naming management functionality as a property of the J2EE server or

EJB client application.

The following table describes the organization of this section.

Table 2

34: Organization of this section (Caching with the naming management functionality)

Category Title Reference location

Explanation Procedure of caching

Clearing the cache used in naming

Settings

Notes

Settings for using the caching functionality

Notes on caching in naming

Note: The function-specific explanation is not available for "Implementation" and "Operations".

2.8.1

2.8.2

2.8.3

2.8.4

2.8.1 Procedure of caching

The following figure shows the procedure by which the naming is cached.

Figure 2

12: Procedure of caching in naming

74

The following is a description of the caching procedure. In this procedure, the EJB home object references with the same name 'Count' are looked up from two J2EE applications on the same J2EE server. The points 1 through 5 indicate processing executed from the J2EE application 1 and points 6 through 9 indicate processing executed from the J2EE application 2.

1. J2EE application 1 generates an instance of the JNDI javax.naming.InitialContext

class.

2. J2EE application 1 requests a search (lookup) of the EJB home object references for the instance of the javax.naming.InitialContext

class. At this time, 'Count' is specified in the name.

2. Naming Management

3. The naming management functionality that receives the request searches the EJB home object references from the name space of the CORBA Naming Service.

4. The naming management functionality obtains the EJB home object references as the search results.

5. The naming management functionality stores the obtained EJB home object references in the cache.

6. J2EE application 2 existing on the same process generates the instance of the JNDI javax.naming.InitialContext

class.

7. J2EE application 2 requests a search (lookup) of the EJB home object references for the instance of the javax.naming.InitialContext

class. At this time, the same name 'Count' as that in 2 is specified as the name.

8. The naming management functionality that receives the request searches the EJB home object references from the cache.

9. The naming management functionality obtains the EJB home object references from cache as the search results.

2.8.2 Clearing the Cache Used in Naming

You can clear the cache used in naming. However, you cannot specify the size of the cache to be cleared. This subsection describes when the cache is cleared and the range that is cleared.

(1) Timing for clearing the cache

The contents of the cache are cleared at one of the following timings:

If an exception occurs in the JNDI and RMI-IIOP APIs, the cache is forcefully cleared.

The cache is cleared at the interval specified in the system properties (by default, the value is 0 seconds and the cache is not cleared).

(2) Cache-clearing range

This subsection describes the range in which the cache is cleared in a naming service.

The cache-clearing range is as follows:

1. Clearing the complete cache area.

2. Clearing only the invalid cache area.

In the first case, the complete cache area is cleared. On the other hand, in the second case, the objects stored in the cache are periodically checked for validity and only the invalid objects are cleared from the cache. Furthermore, in the second case, when the cache is cleared, the status of the CORBA Naming Services that have been searched once is also monitored. As a result, a CORBA Naming Service that has been searched once is not included in the search if the

CORBA Naming Service is down. If you restart the CORBA Naming Service, the search of that CORBA Naming

Service starts automatically.

For details on how to specify the settings for clearing the cache, see

2.8.3 Settings for using the caching functionality

.

Also, if you want to use the error detection functionality, see

2.9.4 Execution environment settings (When the Error

Detection functionality is used)

.

Reference note

When the re-connect functionality of the EJB home object is used, the cache does not become invalid even after the J2EE server is restarted.

Therefore, even if you specify settings to clear only the invalid cache area, the object references of the EJB home objects for the CORBA Naming Service are not deleted from the cache area.

The object references that are not deleted from the cache can be used as are to search (lookup) the EJB home object references.

75

2. Naming Management

2.8.3 Settings for using the caching functionality

This subsection describes the settings for using the caching functionality. The locations for the settings differ in the

J2EE applications and in the EJB client applications.

(1) When the caching functionality is used in the J2EE applications

You specify the definition for using the caching functionality in the J2EE applications in the <configuration> tag of the logical J2EE server ( j2ee-server

) in the Easy Setup definition file. The following table describes the definitions for using the caching functionality specified in the Easy Setup definition file.

Table 2

35: Definitions for using the caching functionality

Specified parameters Settings ejbserver.jndi.cache

ejbserver.jndi.cache.interval

ejbserver.jndi.cache.interval.clear.option

Specify whether to enable caching in naming.

Specify the interval (unit: seconds) for clearing the cache when caching is performed in naming.

Determine the operations (cache-clearing range) for the cache area in naming after the lapse of the interval.

The following is an example of settings when the cache is cleared periodically (when the physical tier is defined).

Example:

<configuration>

<logical-server-type>j2ee-server</logical-server-type>

<param>

<param-name>ejbserver.jndi.cache</param-name>

<param-value>on</param-value>

</param>

<param>

<param-name>ejbserver.jndi.cache.interval</param-name>

<param-value>60</param-value>

</param>

<param>

<param-name>ejbserver.jndi.cache.interval.clear.option</param-name>

<param-value>check</param-value>

</param>

...

</configuration>

(2) When the caching functionality is used in the EJB client applications

You specify the settings as properties when the EJB client application starts.

The method of setting the EJB client application properties differs depending on the commands used for starting the

EJB client application.

• For the cjclstartap command

When the cjclstartap

command is used, you set up the properties in the properties file for the EJB client applications ( usrconf.properties

).

• For the vbj command

When the vbj

command is used, you set up the properties in the batch file/ shell script file, or the command arguments.

The following is an example of settings when the cache is cleared periodically.

Example of system property settings for an EJB client

...

# Cache settings ejbserver.jndi.cache=on ejbserver.jndi.cache.interval=60 ejbserver.jndi.cache.interval.clear.option=check

76

2. Naming Management

2.8.4 Notes on caching in naming

This sub-section describes the notes related to caching of naming.

We recommend that you disable the caching in naming when the EJB home object references and the JDBC data source are cached in the application.

To clear the cache periodically, specify the settings in the Easy Setup definition file. Specify the following parameters in the

<configuration>

tag of the logical J2EE server ( j2ee-server

): ejbserver.jndi.cache.interval.clear.option

Specifies the range for clearing the cache.

ejbserver.jndi.cache

Specifies whether to execute the cache. Specify 'ON'.

ejbserver.jndi.cache.interval

Specifies the cache-clearing interval.

If check

is set in the property ejbserver.jndi.cache.interval.clear.option

in the

<configuration>

tag of the logical J2EE server ( j2ee-server

), the CORBA Naming Service is monitored only at the cache-clearing time specified in the property ejbserver.jndi.cache.interval

.

After the CORBA Naming Service restarts, the value specified in the property ejbserver.jndi.cache.interval

is the maximum time required for detecting the recovery of the

CORBA Naming Service.

When you use the caching functionality, if the J2EE server that holds the EJB home objects is down or if the J2EE application is redeployed when the cache contains stored EJB home object references, the object references of the

EJB home object stored in the cache become invalid. In this condition, if a search request (lookup) for an EJB home object is received, the invalid object references in the cache are returned to the requester. If methods such as the javax.rmi.PortableRemoteObject.narrow() or create methods are executed for such object references, a CORBA exception (such as org.omg.CORBA.OBJECT_NOT_EXIST

) might occur. Note that when a CORBA exception occurs, all the cache information is deleted. In the next search request (lookup), valid information is obtained by connecting to the CORBA Naming Service.

When the CTM is used and if only the invalid cache area is cleared at the specified interval, the object references of the EJB home object in the global CORBA Naming Service are not cleared from the cache area even if the

J2EE server and J2EE application are stopped. If a search request (lookup) for the EJB home objects is received, the un-cleared object references on the cache return to the requester. If the J2EE application is restarted, the cached object references can be used as are. If the J2EE application is not restarted and if you execute a method such as the create

method for the returned object references, a CORBA exception

( org.omg.CORBA.NO_IMPLEMENT

) occurs.

Note that if a CORBA exception occurs, all the cache information is deleted. If the J2EE application is restarted, valid information is obtained by connecting to the global CORBA Naming Service in the next search request

(lookup).

If the J2EE server is restarted by setting the ejbserver.jndi.cache

property to "on" while a business interface is being used, a javax.ejb.EJBException

might occur when a business method is executed.

Note that if a javax.ejb.EJBException

occurs, valid information will be acquired by connecting to a

CORBA naming service the next time a lookup request is made.

77

2. Naming Management

2.9 Detecting errors in a naming service

You use the error detection of naming services as an option of the caching functionality.

If you use the naming service error detection functionality, the EJB client can detect errors faster when an error occurs in the naming service.

This section provides an overview of the naming service error detection functionality and describes the functionality recommended for concurrent use with the naming service error detection functionality.

The following table describes the organization of this section.

Table 2

36: Organization of this section (Naming management error detection)

Category Title Reference location

Explanation What is the naming management error detection functionality

Concurrent use of the round-robin search functionality

Behavior of the naming service error detection functionality

Settings

Notes

Execution environment settings (when the Error Detection functionality is used)

Notes on the naming service error detection functionality

Note: The function-specific explanation is not available for "Implementation" and "Operations".

2.9.1

2.9.2

2.9.3

2.9.4

2.9.5

2.9.1 What is the naming service error detection functionality

If you use the naming service error detection functionality, the J2EE server detects the error when the naming service stops or if machine error or network error occurs on Application Server.

In the Naming Service Error Detection functionality, the J2EE server monitors the status of the Naming Service functionality and can control the use of the Naming Service functionality that can no longer communicate. Therefore, the EJB client need not perform unnecessary communication.

The following figure shows the flow of processing when you use the naming service error detection functionality.

78

2. Naming Management

Figure 2

13: Flow of processing when the naming service error detection functionality is used

If the naming service error detection functionality is not used, the communication is necessarily performed with the naming service when a name is looked up. Therefore, a lot of time might be taken until an error occurs due to inability to communicate with the naming service. On the other hand, if you use the naming service error detection functionality, communication does not take place with the naming service where the error occurs and the error can be detected. Therefore, this does not take a long time.

2.9.2 Concurrent use of the round-robin search functionality

If you use the round-robin search functionality and the naming service error detection functionality concurrently, when an error occurs on one node, the failed node can be easily separated.

The following figure shows the communication when the round-robin search functionality and the naming service error detection functionality are used concurrently.

79

2. Naming Management

Figure 2

14: Communication when the round-robin search functionality and the naming service error detection functionality are used concurrently

If an error is detected in a specific naming service when a name is looked up, the round-robin search functionality switches the communication to a naming service with which communication is possible.

2.9.3 Behavior of the naming service error detection functionality

This section describes the behavior of the naming service error detection functionality.

(1) Lock timing

During naming service error detection, the status of the naming service is checked at the following times and if there is no response, the naming service is locked:

1. When there is no response until the lapse of the sweep interval

2. When there is no response from the naming service when the following operations are first executed after the entire cache area is cleared with the RMI/IIOP communication error as the trigger, and if the cache does not exist:

When InitialContext is generated

When lookup is executed

The following table describes the behavior of the operations for the naming service after the entire cache is cleared.

Table 2

37: Behavior of the operations for the naming service after the entire cache is cleared

Operations in the naming management functionality

When a round-robin search is used When a round-robin search is not used

When

InitialContext

is generated The viability is checked and if the response from the naming service cannot be detected, the naming service is locked.

When lookup is executed

When

InitialContext

is generated for the first time after the EJB client process starts, if there is no response to the confirmation of the naming service operations, the naming service is locked.

The naming service is not locked in cases other than the first time.

Status is checked only for the naming service that attempts to communicate when lookup is issued.

If a response cannot be detected, the naming service is locked. For example, if a round-robin search is being executed in

The viability is checked and if the response from the naming service cannot be detected, the naming service is locked.

80

2. Naming Management

Operations in the naming management functionality

When a round-robin search is used When a round-robin search is not used

When lookup is executed three naming services, the failed naming service is locked at the third lookup at the most.

The viability is checked and if the response from the naming service cannot be detected, the naming service is locked.

In the naming service error detection functionality, when the naming service is locked, the KDJE47111-I message is output to the log at the same time. After the message is output, all the communication with the running naming service functionality is controlled and javax.naming.NamingException

is thrown.

(2) Behavior when the naming service is locked

This point describes the behavior of the naming service when the EJB client generates

InitialContext

or performs lookup for a naming service locked by the naming service error detection functionality.

The following table describes the operations for the locked naming service separately for the cases when the roundrobin search functionality is used and when the functionality is not used.

Table 2

38: Operations for a locked naming service

Operations from the EJB client When a round-robin search is used When a round-robin search is not used

When InitialContext is generated InitialContext for the round robin is returned.

When lookup is executed The object is searched from another naming service registered in the round robin group and returned.

Communication is always controlled.

javax.naming.NamingException

is returned to the EJB client.

Communication is always controlled.

javax.naming.NamingException

is returned to the EJB client.

(3) Timing for unlocking the naming service

This point describes the unlock timing. The status of the naming service is checked at the following time and when a response can be detected from the naming service, the lock is released.

When the sweep interval lapses

When the naming service is unlocked, the KDJE47110-I message is output to the log at the same time. After the message is output, the communication for the running naming service is not controlled.

2.9.4 Execution environment settings (When the Error Detection functionality is used)

The naming service error detection functionality is an option of the caching functionality. Therefore, the caching functionality is presumed to be set. For details on the settings for the caching functionality of the naming service, see

2.8.3 Settings for using the caching functionality

.

To use the naming service error detection functionality, specify the values listed in the following table.

Table 2

39: Settings for using the naming service error detection functionality

Specified parameters Value ejbserver.jndi.cache

ejbserver.jndi.cache.interval

ejbserver.jndi.cache.interval.clear.option

on

1

to

2,147,483,647 check

The following is an example of the system properties settings for an EJB client. In this example, the settings are specified in usrconf.properties

. Furthermore, in this example, the round-robin search functionality is also set concurrently.

81

2. Naming Management

Example of the system property settings for an EJB client

...

# Cache settings ejbserver.jndi.cache=on ejbserver.jndi.cache.interval=60 ejbserver.jndi.cache.interval.clear.option=check

# Define the logical naming service configuration ejbserver.jndi.namingservice.group.list=g1;g2;g3 ejbserver.jndi.namingservice.group.g1.providerurls= corbaname::hostA:900;corbaname::hostB:

900;corbaname::hostC:900 ejbserver.jndi.namingservice.group.g2.providerurls=

corbaname::hostD:700;corbaname::hostE:700 ejbserver.jndi.namingservice.group.g3.providerurls=

corbaname::hostF:800;corbaname::hostG:800;corbaname::hostH:800

...

2.9.5 Notes on the naming service error detection functionality

This subsection describes the notes on the naming service error detection functionality.

(1) Unlock timing

When the naming service error detection functionality is not used, the failed naming service is successfully searched from the client application immediately after the naming service and J2EE server are restarted.

However, when the naming service error detection functionality is used, the lock can only be released at the sweep interval. In the naming management functionality, if the sweep interval does not lapse after the naming service stops, the connection is not established to the actual naming service. In other words, maximum sweep interval time is necessary after the recovery of the naming service functionality until the search is successful. When the naming service error detection functionality is used, we recommend that you specify a short time (recommended value 60) in the sweep interval setup time (value of the ejbserver.jndi.cache.interval

property).

(2) Differences in behavior until 07-60

In Application Server versions until 07-60 and in version 08-00 and later, the lock timing is different. In version 08-00 and later, in addition to the sweep interval lapse timing, the operating status is checked when the naming service is searched from the client application.

(3) Checking the viability of the naming management functionality

When the naming service error detection functionality is used to check the operating status, the naming service might be considered to have stopped when there is a temporary network error and there is no response due to a high load on the server and during a full garbage collection.

82

2. Naming Management

2.10 Switching the CORBA Naming Services

With the naming management functionality, you can switch the CORBA Naming Services connected by JNDI when you search distributed objects through JNDI. You can switch the CORBA Naming Services by passing the name with the prefix corbaname:

to the argument of the lookup method for the instance of the

InitialContext

class.

The following figure shows the procedure of switching the CORBA Naming Services.

Figure 2

15: Procedure of switching the CORBA Naming Services

The description of the switching procedure of the naming service is as follows. In this procedure, a lookup specifying the prefix corbaname:

is executed twice from the J2EE application. The connected CORBA Naming Service is switched according to the host name specified after the prefix.

1. The J2EE application generates an instance of the JNDI javax.naming.InitialContext

class.

2. The J2EE application requests an object search (lookup) for the instance of the javax.naming.InitialContext

class. At this time, the name 'corbaname::MyHost:900#Count1' with the prefix 'corbaname:' is specified.

3. A connection is executed from the naming management functionality that receives the request to the CORBA

Naming Service 'MyHost:900'. After the connection, the EJB home object reference 'Count1' is searched with the name specified in the lookup.

4. The J2EE application requests an object search (lookup) for the instance of the

InitialContext

class. At this time, the name 'corbaname::MyHost:901#Count2' with the prefix 'corbaname:' is specified.

5. A connection is executed from the naming management functionality that receives the request to the CORBA

Naming Service 'MyHost:901'. After the connection, the EJB home object reference 'Count2' is searched with the name specified in the lookup.

The CORBA Naming Services are switched by using the server management commands to resolve the Enterprise

Bean references. For details on the operations, see

9. Setting up the J2EE Application Properties

in the

uCosminexus

Application Server Application Setup Guide

.

Note that when the CORBA Naming Service is running on the local host, specify the computer name or the IP address instead of the character string "localhost" in the settings related to the naming service host name.

Customize the J2EE server properties to specify the host name settings for the naming services. For details on how to

specify the settings, see

2.3.5 Execution environment settings

.

83

2. Naming Management

2.11 Re-using the EJB home object references

(Functionality for re-connecting to the EJB home objects)

The functionality for reconnecting to the EJB home objects enables you to re-use the EJB home objects obtained by the EJB client application when the J2EE server and J2EE applications are restarted after an error in the J2EE server.

After the J2EE server and J2EE applications are restarted, the EJB home objects obtained by the EJB client application can be used as are without re-executing a lookup.

This functionality can be used for the EJB home object references of the Session Bean (Stateless Session Bean or

Stateful Session Bean).

The following table describes the organization of this section.

Table 2

40: Organization of this section (Functionality for reconnecting to the EJB home objects)

Category Title Reference location

Settings

Notes

Execution environment settings (J2EE server settings)

Notes on re-using the EJB home object references

2.11.1

2.11.2

Note: The function-specific explanation is not available for "Explanation", "Implementation" and "Operations".

2.11.1 Execution environment settings (J2EE server settings)

To use the functionality for reconnecting to the EJB home objects, you must specify the J2EE server settings. Specify the J2EE server settings in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy

Setup definition file.

The following table describes the definition of the functionality for reconnecting to the EJB home objects in the Easy

Setup definition file.

Table 2

41: Definition of the functionality for reconnecting to the EJB home objects in the Easy Setup definition file

Specified parameters Settings ejbserver.container.ejbhome.sessionbean.reconnect.enabl

ed

Specify whether to enable the functionality for reconnecting to the EJB home objects.

For details on the Easy Setup definition file and the specified parameters, see

4.6 Easy Setup definition file

in the

uCosminexus Application Server Definition Reference Guide

.

2.11.2 Notes on re-using the EJB home object references

The notes on using the functionality for reconnecting to the EJB home objects are as follows:

When the J2EE server and J2EE applications are restarted, do not change the J2EE applications. If you change the

J2EE applications, you cannot re-use the EJB home object references.

Fix the communication port of the J2EE server. Also, when you restart the J2EE server, do not change the fixed value.

For details on how to define the value, see

2.14.1 Fixing the communication port

and

2.14.2 Fixing the IP address

in the

uCosminexus Application Server EJB Container Functionality Guide

.

In the user property file for the Java applications, specify

VB_TRANSPARENT

as the value of the EJB client operations for when a remote interface communication error ( ejbserver.container.rebindpolicy

key) occurs.

For details on how to define the value, see

2.13 Invoking the EJB remote interface

in the

uCosminexus Application

Server EJB Container Functionality Guide

.

84

2. Naming Management

When a communication error occurs during EJB invocation, the connection is re-established and the request is sent again if you have specified

VB_TRANSPARENT

as the value of the EJB client operations for when a communication error occurs ( ejbserver.container.rebindpolicy

key).

Therefore, we recommend that you use the functionality for reconnecting to the EJB home objects in the reference node system.

85

3

Resource Connections and

Transaction Management

This chapter describes the resources to which Application Server is able to connect and the connections to the resources. This chapter also describes the management of transactions in the resource connections.

87

3. Resource Connections and Transaction Management

3.1 Organization of this chapter

The following table describes the resource connection and transaction management functionality and reference locations.

Table 3

1: Resource connection and transaction management functionality and reference locations

Functionality

Reference location

Overview of resource connections and transaction management

Resource connections

Managing transactions

Resource sign-on method

Connecting to a database

Connecting to a database queue

Outbound connection with OpenTP1 (SPP or TP1/Message Queue)

Inbound connection with OpenTP1

Connection with Cosminexus JMS Provider

Connecting to the SMTP server

Using the JavaBeans resources

Connection with other resources

Functionality for performance tuning

Functionality for fault tolerance

Other resource adapter functionality (For the resource adapters conforming to the Connector 1.5 specifications)

Connection pool clustering functionality

Connection test for resources

Functionality for operations in the firewall environment

Notes on starting transactions with EJB client applications

3.10

3.11

3.12

3.13

3.14

3.15

3.16

3.17

3.18

3.19

3.20

3.2

3.7

3.8

3.9

3.3

3.4

3.5

3.6

88

3. Resource Connections and Transaction Management

3.2 Overview of resource connections and transaction management

The J2EE components, such as EJBs, servlets, and JSPs, included in the J2EE applications on the J2EE server, can connect to the resources, such as databases and OpenTP1. The resource adapter is used to connect to the resources, such as databases and OpenTP1. With Application Server, you can use the resource adapters conforming to the

Connector 1.0 specifications or Connector 1.5 specifications. Application Server also provides the functionality for connecting to the resources, such as the SMTP server and JavaBeans resources, without using a resource adapter.

Application Server also provides the connection pooling and transaction management functionality to access the resources with highly efficient and reliable methods. If you use connection pooling, the connections are pooled for resources, and the connections can be used efficiently. Also, the connections with errors are removed from the connection pool appropriately. If you use the transaction management functionality, the transaction manager can properly control the resource access transactions based on the instructions from the transaction attributes and the JTA interface (

UserTransaction

) specified for each EJB method. A global transaction is used to manage the transactions for multiple resources. If you use a global transaction, you ensure the consistency of updates between resources because the transactions are managed using the two-phase commit protocol.

The following figure shows an example of connecting to the resources using the connection pooling and transaction management functionality.

Figure 3

1: Example of connecting to resources using the connection pooling and transaction management functionality

89

3. Resource Connections and Transaction Management

3.3 Resource connections

This section describes the connection methods for each resource type, and the types of resource adapters used for connecting to resources.

This section also describes the usage methods, functionality, and notes as an explanation for using resource adapters.

The following table describes the organization of this section.

Table 3

2: Organization of this section (Resource connections)

Category Title Reference location

Explanation

Implementation

Settings

How to connect to resources

Types of resource adapters

How to use resource adapters

Resource adapter functionality

Functionality other than the resource adapter functionality

Implementation for connecting to the resources

How to set up resource adapters

Procedure for resource adapter settings (To deploy and use the resource adapter as a J2EE resource adapter)

Procedure for resource adapter settings (To include and use resource adapters in J2EE applications)

Procedure for resource adapter settings (To use resource adapters with

Inbound)

Procedure for resource adapter settings (To use connection pool clustering)

Connection settings for using components other than resource adapters

Notes Notes on resource adapters

Note: The functionality-specific explanation is not available for "Operations".

3.3.5

3.3.6

3.3.7

3.3.8

3.3.1

3.3.2

3.3.3

3.3.4

3.3.9

3.3.10

3.3.11

3.3.12

3.3.13

3.3.1 How to connect to resources

Based on the types of resources, Application Server includes the resources that use resource adapters for connection and the resources that do not use resource adapters for connection. This subsection gives an overview of how to connect to each resource for each resource type.

(1) Resources that use resource adapters for connection

The resources that use resource adapters for connection are as follows:

Database

You can connect Application Server to a database. To connect to the database, use DB Connector as the resource adapter.

You can connect to the following databases with DB Connector:

HiRDB

Oracle

SQL Server

#

XDM/RD E2

#: You can only connect to SQL Server in the case of Windows.

90

3. Resource Connections and Transaction Management

For details on connecting to a database, see

3.6.1 Overview of DB Connector-based connections

.

Database queue

You can connect Application Server to the database queues used with Cosminexus RM. To connect to the database queue, use DB Connector for Cosminexus RM and Cosminexus RM as the resource adapter.

You can connect to the following databases with DB Connector for Cosminexus RM and Cosminexus RM:

HiRDB

Oracle

For details on connecting to a database queue, see

3.7.1 Overview of connections using DB Connector for

Cosminexus RM and Cosminexus RM

.

OpenTP1

You can connect Application Server to the OpenTP1 products - SPP, TP1/Message Queue, and Outbound. To connect to OpenTP1 SPP and Outbound, use uCosminexus TP1 Connector as the resource adapter. To connect to

TP1/Message Queue, use TP1/Message Queue - Access as the resource adapter.

Also, you can use Inbound to connect to Application Server from OpenTP1 SUP. To use Inbound to connect from

OpenTP1 SUP, use the TP1 inbound adapter as the resource adapter.

This subsection describes the details on OpenTP1 connections for each resource adapter used for the connections.

The following table describes reference locations.

Table 3

3: Reference locations for the OpenTP1 connection details

Connection method Reference location

Connections using uCosminexus TP1 Connector

Connections using TP1/Message Queue -Access

Connections using the TP1 inbound adapter

3.8.1 Connections using uCosminexus TP1 Connector

3.8.2 Connections using TP1/Message Queue - Access

4. Invoking Application Server from OpenTP1 (TP1 Inbound Integrated

Function)

CJMSP Broker

When you use the Cosminexus JMS Provider functionality, you can connect Application Server with CJMSP

Broker. To connect to CJMSP Broker, use the CJMSP resource adapter as the resource adapter.

For details on connecting to CJMSP Broker using the CJMSP resource adapter, see

7. Cosminexus JMS Provider

.

Other resources

Regardless of the resource type, you can connect Application Server to the resources connectable with the resource adapters conforming to the Connector 1.0 specifications or Connector 1.5 specifications.

For details on the available resource adapters, see

3.13 Connection with other resources

. For details on the

functionality available for Application Server when you use the resource adapters conforming to the Connector

1.5 specifications, see

3.16 Other resource adapter functionality (For the resource adapters conforming to the

Connector 1.5 specifications)

.

(2) Resources that do not use resource adapters for connection

The resources that do not use resource adapters for connection are as follows:

SMTP server

You can connect Application Server to the SMTP server. For details on connecting to the SMTP server, see

3.11

Connecting to the SMTP server

.

JavaBeans

You can use JavaBeans resources as resources. For details on using JavaBeans resources, see

3.12 Using

JavaBeans resources

.

3.3.2 Types of resource adapters

You can use the resource adapters conforming to the Connector 1.0 specifications or Connector 1.5 specifications with

Application Server.

91

3. Resource Connections and Transaction Management

This subsection describes the resource adapters conforming to the respective specifications. This subsection also describes the differences in the DD schema of resource adapters.

(1) Resource adapters conforming to the Connector 1.0 specifications

You can use the following resource adapters with Application Server:

DB Connector

DB Connector for Cosminexus RM and Cosminexus RM uCosminexus TP1 Connector

TP1/Message Queue - Access

You can use the functionality supported by the Connector 1.0 specifications with these resource adapters.

Note that with DB Connector and DB Connector for Cosminexus RM, you can use the functionality added with

Application Server in addition to the functionality supported by the Connector 1.0 specifications. For details on the

available functionality, see

3.3.4 Resource adapter functionality

.

Tip

With Application Server, apart from these resource adapters, you can use the resource adapters conforming to the Connector

1.0 specifications of the standard specifications. However, when you use the resource adapters conforming to the Connector

1.0 specifications of the standard specifications, the settings in the following tags in the DD ( ra.xml

) are ignored.

<security-permission>

Use the server.policy

file for the security settings.

<authentication-mechanism>

Regardless of the settings,

BasicPassword

is applied.

(2) Resource adapters conforming to the Connector 1.5 specifications

You can use the resource adapters conforming to the Connector 1.5 specifications with Application Server. From the contracts in the Connector 1.5 specifications, the functionality corresponding to the following contracts can be used with Application Server:

Lifecycle Management

Work Management

Message inflow

Transaction inflow

Application Server provides the following resource adapters:

TP1 inbound adapter

CJMSP resource adapter

For details on the available functionality, see

3.3.4 Resource adapter functionality

.

Also, for resource adapters conforming to the Connector 1.5 specifications, see

3.13.1 Resource adapters used for connection with other resources

.

(3) Differences in the schema of the resource adapters conforming to the Connector 1.0

specifications and the Connector 1.5 specifications

This section describes the differences in the DD schema of the resource adapters conforming to the Connector 1.0

specifications and resource adapters conforming to the Connector 1.5 specifications. The DD for a resource adapter is ra.xml

.

The following table describes the main changes from the schema defined in the Connector 1.0 specifications to the schema defined in the Connector 1.5 specifications. For the changes other than those described in this table, see the

Connector 1.5 specifications.

92

3. Resource Connections and Transaction Management

Table 3

4: Main changes from the schema defined in the Connector 1.0 specifications to the schema defined in the Connector 1.5 specifications

Content changed in the Connector 1.5

specifications

DD content in the Connector 1.5 specifications

Specification of the implementation class of the javax.resource.spi.ResourceAdapter

interface

Specification of the Outbound resource adapter

Specification of the Inbound resource adapter

Specification of adminobject

<connector>-<resourceadapter>-<resourceadapter-class> tag

<connector>-<resourceadapter>-<config-property>

tag

<connector>-<resourceadapter>-<outboundresourceadapter> tag

<connector>-<resourceadapter>-<inboundresourceadapter>

tag

<connector>-<resourceadapter>-<adminobject>

tag

An overview of the content changed in the Connector 1.5 specifications is as follows:

Specification of the implementation class o

f the javax.resource.spi.ResourceAdapter

interface

The implementation class of the javax.resource.spi.ResourceAdapter

interface and the elements specifying their configuration properties were added. For details on the functionality that can be implemented with the addition of the javax.resource.spi.ResourceAdapter

interface, see

3.16.1 Managing the resource adapter lifecycle

and

3.16.2 Managing the resource adapter work

.

Specification of the Outbound resource adapter

The elements used for explicitly defining the Outbound resource adapter were added.

Note that you can define multiple connections in one DD with the Outbound resource adapter. For details on specifying multiple connection definitions, see

3.16.6 Specifying multiple connection definitions

.

Specification of the Inbound resource adapter

The elements used for explicitly defining the Inbound resource adapter were added.

Specification of

adminobject

The elements specifying the information related to the Administered objects were added.

(4) Types of RAR files for each resource adapter

The resource adapters that define properties differ depending on the information such as the types of resources to be connected to and the transactions to be used. This section describes the resource adapters used in the following cases:

To use DB Connectors

To use DB Connector for Cosminexus RM and Cosminexus RM

To use other resource adapters

(a) To use DB Connectors

The files for DB Connectors differ depending on the database type to be connected to and the transaction type to be used. The following table describes the DB Connector types.

Table 3

5: DB Connector types

RAR file name Explanation

DBConnector_HiRDB_Type4_CP.rar

DBConnector_HiRDB_Type4_XA.rar

DBConnector_Oracle_CP.rar

Select this file when you use HiRDB Type4 JDBC Driver to connect to HiRDB or XDM/RD E2 without using a local transaction or transaction management.

Select this file when you use HiRDB Type4 JDBC Driver to connect to HiRDB using a global transaction.

Select this file when you use Oracle JDBC Thin Driver to connect to Oracle without using a local transaction or transaction management.

93

3. Resource Connections and Transaction Management

RAR file name

DBConnector_Oracle_XA.rar

DBConnector_SQLServer_CP.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_M ember.rar

Explanation

Select this file when you use Oracle JDBC Thin Driver to connect to Oracle using a global transaction.

Select this file when you use SQL Server JDBC Driver to connect to SQL Server

(only in Windows) without using a local transaction or transaction management.

This is the root resource adapter of the connection pool clustering functionality.

Select this file when a member resource adapter belonging to the root resource adapter connects to Oracle without using a local transaction or transaction management.

This is the member resource adapter of the connection pool clustering functionality. Select this file when you use Oracle JDBC Thin Driver to connect to Oracle without using a local transaction or transaction management. Note that you cannot specify this file in the resource references of J2EE applications.

Note: When you prepare a new DB Connector RAR file, you can use the template files of the HITACHI Connector Property files provided with Application Server to define properties. The template files of the HITACHI Connector Property files are provided for all the DB Connector RAR files. For details on the provided template files, see

4.1.14 Template files of the HITACHI Connector

Property files

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

(b) To use DB Connector for Cosminexus RM and Cosminexus RM

When you connect to a database by integrating the system with

Cosminexus RM

, you must import both, resource adapter for the Cosminexus RM integration (

DB Connector for Cosminexus RM

) and the resource adapter provided with Cosminexus RM. For details on the resource adapter provided with Cosminexus RM, see the manual

uCosminexus Application Server Reliable Messaging

.

The files for DB Connector for Cosminexus RM differ depending on the transaction type to be used and the database type to be connected to. The following table describes the types of DB Connector for Cosminexus RM.

Table 3

6: DB Connector for Cosminexus RM types

RAR file name Explanation

DBConnector_HiRDB_Type4_CP_Cosminex us_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminex us_RM.rar

DBConnector_Oracle_CP_Cosminexus_RM

.rar

DBConnector_Oracle_XA_Cosminexus_RM

.rar

Select this file when you use HiRDB Type4 JDBC Driver to connect to HiRDB without using a local transaction or transaction management.

Select this file when you use HiRDB Type4 JDBC Driver to connect to HiRDB using a global transaction.

Select this file when you use Oracle JDBC Thin Driver to connect to Oracle without using a local transaction or transaction management.

Select this file when you use Oracle JDBC Thin Driver to connect to Oracle using a global transaction.

Note: When you prepare a new RAR file for DB Connector for Cosminexus RM, you can use the template files of the HITACHI

Connector Property files provided with Application Server to define properties. The template files of the HITACHI Connector

Property files are provided for all the DB Connector RAR files. For details on the provided template files, see

4.1.14 Template files of the HITACHI Connector Property files

in the

uCosminexus Application Server Application and Resource Definition Reference

Guide

.

Tip

When you use DB Connector for Cosminexus RM and Cosminexus RM for accessing the JDBC and JMS in the same transaction, you can use a local transaction and conclude the single-phase commit operations for a global transaction by sharing the same physical connection. The conditions for concluding the single-phase commit operations are as follows:

The database system used for DB Connector for Cosminexus RM and Cosminexus RM is the same, and the sign-on method and the security information (user name and password) is identical.

The value Shareable is specified in the <res-sharing-scope> tag in the property files of the J2EE applications using the resource adapters (such as the Session Bean property file and Entity Bean property file).

94

3. Resource Connections and Transaction Management

(c) To use other resource adapters

To connect to

OpenTP1 SPP

and Outbound, you use the resource adapters uCosminexus TP1 Connector and TP1/

Client/J. For details, see the uCosminexus TP1 Connector documentation and the

OpenTP1 Version 7 TP1/Client

User's Guide TP1/Client/J

.

To connect from

OpenTP1 SUP

using Inbound, you use the TP1 inbound adapter. For details, see

4. Invoking

Application Server from OpenTP1 (TP1 Inbound Integrated Function)

.

Also, to connect to

CJMSP Broker

when you use Cosminexus JMS Provider, you use the CJMSP resource adapter.

For details, see

7. Cosminexus JMS Provider

.

Note that to use a new RAR file for the TP1 inbound adapter or the CJMSP resource adapter, you can use the template file provided with Application Server to define properties. For details, see

4.1.14 Template files of the HITACHI

Connector Property files

in the

uCosminexus Application Server Application and Resource Definition Reference

Guide

.

To connect to

TP1/Message Queue

, use the resource adapter TP1/Message Queue - Access. For details, see the

OpenTP1 Version 7 TP1/Message Queue - Access User Guide

.

With Application Server, you can also connect to any resource by using the resource adapters conforming to the

Connector 1.0 specifications or Connector 1.5 specifications. To use these resource adapters, see the documentation for resource adapters.

3.3.3 How to use the resource adapters

This subsection describes how to use the resource adapters. There are two types of methods of using the resource adapters to connect to resources:

Method of deploying and using the resource adapter as a J2EE resource adapter

Method of including and using the resource adapter in a J2EE application

The following is a description of the methods:

(1) Deploying and using the resource adapter as a J2EE resource adapter

Deploy the resource adapter imported into the J2EE server as a shared standalone module. The resource adapter is now available to all the J2EE applications running on that J2EE server. The resource adapters allocated to the J2EE server are called the

J2EE resource adapters

.

(2) Including and using the resource adapter in a J2EE application

Include the resource adapter in a J2EE application to use the resource adapter. The EJBs and WARs included in the same J2EE application can use the resource adapter. For details on how to include and use the resource adapter in a

J2EE application, see

3.3.9 Procedure for resource adapter settings (To include and use the resource adapter in the

J2EE application)

.

Note that the resource adapters that can be included in a J2EE application are limited. For details, see

(3) Resource adapters available in each usage method

.

(3) Resource adapters available in each usage method

The resource adapters must be compatible with the Application Server versions. Also, you can deploy and use the resource adapters conforming to the Connector 1.0 specifications and Connector 1.5 specifications with Application

Server. However, when you include and use the resource adapters in J2EE applications, you cannot use the following resource adapters:

Resource adapters specified in

XATransaction

Resource adapters containing the native library

Resource adapters for which the starting order must be controlled

Resource adapters using the Application Server-specific functionality

The following table describes the usage of the resource adapters provided by Application Server.

95

3. Resource Connections and Transaction Management

Table 3

7: Usage of the resource adapters provided by Application Server

Usage

Resource adapter

Deploying and using the resource adapter as a J2EE resource adapter

Including and using the resource adapter in a J2EE application

Y Y DB Connector Specified in

NoTransaction

or

LocalTransaction

Specified in

XATransaction

Cluster configuration

Root resource adapter

Member resource adapter uCosminexus TP1

Connector

Specified in

NoTransaction

or

LocalTransaction

Specified in

XATransaction

TP1/Message Queue - Access

Cosminexus RM Cosminexus RM (without database)

Cosminexus RM (with database)

DB Connector for Cosminexus RM

TP1 inbound adapter

CJMSP resource adapter

Legend:

Y: Available

--: Not applicable

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

--

--

--

--

--

--

--

--

--

--

Y

If you execute the following operations for the unavailable resource adapters, an error message is output and the operation fails:

Including and importing the resource adapter in a J2EE application

Including the resource adapter in a J2EE application and performing a connection test or starting the resource adapter

3.3.4 Resource adapter functionality

This subsection describes the following resource adapter functionality:

DB Connector

DB Connector used for connection pool clustering (root resource adapter and member resource adapter)

DB Connector for Cosminexus RM

TP1 inbound adapter

CJMSP resource adapter

Other resource adapters conforming to the Connector 1.5 specifications

For details on any other resource adapter functionality, see the documentation for the resource adapter you want to use.

The following table describes the functionality available for each type of resource adapter. For details on the functionality, see the description in the reference location.

96

3. Resource Connections and Transaction Management

Table 3

8: Functionality available for each resource adapter type

Types of resource adapters

Functionality

Connection pooling

Connection pool warming up

Connection count adjustment functionality

Connection sharing or association

Statement pooling

Caching

DataSource objects

Optimizing the containermanaged sign-on for DB

Connector

Detecting connection errors

Waiting for a connection when connections deplete

Retrying to obtain a connection

Displaying the connection pool information

Clearing the connection pool

Automatically closing connections

Connection sweeper

Statement cancellation

Output of the SQL statement for troubleshooting

Automatically closing objects

Managing the resource adapter lifecycle

Managing the resource adapter work

Message inflow

DB

Connect or

Root resource adapter

Member resource adapter

DB

Connect or for

Cosmine xus RM

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

M

Y

N

N

N

N

N

N

N

N

Y

N

N

N

N

N

N

N

N

N

N

N

N

N

N

M

Y

Y

Y

Y

N

Y

M

M

N

Y

Y

Y

Y

Y

M

Y

N

N

N

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

M

Y

N

N

N

TP1 inbound adapter

--

--

CJMSP resource adapter

Y

Y

Other resource adapters conformi ng to the

Connect or 1.5

specifica tions

#1

Y

Y

Reference location

3.14.1

3.14.2

--

--

--

--

--

--

--

--

--

--

--

--

--

--

--

Y

Y

Y

Y

N

N

N

N

N

Y

Y

Y

Y

N

Y

N

N

N

Y

Y

Y

Y

Y

N

Y

Y

Y

N

Y

Y

Y

Y

N

Y

N

N

Y

Y

Y

3.14.3

3.14.4

3.14.7

3.14.8

3.15.1

3.15.2

3.15.3

3.15.4

3.15.5

3.15.6

3.15.7

3.15.8

3.15.10

3.15.11

3.16.1

3.16.2

3.16.3

97

3. Resource Connections and Transaction Management

Types of resource adapters

Functionality

DB

Connect or

Root resource adapter

Member resource adapter

DB

Connect or for

Cosmine xus RM

TP1 inbound adapter

CJMSP resource adapter

Other resource adapters conformi ng to the

Connect or 1.5

specifica tions

#1

N

Y

Reference location

Transaction inflow

Looking up the

Administered objects

Specifying multiple connection definitions

Suspending a connection pool

Restarting a connection pool

N

N

N

N

N

N

N

N

N

N

N

N

N

Y

Y

N

N

N

N

N

Y

--

--

--

--

N

Y

Y

N

N

Y

N

N

3.16.4

3.16.5

3.16.6

3.17.4

Displaying the connection pool status

Connection test for resources

Assigning optional names to J2EE resources

Y

Y

Y

N

Y

Y

Y

Y

N

Y

Y

Y

--

--

--

N

Y

Y

Y

Y

Y

3.18

2.6

PRF trace of the connection ID

Y Y Y Y ----

Legend:

M: Always enabled

Y: Available

N: Not available

--: Not applicable

#1: This table describes whether the functionality provided by Application Server is available. For details on the functionality provided by resource adapters, see the documentation for the resource adapter you want to use.

#2: See

4.6 Trace based performance analysis

in the

uCosminexus Application Server Maintenance and Migration Guide

.

#2

3.3.5 Functionality other than the resource adapter functionality

This subsection describes the functionality implemented apart from the resource adapter functionality. The functionality described in this subsection can be used regardless of the types of resource adapters.

The following table describes the functionality implemented apart from the resource adapter functionality. For details on the functionality, see the description in the reference location.

Table 3

9: Functionality other than the resource adapter functionality

Functionality Reference location

Light transaction

In-process transaction service

Transaction timeout and statement cancellation

Transaction recovery

3.14.5

3.14.6

3.15.8

3.15.9

98

3. Resource Connections and Transaction Management

3.3.6 Implementation for connecting to the resources

To connect from the application to a resource, the resource references must be obtained for Enterprise Beans and servlets. The methods of obtaining the resource references include the method of using lookup and the method of using DI (Dependency Injection).

Note that when using EJB 3.0 or later, use DI to obtain the resource references.

(1) Method of obtaining the resource references by using lookup

When you want to use the lookup method, connect the application to the resource as follows:

1. Use the JNDI to look up the factory class that is used for obtaining the connection to the resource.

Specify the name to be looked up using the DD of Enterprise Beans and servlets. The applicable tag is the

<resref-name>

tag in the

<resource-ref>

tag.

2. Use the connection factory class to obtain the connection.

3. Use the obtained connection to connect to the resource.

4. Close the used connection.

If you use connection pooling, a pooled connection is obtained in step 2 and the connection is returned to the pool in step 4. The user program does not require a connection pooling-aware coding.

(2) Method of obtaining the resource references by using the DI

To use the DI for obtaining the resource references, the DD definitions are unnecessary. For an overview of the DI and the notes on DI usage, see

12.4 Using the DI

.

(3) Notes on connecting to the resources

If you obtain a resource connection through a user program, make sure you close the connection after use.

Specifically, close the connection using the finally

clause so that the connection is definitely closed even when an exception occurs.

Note that the time when the finalize

method is invoked depends on the timing of JavaVM garbage collection, so do not specify the design of using the finalize method to close the connection. If a connection is not closed properly through the user program, the maximum number of connections that can be obtained is reached and you might not be able to obtain more connections.

3.3.7 How to set up resource adapters

The method of setting up resource adapters includes the following two methods:

• Method of deploying and setting up the resource adapter as a J2EE resource adapter

In this method, you directly deploy and set up the resource adapter on the J2EE server.

• Method of including and setting the resource adapter in a J2EE application

This method is specified for the resource adapters that are included and used in a J2EE application.

Reference note

If the resource adapter is DB Connector, the TP1 inbound adapter, or the CJMSP resource adapter, you can use the template files of the HITACHI Connector Property files provided by Application Server. If you use the template file, you can edit the HITACHI Connector Property file before you import the resource adapter. Therefore, the HITACHI

Connector Property file to be edited need not be obtained with the server management commands ( cjgetrarprop command or cjgetresprop

command).

For details on the storage destination of the template files of the HITACHI Connector Property files and the notes on the usage of the template files, see

4.1.14 Template files of the HITACHI Connector Property files

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

99

3. Resource Connections and Transaction Management

!

Important note

To use the resource adapters that were used with the old Application Server versions, the resource adapters must be migrated. For details on how to migrate the resources, see

10.9 Migrating the resource adapters

in the

uCosminexus

Application Server Maintenance and Migration Guide

.

3.3.8 Procedure for resource adapter settings (To deploy and use the resource adapter as a J2EE resource adapter)

This subsection describes the following procedure for deploying and using the resource adapter as a J2EE resource adapter:

Procedure for setting up a new resource adapter

Procedure for changing the resource adapter settings

Procedure for replacing resource adapters

Use the server management commands to set up resource adapters.

(1) Procedure for setting up a new resource adapter

The following figure shows the procedure for setting up a new resource adapter when Application Server is connected to a database or another resource.

Figure 3

2: Procedure for setting up a new resource adapter

100

A description of points 1 to 4 in the figure is as follows:

1. Use the server management commands to import the resource adapter.

Use the cjimportres

command to import the resource adapter.

You import a different RAR file when DB Connector is used to connect to a database and when other resource adapters are used to connect to various resources such as OpenTP1. For details on the resource adapters to be imported, see

3.3.2 Types of resource adapters

.

2. Use the server management commands to deploy the resource adapter.

Use the cjdeployrar command to deploy the resource adapter.

If you deploy a resource adapter, you can use the resource adapter as a J2EE resource adapter. A

J2EE resource adapter

is a resource adapter that is deployed as a shared standalone module for the J2EE server. If you deploy a resource adapter that was imported with the server management commands, the resource adapter becomes available to all the J2EE applications running on the J2EE server.

3. Use the server management commands to define resource adapter properties.

Use the cjgetrarprop

command to obtain the HITACHI Connector Property file, edit the file, and then use the cjsetrarprop

command to apply the edited content.

For details on the resource adapter properties specified for the functionality to be used, see the following locations:

3. Resource Connections and Transaction Management

Settings for using the resource connection and transaction management functionality

3.4.12 Settings in the execution environment

Functionality for performance tuning

3.14.10 Settings in the execution environment

Functionality for fault tolerance

3.15.13 Settings in the execution environment

Setting the optional names for J2EE resources

2.6.6 Setting the optional names for the J2EE resources

4. Use the server management commands to implement the resource adapter connection test.

Use the cjtestres

command to implement the resource adapter connection test. For details on the content to be

verified in the connection test for each resource, see

3.18 Connection test for resources

.

!

Important note

The connection test for connecting to a database by using DB Connector for Cosminexus RM and Cosminexus RM involves the following order:

1. Start DB Connector for Cosminexus RM.

2. Implement the connection test for Cosminexus RM.

3. Start Cosminexus RM.

4. Implement the connection test for DB Connector for Cosminexus RM.

For details on the connection test of the J2EE resource adapters used when DB Connector for Cosminexus RM is used, see

2.7 Functionality for DB Connector for Cosminexus RM

in the manual

uCosminexus Application Server Reliable

Messaging

.

For details on the operations with the server management commands, see

3. Basic Operations of the Server

Management Commands

in the

uCosminexus Application Server Application Setup Guide

. Also, for details on the commands, see

2.4 Resource operation commands used with the J2EE server

in the

uCosminexus Application Server

Command Reference Guide

. For details on the property files, see

4. Property Files Used for Setting Up the Resources

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

!

Important note

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter. When you define the properties for a J2EE application that uses resource adapters, resolve the references from the J2EE application to the resource adapter.

Reference note

In the cases such as those described below, you can set up the resource adapter efficiently by exporting or importing the resource adapter:

When you export the resource adapter set up in the development environment, and then import the resource adapter into the operating environment

When you export the resource adapter that is already running in the operating environment, and then import the resource adapter into an extended J2EE server

Execute the export and import operations using cjexportrar and cjimportres .

Note that you cannot export or import resource adapters between hosts with different Application Server versions and platforms. To set up a resource adapter on the host that exports the resource adapter and the host with a different Application

Server version and platform, set up a new resource adapter.

(2) Procedure for changing the resource adapter settings

This section describes the procedure for changing the settings for a deployed resource adapter. The following figure shows the procedure for changing the settings.

101

3. Resource Connections and Transaction Management

Figure 3

3: Procedure for changing the resource adapter settings

A description of points 1 and 2 in the figure is as follows:

1. Use the server management commands to stop the resource adapter.

Use the cjstoprar

command to stop the resource adapter. Note that before you stop the resource adapter, make sure you stop all the J2EE applications that are using the resource adapter.

2. Use the server management commands to define the resource adapter properties.

The resource adapter is already deployed; therefore, use the cjgetrarprop

command to obtain the property file, edit the file, and then use the cjsetrarprop

command to apply the edited content.

(3) Procedure for replacing the resource adapters

This section describes the procedure for replacing the resource adapters. The following figure shows the procedure for replacing the resource adapters.

Figure 3

4: Procedure for replacing the resource adapters

A description of points 1 to 3 in the figure is as follows:

1. Stop the J2EE server.

Use the cjstopsv

command to stop the J2EE server.

2. Replace the resource adapter.

Use the cjrarupdate

command to replace the resource adapter.

3. Start the J2EE server.

Use the cjstartsv

command to start the J2EE server.

You can also replace a resource adapter without using the cjrarupdate

command. The following figure shows the procedure for replacing the resource adapters without using the cjrarupdate

command.

102

3. Resource Connections and Transaction Management

Figure 3

5: Procedure for replacing the resource adapters (when the

cjrarupdate

command is not used)

A description of points 1 to 7 in the figure is as follows:

1. Use the server management commands to stop the resource adapter.

Use the cjstoprar

command to stop the resource adapter you want to replace. Note that before you stop the resource adapter, make sure you stop all the J2EE applications that are using the resource adapter.

2. Restart the J2EE server.

Use the cjstopsv

command to stop the J2EE server, and then use the cjstartsv

command to start the J2EE server.

3. Use the server management commands to save the resource adapter property definitions.

To inherit the resource adapter property definitions, use the cjgetrarprop command or cjgetresprop command to obtain the HITACHI Connector Property file of the resource adapter.

4. Use the server management commands to undeploy the resource adapter.

Use the cjundeployrar

command to undeploy the resource adapter you want to replace.

5. Use the server management commands to delete the resource adapter.

Use the cjdeleteres

command to delete the resource adapter you want to replace.

6. Use the server management commands to set up the resource adapter.

Set up the resource adapter as described in

(1) Procedure for setting up a new resource adapter

. To inherit the resource adapter property definitions, use the HITACHI Connector Property file obtained in point 3.

7. Use the server management commands to start the resource adapter.

Use the cjstartrar

command to start the resource adapter. Note that after you start the resource adapter, start the J2EE applications that use the resource adapter.

3.3.9 Procedure for resource adapter settings (To include and use the resource adapter in the J2EE application)

Use the server management commands to set up the resource adapter. This subsection describes the procedure for resource adapter settings to include and use the resource adapter in the J2EE application.

Note that the method of setting up a resource adapter when the resource adapter is included and used in an application includes the following two methods:

103

3. Resource Connections and Transaction Management

Method of importing the J2EE application containing the resource adapter into the J2EE server

Method of adding the resource adapter in a J2EE application already imported into the J2EE server

This subsection describes each of the methods.

Note that the resource adapters included in a J2EE application are limited. For details on the resource adapters

included in a J2EE application, see

3.3.3 How to use the resource adapters

.

(1) Method of importing the J2EE application containing the resource adapter into the J2EE server

In this method, you create a J2EE application including the RAR file of the resource adapter, and then import that

EAR file into the J2EE server. The following figure gives an overview of this method.

Figure 3

6: Overview of the method of importing the J2EE application containing the resource adapter into the J2EE server

The following figure shows the procedure for importing a J2EE application containing a resource adapter into the

J2EE server.

Figure 3

7: Procedure for importing a J2EE application containing a resource adapter into the J2EE server

104

A description of points 1 to 4 in the figure is as follows:

3. Resource Connections and Transaction Management

1. Use the server management commands to add the RAR file of the resource adapter into the EAR file of the J2EE application.

Use the cjaddapp

command to add the RAR file of the resource adapter into the EAR file of the J2EE application.

The resource adapters included in the EAR file are limited. For details on the resource adapters included in the

EAR file, see

3.3.3 How to use the resource adapters

.

2. Use the server management commands to import the J2EE application.

Use the cjimportapp

command to import the J2EE application.

3. Use the server management commands to define the resource adapter properties.

Use the cjgetappprop

command to obtain the HITACHI Connector Property file, edit the file, and then use the cjsetappprop command to apply the edited content.

For details on the resource adapter properties specified for the functionality to be used, see the following locations:

Settings for using the resource connection and the transaction management functionality

3.4.12 Settings in the execution environment

Functionality for performance tuning

3.14.10 Settings in the execution environment

Functionality for fault tolerance

3.15.13 Settings in the execution environment

Setting the optional names for J2EE resources

2.6.6 Setting the optional names for the J2EE resources

4. Use the server management commands to implement the resource adapter connection test.

Use the cjtestres

command to implement the resource adapter connection test. For details on the content to be

verified in the connection test for each resource, see

3.18 Connection test for resources

.

(2) Method of adding the resource adapter in an imported J2EE application

In this method, you import the resource adapter (RAR file) into the J2EE server and then add the resource adapter in a

J2EE application that is already imported into the same J2EE server. The following figure gives an overview of this method.

105

3. Resource Connections and Transaction Management

Figure 3

8: Overview of the method of adding the resource adapter in an imported J2EE application

The following figure shows the procedure for adding the resource adapter into an imported J2EE application.

Figure 3

9: Procedure for adding the resource adapter into an imported J2EE application

106

A description of points 1 to 5 in the figure is as follows:

3. Resource Connections and Transaction Management

1. Use the server management commands to import the J2EE application.

Use the cjimportapp

command to import the J2EE application.

2. Use the server management commands to import the resource adapter.

Use the cjimportres

command to import the resource adapter.

3. Use the server management commands to add the resource adapter into the J2EE application.

Use the cjaddapp

command to add the resource adapter into the J2EE application.

4. Use the server management commands to define the resource adapter properties.

Use the cjgetappprop

command to obtain the HITACHI Connector Property file, edit the file, and then use the cjsetappprop

command to apply the edited content.

For details on the resource adapter properties specified for the functionality to be used, see the following locations:

Settings for using the resource connection and the transaction management functionality

3.4.12 Settings in the execution environment

Functionality for performance tuning

3.14.10 Settings in the execution environment

Functionality for fault tolerance

3.15.13 Settings in the execution environment

Setting the optional names for J2EE resources

2.6.6 Setting the optional names for the J2EE resources

5. Use the server management commands to implement the resource adapter connection test.

Use the cjtestres

command to implement the resource adapter connection test. For details on the content to be verified in the connection test for each resource, see

3.18 Connection test for resources

.

3.3.10 Procedure for resource adapter settings (To use the resource adapter with Inbound)

This subsection describes the procedure for the resource adapter and J2EE application settings for executing message inflow. The procedure for the settings varies depending on whether you directly deploy the resource adapter on the

J2EE server, or whether you include the resource adapter in a J2EE application.

(1) Directly deploying the resource adapter on the J2EE server

The following figure shows the procedure for specifying the settings for directly deploying the resource adapter on the

J2EE server.

107

3. Resource Connections and Transaction Management

Figure 3

10: Procedure for specifying the settings for directly deploying the resource adapter on the J2EE server

A description of points 1 to 5 in the figure is as follows. The server management command-based operations are described here.

1. Import the resource adapters conforming to the Connector 1.5 specifications.

Execute the cjimportres

command by specifying

-type rar

.

2. Deploy the resource adapter.

Execute the cjdeployrar

command.

3. Define the resource adapter properties.

Use the cjgetrarprop

command to obtain the HITACHI Connector Property file. Edit the file, and then use the cjsetrarprop

command to apply the edited content.

The Administered objects will be set up here. For details on the settings, see

3.16.8(2) Setting up the Administered objects

.

4. Import the J2EE application containing the Message-driven Bean.

Use the cjimportapp

command.

5. Define the J2EE application properties.

Execute the cjgetappprop

command by specifying

-type all

to obtain HITACHI Application Integrated

Property File. Edit the file, and then execute the cjsetappprop

command by specifying

-type all

to apply the edited content.

The following items will be set up here:

Mapping the Message-driven Beans and resource adapters

For the settings, see

3.16.8(3) Settings for mapping the Message-driven Beans and resource adapters

.

Interfaces used by the Message-driven Beans

For the settings, see

3.16.8(4) Setting up the interfaces used by the Message-driven Beans

.

ActivationSpec

settings

For the settings, see

3.16.8(5) ActivationSpec settings

.

(2) To include and use the resource adapter in the J2EE application

The following figure shows the procedure for specifying the settings to include and use the resource adapter in the

J2EE application.

108

3. Resource Connections and Transaction Management

Figure 3

11: Procedure for specifying the settings for including and using the resource adapter in the J2EE application

A description of points 1 and 2 in the figure is as follows. Note that the server management command-based operations are described here.

1. Import the J2EE application containing the Message-driven Beans.

Use the cjimportapp

command.

2. Define the J2EE application properties.

Execute the cjgetappprop

command by specifying

-type all

to obtain HITACHI Application Integrated

Property File. Edit the file, and then execute the cjsetappprop

command by specifying

-type all

to apply the edited content.

The following items will be set up here:

Information on the Administered objects

For the settings, see

3.16.8(2) Setting up the Administered objects

.

Mapping the Message-driven Beans and resource adapters

For the settings, see

3.16.8(3) Settings for mapping the Message-driven Beans and resource adapters

.

Interfaces used by the Message-driven Beans

For the settings, see

3.16.8(4) Setting up the interfaces used by the Message-driven Beans

.

ActivationSpec settings

For the settings, see

3.16.8(5) ActivationSpec settings

.

3.3.11 Procedure for resource adapter settings (To use connection pool clustering)

The following figure shows the procedure for resource adapter settings for connecting to a database when the connection pool is clustered.

109

3. Resource Connections and Transaction Management

Figure 3

12: Procedure for resource adapter settings in connection pool clustering

110

A description of points 1 to 10 in the figure is as follows:

1. Use the server management commands to import the member resource adapters.

Use the cjimportres

command to import the member resource adapters.

For details on the resource adapters to be imported, see

3.3.2 Types of resource adapters

.

2. Use the server management commands to deploy the member resource adapters.

Use the cjdeployrar

command to deploy the member resource adapters.

3. Use the server management commands to define the member resource adapter properties.

Use the cjgetrarprop

command to obtain the HITACHI Connector Property file, edit the file, and then use the cjsetrarprop

command to apply the edited content.

The items that you can set up by defining the member resource adapter and root resource adapter properties differ.

For details on the items defined in the properties that can be set for the member resource adapters and root resource adapter, see

3.17 Functionality for connection pool clustering

.

For details on the resource adapter properties specified for the functionality to be used, see the following locations:

Settings for using the resource connection and the transaction management functionality

3.4.12 Settings in the execution environment

Functionality for performance tuning

3.14.10 Settings in the execution environment

Functionality for fault tolerance

3.15.13 Settings in the execution environment

Setting the optional names for J2EE resources

2.6.6 Setting the optional names for the J2EE resources

3. Resource Connections and Transaction Management

4. Use the server management commands to implement the connection test for the member resource adapters.

Use the cjtestres

command to implement the connection test for the member resource adapters.

For details on the content to be verified in the connection test for the member resource adapters, see

3.18

Connection test for resources

.

The steps from 1 to 4 are repeated for the number of member resource adapters only.

5. Use the server management commands to start the member resource adapters.

To implement the connection test of the root resource adapter, start the member resource adapters first. Use the cjstartrar

command to start the member resource adapters.

6. Use the server management commands to import the root resource adapter.

Use the cjimportres

command to import the root resource adapter.

For details on the resource adapters to be imported, see

3.3.2 Types of resource adapters

.

7. Use the server management commands to deploy the root resource adapter.

Use the cjdeployrar

command to deploy the root resource adapter.

8. Use the server management commands to define the root resource adapter properties.

Use the cjgetrarprop

command to obtain the HITACHI Connector Property file, edit the file, and then use the cjsetrarprop command to apply the edited content.

9. Use the server management commands to implement the connection test for the root resource adapter.

Use the cjtestres

command to implement the connection test for the root resource adapter.

For details on the content to be verified in the connection test for the root resource adapter, see

3.18 Connection test for resources

.

10. Use the server management commands to stop the member resource adapters.

After you implement the connection test for the root resource adapter, stop the member resource adapter. Use the cjstoprar

command to stop the member resource adapters.

For details on the operations with the server management commands, see

3. Basic Operations of the Server

Management Commands

in the

uCosminexus Application Server Application Setup Guide

. Also, for details on the commands, see

2.4 Resource operation commands used with the J2EE server

in the

uCosminexus Application Server

Command Reference Guide

. For details on the property files, see

4. Property Files Used for Setting Up the Resources

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

!

Important note

To cluster a connection pool, you must resolve the references from the J2EE application to the root resource adapter. When you use the root resource adapter to define the J2EE application properties, resolve the references from the J2EE application to the root resource adapter.

3.3.12 Connection settings for using components other than the resource adapters

To specify the settings for using the JavaBeans resources and JavaMail, apart from the resource adapters, see the following locations:

To use the JavaBeans resources

See

3.12.4 Setting up the JavaBeans resources

.

To use JavaMail

The mail configuration is only used for the SMTP server connection.

Use the POP3 server to receive mails. The IMAP server cannot be used.

For details, see

3.11 Connecting to the SMTP server

.

3.3.13 Notes on the resource adapters

This subsection describes the notes on the resource adapters.

111

3. Resource Connections and Transaction Management

Functionality that is unavailable based on the deploy method

When you include and use the resource adapter in the J2EE application, the following functionality is not enabled even if the resources included in the J2EE application are updated:

Detecting the J2EE application updates

Reloading the J2EE applications

For details, see

13.8.13 Notes and restrictions related to reloading

.

Notes on the display names of the resource adapters

The EJBs and WARs in the J2EE application can concurrently use the resource adapters that are deployed as J2EE resource adapters and the resource adapters that are included in the J2EE application. However, two or more resource adapters with the same display name cannot be used on one J2EE server. If you try to use resource adapters with the same display name on one J2EE server, an error message is displayed and the resource adapter fails to start. The examples of procedures when the resource adapter fails to start are as follows:

Example 1.

1. A resource adapter with the display name 'Rar1' is deployed on the J2EE server.

2. A J2EE application containing a resource adapter with the display name 'Rar1' is imported.

Example 2.

1. A resource adapter with the display name 'Rar2' is deployed on the J2EE server.

2. A resource adapter with the display name 'Rar2' is added to the imported J2EE application.

Example 3.

1. A J2EE application containing a resource adapter with the display name 'Rar3' is imported.

2. A resource adapter with the display name 'Rar3' is deployed on the J2EE server.

Notes on the optional names for resource adapters

If multiple resource adapters are deployed with the same optional name, an error message is displayed and the resource adapter fails to start.

Notes on the start processing of the resource adapters

If the start processing of a resource adapter fails while a J2EE server is being started, the resource adapter status changes from Start to Stop. In this case, the resource adapter does not start even when you start the J2EE server the next time. The application that is using the applicable resource adapter also fails to start.

In such cases, see the error information, eliminate the cause of the error, and then take the following action:

If the transaction support level of the resource adapter is

LocalTransaction

or

NoTransaction

1. Start the resource adapter that changed to Stop status.

2. Start the application that is using the resource adapter.

If the transaction support level of the resource adapter is

XATransaction

1. Start the resource adapter that changed to Stop status.

2. Restart the J2EE server to recover the unconcluded transactions.

3. Start the application that is using the resource adapter.

Other notes

The functionality for referencing the URL connection Resource Factory is not supported.

112

3. Resource Connections and Transaction Management

3.4 Managing transactions

This section gives an overview of transaction management.

The transaction management methods used for resource connections include the Application Server-managed method and user-managed method.

When the transactions are managed with Application Server, you can use the transaction manager of Application

Server to manage the transactions.

The following table describes the organization of this section.

Table 3

10: Organization of this section (Managing transactions)

Category Title Reference location

Explanation

Implementation

#

Transaction management methods for the resource connections

Local transaction and global transaction

Transaction types available for each resource

Functionality provided with the transaction services

Transaction operations during system exceptions

Obtaining the transaction manager

Overview of processing and the points to remember when using the containermanaged transactions (CMT)

3.4.1

3.4.2

3.4.3

3.4.4

3.4.5

3.4.6

3.4.7

Overview of processing and the points to remember when using the

UserTransaction

interface

Overview of processing and the points to remember when using the resource adapter-specific transaction management interface

Overview of processing and the points to remember when transactions are not used

3.4.8

3.4.9

3.4.10

Settings

Notes on the JTA-based transaction implementation

Settings in the execution environment

3.4.11

3.4.12

Note: The functionality-specific explanation is not available for "Operations".

#: For details on the implementation of transactions with the EJB client, see

3.5 Implementing transactions with the EJB client applications

in the

uCosminexus Application Server EJB Container Functionality Guide

.

Tip

From among the resources, the transactions are not managed for the SMTP server and JavaBeans resources.

Reference note

You can also start a transaction with the EJB client application. For the notes on starting transactions with the EJB client

applications, see

3.20 Notes on starting transactions with the EJB client applications

.

3.4.1 Transaction management methods for the resource connections

The transaction management methods for the resource connections include the Application Server-managed method and non-Application Server-managed method (user-managed method). This subsection describes each transaction management method.

113

3. Resource Connections and Transaction Management

(1) Application Server-managed transactions

In this method, transactions are managed through the Application Server transaction manager. The user manages the transaction either by operating the APIs of the javax.transaction.UserTransaction

interface or by specifying the CMT attributes of the EJB method.

• Management by the UserTransaction interface

You can manage the transactions by issuing the APIs of the javax.transaction.UserTransaction

interface from the servlets, JSPs, or EJBs (BMT). For details on the BMT, see

2.7.2 BMT

in the

uCosminexus

Application Server EJB Container Functionality Guide

.

• Management by the CMT attributes of the EJB

You can manage the transactions using the transaction attributes specified for each EJB (CMT) method. For details on the CMT, see

2.7.3 CMT

in the

uCosminexus Application Server EJB Container Functionality Guide

.

For Application Server-managed transactions, you can choose a local transaction or global transaction as the transaction type. For the types of Application Server-managed transactions, see

3.4.2 Local transaction and global transaction

.

(2) User-managed transactions (Transactions not managed by Application Server)

In this method, the user directly manages the transactions using the resource-specific APIs. For example, when the

JDBC interface is used to connect to the database, the user directly operates the APIs such as setAutoCommit()

, commit()

, and rollback()

of the java.sql.Connection

interface.

3.4.2 Local transaction and global transaction

When you use the Application Server-managed transactions, you integrate the Application Server transaction manager and the resource manager (such as DBMS) that manages the resources to manage the transactions. In this case, you choose either a local transaction or a global transaction as the transaction type.

This subsection describes the local transactions and global transactions.

(1) Local transactions

You use a local transaction when only one resource manages the transactions. When you use a local transaction, the resource manager concludes the transaction.

(2) Global transactions

You use a global transaction when multiple resources manage the transactions. When you use a global transaction, the transaction manager adjusts the multiple resource transactions and concludes the transactions in such a way that the consistency is not lost. The two-phase commit protocol is used to conclude the transactions. Note that when you use a global transaction, the in-process transaction service is used. For details on the in-process transaction service, see

3.14.6 In-process transaction service

.

The cost of processing a global transaction is comparatively higher, so we recommend that you use a local transaction when the transactions are managed by a single resource only.

Note that the light transaction functionality

#

is enabled by default, so you cannot use a global transaction. To use a global transaction, you must disable the light transaction functionality.

#

For details on the light transactions, see

3.14.5 Light transactions

.

(3) Relationship between the light transaction functionality and transaction management methods

The

light transaction functionality

provides an optimal environment for the local transactions.

The following table describes the mapping between the transaction management methods and light transactions.

114

3. Resource Connections and Transaction Management

Table 3

11: Mapping the transaction management methods and light transactions

Transaction management method Light transaction enabled Light transaction disabled

Application Server-managed transactions

Local transaction

Global transaction

Non-Application Server-managed transactions

Y

N

Y

Y

Y

Y

Legend:

Y: Available

N: Not available

For details on the light transaction functionality, see

3.14.5 Light transactions

.

3.4.3 Transaction types available for each resource

This subsection describes the transaction types available for the following resources:

Database (Connection method: DB Connector)

Database queue (Connection method: DB Connector for Cosminexus RM and Cosminexus RM)

OpenTP1 (Outbound connection) (Connection method: uCosminexus TP1 Connector or TP1/Message Queue -

Access)

OpenTP1 (Inbound connection) (Connection method: TP1 inbound adapter)

CJMSP Broker (Connection method: CJMSP resource adapter)

Other resources (Connection method: Resource adapters conforming to the Connector 1.5 specifications)

The transaction types available for each resource are determined by the settings in the following items:

Transaction support levels specified for each resource adapter

Different transaction types are available for each of the following three transaction support levels:

NoTransaction

The resource transactions are not managed.

LocalTransaction

The resource transactions are managed using a local transaction.

XATransaction

The resource transactions are managed using a global transaction.

Note that the settings for the transaction support levels are specified as the resource adapter properties. For details on the resource adapter settings, see

3.4.12 Settings in the execution environment

.

Enabling and disabling of the light transaction functionality

The available transaction types differ based on whether the light transaction functionality is enabled or disabled.

(1) For database connections

The following table describes the transaction types determined by the mapping between the connection methods and transaction support levels.

Table 3

12: Available transaction types (for database connections)

Light transaction functionality

Connection method Transaction support level

Enabled Disabled

DB Connector

(DBConnector_HiRDB_Type4_CP.rar)

(DBConnector_Oracle_CP.rar)

NoTransaction

LocalTransaction

No

Local

No

Local

115

3. Resource Connections and Transaction Management

Connection method Transaction support level

Light transaction functionality

Enabled Disabled

Local Local (DBConnector_SQLServer_CP.rar)

(DBConnector_CP_ClusterPool_Root.ra

r)

(DBConnector_Oracle_CP_ClusterPool_

Member.rar)

DB Connector

(DBConnector_HiRDB_Type4_XA.rar)

(DBConnector_Oracle_XA.rar)

Legend:

Global: Global transaction

Local: Local transaction

No: Transactions are not managed

--: Cannot be specified

LocalTransaction

XATransaction

-Global

(2) For connecting to a database queue

The following table describes the transaction types determined by the mapping between the connection methods and transaction support levels.

Table 3

13: Available transaction types (for connecting to a database queue)

Light transaction functionality

Connection method Transaction support level

Enabled Disabled

NoTransaction

LocalTransaction

No

Local

No

Local

DB Connector for Cosminexus RM and Cosminexus

RM

(

DBConnector_HiRDB_Type4_CP_Cosminex us_RM.rar

)

(

DBConnector_Oracle_CP_Cosminexus_RM

.rar

)

DB Connector for Cosminexus RM and Cosminexus

RM

(

DBConnector_HiRDB_Type4_XA_Cosminex us_RM.rar

)

(

DBConnector_Oracle_XA_Cosminexus_RM

.rar

)

XATransaction

-Global

Legend:

Global: Global transaction

Local: Local transaction

No: Transactions are not managed

--: Cannot be specified

(3) For OpenTP1 connections (Outbound connection)

The following table describes the transaction types determined by the mapping between the connection methods and transaction support levels.

116

3. Resource Connections and Transaction Management

Table 3

14: Available transaction types (For OpenTP1 connections (Outbound connection))

Light transaction functionality

Connection method Transaction support level

Enabled Disabled uCosminexus TP1 Connector

TP1/Message Queue - Access

NoTransaction

LocalTransaction

XATransaction

NoTransaction

LocalTransaction

XATransaction

No

Local

No

Local

--

--

No

Local

Global

No

Local

Global

Legend:

Global: Global transaction

Local: Local transaction

No: Transactions are not managed

--: Cannot be specified

(4) For OpenTP1 connections (Inbound connection)

For details on the transaction types available for the TP1 inbound adapter, see

3.13.2 Functionality available for other resource connections

.

(5) For CJMSP Broker connections

The following table describes the transaction types determined by the mapping between the connection methods and transaction support levels.

Table 3

15: Available transaction types (For CJMSP Broker connections)

Light transaction functionality

Connection method Transaction support level

Enabled Disabled

CJMSP resource adapter

NoTransaction

LocalTransaction

XATransaction

No

Local

--

No

Local

--

Legend:

Local: Local transaction

No: Transactions are not managed

--: Cannot be specified

(6) For the other resources

For details on the transaction types available for the resource adapters conforming to the Connector 1.5 specifications,

see

3.13.2 Functionality available for other resource connections

.

3.4.4 Functionality provided with the transaction services

The transaction service provides the following functionality. Note that with Application Server, a transaction service is started as an in-process of the J2EE server.

• Controlling the start, commit conclusion, and rollback conclusion of global transactions

117

3. Resource Connections and Transaction Management

This functionality controls the transaction processing using the two-phase commit protocol. The two-phase commit protocol is a method that separates the processing at the synchronization points into two stages, the prepare processing (resource update preparation) and the commit processing (resource update processing). With the two-phase commit protocol, you can synchronize, commit, or roll back multiple resource objects such as

DBMS. Also, even if an error occurs during the transaction processing, you can consistently and automatically roll back all the resource objects with the two-phase commit protocol.

• Propagating the transaction context (Invoking Enterprise Beans using the RMI-IIOP)

This functionality manages the transaction context that indicates the state of the global transaction. For example, when a client, such as a servlet/ JSP, invokes the remote Enterprise Bean method, this functionality transmits the client-side transaction context to the server-side Enterprise Bean.

• System recovery by managing the transaction information using the status files and restarting the J2EE server after an error occurs

When the J2EE server stops due to a system error, this functionality recovers the transaction processing of the application programs that were running, and rolls back or commits the transaction processing. Whether the transaction is rolled back or committed is determined based on the extent to which the transaction processing has progressed. From the two-phase commit, if the transaction processing has progressed until the pre-completion of the first phase, the global transaction is rolled back. If the first phase from the two-phase commit is complete, the global transaction is rolled back or committed according to the decision for the root transaction branch.

• Duplicating the status file

When you use the status file duplication functionality, if an error occurs on the disk where one status file is allocated, the transaction is recovered using the other status file

#

. However, if you use this functionality, the disk is accessed twice, so the online processing response time is delayed.

#

The online processing cannot be continued.

• Reporting errors during heuristic conclusion in the resource manager

When a heuristic conclusion is detected in the resource manager for resources such as databases, this functionality reports the error through messages.

3.4.5 Transaction operations during system exceptions

During an EJB invocation, the behavior of the invocation source transaction when a system exception occurs at the invocation destination varies as follows depending on the system definition.

(1) When the invocation destination inherits the invocation source transaction (when the transaction attributes of the invocation destination are Required, Supports, and

Mandatory of the CMT)

If a system exception is returned at the invocation destination, the transaction is rolled back by the container. This operation is defined in the EJB specifications.

(2) When the invocation destination does not inherit the invocation source transaction (when the transaction attributes of the invocation destination are BMT, or NotSupported,

RequiresNew, and Never of the CMT)

The invocation source and invocation destination transactions respectively operate as follows:

Invocation source transaction

During remote invocation in the EJB remote interface

When the light transaction is disabled:

The OTS marks the transaction for roll back.

When the light transaction is enabled:

The transaction is not marked for roll back.

During local call optimization in the EJB remote interface

118

3. Resource Connections and Transaction Management

The operation differs based on the value of the ejbserver.distributedtx.rollbackClientTxOnSystemException

key in usrconf.properties

.

If true :

The transaction is marked for roll back.

If false

:

The transaction is not marked for roll back.

During the invocation of the EJB local interface

The transaction is marked for roll back.

Invocation destination transaction

The transaction is rolled back by the container. This operation is defined in the EJB specifications.

For details on the local call optimization, see

2.13.1 Local call optimization in the EJB remote interface

in the

uCosminexus Application Server EJB Container Functionality Guide

.

3.4.6 Obtaining the transaction manager

The transaction manager ( javax.transaction.TransactionManager

or javax.transaction.Transaction

) provides APIs for managing transactions. To use the framework that uses the transaction manager APIs, you can use the JNDI to obtain the transaction manager. To obtain the transaction manager, look up with the name java:comp/TransactionManager

.

This subsection describes the transaction manager APIs supported by Application Server, and the notes on using

Synchronization.

(1) Supported APIs

The following table describes the transaction manager APIs supported by Application Server.

Table 3

16: Transaction manager APIs supported by Application Server

Interface Method javax.transaction.TransactionManager

javax.transaction.Transaction

begin commit getStatus getTransaction resume rollback setRollbackOnly setTransactionTi meout suspend commit delistResource enlistResource getStatus registerSynchron ization rollback

Availability

Y

Y

Y

Y

Y

Y

Y

Y

--

--

Y

Y

Y

Y

Y

119

3. Resource Connections and Transaction Management

Interface Method javax.transaction.Transaction

setRollbackOnly

Legend:

Y: Available

--: Not available

Note: If you try to use an unavailable method, javax.transaction.SystemException

is thrown.

Availability

Y

(2) Notes on using the transaction manager

To use the transaction manager obtained through lookup, implement the processing included in transaction management (such as obtaining, using, and releasing the database connections) in the following range-after the transaction starts and before the transaction concludes, or after the transaction starts and before the transaction is suspended, and after the transaction is restarted and before the transaction concludes. The processing that is implemented before the transaction starts, after the transaction concludes, and while the transaction is suspended, is not included in the transaction management.

Do not use

UserTransaction

with the components that use the transaction manager to control transactions.

A transaction started with the begin method of the transaction manager

( javax.transaction.TransactionManager

) times out at a specified time if the timeout value is specified with the setTransactionTimeout

method before the begin

method is invoked. If the setTransactionTimeout

method is not invoked, the transaction times out at the value (default 180 seconds) specified in the ejbserver.jta.TransactionManager.defaultTimeOut

property of the logical

J2EE server in the Easy Setup Definition file.

(3) Notes on using Synchronization

You cannot use the services provided by the J2EE server with the beforeCompletion

method and afterCompletion method of Synchronization ( javax.transaction.Synchronization

) registered using the registerSynchronization

method of the transaction ( javax.transaction.Transaction

). The examples of services that are not available are as follows:

Resource access

Transaction operations using UserTransaction or CMT

EJB access

JNDI access

From among these services, when resource access is performed, some of the transactions managed by the transaction manager are not managed when the resources are accessed, so a mismatch might occur. To access the resources, specify settings in any framework so that the framework controls the direct transactions for the resources.

Because the above precautions need to be taken, we do not recommend the use of Synchronization in the user programs. If you want to use the transaction conclusion timing from the user program, use javax.ejb.SessionSynchronization

of the EJB.

3.4.7 Overview of processing and the points to remember when using the container-managed transactions (CMT)

If you use a container-managed transaction, you can automatically start the transaction just before the Enterprise Bean business method is invoked and automatically commit the transaction immediately after the processing of the business method ends. The transaction management processing need not be coded as a user program coding at all, and you can easily manage the transactions for accessing the resources.

The following figure shows the sequence for using the container-managed transactions.

120

3. Resource Connections and Transaction Management

Figure 3

13: Sequence for using the container-managed transactions

Remember the following points when you use the container-managed transactions:

When you use the container-managed transactions, you can specify the transaction attributes for each Enterprise

Bean method. You can specify either

Required

,

RequiresNew

,

Mandatory

,

Supports

,

NotSupported

, or

Never

. To use the transaction, specify

Container

in the

<transaction-type>

tag of the DD, and specify the transaction attributes for each method in the

<trans-attribute>

tag. You can also specify the definition in an annotation without using the DD. For details on the transaction attributes, see

2.7.3 CMT

in the

uCosminexus Application Server EJB Container Functionality Guide

. For details on the annotations, see

2. Annotations and Dependency Injection supported by Application Server

in the

uCosminexus

Application Server API Reference Guide

.

When you access the resources in the business method used after the transaction is started, the resource access transactions are automatically managed.

To access multiple resources after the transaction starts, you must use a resource adapter that supports the global transactions, and set the transaction support level of the resource adapter to

XATransaction

.

When you use the container-managed transactions, you need not code the processing for transaction management as the user program coding.

You can use the container-managed transactions with Enterprise Beans. The container-managed transactions cannot be used with servlets and JSPs.

3.4.8 Overview of processing and the points to remember when using the UserTransaction interface

If you use the

UserTransaction

interface, you can send the transaction start and conclusion instructions from the user program to the transaction manager. Use this method when you want to minutely control the transaction with the user program.

To send the transaction start and conclusion instructions from the user program to the transaction manager:

1. Obtain the

UserTransaction

object.

You obtain the UserTransaction object using one of the following methods:

Method of using the JNDI from the Naming Service and looking up "java:comp/UserTransaction"

Method of obtaining the

UserTransaction

object by invoking the getUserTransaction

method of the EJBContext interface

Method of obtaining the UserTransaction object by using the DI

2. Invoke the begin

method of the

UserTransaction

object to start the transaction.

3. Access the resources.

121

3. Resource Connections and Transaction Management

4. Invoke the commit

method or rollback

method of the

UserTransaction

object to conclude the transaction.

The following figure shows the sequence for using the UserTransaction interface.

Figure 3

14: Sequence for using the UserTransaction interface

Remember the following points when you use the UserTransaction interface:

To use the

UserTransaction

interface, specify

Bean

in the

<transaction-type>

tag of the DD. You can also specify the definition in an annotation without using the DD. For details on annotations, see

2.

Annotations and Dependency Injection supported by Application Server

in the

uCosminexus Application Server

API Reference Guide

.

When you access the resources after the transaction is started, the resource access transactions are automatically managed.

To access multiple resources after the transaction starts, you must use a resource adapter that supports the global transactions, and set the transaction support level of the resource adapter to

XATransaction

.

The

UserTransaction

interface can be used with Enterprise Beans, servlets, and JSPs.

A transaction that is started with the user program by using the

UserTransaction

interface must be concluded by issuing commit

or rollback

with the user program even if an exception occurs. If the transaction is not concluded, problems, such as the resource lock is not released, or the subsequent transactions cannot be started, might occur.

3.4.9 Overview of processing and the points to remember when using the resource adapter-specific transaction management interface

The user program can directly control the resource transactions by using the resource adapter-specific interfaces. For example, if DB Connector exists, the user program can directly control the resource transactions by using the setAutoCommit method, commit method, and rollback method of the Connection interface.

122

3. Resource Connections and Transaction Management

The following figure shows the sequence for using the resource adapter-specific transaction management interface.

Figure 3

15: Sequence for using the resource adapter-specific transaction management interface

Remember the following points when you use the resource adapter-specific transaction management interface:

The functionality provided by transaction manager, such as transaction timeout, cannot be used.

The transactions for the access of multiple resources cannot be managed.

3.4.10 Overview of processing and the points to remember when transactions are not used

You can also choose to not manage the resource access transactions. You can use this method to reduce the cost of transaction management when the resources are only referenced.

The following figure shows the sequence when transactions are not used.

Figure 3

16: Sequence when transactions are not used

123

3. Resource Connections and Transaction Management

Remember the following points when you do not use transactions:

Transactions are not used when you specify

Container

in the

<transaction-type>

tag and specify either

NotSupported or Never in the <trans-attribute> tag of the Enterprise Bean DD. You can also specify the definition in an annotation without using the DD. For details on the transaction attributes, see

2.7.3 CMT

in the

uCosminexus Application Server EJB Container Functionality Guide

. For details on annotations, see

2.

Annotations and Dependency Injection supported by Application Server

in the

uCosminexus Application Server

API Reference Guide

.

Transactions are not used when you specify

Bean

in the

<transaction-type>

tag of the Enterprise Bean

DD, and invoke the begin

method of the

UserTransaction

object. You can also specify the definition in an annotation without using the DD. For details on annotations, see

2. Annotations and Dependency Injection supported by Application Server

in the

uCosminexus Application Server API Reference Guide

.

Transactions are not used when the begin

method of the

UserTransaction

object is invoked by servlets and

JSPs.

You can also choose to manage the access to a specific resource adapter without using transactions. To realize this, set the transaction support level of the resource adapter that will not be managed using transactions to

NoTransaction

. The transactions are not managed for a resource adapter with the transaction support level

NoTransaction

even if the resource is accessed after the transaction starts.

3.4.11 Notes on the JTA-based transaction implementation

The following table describes the processing content and operations of the programs that use the JTA to implement transactions.

Table 3

17: JTA operations

Processing content Operations

When an exception inheriting java.rmi.RemoteException

or java.rmi.RemoteException

occurs during EJB invocation

When a CORBA system exception occurs

When the javax.transaction.UserTransaction.commit

method is invoked after a transaction timeout occurs

Whether the client-side transactions will be marked for rollback varies according to the property

( ejbserver.distributedtx.rollbackClientTxOnSy

stemException

) settings. For details on the values set for the properties and the operations, see

3.4.5 Transaction operations during system exceptions

.

The javax.transaction.RollbackException

exception occurs. However, if you invoke the

UserTransaction.commit

method two or more times after a transaction timeout occurs, the java.lang.IllegalStateException

exception occurs from the second time onwards.

An exception does not occur.

When the javax.transaction.UserTransaction.rollback

method is invoked after a transaction timeout occurs

Return value of the javax.transaction.UserTransaction.getStatus

method after the transaction timeout javax.transaction.Status.STATUS_ROLLEDBACK

is returned. However, after the UserTransaction.commit

method, or

UserTransaction.rollback

method is invoked, javax.transaction.Status.STATUS_NO_TRANSACTIO

N is returned.

An exception does not occur and the EJB can be invoked.

EJB invocation from the beforeCompletion method or afterCompletion

method of the EJB for which javax.ejb.SessionSynchronization

is implemented

3.4.12 Settings in the execution environment

To use the resource connection and transaction management functionality, you must set up the J2EE server and the resource adapters.

124

3. Resource Connections and Transaction Management

(1) J2EE server settings

Specify the J2EE server settings with the Easy Setup definition file. Define the resource connection and the transaction management functionality in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy Setup definition file. The following table describes the settings in the Easy Setup definition file. Note that with transaction management you can also specify a transaction timeout.

For details on the Easy Setup Definition file and parameters, see

4.6 Easy Setup Definition file

in the

uCosminexus

Application Server Definition Reference Guide

.

For details on the transaction timeout, see

3.15.8 Transaction timeout and statement cancellation

.

Table 3

18: Definition in the Easy Setup definition file for using the resource connection and transaction management functionality

Items

Transaction types

Specified parameters ejbserver.distributedtx.XATransaction.enabled

Client transaction operations when a system exception occurs

Directory storing the status file ejbserver.distributedtx.rollbackClientTxOnSystemEx

ception

ejbserver.distributedtx.ots.status.directory1

ejbserver.distributedtx.ots.status.directory2

Settings

Specifies whether to use the light transaction or the global transaction. By default, the light transaction is enabled.

Specifies whether to mark the client transaction for rollback when a system exception occurs.

Timeout in error detection ejbserver.connectionpool.validation.timeout

Specified as a directory for storing the status file of the in-process transaction service and the status file backup.

Specifies the timeout value for the connection error detection functionality and the timeout value for the deletion of connections using the connection count adjustment functionality.

!

Important note

Specifying the directory for storing the status file of the in-process transaction service and the status file backup

To guarantee transaction consistency, the in-process transaction service imports the host name or IP address as the identity information of the J2EE server into the status file. Therefore, to change the value set in the vbroker.se.iiop_tp.host

parameter in the J2EE server configuration definition, or to change the IP address of the computer on which the J2EE server is running, without specifying the vbroker.se.iiop_tp.host

parameter:

1. Stop the J2EE server when there are no transactions on the J2EE server.

2. Change the IP address, or the settings in the vbroker.se.iiop_tp.host

parameter.

3. Delete the directory specified in the ejbserver.distributedtx.ots.status.directory1

parameter.

4. Start the J2EE server.

(2) Resource adapter settings

Use the server management commands and property files to specify the resource adapter settings in the execution environment. Define the functionality for managing transactions in the <resourceadapter> tag of the HITACHI

Connector Property file. The following table describes the settings.

For details on the HITACHI Connector Property file, see

4.1 HITACHI Connector Property file

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

125

3. Resource Connections and Transaction Management

Table 3

19: Definition in the HITACHI Connector Property file for the transaction management functionality

Items Specified tags Settings

Transaction support level

<outbound-resourceadapter>-<transaction-support>

tag Specifies the transaction support levels.

Specify no transaction management

( NoTransaction ), local transaction

(

LocalTransaction

), or global transaction

(

XATransaction

).

126

3. Resource Connections and Transaction Management

3.5 Resource sign-on method

You can choose one of the following methods as a resource sign-on method:

• Container-managed sign-on

In this method, Application Server is used to automatically sign-on to the resource. In this method, if you set up the user name and password for each resource adapter, Application Server automatically transmits the user name and password to the resource when the connection is obtained.

To use the container-managed sign-on, specify

Container

in the

<res-auth>

tag within the

<resourceref>

tag of the DD for Enterprise Beans and servlets.

• Component-managed sign-on

In this method, the user program is used to sign-on to the resource. To use this method, the user name and password used when the connection is obtained is specified in the user program.

Example: For DB Connector

When you invoke getConnection of the DataSource class, specify the user name and password in the argument.

To use the component-managed sign-on, specify Application in the <res-auth> tag within the

<resource-ref>

tag of the DD for Enterprise Beans and servlets.

If connection pooling is used, we recommend that you use the container-managed sign-on that can efficiently re-use connections.

Note that when you use Setup Wizard to set up the system, application authentication cannot be used because true is specified in ejbserver.connectionpool.applicationAuthentication.disabled

.

127

3. Resource Connections and Transaction Management

3.6 Connecting to a database

This section describes the functionality of using DB Connector to connect to a database.

The following table describes the organization of this section.

Table 3

20: Organization of this section (Connecting to a database)

Category Title

Explanation Overview of connections using DB Connector

Available J2EE components and functionality

Connectable databases

Types of DB Connectors (RAR file)

Preconditions and notes on connecting to HiRDB

Preconditions and notes on connecting to Oracle

Preconditions and notes on connecting to SQL Server

3.6.6

3.6.7

Settings

Preconditions and notes on connecting to XDM/RD E2

Settings in the execution environment (resource adapter settings)

Note: The functionality-specific explanation is not available for "Implementation" and "Operations".

3.6.8

3.6.9

3.6.1

3.6.2

3.6.3

3.6.4

3.6.5

Reference location

The databases that you can connect to by using DB Connector include HiRDB, Oracle, SQL Server, and XDM/RD

E2. When you connect to a database, the information such as the database connection methods and available JDBC drivers differ according to the type of database you want to connect to. This section describes the preconditions for database connections and the available functionality.

3.6.1 Overview of DB Connector-based connections

To connect to a database, you can use DB Connector as the resource adapter. DB Connector is a resource adapter for accessing the database using the JDBC. To use DB Connector, you look up the connection factory

( javax.sql.DataSource

interface) from the J2EE application.

The following figure gives an overview of connections using DB Connector.

Figure 3

17: Overview of connections using DB Connector

128

With the database connections using DB Connector, you use HiRDB Type4 JDBC Driver, Oracle JDBC Thin Driver, or SQL Server as the JDBC drivers.

For details on the DB Connector settings, see

3.6.9 Settings in the execution environment (resource adapter settings)

, and

4.2 Settings for connecting to a database

in the

uCosminexus Application Server Application Setup Guide

.

For details on the connection methods for connecting to a database queue, see

3.7 Connecting to a database queue

.

3. Resource Connections and Transaction Management

!

Important note

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter. When you customize a J2EE application that uses the resource adapters, resolve the references from the J2EE application to the resource adapter.

3.6.2 Available J2EE components and functionality

This subsection describes the functionality available for the database connections.

The following table provides a database-wise description of the J2EE components and functionality available for the database connections.

Table 3

21: Available J2EE components and functionality

Items HiRDB Oracle11g SQL Server XDM/RD E2

J2EE components Servlet/JSP

Stateless Session Bean

Stateful Session Bean

Singleton Session Bean

Entity Bean (BMP)

Entity Bean (CMP 1.1)

Entity Bean (CMP 2.0)

Y

Y

Y

Y

#1

Y

Y

Y

Y

N

N

Y

Y

Y

Y

Y

Y

N

N

Y

Y

Y

Y

Y

Y

N

N

Y

N

Y

Y

Y

Y

Available functionality

Message-driven Bean

(database access from the onMessage

method)

Connection pooling

Connection pool warming up

Connection sharing association

Caching the

DataSource object

Optimizing the containermanaged sign-on for DB

Connector

Connection count adjustment functionality

Connection sweeper functionality

Displaying the connection pool information

( cjlistpool command)

Clearing the connection pool ( cjclearpool command)

Connection test for resources

Detecting the connection errors

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

R

#5

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

129

3. Resource Connections and Transaction Management

Available functionality

Items

Timeout in detecting connection errors

Waiting to obtain connections during connection depletion

Retrying a connection

Auto-closing a connection

Suspending a connection pool

Restarting a connection pool

Statement pooling

Statement cancellation

Statement setQueryTimeout method

Optional name functionality for J2EE resources

Functionality for reporting exceptions occurring in

Client APIs

PRF trace output of the connection ID

Output of the SQL statement for troubleshooting

Connection pool clustering

HiRDB

Y

Y

Y

Y

Y

Y

Y

#2

Y

Y

Y

Y

Y

Y

Oracle11g

R

R

Y

Y

Y

Y

#6

#6

Y

Y

#3

Y

#3

Y

Y

Y

Y

SQL Server

Y

Y

Y

Y

N

N

Y

Y

Y

Y

Y

N

Y

XDM/RD E2

Y

Y

Y

Y

Y

Y

Y

#2

Y

N

Y

Y

Y

Y

N

Y

#4 N N

Legend:

Y: Available

N: Not available

R: Partially restricted

#1: The CMR functionality, which is the CMP 2.0 functionality, is not available.

#2: The HiRDB auto-reconnect functionality and the statement pooling functionality cannot be used together.

#3 Precautions need to be taken when you connect to Oracle. For details, see

3.6.6 Preconditions and notes on connecting to Oracle

.

#4: This functionality is available when the RAC functionality is used and when Oracle JDBC Thin Driver is used for connection.

#5: This functionality is not available when you use a member resource adapter to connect to Oracle11g.

#6: This functionality is available when you use a member resource adapter to connect to Oracle11g.

3.6.3 Connectable databases

This subsection describes the databases that can be connected to by using DB Connector.

(1) Types of connectable databases

The databases that you can connect to by using DB Connector include HiRDB, Oracle, SQL Server, and XDM/RD

E2. Note that you cannot use global transactions with SQL Server and XDM/RD E2.

130

3. Resource Connections and Transaction Management

(2) Mapping the databases and JDBC drivers

To connect to a database by using DB Connector, you require a JDBC driver compatible with the database. The following table describes the mapping between the database to be connected to and the available JDBC drivers.

Table 3

22: Database to be connected to and the available JDBC drivers (for database connections)

JDBC driver

Database

HiRDB Type4 JDBC Driver Oracle JDBC Thin Driver JDBC driver for SQL Server

HiRDB

Oracle

SQL Server

XDM/RD E2

N

Y

M

N

N

N

N

M

Y

N

N

N

Legend:

M: Available and usage is recommended.

Y: Available.

N: Not available.

(3) JDBC specifications supported by DB Connector

The following table describes the JDBC drivers used for connections and the JDBC specifications supported by DB

Connector. However, if the JDBC drivers used for connections do not support the functionality provided in the JDBC specifications, that functionality cannot be used with DB Connector.

Table 3

23: JDBC drivers used for connections and the JDBC specifications supported by DB Connector

JDBC drivers used for connections JDBC specifications supported by DB Connector

HiRDB Type4 JDBC Driver

Oracle JDBC Thin Driver

SQL Server JDBC Driver 3.0

JDBC Driver 4.0 for SQL Server

JDBC 4.0

JDBC 4.0

JDBC 3.0

JDBC 4.0

Tip

Oracle JDBC Thin Driver supports functionality in the range defined in the JDBC 4.0 specifications. The Oracle extension functionality using the classes and interfaces in the Oracle package is not available.

Also, when Application Server connects to a database by using Oracle JDBC Thin Driver, the extension functionality of

Oracle JDBC Thin Driver, statement cache and connection cache functionality, cannot be used. Use the statement pooling or connection pooling provided with Application Server. For details on statement pooling or connection pooling, see

3.14

Functionality for performance tuning

.

Note that the java.sql.Wrapper

interface is not supported. If a method of the

Wrapper

interface is used, the

UnsupportedOperationException

exception is thrown.

!

Important note

From among the methods of the java.sql.Statement

interface in the JDBC specifications, the following methods are not supported:

setCursorName(String name) setFetchDirection(int direction)

131

3. Resource Connections and Transaction Management

3.6.4 Types of DB Connectors (RAR file)

When you use DB Connector to connect to a database, you use the RAR file supported by the JDBC driver to be used.

Use the server management commands to operate the RAR file. For details on how to operate the RAR file by using the server management commands, see the

uCosminexus Application Server Application Setup Guide

.

The following table describes the types of JDBC drivers and the corresponding RAR files.

Table 3

24: Mapping the JDBC drivers and RAR files

JDBC driver RAR file Explanation

Use this file when transactions are not managed, or when a local transaction is used.

Use this file when a global transaction is used.

HiRDB Type4 JDBC

Driver

DBConnector_HiRDB_Type4_C

P.rar

DBConnector_HiRDB_Type4_X

A.rar

#

DBConnector_Oracle_CP.rar

Oracle JDBC Thin

Driver

DBConnector_Oracle_XA.rar

#

DBConnector_CP_ClusterPoo l_Root.rar

DBConnector_Oracle_CP_Clu sterPool_Member.rar

JDBC driver for SQL

Server

DBConnector_SQLServer_CP.

rar

#: The light transaction functionality cannot be enabled.

Use this file when transactions are not managed, or when a local transaction is used.

Use this file when a global transaction is used.

Use this file when the root resource adapter is used with the connection pool clustering functionality.

Use this file when the member resource adapter is used with the connection pool clustering functionality.

This RAR file is used to connect to SQL Server. Use this file when transactions are not managed, or when a local transaction is used.

3.6.5 Preconditions and notes on connecting to HiRDB

This subsection describes the preconditions and notes on connecting to HiRDB. The available JDBC drivers differ according to the HiRDB version.

(1) Preconditions for HiRDB Version 8

The preconditions for HiRDB Version 8 are as follows:

• Available JDBC driver

The available JDBC driver is HiRDB Type4 JDBC Driver.

• Connection method

You use one of the following RAR files:

DBConnector_HiRDB_Type4_CP.rar

DBConnector_HiRDB_Type4_XA.rar

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

25: Transaction support levels available for each RAR file (HiRDB Version 8)

Light transaction

Used DB Connector

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_HiRDB_Type4_CP.rar

Y Y

DBConnector_HiRDB_Type4_XA.rar

NoTransaction

LocalTransaction

XATransaction

-Y

132

3. Resource Connections and Transaction Management

Legend:

Y: Available

--: Not applicable

(2) Preconditions for HiRDB Version 9

The preconditions for HiRDB Version 9 are as follows:

• Available JDBC driver

The available JDBC driver is HiRDB Type4 JDBC Driver.

• Connection method

You use one of the following RAR files:

DBConnector_HiRDB_Type4_CP.rar

DBConnector_HiRDB_Type4_XA.rar

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

26: Transaction support levels available for each RAR file (HiRDB Version 9)

Light transaction

Used DB Connector

(RAR file) transaction support level

Enabled Disabled

DBConnector_HiRDB_Type4_CP.rar

Y Y

DBConnector_HiRDB_Type4_XA.rar

NoTransaction

LocalTransaction

XATransaction

-Y

Legend:

Y: Available

--: Not applicable

(3) Notes on connecting to HiRDB

Note the following when you connect to HiRDB:

If you use the HiRDB auto-reconnect functionality, the connection is automatically re-established when the

HiRDB server is disconnected due to an error such as the database network error. However, if the connection is lost during a transaction, the

SQLException

exception occurs. When the J2EE application receives the

SQLException

exception, do not continue the processing. If you continue to access DBMS, problems such as data inconsistency might occur.

If you enable the connection pooling functionality and statement pooling functionality and use

Statement.cancel()

, the

SQLException

exception might occur. In this case, we recommend that you disable either the connection pooling functionality or statement pooling functionality.

If the J2EE applications satisfy all the following conditions, two connections are used, which is double the number of users using the HiRDB connections concurrently. Specify a value that is twice the number of users using the

HiRDB connections concurrently in the pd_max_users

operand of the HiRDB common system definitions. For details on the pd_max_users

operand, see the manual

HiRDB Version 9 System Definition

.

1. DB Connector is used with the transaction support level

XATransaction

.

2. The database is accessed by using the connection

#

in the Application Server-managed transactions.

3. Before the transaction in point 2 concludes, the database is accessed by using the connection transaction.

#

outside the

#: This connection is the same connection as the one obtained from DB Connector in point 1.

An error occurs when the J2EE applications satisfy all the following conditions:

1. DB Connector is used with the transaction support level XATransaction .

133

3. Resource Connections and Transaction Management

2. The database is accessed by using the connection

#

in the Application Server-managed transactions.

3. Before the transaction in point 2 concludes, the database is accessed by using the connection

#

outside the transaction.

#: This connection is the same connection as the one obtained from DB Connector in point 1.

If all the following conditions are satisfied, the same connection cannot participate in multiple different global transactions concurrently. Use a different connection for each transaction.

1. DB Connector is used with the transaction support level

XATransaction

.

2. The database is accessed by using the connection

#

in the Application Server-managed transactions.

3. Before the transaction in point 2 concludes, the database is accessed by using the connection transaction.

#

outside the

#: This connection is the same connection as the one obtained from DB Connector in point 1.

If you enable the HiRDB auto-reconnect functionality and statement pooling functionality, the SQLException exception containing message KFPA11901-E might occur during the execution of the SQL statement after the auto-reconnect functionality re-establishes the connection. When you connect to HiRDB using DB Connector with the transaction support level

LocalTransaction

or

NoTransaction

and enable the statement pooling functionality, do not use the HiRDB auto-reconnect functionality. When an error occurs, execute the connection error detection functionality or the cjclearpool command.

3.6.6 Preconditions and notes on connecting to Oracle

This subsection describes the preconditions and notes on connecting to Oracle.

(1) Preconditions for Oracle11g

The preconditions for Oracle11g are as follows:

• Available JDBC driver

The available JDBC driver is Oracle JDBC Thin Driver.

• Connection method

You use one of the following RAR files:

DBConnector_Oracle_CP.rar

DBConnector_Oracle_XA.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_Member.rar

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

27: Transaction support levels available for each RAR file (Oracle11g)

Light transaction

Used DB Connector

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_Oracle_CP.rar

Y Y

DBConnector_Oracle_XA.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_M ember.rar

NoTransaction

LocalTransaction

XATransaction

NoTransaction

LocalTransaction

--

Y

Y

Y

Legend:

Y: Available

134

3. Resource Connections and Transaction Management

--: Not applicable

(2) Notes on connecting to Oracle

Note the following when you connect to Oracle:

(a) Differences in the available J2EE components

The J2EE components available when you use Oracle JDBC Thin Driver to connect to Oracle are as follows:

Servlets /JSPs

Stateless Session Bean

Stateful Session Bean

Entity Bean (BMP)

Entity Bean (CMP2.0)

Message-driven Bean

(b) Settings for preventing the differences in Japanese character code conversion and garbled characters in

Oracle JDBC Thin Driver

When the data is stored in the database and when the data is extracted from the database, the JDBC driver converts the character code between Unicode and the database storage code appropriately. The following figure shows the locations where the character code conversion is implemented when you use Oracle JDBC Thin Driver.

Figure 3

18: Locations where the character code conversion is implemented when Oracle JDBC Thin

Driver is used

2

3

1

4

5

6

The following table describes the character code conversion executed at each location in the figure.

Table 3

28: Locations where the character code conversion is implemented when Oracle JDBC Thin

Driver is used

Location Implemented content

When the external data, such as a network or file, is read by the J2EE server, the external data code is converted to Unicode.

When the data read by the J2EE server is stored in the Oracle server, Unicode is converted to UTF-8. This code conversion is implemented by the JDBC driver part on the J2EE server.

The Oracle server converter converts UTF-8 to the database storage code. This code conversion is implemented on the Oracle server.

The Oracle server converter converts the database storage code to UTF-8.

When the data stored by the J2EE server is obtained from the Oracle server, UTF-8 is converted to Unicode.

When the data obtained with the J2EE server is written to a network or a file, Unicode is converted to the external data code.

135

3. Resource Connections and Transaction Management

When you use Oracle JDBC Thin Driver, the characters might get garbled due to the differences in the mapping rules supported by the converters for JavaVM and the Oracle server. The garbled characters occur due to the combination of the external data character code and the database storage code, and the combination of converters that perform the character code conversion.

To avoid garbled characters, use the following combinations of the external data character code and the database storage code:

• When the external data character code is Shift JIS (CP932)

Specify "AL32UTF8" or "JA16SJISTILDE" in the database storage code. Note that if you specify "JA16SJIS" in the database storage code, the "~" (swung dash) character gets garbled.

• When the external data character code is SJIS

Specify "AL32UTF8" in the database storage code. Note that if you specify "JA16SJIS" in the database storage code, the " 「 ", " 」 ", "//", and "-" characters get garbled.

• When the external data character code is EUC

Specify "AL32UTF8" in the database storage code. Note that if you specify "JA16EUC" in the database storage code, the "

" and "

" characters get garbled.

(c) Dedicated server connection

The following functionality is not available for dedicated server connections. To use the following functionality, use a shared server connection. For details, inquire with the Oracle Support Service.

Statement cancellation

Query timeout

(d) Return value of the select statement during the conclusion of a JTA transaction

When using Oracle with an XA transaction, if you issue the Oracle select

statements for multiple databases that were updated in a transaction during the conclusion of a JTA transaction, the return value of each select statement might be different. This is due to the restrictions in the distributed read consistency for Oracle.

(3) Method of connecting to Oracle using Oracle RAC

The method of connecting to Oracle using Oracle RAC varies according to the Oracle version or the functionality used for load balancing. The following table describes the mapping between the Oracle version, the functionality used for load balancing, and the RAR file used.

Table 3

29: Mapping between the Oracle version, functionality used, and the RAR file used

Oracle version Functionality used for load balancing DB Connector RAR file name

Oracle10g

Oracle11g

Application Server functionality (Connection pool clustering functionality)

Oracle functionality

DBConnector_CP_ClusterPool_Roo t.rar

DBConnector_Oracle_CP_ClusterP ool_Member.rar

DBConnector_Oracle_CP.rar

DBConnector_Oracle_CP_Cosminex us_RM.rar

3.6.7 Preconditions and notes on connecting to SQL Server

This subsection describes the preconditions and notes on connecting to SQL Server.

(1) Preconditions for SQL Server

The preconditions for SQL Server are as follows:

• Available JDBC driver

136

3. Resource Connections and Transaction Management

The available JDBC driver is JDBC driver for SQL Server.

• Connection method

Use

DBConnector_SQLServer_CP.rar

. The RAR file to be used varies according to the SQL Server to be connected to.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

30: Transaction support levels available for each RAR file (SQL Server)

Light transaction

Used DB Connector

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_SQLServer_CP.rar

NoTransaction

LocalTransaction

Y Y

Legend:

Y: Available

Note that you can only connect to SQL Server in Windows.

(2) Notes on connecting to SQL Server

This subsection describes the notes related to the character code conversion in the system and the notes on the DB

Connector settings when you connect to SQL Server.

(a) Notes on character code conversion in a system

When you are connected to SQL Server and want to store data containing a Japanese character code in the database, you must take into account the character code conversion in the system. This section gives an overview of the character code conversion in a system, and describes the notes on specifying the settings to avoid garbled characters.

With Java, the Japanese character code is expressed using Unicode. When you use SQL Server, the character code conversion is implemented during the processing between the Web client and Application Server and between

Application Server and SQL Server.

The following figure gives an overview of the character code conversion when SQL Server is used.

Figure 3

19: Overview of the character code conversion when SQL Server is used

A description of points 1 to 4 in the figure is as follows:

1. When Application Server receives data from the Web client, the external character code is converted to Unicode.

2. When Application Server stores the data in SQL Server, Unicode is converted to the database storage character code.

3. When the data stored in SQL Server is obtained by Application Server, the database storage character code is converted to Unicode.

137

3. Resource Connections and Transaction Management

4. When Application Server sends the data to the Web client, Unicode is converted to the external character code.

When you use SQL Server, problems such as garbled characters might occur depending on the combination of the external character code and database storage character code, and the types of converter used for implementing the character code conversion. To avoid garbling, you must note the character code settings.

SQL Server supports the character data types described in the following table. When you use SQL Server, you can prevent the occurrence of garbling during the character code conversion by using the Unicode data types.

Table 3

31: Character data types supported by SQL Server

Category Character data type

Unicode data types

Non-Unicode character data types nchar

, nvarchar

, ntext char

, varchar

, text

The following paragraphs describe the character code conversion when you use the Unicode data types and when you use the non-Unicode data types as the database storage character code in SQL Server:

When you use the Unicode data types

If true

(default value) is set in the sendStringParametersAsUnicode

key of the DB Connector property, garbling does not occur. If false

is set, and if you use Shift_JIS, EUC-JP, ISO-2022-JP, or UTF-8 in the external character code, garbling might occur.

When you use the non-Unicode character data types

Garbling might occur depending on the external character code settings.

When Windows-31J is used in the external character code

Garbling does not occur.

When Shift_JIS, EUC-JP, or ISO-2022-JP is used in the external character code

The characters such as those shown below might be garbled.

When UTF-8 is used in the external character code

The characters such as those shown below might be garbled.

(b) Notes on specifying the selectMethod property of DB Connector

The following table describes the notes on specifying direct

in the value of the selectMethod

property (item name of

<config-property-name>

) of DB Connector.

Table 3

32: Notes on specifying the selectMethod property of DB Connector

Condition Notes

The connection error detection functionality is enabled

Multiple

Statement

,

PreparedStatement and

CallableStatement

are generated concurrently

A connection error that occurs might be misdiagnosed as normal. As a result, the connection with an error might be returned to the user application program, so do not use the connection error detection functionality. When an error is detected, execute the cjclearpool

command.

The JDBC driver for SQL Server generates a connection to SQL Server for each concurrently generated statement.

Also, note that when the statement pooling functionality is used, connections are generated for each pooled statement, and a large amount of memory is consumed.

(3) Notes on connecting to SQL Server 2005

Make sure you use the connection pooling functionality to connect to SQL Server 2005.

The following events might occur depending on the behavior of SQL Server JDBC Driver 3.0:

138

3. Resource Connections and Transaction Management

(a) The database sessions are not disconnected and the unused sessions are left behind.

The database sessions are not disconnected and the un-used sessions are left behind until garbage collection occurs. To avoid this event, execute the javagc

command.

Note that this event occurs in the following conditions:

When the following operations are performed:

Connection test of DB Connector

Stopping the DB Connector

Execution of the cjclearpool

command

When the following functionality is executed:

Method cancellation functionality

Message KDJE31016-W is output.

Transaction timeout functionality

Message KDJE31002-W is output.

Connection count adjustment functionality

Message KDJE49532-I is output.

Connection sweeper functionality

Message KDJE50010-I is output when the managed connections are destroyed, including cases when the connection sweeper functionality is operated by setting the log or trace level output by DB Connector to

WARNING or INFORMATION.

(b) An attempt to obtain a connection fails.

When the number of database sessions reaches the maximum concurrent user connections for the database because the above-mentioned (a) database sessions are not disconnected, you can no longer generate new sessions. When you execute the getConnection method of the javax.sql.DataSource

interface from the user program, java.sql.SQLException

might occur. To avoid this event, specify

0

(unlimited) as the maximum concurrent user connections for the database.

Note that this event occurs when 1 or more is specified as the maximum concurrent user connections for the database.

(4) Notes on connecting to SQL Server 2008 or SQL Server 2012

The notes on connecting to SQL Server 2008 or SQL Server 2012 are as follows. Note that none of the precautions on using SQL Server 2005 are applicable.

Set the authentication mode of SQL Server 2008 or SQL Server 2012 to the mixed mode (Windows authentication and SQL Server authentication). For details on the authentication mode, see the documentation for SQL Server

2008 or SQL Server 2012.

You cannot specify both JDBC driver JAR files for SQL Server JDBC Driver 3.0 and JDBC driver JAR files for

JDBC Driver 4.0 for SQL Server in the user class path of the J2EE server.

You cannot specify the following settings with

DBConnector_SQLServer_CP.rar

:

Settings added in SQL Server JDBC Driver 2.0

responseBuffering encrypt hostNameCertificate trustServerCertificate trustStore trustStorePassword

Settings added in SQL Server JDBC Driver 3.0

sendTimeAsDatetime

Settings added in JDBC Driver 4.0 for SQL Server authenticationScheme

139

3. Resource Connections and Transaction Management

Therefore, to operate the default value of responseBuffering

as adaptive

, the adaptive buffering functionality is always enabled. For details, see the documentation for SQL Server 2008 or SQL Server 2012.

3.6.8 Preconditions and notes on connecting to XDM/RD E2

This subsection describes the preconditions and notes on connecting to XDM/RD E2.

• Available JDBC driver

The available JDBC driver is HiRDB Type4 JDBC Driver.

• Connection method

Use

DBConnector_HiRDB_Type4_CP.rar

.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

33: Transaction support levels available for each RAR file (XDM/RD E2)

Light transaction

Used DB Connector

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_HiRDB_Type4_CP.rar

NoTransaction

LocalTransaction

Y Y

Legend:

Y: Available

3.6.9 Settings in the execution environment (resource adapter settings)

You must set up the property files to use the functionality for connecting to a database.

Use server management commands and property files to specify the resource adapter settings in the execution environment. Use the HITACHI Connector Property file to define the functionality used for connecting to a database.

This subsection describes the common DB Connector settings for connecting to a database regardless of the functionality used.

• Waiting time until the database connection is established

Specify the time for which a J2EE application waits until a database connection is established with loginTimeout in the <config-property> tag.

For details on the database connection settings, see

4.2 Settings for connecting to a database

in the

uCosminexus

Application Server Application Setup Guide

.

140

3. Resource Connections and Transaction Management

3.7 Connecting to a database queue

This section describes the functionality of using DB Connector for Cosminexus RM and Cosminexus RM to connect to a database queue.

The following table describes the organization of this section.

Table 3

34: Organization of this section (Connecting to a database queue)

Category Title Reference location

Explanation Overview of connections using DB Connector for Cosminexus RM and Cosminexus

RM

Features of connections using DB Connector for Cosminexus RM and Cosminexus

RM

Available functionality

Connectable databases

Types of DB Connector for Cosminexus RM (RAR file)

3.7.1

3.7.2

3.7.3

3.7.4

3.7.5

Preconditions for connecting to a HiRDB queue

Preconditions for connecting to an Oracle queue

3.7.6

3.7.7

Settings Settings for connecting to a database queue

Note: The functionality-specific explanation is not available for "Implementation" and "Operations".

3.7.8

To connect to a database queue, you use DB Connector for Cosminexus RM and Cosminexus RM as the resource adapter.

For details on Cosminexus RM, see the manual

uCosminexus Application Server Reliable Messaging

. Also, for details

on the connectable databases, see

3.6 Connecting to a database

.

3.7.1 Overview of connections using DB Connector for Cosminexus RM and Cosminexus RM

DB Connector for Cosminexus RM is a resource adapter that is integrated with Cosminexus RM and uses the JMS interface to connect to a database.

By integrating with Cosminexus RM, you can use the JMS interface to access the database queue from the servlets,

JSPs, and Enterprise Beans (Session Beans, Entity Beans, and Message-driven Beans). You can also use the JDBC interface to access the database tables.

When you use the JMS interface and JDBC interface to access the same database, you can process the global transaction using a single-phase commit. Due to this, the processing performance improves. Also, the JMS interface and JDBC interface can share the physical connection used for the database connection, so the resources can be utilized effectively.

The following figure gives an overview of connections using DB Connector for Cosminexus RM and Cosminexus

RM.

141

3. Resource Connections and Transaction Management

Figure 3

20: Overview of connections using DB Connector for Cosminexus RM and Cosminexus RM

For database connections through DB Connector for Cosminexus RM and Cosminexus RM, you use HiRDB Type4

JDBC Driver or Oracle JDBC Thin Driver as the JDBC driver.

For details on the settings for DB Connector for Cosminexus RM, see

2.7 Functionality for DB Connector for

Cosminexus RM

in the manual

uCosminexus Application Server Reliable Messaging

.

3.7.2 Features of connections using DB Connector for Cosminexus RM and Cosminexus RM

This subsection describes the features of connections using DB Connector for Cosminexus RM and Cosminexus RM.

(1) Overview of processing by DB Connector for Cosminexus RM and Cosminexus RM

By using DB Connector for Cosminexus RM to integrate with Cosminexus RM, you can send and receive messages using the JMS interface for the database queue, and invoke the Message-driven Beans started by the messages.

When you connect to a database using DB Connector for Cosminexus RM and Cosminexus RM, the following can be realized because the JMS interface and JDBC interface share the physical connection used for access and the processing performance is improved:

Application of the local transactions

Single-phase commit for the global transactions

The following figure gives an overview of DB Connector for Cosminexus RM and Cosminexus RM processing when the JMS interface and JDBC interface are used to access the database from servlets, JSPs, or Enterprise Beans.

142

3. Resource Connections and Transaction Management

Figure 3

21: Overview of the processing for DB Connector for Cosminexus RM and Cosminexus RM

The database is accessed via Cosminexus RM using the JMS interface, and the database is accessed via DB Connector for Cosminexus RM using the JDBC interface. Note that to set up a queue on the database, the JDBC interface-based database access is used internally with Cosminexus RM. Therefore, the database is accessed via the JDBC driver.

Furthermore, with DB Connector for Cosminexus RM, the database is accessed via Cosminexus RM, by sharing the physical connection with Cosminexus RM. These resource adapters use the connection pool for Cosminexus RM to obtain the connections. As a result, the sharing of the physical connections is realized.

(2) Configuring the database connections using DB Connector for Cosminexus RM and

Cosminexus RM

This subsection describes the resource configuration pattern when DB Connector for Cosminexus RM and

Cosminexus RM are used for connection. The resource configurations for the following cases will be described here:

When the JMS interface is used alone

When the same database is accessed with the JMS interface and JDBC interface

When different databases are accessed with the JMS interface and JDBC interface

When the Message-driven Beans are used

Note that the connections can be shared when the same database is accessed with the JMS interface and JDBC interface and when the Message-driven Beans are used. However, to share a connection, the following preconditions must be satisfied:

Preconditions for connection sharing

A database queue is accessed using the JMS interface, and a table is accessed using the JDBC interface in the same transaction through the user program.

The database on which the queue is set by Cosminexus RM and the database that accesses the table are the same.

The same security information (user name and password) and sign-on method are used for accessing the database queue through the JMS interface and for accessing the table on the database through the JDBC interface.

The value

Shareable

is set in the

<res-sharing-scope>

tag of the DD for the J2EE application that specifies the reference to DB Connector for Cosminexus RM and Cosminexus RM.

!

Important note

When you use only the JDBC interface to access the database, use DB Connector as the resource adapter.

143

3. Resource Connections and Transaction Management

If the preconditions for connection sharing are not satisfied, do not access the database using both JMS interface and JDBC interface through DB Connector for Cosminexus RM and Cosminexus RM. In this case, set up the configuration described in

(c) When different databases are accessed with the JMS interface and

JDBC interface

, and use DB Connector to access the tables.

(a) When the JMS interface is used alone

When the database queue alone is accessed with the user program, use the configuration shown in the following figure.

Figure 3

22: Configuration when the JMS interface is used alone

(b) When the same database is accessed with the JMS interface and JDBC interface

When the JMS interface and JDBC interface are used to access the database with the user program, the same database can be accessed by two types of interfaces if the preconditions for connection sharing are satisfied. At this time, use the configuration shown in the following figure.

By using this configuration, you can improve the processing performance of the transactions through connection sharing and utilize the resources effectively.

Figure 3

23: Configuration when the same database is accessed with the JMS interface and JDBC interface

(c) When different databases are accessed with the JMS interface and JDBC interface

When the JMS interface and JDBC interface are used to access the database with the user program, you must use a configuration in which different databases will be accessed for each interface if the preconditions for connection sharing are not satisfied. At this time, use the configuration shown in the following figure.

144

3. Resource Connections and Transaction Management

Figure 3

24: Configuration when different databases are accessed with the JMS interface and JDBC interface

Use DB Connector for Cosminexus RM and Cosminexus RM to access the database queue. Also, to access the database tables, you must prepare and use DB Connector separately.

(d) When the Message-driven Beans are used

When the Message-driven Beans are used, use the configuration show in the following figure. If the connection sharing conditions are satisfied, you can use the JDBC interface of DB Connector for Cosminexus RM and share the connection between the Message-driven Beans and the JDBC interface.

Note that when the Message-driven Beans are used, you can use the global transactions and local transactions when the associated resource adapter is Cosminexus RM 01-01 or later. When you use the Cosminexus RM 01-00 resource adapter, you must use a global transaction. At this time, you cannot use a local transaction, but if the preconditions for connection sharing are satisfied, a global transaction is concluded through a single phase.

Figure 3

25: Configuration when the Message-driven Beans are used

3.7.3 Available functionality

For details on the functionality available for connections using DB Connector for Cosminexus RM and Cosminexus

RM, see

2.7 Functionality for DB Connector for Cosminexus RM

in the manual

uCosminexus Application Server

Reliable Messaging

.

Note that when you use the JDBC interface to connect to a database, you can use the same functionality as when you use DB Connector for connection. For details on the available functionality, see

3.3.4 Resource adapter functionality

.

145

3. Resource Connections and Transaction Management

3.7.4 Connectable databases

This subsection describes the databases that can be connected to by using DB Connector for Cosminexus RM and

Cosminexus RM.

(1) Types of connectable databases

The databases that can be connected by using DB Connector for Cosminexus RM and Cosminexus RM include

HiRDB and Oracle. Note that you cannot connect to SQL Server and XDM/RD E2.

(2) Mapping the databases and JDBC drivers

To use DB Connector for Cosminexus RM and Cosminexus RM to connect to a database, you require a JDBC driver compatible with the database.

The following table describes the database to be connected to and the available JDBC drivers.

Table 3

35: Database to be connected to and the available JDBC drivers (for connecting to a database queue)

JDBC driver

Database

HiRDB Type4 JDBC Driver Oracle JDBC Thin Driver

HiRDB Version 8

HiRDB Version 9

Oracle

Y

Y

N

N

N

Y

Legend:

Y: Available

N: Not available

(3) Notes

Note the following when you use DB Connector for Cosminexus RM and Cosminexus RM to connect to a database:

A JDBC-specific transaction control cannot be executed with the JDBC connection ( java.sql.Connection.

Connection

) provided by DB Connector for Cosminexus RM. If a JDBC-specific transaction control is executed, an exception occurs when the setAutoCommit(boolean) method is invoked with the argument false

, and when the releaseSavepoint(SavePoint) method, rollback(Savepoint)

method, setSavepoint()

method, and setSavepoint(String)

method are invoked. Use DB Connector when you want to execute a JDBC-specific transaction control.

The collection points and event ID of the trace based performance analysis for DB Connector for Cosminexus RM partially differs from that for DB Connector.

For a JDBC connection ( java.sql.Connection. Connection

), the trace based performance analysis is output at the two trace collection points of JDBC connection of DB Connector for Cosminexus RM with one-time access, and the JDBC connection in DB Connector.

Also, the trace based performance analysis is output at the same trace collection points as DB Connector for the

JDBC connection products (such as java.sql.Statement

). The trace based performance analysis is only output at the trace collection points for DB Connector for Cosminexus RM for java.sql.DataSource

.

When the operation information is monitored with DB Connector for Cosminexus RM, incorrect values are output for the following items of DB Connector for Cosminexus RM resource adapter. DB Connector for Cosminexus

RM obtains a connection via Cosminexus RM; therefore, the monitored information of the integrated resource adapter is accumulated and output to Cosminexus RM.

Transaction support level

Current value of the pool (total)

Number of connections in use

Number of unused connections

146

3. Resource Connections and Transaction Management

Execution count of the createManagedConnection()

method of

ManagedConnectionFactory

Execution count of the getConnection() method of ManagedConnection

Execution count of the cleanup() method of ManagedConnection

Execution count of the destroy()

method of

ManagedConnection

Execution time of the allocateConnection()

method of

ConnectionManager

Execution time of the createManagedConnection()

method of

ManagedConnectionFactory

Failure count of the allocateConnection()

method of

ConnectionManager

Number of times the

FATAL

error occurred in

ManagedConnection

DB Connector for Cosminexus RM shares the connection pool of the integrated Cosminexus RM. Therefore, you need not specify the settings for each functionality of the connection pool in DB Connector for Cosminexus RM.

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter.

When you customize a J2EE application that uses the resource adapters, resolve the references from the J2EE application to the resource adapter.

3.7.5 Types of DB Connector for Cosminexus RM (RAR file)

When you use DB Connector for Cosminexus RM to connect to a database, use a RAR file according to the JDBC driver to be used. Use the server management commands to operate the RAR files. For details on how to use the server management commands to operate the RAR files, see the

uCosminexus Application Server Application Setup

Guide

.

The following table describes the types of JDBC drivers and the corresponding RAR files.

Table 3

36: Mapping the JDBC drivers and RAR files

JDBC driver RAR file Explanation

HiRDB Type4 JDBC Driver

Oracle JDBC Thin Driver

DBConnector_HiRDB_Type4_CP_Cosminex us_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminex us_RM.rar

#

DBConnector_Oracle_CP_Cosminexus_RM

.rar

DBConnector_Oracle_XA_Cosminexus_RM

.rar

#

#: The light transaction functionality cannot be enabled.

Use this file when the transactions are not managed, or when a local transaction is used.

Use this file when a global transaction is used.

Use this file when the transactions are not managed, or when a local transaction is used.

Use this file when a global transaction is used.

3.7.6 Preconditions for connecting to a HiRDB queue

This subsection describes the preconditions for connecting to a HiRDB queue.

(1) Preconditions for HiRDB Version 8

The preconditions for HiRDB Version 8 are as follows:

• Available JDBC driver

The available JDBC driver is HiRDB Type4 JDBC Driver.

• Connection method

You use either of the following RAR files:

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar

147

3. Resource Connections and Transaction Management

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

37: Transaction support levels available for each RAR file (HiRDB Version 8)

Used DB Connector for Cosminexus RM

(RAR file)

Transaction support level

Light transaction

Enabled Disabled

DBConnector_HiRDB_Type4_CP_Cosminex us_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminex us_RM.rar

NoTransaction

LocalTransaction

XATransaction

Y

--

Y

Y

Legend:

Y: Available

--: Not applicable

(2) Preconditions for HiRDB Version 9

The preconditions for HiRDB Version 9 are as follows:

• Available JDBC driver

The available JDBC driver is HiRDB Type4 JDBC Driver.

• Connection method

You use either of the following RAR files:

DBConnector_HiRDB_Type4_CP_Cosminexus_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminexus_RM.rar

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

38: Transaction support levels available for each RAR file (HiRDB Version 9)

Light transaction

Used DB Connector for Cosminexus RM

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_HiRDB_Type4_CP_Cosminex us_RM.rar

DBConnector_HiRDB_Type4_XA_Cosminex us_RM.rar

NoTransaction

LocalTransaction

XATransaction

Y

--

Y

Y

Legend:

Y: Available

--: Not applicable

3.7.7 Preconditions for connecting to an Oracle queue

This subsection describes the preconditions for connecting to an Oracle queue.

• Available JDBC driver

The available JDBC driver is Oracle JDBC Thin Driver.

• Connection method

148

3. Resource Connections and Transaction Management

Use

DBConnector_Oracle_CP_Cosminexus_RM.rar

or

DBConnector_Oracle_XA_Cosminexus_RM.rar

.

The specifiable transaction support level varies according to the RAR file type. The availability of the light transaction also differs.

The following table describes the transaction support levels that can be specified for each RAR file.

Table 3

39: Transaction support levels available for each RAR file (Oracle9i)

Light transaction

Used DB Connector for Cosminexus RM

(RAR file)

Transaction support level

Enabled Disabled

DBConnector_Oracle_CP_Cosminexus_RM

.rar

DBConnector_Oracle_XA_Cosminexus_RM

.rar

NoTransaction

LocalTransaction

XATransaction

Y

--

Y

Y

Legend:

Y: Available

--: Not applicable

3.7.8 Settings for connecting to a database queue

For details on the settings for connecting to a database queue, see

2.7 Functionality for DB Connector for Cosminexus

RM

in the manual

uCosminexus Application Server Reliable Messaging

.

149

3. Resource Connections and Transaction Management

3.8 Outbound connection with OpenTP1 (SPP or TP1/

Message Queue)

This section describes the functionality for connecting OpenTP1 (SPP or TP1/Message Queue) and Outbound.

The following table describes the organization of this section.

Table 3

40: Organization of this section (Outbound connection with OpenTP1 (SPP or TP1/Message

Queue))

Category Title Reference location

Explanation Connections using uCosminexus TP1 Connector

3.8.1

Settings

Connections using TP1/Message Queue - Access

Connection settings for OpenTP1 and Outbound

Note: The functionality-specific explanation is not available for "Implementation" and "Operations".

3.8.2

3.8.3

Application Server can connect to OpenTP1 SPP or TP1/Message Queue. Use the following resource adapters to connect to OpenTP1:

Use uCosminexus TP1 Connector to connect to OpenTP1 SPP.

Use TP1/Message Queue - Access to connect to TP1/Message Queue.

This section describes the connections with OpenTP1.

3.8.1 Connections using uCosminexus TP1 Connector

To connect to a J2EE server and OpenTP1 SPP, you combine and use uCosminexus TP1 Connector and TP1/Client/J as the resource adapters.

The following figure shows OpenTP1 integration.

Figure 3

26: OpenTP1 integration using uCosminexus TP1 Connector

150

uCosminexus TP1 Connector uses TP1/Client/J RPC to connect to OpenTP1, and accesses OpenTP1 SPP. Due to this, you can integrate OpenTP1 SPP with a J2EE server.

!

Important note

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter. When you customize a J2EE application that uses the resource adapters, resolve the references from the J2EE application to the resource adapter.

For details on the uCosminexus TP1 Connector settings, see the uCosminexus TP1 Connector documentation. For details on the TP1/Client/J settings, see the

OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/J

.

Also, for details on how to set up the resource adapters using the server management commands, see the uCosminexus

TP1 Connector documentation, the manual

OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/J

, and

4.4

Settings for connecting to other resources

in the

uCosminexus Application Server Application Setup Guide

.

3. Resource Connections and Transaction Management

3.8.2 Connections using TP1/Message Queue - Access

To connect Application Server and TP1/Message Queue, you use TP1/Message Queue - Access as the resource adapter.

The following figure shows the TP1/Message Queue integration using TP1/Message Queue - Access.

Figure 3

27: TP1/Message Queue integration using TP1/Message Queue - Access

TP1/Message Queue - Access provides the JMS interface. The J2EE server uses this JMS interface to connect to TP1/

Message Queue.

!

Important note

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter. When you customize a J2EE application that uses the resource adapters, resolve the references from the J2EE application to the resource adapter.

For details on the TP1/Message Queue - Access settings, see the

OpenTP1 Version 7 TP1/Message Queue - Access

User Guide

.

Also, for details on how to set up the resource adapters using the server management commands, see

4.4 Settings for connecting to other resources

in the

uCosminexus Application Server Application Setup Guide

.

3.8.3 Connection settings for OpenTP1 and Outbound

For details on the settings for establishing a connection using uCosminexus TP1 Connector, see the uCosminexus TP1

Connector documentation, the

OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/J

, and

4.4 Settings for connecting to other resources

in the

uCosminexus Application Server Application Setup Guide

.

For details on the settings for establishing a connection using TP1/Message Queue - Access, see the

OpenTP1 Version

7 TP1/Message Queue - Access User Guide

, and

4.4 Settings for connecting to other resources

in the

uCosminexus

Application Server Application Setup Guide

.

151

3. Resource Connections and Transaction Management

3.9 Inbound connection with OpenTP1

When you invoke a business program running on a J2EE server for Application Server from the SUP on a legacy system using OpenTP1, you use the TP1 inbound adapter as the resource adapter for connecting OpenTP1 and the

J2EE server.

The TP1 inbound adapter is a resource adapter conforming to the Connector 1.5 specifications and provides the following functionality:

Substitution functionality for OpenTP1 schedule services

Functionality for executing OpenTP1 and RPC communication

By using the above functionality, you can invoke the business programs on the J2EE server using the same procedure as that for invoking OpenTP1 SPP from OpenTP1 SUP.

For details on connecting to OpenTP1 using the TP1 inbound adapter, see

4. Invoking Application Server from

OpenTP1 (TP1 Inbound Integrated Function)

.

!

Important note

The TP1 inbound integrated function can be invoked from the SUP, SPP, and MHP, but the invocation from the SUP will be described as an example in this manual.

152

3. Resource Connections and Transaction Management

3.10 Connection with Cosminexus JMS Provider

When you use the JMS Provider functionality provided by Application Server, you use the CJMSP Broker process to manage the message destinations. Use the CJMSP resource adapter to connect the J2EE server and CJMSP Broker.

By using the CJMSP resource adapter, you can send and receive messages with the PTP messaging model or Pub/Sub messaging model.

For details on connecting to OpenTP1 using the CJMSP resource adapter, see

7. Cosminexus JMS Provider

.

153

3. Resource Connections and Transaction Management

3.11 Connecting to the SMTP server

A J2EE application can send a mail to the SMTP server by using JavaMail.

For details on the settings for connecting to the SMTP server, see

6.3 Mail configuration settings

in the

uCosminexus

Application Server Application Setup Guide

.

154

3. Resource Connections and Transaction Management

3.12 Using the JavaBeans resources

This section describes the use of the JavaBeans resources.

The following table describes the organization of this section.

Table 3

41: Organization of this section (Using the JavaBeans resources)

Category Title

Explanation

Implementation

Settings

JavaBeans resource functionality

Procedure for starting the JavaBeans resources

Implementing the JavaBeans resources

Setting up the JavaBeans resources

Replacing the JavaBeans resources

Note: The functionality-specific explanation is not available for "Operations".

Reference location

3.12.1

3.12.2

3.12.3

3.12.4

3.12.5

3.12.1 JavaBeans resource functionality

With the JavaBeans resources, you can store and manage the settings for operating the J2EE applications in a batch.

You can obtain the settings by looking up the JavaBeans resource from the J2EE application by using JNDI.

3.12.2 Procedure for starting the JavaBeans resources

You can start multiple JavaBeans resources on a J2EE server. The following figure shows the procedure for starting the JavaBeans resources when the server management commands are used.

Figure 3

28: Procedure for starting the JavaBeans resources

1. Import and start the JavaBeans resource.

Use the server management commands to import and start the JavaBeans resource on the J2EE server.

2. Register the JavaBeans resource references to the Naming Service.

When you start the JavaBeans resource, register the JavaBeans resource references in the J2EE resource

Namespace of the Naming Service.

3. Look up from the J2EE application to the Naming Service.

155

3. Resource Connections and Transaction Management

Perform a look up from the J2EE application using the JavaBeans resource into the Naming Service. The set method of the JavaBeans resource is invoked by extending the lookup processing, and the property values specified in the JavaBeans resource property file are set up.

4. Use the obtained references to invoke the get

method of the JavaBeans resource.

Use the references obtained by lookup to invoke the get method of the JavaBeans resource, and use the get method to obtain the values specified with the set

method.

If a single class configures the implementation class of the JavaBeans resource, the class is available in the class file format, and if multiple classes configure the implementation class, like the classes related to the JavaBeans resource class, the classes are available in the JAR file format.

3.12.3 Implementing the JavaBeans resources

This subsection uses examples to describe the procedure for implementing the JavaBeans resources.

(1) Import settings

This section describes the required settings and notes when you use the server management commands

( cjimportjb

command) to import the JavaBeans resources.

(a) Settings for the JavaBeans resource property file

Create the JavaBeans resource property file keeping the following points in mind:

Specify the class name and implementation class name of the JavaBeans resource in the

<res-type>

tag and

<class-name> tag. If you want to set the same value in the <res-type> tag and <class-name> tag, you can omit the

<res-type>

tag.

Specify the method names of the set

method and get

method in the

<property-name>

tag.

Specify the argument type of the set method in the <property-type> tag.

If the actual argument type of the applicable set

method does not match the value in the

<property-type> tag, an error occurs during lookup.

Specify the value passed to the argument of the set

method in the

<property-value>

tag.

An example of settings for the JavaBeans resource property file is as follows:

<!DOCTYPE hitachi-javabeans-resource-property PUBLIC '-//Hitachi, Ltd.//DTD JavaBeans

Resource Property 7.0//EN'

'http://localhost/hitachi-javabeans-resource-property_7_0.dtd'>

<hitachi-javabeans-resource-property>

<description></description>

<display-name>JavaBean_resource</display-name>

<class-name>com.mycompany.mypackage.MyJavaBean</class-name>

<runtime>

<property>

<property-name>UserName</property-name>

<property-type>java.lang.String</property-type>

<property-value>Hitachi</property-value>

</property>

<property>

<property-name>UserID</property-name>

<property-type>java.lang.String</property-type>

<property-value>01234567</property-value>

</property>

</runtime>

</hitachi-javabeans-resource-property>

The template file ( jb_template.xml

) of the JavaBeans resource property file is stored in the following directory:

Cosminexus-installation-directory

\CC\admin\templates

156

3. Resource Connections and Transaction Management

(b) How to use the -d option

By using the -d option during an import operation, the JavaBeans resources can be imported with the same directory configuration and without creating an archive. Specify the top directory to be imported as the directory to be specified in

-d

.

An example of specifying the

-d

option when you import a JavaBeans resource is as follows. In this example, the

"MyJavaBean" class with package name "com.mycompany.mypackage" is imported.

Directory-specified-in--d

\

+ com\

+ mycompany

+ mypackage

+ MyJavaBean.class

The -d option imports all the files existing beneath the specified directory, so do not include unnecessary files in the directory.

Notes on importing multiple JavaBeans resources

You cannot import a JavaBeans resource with the same implementation class name as that of an imported

JavaBeans resource. Delete the JavaBeans resource that was imported earlier and then import the target JavaBeans resource, or change and re-create the implementation class name, and then import the JavaBeans resource.

(2) Creating the implementation class of the JavaBeans resources

You declare the method for operating the data (property) managed by JavaBeans. To register the data, specify the set method ( set +

property-name

). To reference the data, specify the get method ( get +

property-name

).

An example implementation of the class that registers and references the JavaBeans resource is as follows: package com.mycompany.mypackage; public class MyJavaBean {

private String username;

private String userid;

public void setUserName(String user_name) {

this.username = user_name;

}

public void setUserID(String user_id) {

this.userid = user_id;

}

public String getUserName() {

return this.username;

}

public int getUserID() {

return this.userid;

}

}

(3) Application settings

This section describes the implementation and definitions required in an application when you use the JavaBeans resources.

(a) Implementing lookup (JavaBeans resources)

You obtain a JavaBeans resource by using lookup or DI. This section describes how to look up with the java:comp/env

format.

Context initCtx = new InitialContext();

MyJavaBean jb = (MyJavaBean) initCtx.lookup("java:comp/env/bean/myJB");

Like other resources, the range of JavaBeans resource lookup is the application in the same J2EE server process.

(b) Contents defined in the DD (JavaBeans resources)

To use lookup to obtain a JavaBeans resource, you define the information on the name to be looked up and the implementation class name in the DD ( ejb-jar.xml

or web.xml

). The tags to be specified are as follows:

157

3. Resource Connections and Transaction Management

In the

<resource-env-ref-name>

tag, you specify the value to be specified in the java:comp/env format for lookup.

In the

<resource-env-ref-type>

tag, specify the implementation class name of the JavaBeans resource.

Also, when you deploy a created application on the J2EE server, bind the reference name in lookup and the actual name with linked-to . To execute this operation, use the server management commands ( cjsetappprop command).

Use cjgetappprop to obtain the property file of the relevant application.

Add the

<linked-to>

tag in the

<resource-env-ref>

tag and specify the display name of the JavaBeans resource to be used.

Use cjsetappprop to set up the property file of the relevant application.

The following is an example of the

<resource-env-ref>

tag in the property file passed by cjsetappprop

:

<resource-env-ref>

<resource-env-ref-name>bean/myJB</resource-env-ref-name>

<resource-env-ref-type>com.mycompany.mypackage.MyJavaBean</resource-env-ref-type>

<linked-to>JavaBean_resource</linked-to>

</resource-env-ref>

(4) Starting and terminating an application

You start or terminate an application that uses a JavaBeans resource with the server management commands or

Management Server. For details on how to start an application, see

10.2.1 Starting J2EE applications

in the

uCosminexus Application Server Application Setup Guide

. For details on how to terminate an application, see

10.2.2

Stopping J2EE applications

in the

uCosminexus Application Server Application Setup Guide

.

Application Server provides a sample program for JavaBeans resources. For an overview and the execution method of the sample program, see

Appendix M.6 Sample program for JavaBeans resources

in the

uCosminexus Application

Server System Setup and Operation Guide

.

3.12.4 Setting up the JavaBeans resources

This subsection describes the settings for the JavaBeans resources.

You use the server management commands to set up the properties for the JavaBeans resources and to import the

JavaBeans resources.

To set up the JavaBeans resources, use the server management commands.

This subsection describes the procedure for setting up a new JavaBeans resource, the procedure for changing the settings, and the procedure for replacing the JavaBeans resource.

(1) Procedure for setting up a new JavaBeans resource

The following figure shows the procedure for setting up a new JavaBeans resource.

Figure 3

29: Procedure for setting up a new JavaBeans resource

158

A description of points 1 and 2 in the figure is as follows:

1. Create the JavaBeans resource property file and define the JavaBeans resource properties.

3. Resource Connections and Transaction Management

Use the template for the JavaBeans resource property file to create the JavaBeans resource property file, and then define the properties for the JavaBeans resource. The template for the JavaBeans resource property file is stored in the following directory:

In Windows

Cosminexus-installation-directory

\CC\admin\templates\jb_template.xml

In UNIX

/opt/Cosminexus/CC/admin/templates/jb_template.xml

For details on the content that can be specified in the definition of the JavaBeans resource properties, see

(4)

Content that can be specified in the definition of the JavaBeans resource properties

.

2. Use the server management commands to import the JavaBeans resource.

Specify the path of the JavaBeans resource property file set up in point 1 and the JAR file containing the

JavaBeans resource, in the argument, use the cjimportjb

command, and then import the JavaBeans resource.

For details on the operations with server management commands, see

3. Basic Operations of Server Management

Commands

in the

uCosminexus Application Server Application Setup Guide

. Also, for details on the commands, see

2.4 Resource operation commands used with the J2EE server

in the

uCosminexus Application Server Command

Reference Guide

. For details on the property files, see

4.2 Property files for JavaBeans resources

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

Reference note

When you import multiple JavaBeans resources, you cannot import a JavaBeans resource with the same implementation class name as an imported JavaBeans resource. Delete the JavaBeans resource that was imported earlier, or change and re-create the implementation class name, and then import the JavaBeans resource.

Also, if another class file is being used apart from the implementation class of the JavaBeans resource, the other class file is not checked.

If you use the

-d

option in the cjimportjb

command during the import operation, the JavaBeans resources can be imported with the same directory configuration and without generating an archive. As directory, specify the top directory to be imported.

Note that if the specified directory is not a directory configuration, all the files directly beneath the specified directory will be imported.

To import all the files existing under the specified directory, do not include unnecessary files in the directory.

!

Important note

To use a JavaBeans resource, you must resolve the references from the J2EE application to the JavaBeans resource. When you define the properties of a J2EE application that uses the JavaBeans resource, resolve the references from the J2EE application to the JavaBeans resource.

(2) Procedure for changing the settings of a JavaBeans resource

The following figure shows the procedure for changing the settings of a JavaBeans resource.

Figure 3

30: Procedure for changing the settings of a JavaBeans resource

A description of points 1 and 2 in the figure is as follows:

1. Use the server management commands to stop the JavaBeans resource.

Use the cjstopjb

command to stop the JavaBeans resource. Note that before you stop the JavaBeans resource, stop all the J2EE applications that are using the JavaBeans resource.

159

3. Resource Connections and Transaction Management

2. Use the server management commands to define the JavaBeans resource properties.

Use the cjgetjbprop

command to obtain the JavaBeans resource property file, edit the file, and then use the cjsetjbprop

command to apply the edited content.

For details on the content you can specify in the definition of the JavaBeans resource properties, see

(4) Content that can be specified in the definition of the JavaBeans resource properties

.

(3) Procedure for replacing the JavaBeans resource

The following figure shows the procedure for replacing the JavaBeans resource.

Figure 3

31: Procedure for replacing the JavaBeans resource

A description of points 1 to 4 in the figure is as follows:

1. Use the server management commands to stop the JavaBeans resource.

Use the cjstopjb

command to stop the JavaBeans resource you want to replace. Note that before you stop the

JavaBeans resource, stop all the J2EE applications that are using the JavaBeans resource.

2. Restart the J2EE server.

Use the cjstopsv command to stop the J2EE server, and then use the cjstartsv command to restart the

J2EE server.

3. Use the server management commands to delete the JavaBeans resource.

Use the cjdeletejb

command to delete the JavaBeans resource you want to replace.

4. Use the server management commands to import the JavaBeans resource.

Use the cjimportjb

command to import a new JavaBeans resource.

(4) Content that can be specified in the definition of the JavaBeans resource properties

To set up new JavaBeans resource properties, use the template of the JavaBeans resource property file to create the

JavaBeans resource property file, and then define the properties. Also, to change the settings, use the server management commands to obtain the JavaBeans resource property file, and then define the properties. Use the cjgetjbprop

command to obtain the JavaBeans resource property file, edit the file, and then use the cjsetjbprop command to apply the edited content.

The following table describes the main content that can be specified in the definition of the JavaBeans resource properties.

Table 3

42: Main content that can be specified in the definition of the JavaBeans resource properties

Category Item Settings

Runtime properties Resource type

Property information

Specify the class name of the JavaBeans resource in the

<res-type>

tag.

Specify the information in the following tags beneath the

<property>

tag:

160

3. Resource Connections and Transaction Management

Category

Runtime properties

Optional name information

Item

Property information

Optional name

Settings

Specify the method name of the set method and get method of the JavaBeans resource in the

<propertyname>

tag.

Specify the argument type of the set method of the

JavaBeans resource in the <property-type> tag.

Specify the value passed to the argument of the set method of the JavaBeans resource in the

<propertyvalue> tag.

Specify the optional name for the JavaBeans resource in the

<resource-env-external-property>-

<optional-name>

tag, when you want to assign an optional name to the JavaBeans resource.

For the optional name settings, see

2.6.6 Setting the optional names for the J2EE resources

.

Reference note

The <res-auth> attribute and <res-sharing-scope> attribute specified in the <resource-ref> tag of the DD

( ra.xml

) cannot be specified in the

<resource-env-external-property>

tag of the JavaBeans resource property file.

3.12.5 Replacing the JavaBeans resources

This subsection describes the procedure for replacing the JavaBeans resources. To replace a JavaBeans resource, stop the J2EE application and JavaBeans resource, restart the J2EE server, and then replace the JavaBeans resource. You use the server management commands to replace the JavaBeans resources.

The procedure is as follows:

1. Stop the J2EE application that is using the JavaBeans resource you want to replace.

To stop the J2EE application, execute the cjstopapp

command. The format and example of execution of the cjstopapp

command are as follows:

Format of execution

cjstopapp

J2EE-server-name

-name

J2EE-application-name

Example of execution

cjstopapp MyServer -name App1

2. Stop the JavaBeans resource you want to replace.

To stop the JavaBeans resource, execute the cjstopjb

command. The format and example of execution of the cjstopjb command are as follows:

Format of execution

cjstopjb

server-name

-resname

display-name-of-JavaBeans-resource

Example of execution

cjstopjb MyServer -resname javabeansname

3. Restart the J2EE server.

To delete a JavaBeans resource that is started once, you must restart the J2EE server. To stop the J2EE server, execute the cjstopsv command. The format and example of execution of the cjstopsv command are as follows:

Format of execution

cjstopsv

J2EE-server-name

161

3. Resource Connections and Transaction Management

Example of execution

cjstopsv MyServer

After you stop the J2EE server, start the server once again. To start the J2EE server, execute the cjstartsv command. The format and example of execution of the cjstartsv

command are as follows:

Format of execution

cjstartsv

J2EE-server-name

Example of execution

cjstartsv MyServer

4. Delete the JavaBeans resource you want to replace.

To delete the JavaBeans resource, execute the cjdeletejb

command. The format and example of execution of the cjdeletejb command are as follows:

Format of execution

cjdeletejb

server-name

-resname

display-name-of-JavaBeans-resource

Example of execution

cjdeletejb MyServer -resname MyJavaBeans

5. Import the replaced JavaBeans resource.

To import the JavaBeans resource, execute the cjimportjb command. The format and example of execution of the cjimportjb command are as follows:

Format of execution

cjimportjb

server-name

-f

JAR-file-path

-c

path-of-the-JavaBeans-resource-property-file

Example of execution

cjimportjb MyServer -f Myjavabeans.jar -c Myjavabeansprop.xml

6. Start the JavaBeans resource.

To start the JavaBeans resource, execute the cjstartjb command. The format and example of execution of the cjstartjb

command are as follows:

Format of execution

cjstartjb

server-name

-resname

display-name-of-JavaBeans-resource

Example of execution

cjstartjb MyServer -resname javabeansname

7. Start the J2EE application.

To start the J2EE application, execute the cjstartapp

command. The format and example of execution of the cjstartapp

command are as follows:

Format of execution

cjstartapp

J2EE-server-name

-name

J2EE-application-name

Example of execution

cjstartapp MyServer -name App1

162

3. Resource Connections and Transaction Management

3.13 Connection with other resources

This section describes the connections with resources other than those described in the previous sections.

3.13.1 Resource adapters used for connection with other resources

With Application Server, you can use the resource adapters conforming to the Connector 1.0 specifications or

Connector 1.5 specifications and connect to any resource.

The Connector 1.5 specifications determine the following two models for the communication between the J2EE server and resource adapter. With Application Server, you can use a resource adapter that is compatible with these communication models.

• Outbound

A communication model that accesses the resource adapter from the J2EE server.

• Inbound

A communication model that accesses the J2EE server from the resource adapter.

Application Server supports the following contracts of the Connector 1.5 specifications:

• Lifecycle Management

This contract is used to manage the start or termination processing of the resource adapter.

• Work Management

This contract is used by the resource adapter to handle threads.

• Message inflow

This contract is used to receive the messages from the EIS, and use the Message-driven Beans from the resource adapter.

• Transaction inflow

This contract is used to handle the transactions in the message inflow.

For details on the Application Server functionality based on these contracts, see

3.16.1 Managing the resource adapter lifecycle

,

3.16.2 Managing the resource adapter work

,

3.16.3 Message inflow

, and

3.16.4 Transaction inflow

.

Application Server also supports the functionality added by the Connector 1.5 specifications for the following existing contracts:

• Connection Management

You can detect invalid connections.

For details on the functionality for detecting invalid connections, see

3.15.1 Detecting the connection errors

.

• Common Client Interface

You can use the message inflow-related APIs. For details on the unique specifications provided for these APIs in

Application Server, see

3.16.7 Application Server-specific Connector 1.5 API specifications

.

3.13.2 Functionality available for other resource connections

This subsection describes the functionality that can be used with Application Server from among the functionality provided in Connector 1.5. The available functionality varies for Outbound and for Inbound. For details on the

Application Server functionality available with the resource adapters conforming to the Connector 1.5 specifications,

see

3.3.4 Resource adapter functionality

.

(1) Functionality available with Outbound

The following functionality is available with Outbound:

Transaction management by local transactions and global transactions

Using the message queue

163

3. Resource Connections and Transaction Management

(2) Functionality available with Inbound

With Inbound, you can use Non-Transacted Delivery (message delivery in which the EIS does not participate in the transaction) and Transacted Delivery (message delivery in which the EIS participates in the global transaction of

Application Server).

Reference note

Transaction inflow (message delivery in which the invocation of the Message-driven Bean participates in the EIS transaction) is only supported by the TP1 inbound integrated function.

(3) Mapping the usage and transaction levels of the resource adapters

The following table describes the transaction levels that can be specified when a resource adapter is used with

Outbound.

Table 3

43: Transaction levels that can be specified when a resource adapter is used with Outbound

Used communication model

Transaction management method

Transaction attribute

NoTransaction

Transaction support level

LocalTransaction

XATransaction

#

Outbound CMT Y Y Y

BMT

Required

RequiresNew

Supports

NotSupported

Mandatory

Never

-Y Y Y

Legend:

Y: Available

--: Not applicable

#: If the resource adapter is included in a J2EE application,

XATransaction

is not available.

Tip

The following table describes the transaction attributes that can be specified when a resource adapter is used with Inbound.

Table 3

44: Transaction attributes that can be specified when a resource adapter is used with

Inbound

Used communication model Transaction management method Transaction attribute

Inbound CMT

Required

#

NotSupported

BMT --

Legend:

--: Not applicable

#: You cannot specify this attribute for the CJMSP resource adapter or FTP inbound adapter.

164

3. Resource Connections and Transaction Management

3.14 Functionality for performance tuning

This section describes the functionality for performance tuning.

The following table describes the organization of this section.

Table 3

45: Organization of this section (Functionality for performance tuning)

Category Title

Explanation

Implementation

Settings

Connection pooling

Functionality available with connection pooling

Connection sharing or association

Statement pooling

Light transaction

In-process transaction service

Caching the DataSource objects

Optimizing the container-managed sign-on for DB Connector

Definitions in cosminexus.xml

Settings in the execution environment

Note: The functionality-specific explanation is not available for "Operations".

3.14.6

3.14.7

3.14.8

3.14.9

3.14.10

Reference location

3.14.1

3.14.2

3.14.3

3.14.4

3.14.5

3.14.1 Connection pooling

This functionality pools the resource connections (JDBC connection and resource adapter connections) according to the volume of resource access from the J2EE components, such as servlets, JSPs, and EJBs. By pooling these connections, the resource connection requests from the user application are processed at a high speed.

(1) Preconditions

The connection pooling functionality might be available or unavailable depending on the types of resource and the combinations of connection methods. The following table describes the usage of the connection pooling functionality.

Table 3

46: Usability of the connection pooling functionality

Types of resources Connection method Usability

Database

Database queue

OpenTP1

SMTP server

JavaBeans resources

Other resources

DB Connector

DB Connector for Cosminexus RM and Cosminexus RM uCosminexus TP1 Connector

TP1/Message Queue - Access

Mail configuration

--

Resource adapters conforming to the Connector 1.0

specifications or Connector 1.5 specifications

Y

Y

Y

Y

N

N

Y

Legend:

Y: Available

N: Not available

--: Not applicable

165

3. Resource Connections and Transaction Management

(2) Generating and initializing the connection pool

The connection pool is generated and initialized during the start processing of the resource. If the connection pool warming up functionality is enabled, a connection is generated at this point. If the connection pool warming up functionality is disabled, a connection is not generated when the resource starts, but is generated when the first connection request occurs.

The connection pool is generated as follows:

When you use resource adapters conforming to the Connector 1.0 specifications, one connection pool is generated for the resources.

When you use resource adapters conforming to the Connector 1.5 specifications, one connection pool is generated per connection definition.

(3) Terminating the connection pool

When you undeploy resources or when you terminate the J2EE server, you delete all the connections in the connection pool as well as the connection pool itself. Note that when the connection pool is terminated, all the connection-related transactions are assumed to have concluded.

(4) Destroying the connections with exceptions

If an error such as a database error occurs, the connections stored in the connection pool can no longer be used, and must be quickly discarded from the connection pool.

If an exception occurs in a connection, or in the processing of a product from the connection such as

Statement

,

Application Server destroys the relevant connection from the connection pool when the connection is closed.

However, if the conclusion of the local transaction terminates normally, the connection is determined to be normal and is not destroyed.

If an exception occurs in a connection or a product from the connection when a connection is maintained normally, and if you are using a global transaction, Application Server destroys the connection without returning the connection to the connection pool even if the transaction is concluded normally. Therefore, extra connections are generated and might affect the performance.

Note that when a transaction times out, the connections are destroyed from the connection pool regardless of the transaction type.

(5) Notes on using a connection pool

Note the following when you use a connection pool:

Do not use the functionality for forceful disconnection (such as timeout) from the database server.

The connections managed in a connection pool store the authentication information (such as user name and password) used for obtaining the connection, so you must take precautions according to the sign-on form.

For container-managed sign-on

Normally, single authentication information is used for a connection request to one connection pool, so no particular precautions need to be taken.

For component-managed sign-on

You must take precautions when a combination of multiple user names and passwords is used. There is one connection pool for each resource, so when multiple users use one resource, the multiple users share one connection pool. In this case, one user cannot use the connections equal to the value specified as the maximum connection pool value.

Furthermore, if there are no connections with matching authentication information among the unused connections in the connection pool, the following operations are performed depending on the total number of connections in the pool:

If the total number of connections reaches the specified maximum connection pool value, the unused connections are destroyed and new connections are generated.

If the total number of connections does not reach the specified maximum connection pool value, new connections are generated.

166

3. Resource Connections and Transaction Management

(6) Connection pooling operations

The following table describes the connection pooling operations of the resource adapters.

Table 3

47: Connection pool status and operations

Processing of the user application program

Connection pool state Connection pool operations

Connection request There are unused connections in the pool.

The connection that is unused for the longest time is selected and passed to the user application program. The status of the selected connection in the pool changes to in-use.

A new connection is established. The established connection is passed to the user application, and the status of the connection in the pool changes to in-use.

There are no unused connections in the pool, and the total number of connections in the pool is less than the value of MaxPoolSize .

There are no unused connections in the pool, and the total number of connections in the pool has reached the value of

MaxPoolSize

.

There are unused connections in the pool, but there are no connections with matching authentication information.

An exception is reported to the user application program, and the connection cannot be obtained. To obtain the connection again, specify

Retry Count

and

Retry Interval

.

Releasing the connections

The following processing is implemented depending on the total number of connections in the pool:

• If the number of connections in the pool is less than the

MaxPoolSize value

A new connection is established and is passed to the user application.

• If the number of connections in the pool reaches the

MaxPoolSize value

Among the unused connections, the connections that are pooled first are destroyed, and then new connections are created and passed to the user application.

The status of this connection in the pool changes to unused.

--

There are no errors in the released connections and the connections can be reused.

The released connection cannot be reused.

The connection pool warming up functionality is used.

This connection is destroyed.

Waiting for a connection when connections deplete

When you start a resource adapter or start a server when the resource adapter is already running, connections are generated and pooled up to the value in

MinPoolSize

.

To use the connection pool warming up functionality, specify

Warmup

.

If the maximum number of connections are pooled in the connection pool and there are no usable connections in the pool (connection depletion), you can set the connection request to pending.

The pending connection request can obtain a connection as soon as a connection is released.

To wait for a connection when connections deplete, specify

RequestQueueEnable and RequestQueueTimeout .

Legend:

--: Not applicable

The following table lists the notes on using the connection pool warming up functionality.

167

3. Resource Connections and Transaction Management

Table 3

48: Notes on using the connection pool warming up functionality

Condition Notes

Specifying the authentication information (such as user name and password) for container authentication

Specifying

#

MinPoolSize

You must take precautions when you use a combination of multiple user names and passwords with the component-managed sign-on. There is one connection pool for each resource, so when multiple users use one resource, the multiple users share one connection pool. In this case, one user cannot use the connections equal to the value specified as the maximum connection pool value.

In a container-managed sign-on, normally single authentication information is used for a connection request to one connection pool, so no particular precaution needs to be taken.

In the following cases, the pooled connections might be lesser than the value specified in

MinPoolSize

:

When the connection sweeper executes the connection release processing

When you execute the cjclearpool (deleting the connections in the connection pool) command

When an error occurs in the connection

When a resource starts, the number of connections specified in MinPoolSize is generated; therefore, starting the server or resource adapter might take more time as compared to when the connection pool warming up functionality is not used.

Also, at this time "

value-specified-in-bufSize

x

memory-for-the-number-of-connectionsgenerated

" is allocated in the Java heap area.

If you use the warming up functionality specifying a more than necessary large value in

MinPoolSize

, the Java heap is used up when you allocate the memory and

OutOfMemoryError

might occur.

Therefore, set the value of

MinPoolSize

to no more than the maximum number of concurrent connections of the resource manager used.

#: The connections managed with the connection pool store the authentication information (such as user name and password) for container authentication used during the operation of the warming up functionality.

3.14.2 Functionality available with connection pooling

When you use the connection pooling functionality, the following functionality is additionally available:

(1) Connection pool warming up

The Connection pool warming up is a functionality that pools the minimum number of connections defined in the connection pool settings, in advance, during the resource start processing executed when the server or resource adapter is started. Due to this, you can improve the response to the connection requests made immediately after you begin using the connection pool.

You set up the connection pool warming up functionality as a resource adapter attribute (property). For details on the

content that can be specified in the resource adapter property definitions, see

3.14.10 Settings in the execution environment

.

(2) Connection count adjustment functionality

The connection count adjustment functionality reduces the unnecessary connections in the connection pool from the minimum specified connection pool value up to the maximum value in a phased manner. If you enable this functionality, the number of connections in the pool is gradually reduced up to a number appropriate for the actual operation results, so you can reduce the cost of generating the connections and save resources when the minimum specified connection pool value is exceeded.

You can also set a timeout value for the response time for deleting the connections during the connection count adjustment. If a server or network error occurs and no response returns from the resource, a response might not be returned even for the connection deletion processing. In this way, even if the response does not return from the resource, you can terminate the connection deletion processing and continue the rest of the processing by specifying a timeout value.

168

3. Resource Connections and Transaction Management

Operations of the connection count adjustment functionality

If you use the connection count adjustment functionality, the number of connections in the pool is adjusted at the maximum number of connections used concurrently during the period between the previous connection count adjustment and the next connection count adjustment. During the connection count adjustment, if the number of connections in the pool is greater than the maximum number of concurrently used connections, the connection deletion processing will operate. For example, if the number of connections in the pool is 8 currently, and the maximum number of connections used concurrently during the period between the previous connection count adjustment and the next connection count adjustment is 5, there are 3 more connections in the pool, so three connections are deleted from the connection pool, and the adjusted connection count becomes 5.

Note that the connection count adjustment functionality operates at regular intervals.

For details on the settings for the connection count adjustment functionality, see

3.14.10 Settings in the execution environment

.

Timeout in the connection deletion processing

You can set a timeout value for the response time for the connection deletion processing of the connection count adjustment functionality. Note that you can specify any value (default value is 5 seconds) as the timeout value for the connection deletion processing, in the keys specified for the J2EE server in the Easy Setup definition file.

However, if the maximum value of the connection pool is unlimited, the timeout value of the connection deletion processing is disabled.

Also, the connection management threads are used for the connection deletion processing timeout; therefore, if you specify a timeout for the connection deletion processing, a lot of memory is consumed compared to when the timeout is not set. If you want to set a timeout, estimate the required amount of memory appropriately.

For details on the connection management threads, see

3.15.1 Detecting the connection errors

.

(3) Connection sweeper operations

The connection sweeper functionality that is used to destroy the unused connections in the connection pool at regular intervals operates as follows:

The connection sweeper operates after the lapse of the

SweeperInterval

value from the termination of the previous connection sweeper operation.

The connection sweeper monitors the unused connections in the pool.

The unused connections, for which the time elapsed since the last usage is the

ConnectionTimeout

value or more, are destroyed. The connection sweeper does nothing in the case of the unused connections, for which the time elapsed since the last usage is less than the

ConnectionTimeout

value.

3.14.3 Connection sharing or association

The connection sharing and connection association are the shared connection functionality. By using the shared connection functionality, you can use the resources effectively and improve the performance. Enable the connection association functionality as and when required.

When you manage transactions using local transactions, you must access the resource, such as the database, with one resource connection only. If you use the shared connection functionality, you can access the resources with one resource connection only without any consideration, in the user application.

Similarly in a global transaction, the operation is optimized to a single-phase commit when only one resource connection participates in a transaction; therefore, you can reduce the cost of concluding the transaction.

(1) Physical connection and logical connection

A

physical connection

indicates the connection to a resource you want to connect to. Normally the J2EE components such as servlets and Enterprise Beans are operated by a container, instead of being operated directly. For example,

ManagedConnection (javax.resource.spi.ManagedConnection)

for a resource adapter.

A

logical connection

indicates a connection that the J2EE components such as servlets and Enterprise Beans operate directly. For example, in the case of a resource adapter, javax.resource.cci.Connection

or a connection independently provided by a resource adapter.

169

3. Resource Connections and Transaction Management

The relationship between a physical connection and logical connection is that, generally, a logical connection is generated from a physical connection. The physical connections are managed with a connection pool and the connection pool obtains and closes the physical connections.

For a connection request from the J2EE components such as servlets and Enterprise Beans, the connection pool generates and returns the logical connections from the physical connection. For a request to release connections, the connection pool closes the logical connections only, and manages the physical connections in the pool, without closing the connections.

(2) Connection sharing

If the connection association functionality is not enabled, the connections are shared by the Application Servermanaged transactions. The connection sharing in a transaction uses the resource connections most effectively. The following figure shows the connection sharing in a transaction.

Figure 3

32: Relationship between the logical connection and physical connection (connection sharing in a transaction)

When the connection association functionality is enabled and the connections are shared outside the Application

Server-managed transactions, the connection sharing is performed by the instances of the J2EE components such as servlets and Enterprise Beans. The following figure shows the connection sharing in components.

170

3. Resource Connections and Transaction Management

Figure 3

33: Relationship between the logical connection and physical connection (connection sharing in components)

(a) Conditions for connection sharing

For connection sharing, all the following conditions must be satisfied:

The connection sharing is performed on the same J2EE server.

The connection sharing is performed for the same resource.

The sign-on method and security information (user name and password) are the same.

Shareable is specified in <res-sharing-scope> of the standard DD.

The connection sharing is performed in the same Application Server-managed transaction

#

#

You can also perform connection sharing outside the Application Server-managed transactions.

To enable connection sharing outside the Application Server-managed transactions, specify the settings by customizing the J2EE server properties. For details on customizing the J2EE server operation settings, see

3.14.10 Settings in the execution environment

.

Note that connection sharing is not performed if

NoTransaction

is specified as the transaction support level of the resource adapter.

For details on defining connection sharing, see

3.14.9 Definitions in cosminexus.xml

.

(b) Defining connection sharing

In the

<res-sharing-scope>

tag of the standard DD or cosminexus.xml

of the servlets and Enterprise

Beans, you specify whether the connections will be shared. You can specify the settings for each resource reference.

The connection sharing is enabled by default. To disable connection sharing, specify Unshareable in <ressharing-scope>

.

For details on the J2EE application settings, see

3.14.9 Definitions in cosminexus.xml

.

(c) Notes

You cannot reuse java.sql.Connection

between multiple transactions.

To use java.sql.Connection

in a transaction, use the getConnection()

method from javax.sql.DataSource

and obtain the connections for each transaction.

Note that java.sql.Connection

cannot be reused from inside the transaction to outside the transaction.

171

3. Resource Connections and Transaction Management

(3) Connection association

When you use a connection with persistence that has exceeded the transaction scope, connection sharing in a transaction is not available. In such a case, enable the connection association functionality.

The connection association switches the relationship between the logical connection and physical connection and implements resource access using one resource connection.

Figure 3

34: Relationship between the logical connection and physical connection (connection association)

Figure 3

35: Relationship between the logical connection and physical connection (when connection association and connection sharing are used together)

(a) Conditions for connection association

For connection association, all the following conditions must be satisfied:

The connection association functionality is enabled.

172

3. Resource Connections and Transaction Management

The connection association is performed on the same J2EE server.

The connection association is performed for the same resource.

The sign-on method and security information (user name and password) are the same.

Shareable

is specified in

<res-sharing-scope>

of the standard DD.

#

The connection association is performed in the same Application Server-managed transaction

#

If true

is set in the ejbserver.connectionpool.association.enabledDespiteUnshareableSetting

key of usrconf.properties

, the connection association is performed even if

Unshareable

is specified in

<res-sharing-scope>

of the standard DD.

This property has only been provided for downward compatibility.

(b) Defining connection association

The connection association is disabled by default.

Specify the settings for enabling connection association by customizing the J2EE server properties. For details on

customizing the J2EE server operation settings, see

3.14.10 Settings in the execution environment

.

(c) Notes

The products from java.sql.Connection

(example: java.sql.Statement

) cannot be used exceeding the transaction scope.

3.14.4 Statement pooling

When you use DB Connector, you can use the pooling functionality that reuses JDBC APIs java.sql.PreparedStatement

and java.sql.CallableStatement

. By the statement pooling functionality, you can try to improve the performance when

PreparedStatement

and

CallableStatement are used. Note that you specify the pool size for

PreparedStatement

and

CallableStatement

in the DB

Connector settings. For details on the guidelines for specifying the pool size when a statement pooling is used, see

8.5.2 Using statement pooling

in the

uCosminexus Application Server System Design Guide

. Also, for details on defining the DB Connector properties, see

4.2.2 Defining the DB Connector properties

in the

uCosminexus

Application Server Application Setup Guide

.

With the statement pooling functionality, the statement is initialized when the statement is reused. You specify the content to be initialized by customizing the J2EE server properties. For details on the settings of the statement pooling functionality, see

3.14.10 Settings in the execution environment

.

To use the statement pooling functionality, you must use the connection pooling functionality. Also, if global transaction is specified in the transaction support level, the statement pooling functionality might be unavailable depending on the HiRDB version.

!

Important note

When you use HiRDB Type4 JDBC Driver, the pool size of PreparedStatement and CallableStatement is restricted. For details on the specifiable pool size, see

4.1.10 Properties that can be specified in the <config-property> tag set in DB

Connector

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

(1) Preconditions

The following table describes the usage of statement pooling based on the mapping with the transaction support level, the use of connection pooling, and the database type used.

173

3. Resource Connections and Transaction Management

Table 3

49: Usage of statement pooling

Connection pooling is used

Transaction support level

HiRDB

#1

Oracle SQL Server XDM/RD E2

Connection pooling is not used

HiRDB/Oracle/SQL

Server

N No transaction

(

NoTransaction

)

Local transaction

)

( LocalTransaction

Global transaction

( XATransaction )

Y

Y

Y

#2

Y

Y

Y

Y

Y

N

Y

Y

N

N

N

Legend:

Y: Can be used

N: Cannot be used

#1: Do not execute the definition SQL statement when you use the statement pooling functionality. When you execute the definition

SQL statement, you cannot use the statement pooling functionality. Also, when you execute the definition SQL statement, you must set up

PDDDLDEAPRP=YES

as the HiRDB client environment variable.

#2: This can be used if the return value of

DatabaseMetaData#supportsStatementPooling()

of the JDBC is true

.

Note that when you use XDM/RD E2, the statement pooling functionality is available only when you use XDM/RD

E2 11-03 or later and HiRDB Type4 JDBC Driver 08-02 or later. For details on the settings of the statement pooling

functionality, see

3.14.10 Settings in the execution environment

.

(2) Statement pooling operations

This section describes the statement pooling operations specified in the resource adapter configuration properties.

The following table describes the operations of the statement pooling functionality.

Table 3

50: Statement pool states and operations

User application program processing

Statement pool state Statement pool operations

Requesting the generation of

PreparedStatement

and

CallableStatement

There are unused

PreparedStatement

and

CallableStatement

in the pool

There are no unused

PreparedStatement and

CallableStatement

in the pool, and the total number of

PreparedStatement

and

CallableStatement in the pool is less than the value of

PreparedStatementPoolSiz e

and

CallableStatementPoolSiz e

There are no unused

PreparedStatement

and

CallableStatement

in the pool, and the total number of

PreparedStatement

and

CallableStatement

in the

Either of the unused PreparedStatement or

CallableStatement

are selected in the pool and passed to the user application program. The status of the selected PreparedStatement or

CallableStatement in the pool changes to in-use.

New

PreparedStatement

and

CallableStatement

are generated. The generated PreparedStatement and

CallableStatement

are passed to the user application, and the status of

PreparedStatement and

CallableStatement

in the pool changes to in-use.

PreparedStatement and

CallableStatement

with the oldest time stamp

#

are deleted from the pool, and then new

PreparedStatement and

CallableStatement

are generated. The generated

PreparedStatement

and

174

3. Resource Connections and Transaction Management

User application program processing

Requesting the generation of

PreparedStatement and

CallableStatement

Releasing PreparedStatement and

CallableStatement

Statement pool state Statement pool operations pool is the value of

PreparedStatementPoolSiz e

and

CallableStatementPoolSiz e or more

--

CallableStatement

are passed to the user application, and the status of

PreparedStatement

and

CallableStatement

in the pool changes to in-use.

PreparedStatement and

CallableStatement

are returned to unused in the pool.

Legend:

--: Not applicable

#: The time stamps for PreparedStatement and CallableStatement in the pool are updated at the following times:

When the new

PreparedStatement

and

CallableStatement

are added in the pool

When the status of

PreparedStatement

and

CallableStatement

in the pool changes to in-use

(3) Notes on using the statement pooling functionality

The following table describes the notes on using the statement pooling functionality.

Table 3

51: Notes on using the statement pooling functionality

Condition Notes

--

--

Connecting to Oracle or SQL

Server

Compared to when the statement pooling functionality is not used, the memory is only consumed for the number of pooled PreparedStatement and

CallableStatement . For details on the memory used for each statement, see the documentation for JDBC driver in use.

There is a statement pool for each connection in the connection pool, so the maximum number of pooled

PreparedStatement

and

CallableStatement

becomes

MaxPoolSize

x

(PreparedStatementPoolSize +

CallableStatementPoolSize)

.

If you use the statement pooling functionality together with the connection count adjustment functionality or the connection error detection functionality, the unused connections removed from the connection pool are not counted as the number of connections in the connection pool. Therefore, the number of pooled

PreparedStatement

and

CallableStatement

might temporarily exceed the

maximum-connection-pool-value

x

PreparedStatementPoolSize

, and

maximum-connection-pool-value

x

CallableStatementPoolSize

.

If you use the statement pooling functionality to reuse the statements, the value specified for setMaxFieldSize

might not be initialized.

The value is not initialized when all of the following conditions are satisfied:

- DB Connector supporting Oracle JDBC Thin Driver is used

- The setMaxFieldSize

method is used to change the value of java.sql.PreparedStatement

or java.sql.CallableStatement

• When you use the statement pooling functionality and the connection error detection functionality together

One

PreparedStatement

, used for detecting the connection errors, is pooled for each connection. Therefore, when you determine

PreparedStatementPoolSize

and

CallableStatementPoolSize

, add

PreparedStatement

for detecting the connection errors in the estimation of the number of resources, and set

CallableStatementPoolSize

to a value that is less than the maximum number of statements.

#

• When you use the statement pooling functionality and the connection pool warming up functionality together

175

3. Resource Connections and Transaction Management

Condition

Connecting to Oracle or SQL

Server

Notes

When the connections are generated and pooled, one PreparedStatement , generated with the SQL statement used for detecting the connection errors, is pooled for each connection.

• When you use the statement pooling functionality and the result set holding functionality together

When you use the result set holding functionality with an Oracle connection, specify the result set holding functionality in the argument of the

Connection.prepareStatement()

method or prepareCall()

method.

You cannot specify the result set holding functionality with the

Connection.setHoldability()

method.

Legend:

--: Not applicable

#

When you use the connection error detection functionality, set

CallableStatementPoolSize

to a value less than the maximum number of statements.

If you use the connection error detection functionality, the process of detecting the connection errors is executed when the number of pooled

CallableStatement

reaches the maximum number of statements. At this time, if

CallableStatementPoolSize =

maximum-number-of-statements

is set, the maximum number of resources that can be used in one JDBC driver connection is exceeded, so an exception occurs. If an exception occurs, an error is determined; therefore, that connection is deleted from the connection pool and simultaneously the statement pool is also destroyed. In other words, using the statement pooling functionality becomes meaningless.

3.14.5 Light transaction

The light transaction is a functionality that provides an optimum environment for the local transactions. As a result, an excellent local transaction performance is obtained. The light transaction can be applied only when local transactions are used. If the light transaction functionality is enabled, the EJBs can be invoked remotely in a transaction only when the invocation destination is BMT.

The light transaction functionality is enabled by default. An error occurs if you use a global transaction when the light transaction functionality is enabled. Therefore, when you want to use a global transaction, you must disable the light transaction functionality.

You specify the settings for enabling the light transaction functionality by customizing the J2EE server properties. For

details on customizing the settings for the J2EE server operations, see

3.4.12 Settings in the execution environment

.

3.14.6 In-process transaction service

With Application Server, you can start a transaction service in the J2EE server in-process. If you start the transaction service in the in-process, the transaction processing is optimized so that the processing is executed in the J2EE server process, so a high-performance system can be implemented.

The in-process transaction service supports the OTS 1.3 specifications provided with CORBA.

3.14.7 Caching the DataSource objects

When you access a database from a J2EE application, the JNDI interface is used to request the search of the javax.sql.DataSource

type objects (hereafter,

DataSource

objects). With the default J2EE server operations, when the applicable

DataSource

is registered, the instances of the

DataSource

object are generated and returned to the application.

At this time, if you use

DataSource

object caching, the J2EE server caches the instances of the registered

DataSource

object, and returns the same instances for a search request. If you use

DataSource

object caching, the search time for the DataSource objects is shortened.

176

3. Resource Connections and Transaction Management

You specify the settings for caching the

DataSource

objects by customizing the J2EE server properties. For details

on customizing the settings for the J2EE server operations, see

3.14.10 Settings in the execution environment

.

(1) Preconditions

The

DataSource

object caching functionality is enabled when

DataSource

is looked up with the business method of the Enterprise Beans and the service method of the servlets/JSPs, and the relevant instance is not stored in the member variable.

The functionality is not enabled when the

DataSource

object looked up with the business method and service method is stored in the member variable and is also used with other methods. The functionality is also not enabled when the DataSource object looked up in the initialization methods such as the ejbCreate method of Enterprise

Bean and the init

method of servlets/JSPs is stored in the member variable and is used in the business method and service method.

(2) Notes

If you use a resource adapter such as that described below when the

DataSource

object caching functionality is used, the

<resource-ref>

definition in the property file might not be enabled during operations:

You use a resource adapter in which multiple

<resource-ref>

tags are defined for the same resource from the same J2EE component, and a different value is specified in the

<res-sharing-scope>

tag and

<resauth>

tag existing in each

<resource-ref>

tag.

To define multiple

<resource-ref>

tags with the same J2EE component, make sure you use another resource

(resource adapter with a different deployment unit).

3.14.8 Optimizing the container-managed sign-on for DB Connector

DB Connector supports container-managed sign-on and component-managed sign-on.

The features of each method are as follows:

In

container-managed sign-on

When you use a container-managed sign-on, the user name and password set for DB Connector is used to access the database.

In

component-managed sign-on

When you use a component-managed sign-on, the user name and password passed to the getConnection method of the connection factory is used to access the database.

Note that when you use

DBConnector_DABJ_XA.rar

(when you use a global transaction), only the user name and password specified in the

XAOpen

string is enabled. Therefore, you cannot perform a componentmanaged sign-on where you specify the user name and password with the getConnection

method.

If you use the sign-on optimization functionality when you perform a container-managed sign-on, the containermanaged sign-on operations are optimized and the performance of obtaining a database connection improves.

You specify the settings for optimizing the container-managed sign-on for DB Connector by customizing the J2EE

server properties. For details on customizing the settings for the J2EE server operations, see

3.14.10 Settings in the execution environment

.

!

Important note

Use the container-managed sign-on optimization when you do not want to perform a component-managed sign-on. If you perform the container-managed sign-on optimization, the component-managed sign-on cannot be used.

When you use the connection pool clustering functionality, you cannot mix container-managed sign-on and componentmanaged sign-on in one clustered connection pool.

177

3. Resource Connections and Transaction Management

3.14.9 Definitions in cosminexus.xml

From among the functionality for performance tuning, you define connection sharing in the

<rar>

tag of cosminexus.xml

. The following table describes the definition of the functionality for performance tuning in cosminexus.xml

.

Table 3

52: Definition of the functionality for performance tuning in cosminexus.xml

Specified tag Settings

<resource-external-property>-<res-sharingscope>

tag

Specify whether the obtained connections will be shared.

For details on cosminexus.xml

, see

2. Application Property File (cosminexus.xml)

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

3.14.10 Settings in the execution environment

To use the functionality for performance tuning, you must specify the settings for the J2EE server, resource adapters, and J2EE applications.

(1) J2EE server settings

You implement the J2EE server settings with the Easy Setup definition file. Specify the performance tuning definition in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy Setup definition file.

The following table describes the definition of the functionality for performance tuning in the Easy Setup definition file.

Table 3

53: Definition of the functionality for performance tuning in the Easy Setup definition file

Item Specified parameters Settings

Enabling connection sharing outside the Application Server-managed transactions ejbserver.connectionpool.sharingOutsideTransa

ctionScope.enabled

Connection association

Statement initialization in the statement pooling functionality

Caching the DataSource objects

Optimizing the container-managed sign-on for DB Connector ejbserver.connectionpool.association.enabled

ejbserver.connectionpool.association.enabledD

espiteUnshareableSetting ejbserver.connector.statementpool.clear.backc

ompat ejbserver.jndi.cache.reference

ejbserver.connectionpool.applicationAuthentic

ation.disabled

Specifies the connection sharing operations to be performed when connections are obtained multiple times outside the Application Servermanaged transactions.

Specifies whether to use the connection association functionality.

Specifies whether to use the connection association functionality even when non-sharing

# of resources is set in the system properties.

Specifies the content of the statement to be initialized when a statement is reused in the statement pooling functionality.

Specifies whether to enable

DataSource object caching.

Specifies whether to enable the optimization

178

3. Resource Connections and Transaction Management

Item Specified parameters Settings

Optimizing the container-managed sign-on for DB Connector

Timeout in error detection ejbserver.connectionpool.applicationAuthentic

ation.disabled

ejbserver.connectionpool.validation.timeout

functionality of container-managed signon.

Specifies the timeout value for the connection error detection functionality and the timeout value for deleting the connections by using the connection count adjustment functionality.

#: When

Unshareable

(resources are not share) is specified in the

<res-sharing-scope>

tag of the WAR property file,

Entity Bean property file, Session Bean property file, or Message-driven Bean property file.

For details on the light transaction settings, see

3.4.12 Settings in the execution environment

.

Note that the in-process transaction service functionality is used with the default settings. You need not specify the settings.

For details on the Easy Setup Definition file and parameters, see

4.6 Easy Setup Definition file

in the

uCosminexus

Application Server Definition Reference Guide

.

(2) Resource adapter settings

Use the server management commands and property files to specify the resource adapter settings in the execution environment. Use the HITACHI Connector Property file to define the functionality for performance tuning.

The following table describes the definition of the functionality for performance tuning in the HITACHI Connector

Property file.

Table 3

54: Definition of the functionality for performance tuning in the HITACHI Connector Property file

Category Items Specified tags Settings

Connection pooling Minimum and maximum number of connections

Connection pool warming up

Connection management threads

MinPoolSize

and

MaxPoolSize

in the

<property> tag

Warmup in the <property> tag

NetworkFailureTimeout in the

<property>

tag

Specifies the minimum and maximum number of connections to be pooled in the connection pool.

Connection count adjustment functionality

ConnectionPoolAdjustm entInterval

in the

<property>

tag

Specifies the use of the connection pool warming up functionality.

Specifies the use of the connection management threads.

When you use the connection management threads, a timeout is set for the connection error detection functionality and the connection count adjustment functionality.

The timeout value is fixed at 5 seconds with version 07-60 or earlier. With version 08-00 or later, you can specify any timeout value

(default value is 5 seconds).

Specifies the interval at which the connection count adjustment functionality will be operated.

Note that when a timeout is set for the connection count adjustment functionality, the use of connection management threads is enabled with

NetworkFailureTimeout .

#1

179

3. Resource Connections and Transaction Management

Category Items Specified tags Settings

Statement pooling Pool size of

PreparedStatemen t

#2

Pool size of

CallableStatemen t

#2

PreparedStatementPool

Size property>

CallableStatementPool

Size

in the

in the property>

<config-

tag

<config-

tag

Specifies the pool size of

PreparedStatement

Specifies the pool size of

CallableStatement

.

.

#1: The key is the same as that for the timeout in the connection error detection functionality. Therefore, when you use a timeout for the connection error detection functionality, a timeout is also used for the connection count adjustment functionality.

#2: In XDM/RD E2 version 11-01 or earlier, the statement pooling functionality cannot be used; therefore, so specify 0 for these properties.

For details on the HITACHI Connector Property file, see

4.1 HITACHI Connector Property file

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

(3) J2EE application settings

You implement the J2EE application settings in the execution environment using the server management commands and property files. To define the functionality for performance tuning, use the WAR property file, Session Bean property file, Entity Bean property file, or Message-driven Bean property file.

The tags specified in these property files correspond to cosminexus.xml

or DD. For details on the definitions in cosminexus.xml

, see

3.14.9 Definitions in cosminexus.xml

.

180

3. Resource Connections and Transaction Management

3.15 Functionality for fault tolerance

This section describes the functionality for fault tolerance.

The following table describes the organization of this section.

Table 3

55: Organization of this section (Functionality for fault tolerance)

Category Title

Explanation

Implementation

Settings

Detecting the connection errors

Waiting for a connection when connections deplete

Retrying to obtain a connection

Displaying the connection pool information

Clearing the connection pool

Automatically closing the connections

Connection sweeper

Transaction timeout and statement cancellation

Transaction recovery

Output of the SQL statement for troubleshooting

Automatically closing the objects

Definitions in cosminexus.xml

Settings in the execution environment

Note: The functionality-specific explanation is not available for "Operations".

3.15.6

3.15.7

3.15.8

3.15.9

3.15.10

3.15.11

3.15.12

3.15.13

Reference location

3.15.1

3.15.2

3.15.3

3.15.4

3.15.5

3.15.1 Detecting the connection errors

When you use connection pooling, an error connection might be returned for a connection request from a user program if a resource is down or a network error occurs. If you use the connection error detection functionality, you can check whether an error has occurred in the pooled connections and make sure that an error connection is not returned unless otherwise necessary.

You can use the connection error detection functionality together with the connection retry functionality. In this case, if a connection error is detected during a connection request from the user program, you can try to obtain a new connection and return a connection to the user program as soon as the error is restored.

Note that creating and returning a new connection is only enabled when the time for detecting the connection errors is set to "when the connection is requested".

For the times at which the connection errors are detected, see

(2) Timing at which error detection is implemented

.

(1) Preconditions

The following table describes the usability of the connection error detection functionality.

Table 3

56: Usability of the connection error detection functionality

Resource Connection method

Database

Database queue

OpenTP1

DB Connector

DB Connector for Cosminexus RM and Cosminexus RM uCosminexus TP1 Connector

Usability

Y

Y

N

#1

181

3. Resource Connections and Transaction Management

OpenTP1

Resource

SMTP server

JavaBeans resource

Other resources

Connection method

TP1/Message Queue - Access mail configuration

--

Resource adapters conforming to the Connector 1.0

specifications or Connector 1.5 specifications

Usability

N

#1

R

N

N

#2

Legend:

Y: Available

N: Not available

R: Depends on conditions

--: Not applicable

#1: The connection error detection functionality provided by Application Server is not available, but uCosminexus TP1 Connector or

TP1/Message Queue - Access provide functionality similar to the connection error detection functionality.

#2: Available when you are using the resource adapters conforming to the Connector 1.5 specifications and when the resource adapter implements the getInvalidConnections

method of the

ValidatingManagedConnectionFactory

interface.

(2) Timing at which error detection is implemented

You can choose one of the timings listed in the table as the timing for detecting the connection errors.

Table 3

57: Timing for detecting the connection errors

Error detection timing Contents

When a connection is requested

Regular intervals

Error detection is implemented every time a connection is obtained. In this case, the response performance of the connection request deteriorates, but the probability of obtaining an error connection will lower. This is useful when the frequency of connection requests is less and obtaining an error connection is not permitted.

Error detection is implemented at fixed time intervals. By lengthening the error detection interval to some extent, you can reduce the performance deterioration caused by the error detection processing. However, the probability of obtaining an error connection is higher. This is useful when the frequency of connection requests is high and obtaining an error connection is permitted to some extent.

Note that by default error detection is implemented for a connection request. You can also specify settings to not detect the connection errors.

You specify the settings to switch between the enabling and disabling of connection error detection and the time at

which errors are detected as the resource adapter properties. For details on the resource adapter settings, see

3.15.13

Settings in the execution environment

.

(3) Timeout in error detection

You can specify a timeout for the response time to detect the connection errors.

If a server error or network error occurs and no response returns from the resource, a response might not be returned even for the execution of the connection error detection. By setting a timeout, the connection check is terminated and the processing can be continued even if no response returns from the resource. Note that you can specify any value for the timeout in error detection in the key specified for the J2EE server in the Easy Setup definition file (the default value is 5 seconds).

The connection management threads are used to operate the timeout for detecting the connection errors. The connection management threads are created in the system according to the maximum number of connections in the connection pool, when the resource adapter starts. The relationship between the number of connection management threads and the maximum number of connections in the connection pool is as follows:

Number-of-connection-management-threads

=

maximum-number-of-connections-in-the-connection-pool

x

2

Therefore, if you set a timeout for detecting the connection errors, a lot of memory is consumed compared to when the timeout is not set. Estimate the required amount of memory appropriately.

182

3. Resource Connections and Transaction Management

Also, if the settings for the maximum number of connections in the connection pool are unlimited, a message is output and the timeout for detecting the connection errors is disabled.

For notes on enabling the timeout for detecting the connection errors, see

(5) Notes

.

You specify the settings for enabling and disabling the timeout for detecting the connection errors by customizing the resource adapter properties. For details on the resource adapter property settings, see

3.15.13 Settings in the execution environment

.

(4) Checking operations

This section describes the operations when the detection of connection errors is implemented for a connection request, and when the detection of connection errors is implemented at regular intervals.

• When the detection of connection errors is implemented for a connection request

The operations when the detection of connection errors is implemented for a connection request are as follows:

1. The unused connections are obtained from a connection pool.

2. The connection check method is used to check if there are any errors in the connections.

If the timeout for detecting the connection errors is disabled, this check is implemented by extending the connection request.

If the timeout for detecting the connection errors is enabled, this check is implemented with the connection management threads. Due to an error such as a server error or network error, when the response from the check method does not return within the timeout value, a connection error is determined to have occurred. At this time, a message is output.

Note that if the connection check method is not implemented for a resource adapter, the connection state is not checked.

3. If an error occurs in the connection, the connection used for the check is destroyed and a new connection is created and returned to the user program.

If there is no error in the connection, the connection used for the check is returned to the user program.

• When the detection of connection errors is implemented at regular intervals

The operations when the detection of connection errors is implemented at regular intervals are as follows:

1. One unused connection is obtained from the connection pool and checked for validity.

However, if the unused connections are not pooled, the connections are not checked.

2. If the timeout for detecting the connection errors is disabled, the connection check method is used to check if there are any errors in the connection, at regular intervals.

If the timeout for detecting the connection errors is enabled, the connection management threads are used to implement a check at regular intervals. Due to an error such as a server error or network error, when the response from the check method does not return within the timeout value, a connection error is determined to have occurred. At this time, a message is output.

Note that if the connection check method is not implemented for a resource adapter, the connection state is not checked.

3. If there is an error in the connection and if the timeout for detecting the connection errors is disabled, the connection used for the connection check is destroyed, and the in-use connection in the connection pool is marked as non-reusable. Also, the unused connection is destroyed.

If the timeout for detecting the connection errors is enabled, the connection used for the connection check is destroyed and the connection management threads mark the in-use connection in the connection pool as nonreusable. Also, the unused connection is removed from the connection pool and destroyed.

If there is no error in the connection, the connection used for the connection check is returned to the connection pool.

(5) Notes

The notes on the error detection functionality are as follows:

(a) Notes on using the resources in a parallel server configuration

When the detection of connection errors is implemented at regular intervals, a sample check is performed for the connections in the connection pool, so even if errors occur on some of the servers, the errors might not be detected.

183

3. Resource Connections and Transaction Management

(b) Notes on enabling the timeout for detecting the connection errors

The notes on enabling the timeout for detecting the connection errors are as follows:

If you set a timeout for the detection of connection errors, error detection threads are generated in the system according to the number of connections in the connection pool. Therefore, if you set a timeout for the detection of connection errors, note that a lot of memory is consumed compared to when the timeout is not set.

You can only create the error detection threads equal to twice the maximum number of connections in the connection pool. Estimate the required amount of memory appropriately.

If the system operations are continued when the errors, such as the server error or network error, occur repeatedly, the connection management threads that are executing the connection check method continue to increase and all the connection management threads prepared in the system might be used up. If no connection management threads are available, a message is output and the connection request results in an error.

When the detection of connection errors is implemented, the unused connections removed from the connection pool are not counted as the number of connections in the connection pool. Therefore, the total of the connections in the connection pool and the unused connections removed from the connection pool might temporarily exceed the maximum number of connections in the connection pool.

(c) Notes on using resources that cannot use the error detection functionality

Set the following parameter in the HITACHI Connector Property file so that the connection management threads are not used for resources that cannot use the error detection functionality:

Timeout for detecting the connection errors

ValidationType=0 in <property> tag

3.15.2 Waiting for a connection when connections deplete

The state when the connections are pooled up to the maximum number specified for the connection pool and there are no usable connections in the pool is called

connection depletion

.

When the connections deplete, you can set the connection requests to a pending state. The pending connection requests can obtain a connection as soon as a connection is released. Due to this, connections can be obtained efficiently when the connections are depleted. The following figure shows the process of waiting to obtain a connection when connections deplete.

Figure 3

36: Waiting for a connection when connections deplete

184

In this figure, the maximum number of the connection pool is 2. Therefore, even if there are connection requests from four getConnection methods, only up to two requests can be processed. The first two connection requests can obtain the connections because there are connections in the connection pool. The remaining two are in the connection depletion state, so these requests enter the connection pending queue and wait for a connection to be released.

Note that you can specify settings to wait to obtain a connection when you use a connection pool.

To wait to obtain a connection, you must set up the following content as the resource adapter properties:

Whether to wait to obtain a connection when the connections deplete

Maximum connection pending time

For details on the resource adapter settings, see

3.15.13 Settings in the execution environment

.

3. Resource Connections and Transaction Management

(1) Operations for connection depletion

When you specify settings to wait to obtain a connection, the connection requests during connection depletion enter a pending state. If the waiting time for obtaining a connection request exceeds the maximum waiting time, an exception will be thrown in the user program.

Also, the connection requests are restarted at one of the following times:

When a connection is released and an unused connection is available

When a connection is destroyed and the number of connections is less than the maximum number

Note that if an error occurs after the connection requests are restarted, the retry processing is executed if the connection retry functionality is enabled.

3.15.3 Retrying to obtain a connection

Connection retry is a functionality that automatically retries to obtain a connection when there are no available connections in the connection pool and when the establishment of a physical connection fails. By using the connection retry functionality, if an attempt to obtain a connection fails, you need not use the user program to retry to obtain a connection.

You can retry to obtain a connection when one of the following conditions is satisfied:

All the following conditions are satisfied and there are no available connections (unused connections) in the connection pool:

The line 'waiting for a connection when connections deplete' is disabled.

The total number of connections in the connection pool has reached the maximum number of connections to be pooled.

When a physical connection cannot be established due to any of the following conditions:

The total number of connections in the connection pool has reached the maximum number of connections to be pooled, and there are no unused connections with matching authentication information.

The total number of connections in the connection pool has not reached the maximum number of connections to be pooled.

Connection pooling is disabled.

Note that if a connection cannot be obtained even after retrying, an exception is reported to the application program and the process of obtaining a connection fails.

For the operations to be performed when the connection pool depletes, follow the description in

3.15.2 Waiting for a connection when connections deplete

.

To implement the connection retry functionality, you must set up the following content as the resource adapter properties:

Retry count

Specifies the number of times the process will be retried.

Retry interval

Specifies the interval until the next retry attempt in seconds.

Note that if the retry count and retry interval is increased, the requests might have to wait when the processing to obtain connections accumulate.

For details on the resource adapter settings, see

3.15.13 Settings in the execution environment

.

(1) Preconditions

The following table describes the preconditions for using the connection retry functionality.

185

3. Resource Connections and Transaction Management

Table 3

58: Using the connection retry functionality

Resource Connection method

Database

Database queue

OpenTP1

SMTP server

JavaBeans resource

Other resources

DB Connector

DB Connector for Cosminexus RM and

Cosminexus RM uCosminexus TP1 Connector

TP1/Message Queue - Access

Mail configuration

--

Resource adapters conforming to the

Connector 1.0 specifications or Connector 1.5

specifications

Legend:

Y: Available

N: Not available

--: Not applicable

Usability

Y

Y

N

N

Y

Y

Y

3.15.4 Displaying the connection pool information

You can use the cjlistpool

command to display the information on the connections in the connection pool. You can also execute the cjlistpool command for the member resource adapters when the connection pool clustering functionality is used.

For the command details, see

cjlistpool (Displaying the list of connection pools)

in the

uCosminexus Application

Server Command Reference Guide

. Also, for details on the connection pool clustering functionality, see

3.17

Functionality for connection pool clustering

.

An example of displaying the connection information of a member resource adapter is as follows. Note that if the connection pool is disabled, the connection information is not displayed.

186

3. Resource Connections and Transaction Management

Figure 3

37: Example of displaying the connection information of a member resource adapter

3.15.5 Clearing the connection pool

If a connection is lost because a database server is down, the pooled connections remain in the connection pool. You can delete these connections using the cjclearpool command.

For the command details, see

cjclearpool (Deleting the connections in the connection pool)

in the

uCosminexus

Application Server Command Reference Guide

.

3.15.6 Automatically closing the connections

The connection of a resource that is opened with the user program must be closed with the user program. With this functionality, the Web container and EJB container automatically close a connection if the user program cannot close the connection due to reasons such as the occurrence of an exception.

You can enable and disable the auto-close connection functionality based on the functionality. The following table describes the methods and switching of auto-close connection.

187

3. Resource Connections and Transaction Management

Table 3

59: Auto-close connection method and switching of the functionality

Auto-close method Switching between enable and disable

Web container-based auto-close connection

EJB container-based auto-close connection

Y

#1, #2

N

#1 Always enabled.

Remarks

--

Legend:

Y: Can be switched

N: Cannot be switched

--: Not applicable

#1: The target resource is the resource adapter connection.

#2: The Web container-based auto-close connection functionality is enabled by default. You specify the settings for disabling the functionality by customizing the J2EE server properties. For details on customizing the settings for the J2EE server operations, see

3.15.13 Settings in the execution environment

.

(1) Web container-based auto-close connection

From among the JDBC connections that are obtained or opened in the servlet and JSP service methods, the connections that are not closed when the method execution finishes are automatically closed by the J2EE container.

Due to this, the connections that are open and accumulating can be closed automatically.

Note that the auto-close connection functionality is also enabled when the connections are obtained or used by other methods in a servlet, or by the external classes.

The Web container-based auto-close connection is executed when the servlet and JSP service methods are completed.

(2) EJB container-based auto-close connection

With this functionality, the EJB container automatically closes and releases a connection if the user cannot close a resource connection obtained in the EJB, due to reasons such as the occurrence of an exception.

The EJB container-based auto-close connection is implemented at the following times:

When the EJB is destroyed

When a business method is returned with the Stateless Session Bean

When the Stateful Session Bean is passivated

When a business method is returned with the Singleton Session Bean

Note that auto-close connection is implemented at the following times with the Singleton Session Bean or Stateless

Session Bean specifying the

@Asynchronous

annotation:

When the Singleton Session Bean or Stateless Session Bean instances are destroyed

When the execution of the method specifying the @Asynchronous annotation in the Singleton Session Bean or

Stateless Session Bean is completed

(3) Method that confirms the execution of auto-close connection

You can use the message log or PRF trace to confirm that the auto-close connection functionality was executed.

We recommend that you use the message log to confirm the execution of the functionality when the performance need not be considered, such as during testing and troubleshooting; and the PRF trace when you want to confirm the execution of the functionality during real operations.

(a) Method of confirming with the message log

Set the log level to

Warning

.

When auto-close connection is executed, KDJE31010-W is output to the J2EE server message log.

For details on how to set the log level, see

3.3.6 Settings for collecting the J2EE server log

in the

uCosminexus

Application Server Maintenance and Migration Guide

.

188

3. Resource Connections and Transaction Management

(b) Method of confirming with the PRF trace

Set the PRF trace collection level of the JCA container functionality layer to Detail .

When auto-close connection is executed, the following event IDs are output to the PRF trace file:

0x8B84

0x8B85

For details on how to set the PRF trace collection level, see

3.3.6 Settings for collecting the J2EE server log

in the

uCosminexus Application Server Maintenance and Migration Guide

. Also, for details on how to set the PRF trace collection level for each functionality layer, see

cprflevel (Displaying and changing the PRF trace collection level)

or

cprfstart (Starting the PRF daemon)

in the

uCosminexus Application Server Command Reference Guide

.

(4) Notes

The connections that are obtained using the threads generated by the user (user thread) in Servlets/ JSPs are not closed automatically.

If there are unconcluded transactions when a connection is auto-closed, the transaction is rolled back. Also, if there are unconcluded transactions when a connection is closed with a user program, the transactions are committed implicitly.

3.15.7 Connection sweeper

Connection sweeper is a functionality that monitors the connection pool at regular intervals, and destroys the unused connections that are not used for a fixed period of time. If the time elapsed since the applicable connection was last used is equal to the specified time or more, the connection will be destroyed. This functionality can be used in cases when there is a gateway, such as a firewall, between Application Server and database server, and the connection is disconnected at a fixed time.

The connection sweeper functionality is disabled by default. Note that you specify the settings for the connection

sweeper functionality as the resource adapter properties. For details on the resource adapter settings, see

3.15.13

Settings in the execution environment

.

Note that when you use the connection sweeper functionality, specify settings so that the total value of

ConnectionTimeout

and

SweeperInterval

in the

<property>

tag of the HITACHI Connector Property file is less than the connection disconnecting time. Also, by setting a long

ConnectionTimeout

, you can extend the period for which a connection is stored.

3.15.8 Transaction timeout and statement cancellation

The transaction timeout functionality monitors the time elapsed since the transaction was started, and rolls back the transaction when the specified time has lapsed. The monitoring time is from the completion of transaction startup until the start of transaction conclusion. After the transaction times out, the access to the JTA and the JDBC interface in the applicable transaction reports an exception.

The transaction timeout functionality is enabled for the Application Server-managed transactions.

Note that after a transaction times out in the BMT, servlets, or JSPs, if you issue

UserTransaction.commit/ rollback

for the applicable transaction, you can access the JTA and JDBC interface.

#: Whether a timeout has occurred is checked every second; therefore, a calculation error of a maximum of one second occurs for the time set up as a transaction timeout.

(1) Transaction timeout settings

You can specify the transaction timeout settings for the J2EE servers,

UserTransaction

interface, or CMT attribute of the EJB.

189

3. Resource Connections and Transaction Management

(a) Settings for the J2EE servers

You specify the transaction timeout settings for the J2EE servers by customizing the J2EE server properties. For

details on customizing the settings for the J2EE server operations, see

3.15.13 Settings in the execution environment

.

(b) Settings for the UserTransaction interface

Use the setTransactionTimeout

method of the

UserTransaction

interface to change the default values.

(c) Settings for the CMT attribute of the EJB

Use the server management commands to specify the settings for the CMT attribute of the EJB. You can choose to specify the settings for Beans, interfaces, and methods.

The settings are enabled for one of the following methods:

Method in which the transaction attribute is set to

Required

and the EJB container starts the transaction

Method in which the transaction attribute is set to

RequiresNew

The timeout settings are disabled for the

Supports

attribute and

Mandatory

attribute operating in the transaction propagated from the client and for the

NotSupported

attribute and

Never

attribute that do not use transactions.

For details on the transaction attributes, see

2.7.3 CMT

in the

uCosminexus Application Server EJB Container

Functionality Guide

.

Note that the priority order of the settings is as follows:

1. Settings for methods

2. Settings for interfaces

3. Settings for Beans

4. Settings for J2EE servers

You specify the transaction timeout settings for Beans as the attributes (properties) of the Session Bean, Entity Bean, or Message-driven Bean included in the J2EE application. For details on the J2EE application settings, see

3.15.13

Settings in the execution environment

.

(2) Statement cancellation when a transaction timeout occurs

If a transaction times out when the SQL statement being executed has not returned, the statement is cancelled.

To enable statement cancellation, you must specify true

in the

CancelStatement

property of DB Connector. For

details on the resource adapter settings, see

3.15.13 Settings in the execution environment

.

3.15.9 Transaction recovery

This functionality concludes the 2-phase transactions that are in the prepared state or heuristic completion state due to the J2EE server and resource manager errors. This functionality is enabled when you use the global transactions.

When you start a J2EE server, the full transaction recovery processing is executed unconditionally for the imported resources. Also, partial recovery processing is executed even when the resource manager is down during the execution of a transaction.

Note that when you are using the in-process transaction service, you can display the transaction status with the server management command cjlisttrn

. Also, you can use the cjlisttrnfile

command to display the unconcluded transaction information remaining in the status file of a stopped J2EE server.

When the light transaction is enabled, the transaction recovery functionality is not available.

!

Important note

If the transaction is not recovered due to the restarting of the J2EE server, the user must recover the transaction manually following the recovery procedure for each resource.

190

3. Resource Connections and Transaction Management

(1) Checking the unconcluded transactions and setting up a timeout when the J2EE server is terminated

When the J2EE server terminates normally, the J2EE server checks if there are any unconcluded transactions and then stops. If unconcluded transactions exist, the J2EE server waits infinitely until the transactions are completed. Also, the resources cannot be deleted until that transaction is concluded.

On the other hand, if a transaction need not be resolved quickly, such as during system development, you can set a timeout value for checking the unconcluded transactions. If a timeout occurs, the stop processing of the J2EE server is executed even if the checking of the unconcluded transactions is not complete. However, set a timeout value for operations such as J2EE application development. To guarantee transaction reliability during the operations of the

J2EE applications, we recommend that you do not set a timeout value.

You specify the timeout settings by customizing the J2EE server properties. For details on customizing the settings for

the J2EE server operations, see

3.15.13 Settings in the execution environment

.

(2) Notes

The notes on transaction recovery are as follows:

(a) Notes when the resource adapter fails to start when you start the J2EE server

When you start the J2EE server, if the resource adapter using the

XATransaction

fails to start, the J2EE server does not recover the transaction, outputs the message KDJE48605-E, and terminates forcefully. In this case, eliminate the reason due to which the resource adapter failed to start, and then restart the J2EE server. This concludes the prepared or heuristic transactions.

(b) Notes on restarting the J2EE server

If you delete the resources after the J2EE server terminates forcefully or abnormally, the transaction cannot be recovered. Therefore, do not change the configuration of the resource when you restart the J2EE server.

You must restart the J2EE server with the same port as the receiving port before forced or abnormal termination.

Therefore, do not change the value of the parameter ejbserver.distributedtx.recovery.port

in the

<configuration>

tag in the Easy Setup definition file. Note that if you set up the system without using

Management Server, do not change the ejbserver.distributedtx.recovery.port

key in usrconf.properties

.

(c) Permissions for executing transaction recovery

The default user set up in the resource (such as

XADataSource

) executes the recovery. Specific permissions and settings are required to scan the unconcluded transactions depending on the resource manager. Also, when multiple users sign on, the default user must be assigned appropriate permissions in the resource manager that can conclude the transactions of the other users. For details, see the documentation for each resource.

When a transaction is recovered in Oracle and Oracle JDBC Thin Driver is used as the JDBC driver, the user must have the following permissions:

SELECT permission for SYS.DBA_PENDING_TRANSACTIONS

FORCE ANY TRANSACTION permission

Permission to

EXECUTE SYS.DBMS_SYSTEM

For details on the settings to use Oracle, see

4.1.7 Setting up the database connection environment (Oracle settings)

in the

uCosminexus Application Server System Setup and Operation Guide

.

(d) Number of connections used

Note the number of connections that are used when a transaction is recovered.

With J2EE server, you establish the following connections for one resource adapter that has the transaction support level

XATransaction

:

Connections pooled in a connection pool

Connection for recovery (one)

191

3. Resource Connections and Transaction Management

The maximum number of connections that the same resource manager requires is the value indicated by the following expression. Take precautions when there is an upper limit to the number of connections for the resource manager.

Maximum number of connections required for the same resource manager = IR(1) + ... + IR(

N

) +

N

IR(i)

Maximum number of connections in the pool settings for the i th

resource adapter.

1 <= i <= N

.

N

For the resource adapters conforming to the Connector 1.0 specifications, the number of resource adapters connected to the same resource manager.

For the resource adapters conforming to the Connector 1.5 specifications, total number of connection definitions in the resource adapter connected to the same resource manager.

The target resource adapter is the one that is running and has the transaction support level

XATransaction

.

(3) Procedure for checking the transaction information

This section describes how to check the transaction information of a running and stopped J2EE server. You can check information such as the state of the transactions in a running J2EE server and the presence or absence of unconcluded transactions in a stopped J2EE server.

(a) Procedure for checking a running transaction

You can check the information for a running transaction on the J2EE server. You can check the information such as the transaction state, global transaction ID, time elapsed, and the branch type.

Use the cjlisttrn

command to check a running transaction. The format and example of execution are as follows:

Format of execution

cjlisttrn [

server-name

] -bqual

Example of execution

cjlisttrn MyServer -bqual

You can also check the state of an unconcluded transaction. To check the information for an unconcluded transaction, specify

-pending

in the argument. The format and example of execution for checking the information on an unconcluded transaction are as follows:

Format of execution

cjlisttrn [

server-name

] -pending -bqual

Example of execution

cjlisttrn MyServer -pending -bqual

For details on the cjlisttrn command and the information that can be obtained, see

cjlisttrn (Displaying the transaction information of a running J2EE server)

in the

uCosminexus Application Server Command Reference

Guide

.

(b) Procedure for checking a stopped transaction

You can check the transaction information of a stopped J2EE server. You can check the information such as the transaction state, global transaction ID, time elapsed, and the branch type. You can also check if any unconcluded transactions are remaining.

Use the cjlisttrnfile

command to check a stopped transaction. The format and example of execution are as follows:

Format of execution

cjlisttrnfile [

server-name

] -bqual

192

3. Resource Connections and Transaction Management

Example of execution

cjlisttrnfile MyServer -bqual

If there are any unconcluded transactions when the J2EE server has stopped, conclude the transaction by executing the following processing as and when required:

Restart the J2EE server ( cjstartsv command)

Start the J2EE server in the recovery mode ( cjstartrecover

command)

For details on the cjlisttrnfile

command and the information that can be obtained, see

cjlisttrnfile (Displaying the transaction information of a stopped J2EE server)

in the

uCosminexus Application Server Command Reference

Guide

.

3.15.10 Output of the SQL statement for troubleshooting

If a deadlock or slowdown error occurs, the issued SQL statement might be the cause of the error. Therefore, the output of the issued SQL statement to the log makes the error cause analysis easy. The SQL information output to the log is called the

SQL statement for troubleshooting

.

(1) Output timing

The SQL statement for troubleshooting is output at the following times:

When the transaction times out

When a J2EE application is terminated forcefully

When the method cancellation command is executed

When method cancellation is executed after a method timeout occurs

(2) Output destination

The SQL statement for troubleshooting is output to the resource adapter operation log and the trace based performance analysis.

With the resource adapter operation log, the SQL statement for troubleshooting is output to the KDJE50080-W message. For details, see

KDJE50080-W

in the

uCosminexus Application Server Messages

.

With the trace based performance analysis, the SQL statement for troubleshooting is output to the event ID

0x8C41

.

For details, see

8. Trace Collection Points and PRF Trace Collection Levels of the Trace Based Performance Analysis

in the

uCosminexus Application Server Maintenance and Migration Guide

.

(3) Output content

If the SQL statement is issued in the connection for output, the physical connection stores the SQL statement. This

SQL statement stored by the physical connection is output as the SQL statement for troubleshooting.

Physical connection that stores the SQL statement

The physical connections storing the SQL statements, for the various timings at which the SQL statement for troubleshooting is output, are as follows:

• When a transaction times out

The physical connection supporting the connection that participates in the transaction.

• When a J2EE application is terminated forcefully, when the method cancellation command is executed, or when method cancellation is executed after a method timeout occurs

The physical connection supporting the connection that participates in the transaction when the transaction is being processed.

If no transactions are being used, then the physical connection supporting the connection being used by the instance that forcefully stops the application or executes method cancellation stores the SQL statement for troubleshooting. Note that the SQL statement for troubleshooting is not output to a closed connection.

193

3. Resource Connections and Transaction Management

APIs storing the SQL statement

When the following APIs are invoked by the user application, the SQL statement passed in the argument is stored in the physical connection. One SQL statement is stored for each physical connection. Whenever an API is invoked, the latest SQL statement is overwritten. The following table describes the APIs storing the SQL statement.

Table 3

60: List of APIs storing the SQL statement

Interface Method java.sql.Connection

java.sql.Statement

prepareCall(String sql) prepareCall(String sql, int resultSetType, int resultSetConcurrency) prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) prepareStatement(String sql) prepareStatement(String sql, int autoGeneratedKeys) prepareStatement(String sql, int[] columnIndexes) prepareStatement(String sql, int resultSetType, int resultSetConcurrency) prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) prepareStatement(String sql, String[] columnNames) addBatch(String sql) execute(String sql) execute(String sql, int autoGeneratedKeys) execute(String sql, int[] columnIndexes) execute(String sql, String[] columnNames) executeBatch()

#1 executeQuery(String sql) executeUpdate(String sql) executeUpdate(String sql, int autoGeneratedKeys) executeUpdate(String sql, int[] columnIndexes) executeUpdate(String sql, String[] columnNames) java.sql.PreparedStatement

Display target method inherited from java.sql.Statement

addBatch()

#2 java.sql.CallableStatement

execute()

#2 executeQuery()

#2 executeUpdate()

#2

Display target method inherited from java.sql.PreparedStatement

#1: When you execute the executeBatch() method, the SQL statement finally added with the addBatch(String sql) method and addBatch()

method is stored in the physical connection.

#2: When you execute the addBatch()

method, execute()

method, executeQuery()

method, and executeUpdate()

method, the SQL statement given by the arguments of the prepareStatement

method and

194

3. Resource Connections and Transaction Management prepareCall method of java.sql.Connection

is stored in the physical connection. However, the IN parameter place holder ("

?

") of the SQL statement is output as "

?

" without being substituted.

(4) Notes

The notes on the functionality to output the SQL statement for troubleshooting are as follows:

This functionality is always enabled when you use DB Connector. The functionality is disabled when a resource adapter other than DB Connector is used.

If the messages output to the SQL log for troubleshooting, in the resource adapter operation log, exceed 4 KB, the message is only output up to 4 KB.

For the connections shared by connection sharing and connection association, only one SQL log for troubleshooting is output because there is one physical connection.

3.15.11 Automatically closing the objects

The objects such as the Statement objects that are opened with the user program must be closed with the user program. However, if the objects cannot be closed, DB Connector automatically closes the following objects that are generated from the user handle ( java.sql.Connection

):

Statement object

PreparedStatement object

CallableStatement

object

ResultSet

objects generated from various statements and

DatabaseMetaData

3.15.12 Definitions in cosminexus.xml

From among the functionality for fault tolerance, you specify the CMT transaction timeout definition in the

<ejbjar>

tag of cosminexus.xml

. The following table describes the definition of the functionality for fault tolerance in cosminexus.xml

.

Table 3

61: Definition of the functionality for fault tolerance in cosminexus.xml

Specified tag Settings

<message>-<ejb-transaction-timeout>

tag

<entity>-<ejb-transaction-timeout>

tag

<session>-<ejb-transaction-timeout> tag

Specifies the time at which the CMT transaction will time out.

For details on cosminexus.xml

, see

2. Application Property File (cosminexus.xml)

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

3.15.13 Settings in the execution environment

This subsection describes the settings for using the functionality for fault tolerance.

Note that the settings for the following functionality need not be specified beforehand.

Displaying the connection pool information

Clearing the connection pool

Output of the SQL statement for troubleshooting

Automatically closing the objects

195

3. Resource Connections and Transaction Management

(1) J2EE server settings

You implement the J2EE server settings in the Easy Setup definition file. Specify the fault tolerance definition in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy Setup definition file.

The following table describes the definition of the functionality for fault tolerance in the Easy Setup definition file.

Table 3

62: Definition of the functionality for fault tolerance in the Easy Setup definition file

Category Property Settings

Automatically closing the connections

Transaction timeout (for J2EE servers)

#1

Transaction recovery ejbserver.webj2ee.connectionAu

toClose.enabled

ejbserver.jta.TransactionManag

er.defaultTimeOut

Specifies whether the connection will be automatically closed by the Web application.

Specifies the default timeout value for the transactions running on the J2EE server.

Timeout during the checking of unconcluded transactions

#2

Timeout in error detection ejbserver.distributedtx.recove

ry.port

ejbserver.distributedtx.recove

ry.completionCheckOnStopping.t

imeout ejbserver.connectionpool.valid

ation.timeout

Specifies the fixed port number used for transaction recovery when a global transaction is used.

Specifies the timeout value for checking if an in-progress transaction is complete, when the

J2EE server is stopped.

Specifies the timeout value for the connection error detection functionality and the timeout value for the connection deletion processing by the connection count adjustment functionality.

#1: In the CMT, you can also specify the settings for the Enterprise Beans, interfaces, and methods. To specify the settings for

Enterprise Beans, interfaces, and methods, use the server management commands to specify the settings in the property files when

the J2EE applications are set up. For details on the J2EE application settings, see

3.15.12 Definitions in cosminexus.xml

.

#2: Set up the timeout during application development. To guarantee transaction reliability during the operations of the J2EE applications, we recommend that you do not set a timeout value.

For details on the Easy Setup Definition file and parameters, see

4.6 Easy Setup Definition file

in the

uCosminexus

Application Server Definition Reference Guide

.

(2) Resource adapter settings

Use the server management commands and property files to specify the resource adapter settings in the execution environment. Use the HITACHI Connector Property file to define the functionality for fault tolerance.

The following table describes the definition of the functionality for fault tolerance in the HITACHI Connector

Property file.

Table 3

63: Definition of the functionality for fault tolerance in the HITACHI Connector Property file

Items Specified parameters Settings

Detecting the connection errors ValidationType and

ValidationInterval

in the

<property>

tag

Connection management threads

NetworkFailureTimeout

in the

<property> tag

Specifies the time at which the connection errors will be detected and the intervals at which the errors will be detected.

Note that to set up a timeout for detecting the connection errors, you enable the usage of the connection management threads with

NetworkFailureTimeout

.

#1

Specifies whether the connection management threads will be used.

When you use the connection management threads, a timeout is set for the connection error detection functionality and the connection count adjustment functionality.

The timeout value is fixed at 5 seconds with version 07-60 or earlier. With version 08-00

196

3. Resource Connections and Transaction Management

Items

Connection management threads

Waiting for a connection when connections deplete

Specified parameters

NetworkFailureTimeout in the

<property>

tag

RequestQueueEnable

in the

<property>

tag

RequestQueueTimeout

in the

<property> tag

RetryCount in the <property> tag

Settings or later, you can specify any timeout value

(default value is 5 seconds).

Specifies whether to enable the waiting for a connection when connections deplete.

Specifies the waiting time for obtaining a connection.

Retrying to obtain a connection

Connection sweeper

RetryInterval

in the

<property>

tag

SweeperInterval in the <property> tag

#2

ConnectionTimeout in the

<property>

tag

#2

Specifies the retry count for a failure to obtain a connection.

Specifies the retry interval for a failure to obtain a connection.

Specifies the interval at which the automatic destruction of connections (connection sweeper) will operate.

Specifies the time from the last use of the connection until the determination of the automatic destruction of the connection.

Statement cancellation CancelStatement in the <property> tag

Specifies whether to enable statement cancellation when a transaction times out.

#1: You set up the timeout for the connection error detection functionality and the connection count adjustment functionality in the same key. Therefore, when you use a timeout for the connection error detection functionality, a timeout is also used for the connection count adjustment functionality.

#2 If the set value is less than 3600 seconds, KDJE48604-W is output.

For details on the HITACHI Connector Property file, see

4.1 HITACHI Connector Property file

in the

uCosminexus

Application Server Application and Resource Definition Reference Guide

.

(3) J2EE application settings

You implement the J2EE application settings in the execution environment with the server management commands and property files. To define the functionality for fault tolerance, use the Session Bean property file, Entity Bean property file, or Message-driven Bean property file.

The tags specified in these property files are mapped in cosminexus.xml

. For details on the definitions in cosminexus.xml

, see

3.15.12 Definitions in cosminexus.xml

.

197

3. Resource Connections and Transaction Management

3.16 Other resource adapter functionality (For the resource adapters conforming to the Connector 1.5

specifications)

This section describes the resource adapter functionality other than the functionality described in

3.14 Functionality for performance tuning

,

3.15 Functionality for fault tolerance

, and

3.17 Functionality for connection pool clustering

.

The following table describes the organization of this section.

Table 3

64: Organization of this section (Other resource adapter functionality (For the resource adapters conforming to the Connector 1.5 specifications))

Category Title Reference location

Explanation

Implementation

Settings

Managing the resource adapter lifecycle

Managing the resource adapter work

Message inflow

Transaction inflow

Looking up Administered objects

Specifying multiple connection definitions

Application Server-specific Connector 1.5 API specifications

Settings for using the resource adapters conforming to the Connector 1.5

specifications

Notes

Examples of property file specification

Notes on using the resource adapters conforming to the Connector 1.5 specifications

Note: The functionality-specific explanation is not available for "Operations".

3.16.1

3.16.2

3.16.3

3.16.4

3.16.5

3.16.6

3.16.7

3.16.8

3.16.9

3.16.10

The above functionality is available with the resource adapters conforming to the Connector 1.5 specifications. For details on the resource adapters conforming to the Connector 1.5 specifications available with Application Server, see

3.3.2(2) Resource adapters conforming to the Connector 1.5 specifications

.

Reference note

When you use resource adapters other than those described in

3.3.2(1) Resource adapters conforming to the Connector 1.0

specifications

, such as the resource adapters conforming to the Connector 1.5 specifications, we recommend that the trace be output at the entry and exit of the resource adapter processing. The output trace will be used to isolate the causes when errors occur.

3.16.1 Managing the resource adapter lifecycle

When you use the resource adapters conforming to the Connector 1.5 specifications, you can use the J2EE server to manage the lifecycle of the resource adapters.

Resource adapter lifecycle management

is functionality that manages the start and stop processing of the resource adapters with the J2EE servers.

(1) Preconditions

Resource adapter lifecycle management is enabled when the resource adapter satisfies the following conditions:

The classes described in

(2) Classes used for lifecycle management

are implemented in the resource adapter.

The JavaBeans class name implementing the javax.resource.spi.ResourceAdapter

interface is specified in

<connector>-<resourceadapter>-<resourceadapter-class>

of the DD ( ra.xml

).

198

3. Resource Connections and Transaction Management

Note that if

<connector>-<resourceadapter>-<resourceadapter-class>

is not specified in the DD, the resource adapter lifecycle is not managed.

(2) Classes used for lifecycle management

This section describes the classes used for resource adapter lifecycle management. The classes to be used include the classes that must be implemented in the resource adapter and the classes provided by the J2EE servers.

■ Classes that must be implemented in the resource adapter

The following classes must be implemented with the resource adapter. Note that the Connector 1.5 specifications define that these classes be implemented as JavaBeans.

• Implementation class of the

javax.resource.spi.ResourceAdapter

interface

• Implementation class of the

javax.resource.spi.ManagedConnectionFactory

interface

• Implementation class of

AdminObject

(Administered object)

For the detailed implementation, see the Connector 1.5 specifications.

■ Classes provided by the J2EE servers

The J2EE server provides the following classes:

• Implementation class of the

javax.resource.spi.work.WorkManager

interface

The methods such as the doWork(Work) method, scheduleWork(Work) method, and startWork(Work) method are implemented in this class.

• Implementation class of the

javax.resource.spi.BootstrapContext

interface

The createTimer()

method, getWorkManager()

method, and getXATerminator()

method are implemented in this class.

Note that if you invoke the getXATerminator

method of the

BootstrapContext

interface with

Application Server, null is returned.

(3) Controlling lifecycle management

This section describes the controlling of the start and stop processing of the resource adapters whose lifecycles are to be managed.

The start and stop processing of a resource adapter is executed at the following times:

When you start or stop a J2EE resource adapter (when you execute the cjstartrar

command or cjstoprar command)

When you start or stop a J2EE server (when you execute the cjstartsv

command or cjstopsv

command)

When you start or stop an application containing the resource adapter (when you execute the cjstartapp command or cjstopapp

command)

■ Control procedure when the resource adapter start processing is executed

The following figure shows the control procedure when the resource adapter start processing is executed.

199

3. Resource Connections and Transaction Management

Figure 3

38: Control procedure when the resource adapter start processing is executed

200

The following points describe the control executed by the resource adapter start processing. Note that the item numbers correspond to the numbers in the figure.

1.

2.

WorkManager

(implementation class of the javax.resource.spi.work.WorkManager

interface) is generated.

BootstrapContext

(implementation class of the javax.resource.spi.BootstrapContext

interface) is generated.

3. ResourceAdapterJavaBean (implementation class of the javax.resource.spi.ResourceAdapter

interface) is generated.

The implementation class generated as

ResourceAdapterJavaBean

is the class specified in

<connector>-<resourceadapter>-<resourceadapter-class>

in the DD ( ra.xml

) of the resource adapter.

If the class specified in this tag cannot be instantiated, the resource adapter fails to start

#

KDJE48589-E message is output.

. In this case, the

4. The properties are set up in

ResourceAdapterJavaBean

.

The value specified in

<connector>-<resourceadapter>-<config-property>

in the DD

( ra.xml

) is set up in

ResourceAdapterJavaBean

that was generated in 3. The settings are executed with the setter

method complying with the JavaBean specifications. If an exception occurs during the invocation of the setter

method, the KDJE48594-W message is output. However, the processing continues.

5. The start

method of the javax.resource.spi.ResourceAdapter

interface is invoked and the resource adapter is started.

If the invocation of this method throws an exception, the resource adapter fails to start

KDJE48590-E message is output.

#

. In this case, the

6.

ResourceAdapterJavaBean

and

ManagedConnectionFactoryJavaBean

are associated (for

Outbound).

When you use the lifecycle management functionality, the implementation class of the javax.resource.spi.ManagedConnectionFactory

interface implements the javax.resource.spi.ResourceAdapterAssociation

interface. ResourceAdapterJavaBean and ManagedConnectionFactory are associated using the setResourceAdapter(ResourceAdapter)

method of the javax.resource.spi.ResourceAdapterAssociation

interface.

Also, in the following cases, the resource adapter fails to start

#

. In this case, KDJE48591-E is output.

3. Resource Connections and Transaction Management

7.

When the javax.resource.spi.ResourceAdapterAssociation

interface is not implemented for

ManagedConnectionFactoryJavaBean

When an exception is thrown for the invocation of the setResourceAdapter

method

AdminObjectJavaBean

(Administered object) is generated and the properties are set up.

The implementation class generated as

AdminObjectJavaBean

is the class specified in

<connector>-

<resourceadapter>-<adminobject>-<adminobject-class>

in the DD ( ra.xml

) of the resource adapter. If the class specified in this tag cannot be instantiated, the resource adapter fails to start

#

KDJE48597-E message is output.

. In this case, the

Also, the value specified in

<connector>-<resourceadapter>-<adminobject>-<configproperty>

in the DD ( ra.xml

) is set up in

AdminObjectJavaBean

. The settings are executed with the setter

method complying with the JavaBean specifications. If an exception occurs during the invocation of the setter

method of

AdminObjectJavaBean

, the KDJE48598-W message is output. However, the processing continues.

#

For the resource adapters included in an application, when the resource adapter fails to start, the start processing of the application containing that resource adapter also fails.

■ Control procedure when the resource adapter stop processing is executed

The following figure shows the control procedure when the resource adapter stop processing is executed.

Figure 3

39: Control procedure when the resource adapter stop processing is executed

The following points describe the control executed by the resource adapter stop processing. Note that the item numbers correspond to the numbers in the figure.

1. A check is executed to confirm that all the EJBs, servlets, and Message-driven Beans, referencing the resource adapter to be stopped, are stopped.

Make sure that the following elements are not being used:

Inbound resource adapter

Connection factory

2.

Administered object

If these elements are being used, the resource adapter stop processing is cancelled.

AdminObjectJavaBean (Administered object) is destroyed.

201

3. Resource Connections and Transaction Management

3. The stop

method of the javax.resource.spi.ResourceAdapter

interface is invoked and the resource adapter stops.

If the invocation of this method throws an exception, the KDJE48590-E message is output and the resource adapter stop processing fails.

4.

ResourceAdapterJavaBean is destroyed.

■ Transition of the resource adapter state

The state of the resource adapter changes to

Started

or

Stopped

when the resource adapter start or stop processing is executed.

The following figure shows the transition of the resource adapter state.

Figure 3

40: Transition of the resource adapter state

(4) Notes on using the lifecycle management functionality

Note the following points when you use the lifecycle management functionality:

If multiple resource adapters are deployed to a J2EE server, the order in which the start and stop processing is executed is not definite. Also, if multiple resource adapters are included in an application, the order in which the start and stop processing is executed is not definite. If a processing depends on the execution order, the operations are not guaranteed.

For the resource adapters included in an application, the resource adapter start processing is executed before the start processing of the EJBs and Servlets included in the application. Also, the resource adapter stop processing is executed after the stop processing of the EJBs and Servlets included in the application.

Execute the following processing appropriately with the processing of ResourceAdapter.stop

:

Destroying

Timer

generated with

BootstrapContext.createTimer

(

Timer#cancel

)

Termination instruction to the

Work

object registered in

WorkManager

(

Work#release

)

3.16.2 Managing the resource adapter work

When you use the resource adapters conforming to the Connector 1.5 specifications, you can manage the threads used by the resource adapters through the J2EE server.

Resource adapter work management

is a functionality for using the threads appropriately when a resource adapter is operated by multithreading. The J2EE server manages the threads in a pool, and allocates the threads to the necessary resource adapters.

!

Important note

The J2EE application execution time is not monitored for the thread that executes Work for which work is to be managed.

For details on monitoring the J2EE application execution time, see

5.3 Monitoring and cancelling the J2EE application execution time

in the

uCosminexus Application Server Operation, Monitoring, and Linkage Guide

.

(1) Preconditions

The resource adapter work management functionality is available when the lifecycle of the resource adapter is being

managed. For details on the resource adapter lifecycle management, see

3.16.1 Managing the resource adapter lifecycle

.

202

3. Resource Connections and Transaction Management

(2) Classes used for work management

This section describes the classes used for managing the resource adapter work. The classes to be used include the classes that must be implemented in the resource adapter and the classes provided by the J2EE servers. Note that the classes provided by the J2EE servers are the same as the classes used for the lifecycle management. See

3.16.1(2)

Classes used for lifecycle management

.

■ Classes that must be implemented in the resource adapter

The following class must be implemented with the resource adapter:

• Implementation class of the

javax.resource.spi.work.Work

interface

You must implement the processing you want to execute in the run

method of this class.

Note that if you want to use a resource adapter to manage the timing for work registration, allocation of work to threads, and work termination, execute the implementation class of the javax.resource.spi.work.WorkListener

interface as well.

(3) Procedure for work management

This section describes the procedure for work management.

The following figure shows gives an overview of work management.

203

3. Resource Connections and Transaction Management

Figure 3

41: Overview of work management

204

The following points describe the procedure shown in the figure:

1. Registering

Work

The resource adapter generates

Work

(implementation class of the javax.resource.spi.work.Work

interface) and registers

Work

in

WorkManager

.

At this time, the

WorkManager

instance is passed to the resource adapter via

BootstrapContext

. For details on

WorkManager

, see

3.16.1 Managing the resource adapter lifecycle

.

If you also register WorkListener ( javax.resource.spi.work.WorkListener

) in WorkManager at the same time as registering

Work

, thereafter, when the registration of

Work

is complete (when 1 is executed), when a thread is allocated to

Work

(when 2 is executed), and when the processing of

Work

is complete (when 3 is executed), you can obtain each event (implementation class of the javax.resource.spi.work.WorkEvent

interface).

2. Allocating work to a free thread

The J2EE server allocates a free thread to

Work

registered in

WorkManager

, and executes the run

method implemented in

Work

.

3. Terminating

Work

and calling back the threads

The J2EE server calls back the thread, which was allocated to the processed Work, to the thread pool.

The called back thread returns to the pool and waits or is released according to the settings for thread pooling.

3. Resource Connections and Transaction Management

Note that if an exception occurs in the methods of the javax.resource.spi.work.Work

interface or javax.resource.spi.work.WorkListener

interface during this procedure, the KDJE48592-E or

KDJE48593-E message is output respectively.

The following figure shows the transition in the state of

Work

registered in

WorkManager

.

Figure 3

42: Transition of Work state

Note that the time at which a method is returned varies according to the method used for registering

Work

in

WorkManager . The following table and figure show the times at which each method is returned. Note that apart from the time at which the method is returned, there is no difference in the processing of these methods.

Table 3

65: Times at which the methods are returned

Method Return timing scheduleWork startWork doWork

Registers Work and returns immediately.

Returns when a thread is allocated to Work .

Returns when the processing of Work is completed.

205

3. Resource Connections and Transaction Management

Figure 3

43: Time at which the scheduleWork method is returned

Figure 3

44: Time at which the startWork method is returned

206

3. Resource Connections and Transaction Management

Figure 3

45: Time at which the doWork method is returned

(4) Thread pooling

The thread pooling functionality manages the threads allocated to work in a

thread pool

.

■ Settings for thread pooling

After you import the resource adapter into the J2EE server, you specify the settings for thread pooling in the

<hitachi-connector-property>-<resourceadapter-runtime>-<property>

tag of the HITACHI

Connector Property file and set up as the property of each resource adapter. For details on the procedure for specifying the settings, see

5.4 Resource adapter property definition

in the

uCosminexus Application Server Application Setup

Guide

.

The following table describes the values that can be set in the thread pool.

Table 3

66: Values that can be set in the thread pool

Value that can be set (Property name) Explanation

Maximum number of threads executed concurrently

( MaxTPoolSize )

Minimum number of threads in the thread pool

(

MinTPoolSize

)

Maximum survival period until the thread to which no

Work

is allocated is released [unit: seconds]

( TPoolKeepalive )

Specifies the maximum number of threads executed concurrently in

WorkManager .

If there are no free threads when

Work

is registered, new threads are generated and allocated to

Work

if the number of threads running in

WorkManager

is less than this value.

If the number of running threads is equal to this value or more, Work is not accepted and javax.resource.spi.work.WorkRejectedException

is thrown.

Specifies the minimum number of threads pooled in the thread pool.

Even if no

Work

is registered in

WorkManager

, threads equal to this value are always pooled.

Also, if 0 is specified in this value, threads are not generated until Work is registered.

Specifies the period until the threads to which no

Work

is allocated are released from the thread pool, in seconds.

207

3. Resource Connections and Transaction Management

Value that can be set (Property name)

Maximum survival period until the thread to which no

Work

is allocated is released [unit: seconds]

(

TPoolKeepalive

)

Explanation

If no Work is allocated even after the lapse of TPoolKeepalive seconds since the thread became free, that thread is released.

However, the thread is not released if the number of threads existing in the thread pool is only up to the

MinTPoolSize

value.

For details on the specification method and the specifiable values, see

4.1 HITACHI Connector Property file

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

Note that if the lifecycle management functionality is not enabled (when

<resourceadapter-class>

is not specified in the DD ( ra.xml

) of the resource adapter), the value of the property that specifies thread pooling is ignored.

■ Lifecycle of the threads used for work management

The following figure shows the lifecycle of the threads used by the work management functionality.

The lifecycle of a thread varies according to the state of the thread pool and the running threads.

Figure 3

46: Lifecycle of a thread (when there are no free threads in the thread pool and the number of running threads is less than MaxTPoolSize)

Figure 3

47: Lifecycle of a thread (when there are free threads in the thread pool)

208

3. Resource Connections and Transaction Management

Figure 3

48: Lifecycle of a thread (when there are no free threads in the thread pool and the number of running threads has reached MaxTPoolSize)

A thread is generated when the resource adapter invokes the scheduleWork

method, startWork

method, or doWork

method and both the following states are applicable:

There are no free threads in the thread pool.

The number of running threads in

WorkManager

is less than

MaxTPoolSize

.

When the processing of Work is complete, the thread is in the waiting state in the thread pool. When the next Work is registered, the thread is again in the execution state.

In the thread pool, a thread is released if

Work

is not allocated even after the lapse of the seconds specified in

TPoolKeepalive

. However, by releasing that thread, if the number of threads in the thread pool becomes less than

MinTPoolSize

, the thread is not released.

■ Relationship between the Message-driven Bean instance pool and thread pooling

The operation when the resource adapter uses

Work

to invoke the Message-driven Beans varies according to the relationship between the maximum number of instances in the Message-driven Bean instance pool and

MaxTPoolSize

of the resource adapter.

The following table describes the operations for each relationship between the maximum number of instances in the

Message-driven Bean instance pool and

MaxTPoolSize

of the resource adapter. This operation is executed when one Message-driven Bean is invoked from one resource adapter.

Table 3

67: Operations when the resource adapter invokes the Message-driven Beans using Work

Relationship between the maximum number of instances in the Message-driven Bean instance pool and MaxTPoolSize of the resource adapter

Operation

MaxTPoolSize

> maximum number of instances in the Message-driven Bean instance pool

MaxTPoolSize

= maximum number of instances in the Message-driven Bean instance pool

MaxTPoolSize

< maximum number of instances in the Message-driven Bean instance pool

The Message-driven Beans can be executed from

Work

until the maximum number of instances in the Message-driven Bean instance pool is reached.

The Work count exceeding the maximum number of instances in the Messagedriven Bean instance pool enters a state of waiting to obtain a Message-driven

Bean instance.

The Message-driven Beans can be executed from

Work

until the maximum number of instances in the Message-driven Bean instance pool is reached.

The javax.resource.spi.work.WorkRejectedException

exception is thrown for the

Work

count exceeding the maximum number of instances in the Message-driven Bean instance pool. The state does not change to waiting to obtain instances.

The number of concurrently available Message-driven Bean instances becomes the number of

MaxTPoolSize

. The Message-driven Beans can be executed from Work until the running Work count reaches MaxTPoolSize .

The javax.resource.spi.work.WorkRejectedException

exception is thrown for the

Work

count exceeding

MaxTPoolSize

. The state does not change to pending.

209

3. Resource Connections and Transaction Management

Tip

You specify the thread pooling of the work management functionality for the resource adapters. On the other hand, you set up the Message-driven Bean instance pool for the Message-driven Beans.

When the resource adapter invokes multiple Message-driven Beans, in the

MaxTPoolSize

of the resource adapter, you set up the total value considering the number of threads required for each Message-driven Bean.

(5) Work management start and termination processing

The work management start and termination processing is executed when the start and termination processing of the lifecycle management functionality is executed.

The operations executed in each processing are as follows:

■ Start processing

With the work management start processing, threads are generated according to the settings for thread pooling. If

MinTPoolSize

is 1 or more, the threads are generated for the value in

MinTPoolSize

and are stored in the thread pool as free threads.

■ Termination processing

Some of the content executed in the termination processing differs for a normal termination and for an abnormal or forced termination. Note that abnormal termination occurs when an exception is thrown during the execution of the stop

method of the

ResourceAdapter

interface. Also, forced termination is the termination processing executed by extending the execution of the cjstopapp -force

command or cjstopapp -cancel

command.

Reference note

When you execute the cjstopsv -f

command, the J2EE server is stopped without executing the resource adapter termination processing. Therefore, the processing described here is not executed.

1. The stop

method of the

ResourceAdapter

interface is invoked for the resource adapter from the J2EE server, and the stop processing is instructed.

Also, the release

method of

Work

is invoked by extending this processing, and Work is released.

2. The resource adapter stops accepting new

Work

.

This is after the processing in 1 is executed, so normally there is no

Work

registration request. If there is a

Work registration request, javax.resource.spi.work.WorkRejectedException

is thrown as an exception.

3. The system waits until the processing of the Work is completed.

The system waits until the entire execution of the run

method of the running

Work

is completed.

Tip

If method cancellation is executed for a Message-driven Bean invoked from Work , the Message-driven Bean is terminated forcefully. However, in that case, the processing of the running

Work

does not stop.

If a Message-driven Bean is invoked from

Work

, the Message-driven Bean is terminated before the resource adapter. If you invoke a Message-driven Bean from

Work

after the Message-driven Bean is terminated, and if you invoke the createEndpoint method of javax.resource.spi.endpoint.MessageEndpointFactory

, an exception is thrown.

For details, see

3.16.3 Message inflow

.

(6) Notes on using the work management functionality

With the

Work

and

WorkListener

methods, only the invocation of Message-driven Beans based on the message inflow contract is available as the J2EE server functionality.

Make the

Work

and

WorkListener

methods thread-safe.

Do not implement processing dependent on the executing thread in the

WorkListener

method. The operations might not function properly if the executing thread-dependent processing is included.

210

3. Resource Connections and Transaction Management

3.16.3 Message inflow

A

message inflow

is a contract between the resource adapters and Message-driven Beans. The resource adapters complying with the Connector 1.5 specifications can receive messages from the message providers such as EIS, and operate the message endpoint (Message-driven Bean) on Application Server. The message endpoint asynchronously processes the messages sent from the message provider.

You can use the following two message delivery methods with Application Server:

Non-Transacted Delivery

Transacted Delivery

The difference in the methods is the participation of the invocation source EIS in the transaction.

(1) Preconditions

The message inflow is enabled when the resource adapters and Message-driven Beans satisfy the following conditions:

The Message-driven Beans invoked in the message inflow must conform to EJB 2.1 or later.

With EJB 2.1 or later, the Message-driven Bean can implement any message listener and not only javax.jms.MessageListener

. A message listener is a listener used to deliver messages between the resource adapters and Message-driven Beans. By implementing a resource adapter-supported message listener in the Message-driven Bean, generic messages can be received.

If you try to execute message inflow in EJB 2.0 Message-driven Bean, an error occurs when the application starts, and the application fails to start. In this case, the KDJE42088-E message is output.

To execute message inflow, you must specify the following settings as the attributes of the resource adapters and

Message-driven Beans:

Information to be set up in the Administered object (resource adapters)

Mapping of the Message-driven Beans and resource adapters (Message-driven Beans and resource adapters)

Information to be set up in

ActivationSpec

(Message-driven Beans)

Interfaces used by the Message-driven Beans (Message-driven Beans and resource adapters)

For details on the resource adapter and J2EE application settings for executing message inflow, see

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

.

Also, a Transacted Delivery is enabled when the conditions described in the following table are satisfied.

Table 3

68: Conditions when a Transacted Delivery is enabled

Message-driven Bean settings

J2EE server settings

Transaction management type <transactiontype> is Container

Transaction attribute

<trans-attribute> is

Required

Transaction attribute

<trans-attribute> is

NotSupported

Transaction management type

<transaction-type> is

Bean ejbserver.distributedtx.XAT

ransaction.enabled

true false

Y

R

N

N

N

N

Legend:

Y: The EIS delivering the message is included in the global transaction and then the transaction is started.

R: The EIS delivering the message is not included in the transaction and the local transaction is started.

N: The transaction is not started.

Also, to use a Transacted Delivery, you must use resource adapters conforming to the Connector 1.5 specifications and supporting Transacted Delivery. For details on the settings, see the documentation for the resource adapter in use.

211

3. Resource Connections and Transaction Management

(2) Procedure for controlling the message inflow (for a Non-Transacted Delivery)

A Non-Transacted Delivery is a message delivery in which the EIS that delivers the messages does not participate in the transaction.

The following figure shows the control procedure when the message inflow is used with a Non-Transacted Delivery.

Figure 3

49: Control procedure when the message inflow is used with a Non-Transacted Delivery

The following points describe the control executed when the message inflow is used with a Non-Transacted Delivery.

Note that the item numbers correspond to the numbers in the figure.

1. The properties are set up in

ActivationSpecJavaBean

of the resource adapter by the application start processing.

The content specified in the Message-driven Bean attribute

<activation-config>

is set up.

2. The J2EE server invokes the endpointActivation

method. As a result, the starting of the message endpoint is reported to the resource adapter.

3. The EIS sends a message.

4. The resource adapter invokes the createEndpoint

message for

MessageEndpointFactory

.

5.

MessageEndpointFactory

generates an endpoint proxy.

6. The resource adapter invokes a message listener method, such as the onMessage

method, for the endpoint proxy.

7. The endpoint proxy invokes a message listener method, such as the onMessage

method, for the Message-driven

Bean.

8. When the processing is complete, the J2EE server invokes the endpointDeactivation

method. As a result, the stopping of message endpoint is reported to the resource adapter.

(3) Procedure for controlling the message inflow (for a Transacted Delivery)

A Transacted Delivery is a message delivery in which the EIS that delivers the messages participates in the transaction.

The following figure shows the control procedure when the message inflow is used with a Transacted Delivery.

212

3. Resource Connections and Transaction Management

Figure 3

50: Control procedure when the message inflow is used with a Transacted Delivery

The following points describe the control executed when the message inflow is used with a Transacted Delivery. Note that the item numbers correspond to the numbers in the figure.

1. The properties are set up in

ActivationSpecJavaBean

of the resource adapter by the application start processing.

The content specified in the Message-driven Bean attribute

<activation-config>

is set up.

2. The J2EE server invokes the endpointActivation

method. As a result, the starting of the message endpoint is reported to the resource adapter.

3. The EIS sends a message.

4. The resource adapter invokes the createEndpoint

message for

MessageEndpointFactory

.

5.

MessageEndpointFactory

generates an endpoint proxy.

6. The resource adapter invokes a message listener method, such as the onMessage

method, for the endpoint proxy.

7. The invoked endpoint proxy invokes a start transaction instruction for the transaction manager.

8. The transaction manager invokes the start

method and starts the transaction.

9. The endpoint proxy invokes a message listener method, such as the onMessage

method, for the Message-driven

Bean.

10. The endpoint proxy instructs the conclusion of the transaction to the transaction manager.

11. The transaction manager invokes the transaction conclusion methods, such as the prepare

method and commit method, to conclude the transaction.

12. When the processing is complete, the J2EE server invokes the endpointDeactivation

method. As a result, the stopping of message endpoint is reported to the resource adapter.

213

3. Resource Connections and Transaction Management

(4) Deploying and undeploying the message endpoint

This section describes the processing executed for deploying and undeploying the message endpoint.

■ Deploying the message endpoint

This section describes the processing executed for deploying the message endpoint. The message endpoint is deployed when you start an application containing the Message-driven Beans when the resource adapter is running.

The following figure shows the processing for deploying the message endpoint.

Figure 3

51: Processing for deploying the message endpoint

214

The following points describe the processing executed for deploying the message endpoint. The item numbers correspond to the numbers in the figure.

1. Start the J2EE application containing the Message-driven Beans when the resource adapter is running.

2. The J2EE server generates

MessageEndpointFactory

.

MessageEndpointFactory

is an instance of javax.resource.spi.endpoint.MessageEndpointFactory

provided by the J2EE server.

javax.resource.spi.endpoint.MessageEndpointFactory

is a factory class that provides an endpoint instance to the resource adapter.

3. The J2EE server generates

ActivationSpec

.

ActivationSpec is a JavaBean that sets up the information required for starting the Message-driven Beans

(endpoint).

4. The J2EE server sets up the

ActivationSpec

property.

The information specified in the

ActivationSpec

property is set up as an attribute of the application that contains the Message-driven Beans.

5. The J2EE server invokes the javax.resource.spi.ResourceAdapter#endpointActivation(MessageEndpointFactory

, ActivationSpec)

method.

At this time, the generated and set up

MessageEndpointFactory

and

ActivationSpec

instances are specified as arguments. Note that if an exception occurs during the invocation of the endpointActivation method, the KDJE43174-E message is output and the starting of the application is canceled.

6. If the method specified in 5 is invoked, the resource adapter prepares to receive the messages from the message provider.

■ Undeploying the message endpoint

This section describes the processing executed for undeploying the message endpoint. The message endpoint is undeployed when you stop an application containing the Message-driven Beans.

The following figure shows the processing for undeploying the message endpoint.

3. Resource Connections and Transaction Management

Figure 3

52: Processing for undeploying the message endpoint

The following points describe the processing executed for undeploying the message endpoint. The item numbers correspond to the numbers in the figure.

1. Stop the J2EE application containing the Message-driven Beans.

2. The J2EE server invokes javax.resource.spi.ResourceAdapter#endpointDeactivation(MessageEndpointFacto ry, ActivationSpec)

.

At this time, the same

MessageEndpointFactory

and

ActivationSpec

instances, which were specified for deployment, are specified as arguments. Note that if an exception occurs during the invocation of this method, the message KDJE43175-W is output. However, even if an exception occurs, the application stop processing continues.

3. If the method specified in 2 is invoked, the resource adapter executes the processing to terminate the receiving of messages from the message provider.

■ Processing of the resource adapter for delivering the messages

This section describes the processing of the resource adapter for delivering the messages.

The resource adapter invokes the message endpoint (Message-driven Bean) by using the message endpoint proxy.

This proxy is obtained by invoking the createEndpoint

method of javax.resource.spi.endpoint.MessageEndpointFactory

from the resource adapter.

!

Important note

If you invoke the

MessageEndpointFactory

method after the application stops, the javax.resource.spi.UnavailableException

exception is thrown. At this time, the message KDJE43177-E is output. Also, when the message endpoint method is invoked, the java.lang.IllegalStateException

exception is thrown. At this time, the message KDJE43177-E is output.

In a Transacted Delivery, if you stop a J2EE application during message delivery, the transaction might be rolled back.

At this time, KDJE31011-E or KDJE31012-E error might occur. These errors might also occur when you stop the running J2EE application when the J2EE server is stopped.

3.16.4 Transaction inflow

A

transaction inflow

is a contract between the resource adapters and Application Server when the message endpoint

(Message-driven Bean) on Application Server is involved in a message provider transaction.

The message endpoint (Message-driven Bean) participates in the transaction associated with the transaction identifier of the message provider.

Note that a transaction inflow is only available with the TP1 inbound integrated function.

The following figure shows the procedure for controlling the transaction inflow.

215

3. Resource Connections and Transaction Management

Figure 3

53: Procedure for controlling the transaction inflow

The following points describe the flow of processing in the figure. Note that the item numbers correspond to the numbers in the figure.

1. The EIS sends a message to the TP1 inbound adapter.

2. The TP1 inbound adapter propagates the EIS transaction identifier to the transaction manager.

3. The TP1 inbound adapter executes the Message-driven Bean.

4. An SQL statement is executed from the Message-driven Bean and the DB is updated.

5. After the execution of Message-driven Bean, the TP1 inbound adapter sends the execution results to the EIS.

6. After receiving the execution results, the EIS sends the instruction to conclude the transaction to the TP1 inbound adapter.

7. The TP1 inbound adapter sends the instruction to conclude the transaction to the transaction manager.

8. The transaction is concluded.

3.16.5 Looking up Administered objects

You can obtain the Administered objects ( AdminObject ) using lookup. An Administered object is required to obtain the information of the message destination for sending messages from inside a J2EE application and for receiving the messages synchronously. To look up an Administered object, you must specify the resource adapter and

J2EE application settings. This subsection gives an overview of the settings.

Reference note

The specifications of the Administered object depend on the resource adapter specifications. For details, follow the specifications of the resource adapter in use.

(1) Setting up the Administered objects to be looked up

You set up the information for the Administered objects to be looked up, as the resource adapter properties. Specify the resource adapter properties with the HITACHI Connector Property file.

To set an Administered object as a lookup target, make sure you specify the name of the Administered object in the

<adminobject-name>

tag. When multiple Administered objects are defined for each resource adapter, the

Administered object name is used to identify the Administered object uniquely.

For details on the settings, see

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5

specifications

.

216

3. Resource Connections and Transaction Management

(2) J2EE application settings

The J2EE application settings for looking up an Administered object can be specified in the property files or annotations.

(a) When using a property file

Specify the following elements beneath the

<resource-env-ref>

tag:

Specify the name to be used for lookup beneath the

<resource-env-ref-name>

tag. Specify the type of the

Administered object that will be referenced beneath the

<resource-env-ref-type>

tag. Specify the

Administered object name of the resource adapter and the resource adapter display name beneath the <linkedadminobject>

tag.

!

Important note

In EJB 2.1 and later, the

<message-destination-ref>

tag provided as the element for referencing the Administered objects is not available with Application Server.

For details on the settings, see

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5

specifications

.

(b) When using an annotation

Specify the name of the Administered object to be looked up in the mappedName

attribute of

@Resource

. Specify the name in the following format. Use "!#" as the delimiter between the resource adapter display name and

Administered object name.

@Resource(mappedName="

resource-adapter-display-name

!#

Administered-object-name

")

3.16.6 Specifying multiple connection definitions

When you use the resource adapters conforming to the Connector 1.5 specifications, you can specify multiple connection definitions for one resource adapter. You can specify the settings, such as those for the connection pool and log output, for each connection definition.

To identify a connection definition in a resource adapter, you use the

connection definition identifier

. The connection identifier is the value specified in

<connectionfactory-interface>

in the DD. The

<connectionfactory-interface>

value has a unique value for each connection definition in the resource adapter.

Note that you can check the connection definition identifier for each connection definition included in the resource adapter if you execute the following server management commands by specifying the -outbound option:

cjlistapp

command (for the RAR files included in an application)

For details, see

cjlistapp (Displaying a list of applications)

in the

uCosminexus Application Server Command

Reference Guide

.

cjlistres

command

For details, see

cjlistres (Displaying a list of resources)

in the

uCosminexus Application Server Command

Reference Guide

.

cjlistrar

command

For details, see

cjlistrar (Displaying a list of resource adapters)

in the

uCosminexus Application Server Command

Reference Guide

.

This subsection describes the elements that can be specified in the connection definitions and the locations for specifying these elements. This subsection also describes the points to remember when you specify multiple connection definitions.

217

3. Resource Connections and Transaction Management

(1) Elements specifiable in the connection definitions and the location of specification

This section describes the elements that can be specified in the connection definitions and the locations for specifying these elements.

■ Location of specification in the DD and the elements that can be specified in the connection definition

You specify the connection definition beneath

<connection-definition>

in the DD complying with the

Connector 1.5 specifications. The elements specified beneath <connection-definition> are as follows:

<managedconnectionfactory-class>

<config-property>

<connectionfactory-interface>

<connectionfactory-impl-class>

<connection-interface>

<connection-impl-class>

■ Mapping the hierarchical structure and connection definitions of the HITACHI Connector Property file

With the change in the hierarchical structure in the DD ( ra.xml

), a hierarchy corresponding to the connection definition is added in the property file as well.

For the resource adapters already imported into the J2EE server, you use the HITACHI Connector Property file to change the resource adapter properties. The values defined in the HITACHI Connector Property file are applied to the resource adapter on the J2EE server by using the server management commands. For details on the procedure for using the property file to specify properties, see

3.5 Specifying properties using property files

in the

uCosminexus

Application Server Application Setup Guide

.

Note that the resource adapter operation-related properties include items defined for each connection definition and items defined for the entire resource adapter. You specify the items defined for each connection definition beneath

<outbound-resourceadapter>-<connection-definition>

in the HITACHI Connector Property file.

You specify the items defined for the entire resource adapter beneath <resourceadapter-runtime>-

<property>

.

For details on the method of specification, see

4.1.1 Content specified in the HITACHI Connector Property file

in the

uCosminexus Application Server Application and Resource Definition Reference Guide

.

■ How to define link resolution in J2EE applications (method of specifying in <resource-ref>-<linked-to>,

<cmp-map>-<datasource-name>, or mappedName)

With the J2EE applications that reference the resource adapters conforming to the Connector 1.5 specifications, you must define the connection definition that will be referenced by the J2EE application for link resolution.

Specify the definition using one of the following methods:

<resource-ref>-<linked-to>

in the J2EE application property files (WAR property file, Session Bean property file, Entity Bean property file, or MessageDrivenBean property file)

<cmp-map>-<datasource-name>

in the J2EE application property file (Entity Bean property file) mappedName

attribute of the annotation

@Resource

!

Important note

If the referenced resource is a resource adapter conforming to the Connector 1.5 specifications, make sure you specify the connection definition identifier. If the connection definition identifier is omitted, the link resolution fails. Also, if the referenced resource is a resource adapter conforming to the Connector 1.0 specifications, do not specify the connection definition identifier. If the connection definition identifier is specified, the link resolution fails.

Specify a referenced resource containing a connection definition identifier in the following format:

resource-adapter-display-name

!

connection-definition-identifier

A description of the specified contents is as follows:

218

3. Resource Connections and Transaction Management

resource-adapter-display-name

The value of the

<connector>-<display-name>

element in the DD ( ra.xml

) of the referenced resource adapter.

connection-definition-identifier

The value of the

<connector>-<resourceadapter>-<outbound-resourceadapter>-

<connection-definition>-<connectionfactory-interface>

element in the DD ( ra.xml

) of the referenced resource adapter.

Note that you can also check the resource adapter display name and connection definition identifier with the following server management commands:

cjlistapp

command (for the RAR files included in an application) cjlistres

command cjlistrar

command

(2) Points to remember when using a connection pool

With a resource adapter for which multiple connection definitions are specified, you can manage the connection pools for the connection definitions. You specify the connection pool definition with the elements beneath

<outboundresourceadapter>-<connection-definition>-<connector-runtime>-<property>

in the

HITACHI Connector Property file.

The points to remember when there are multiple connection pools are as follows:

■ Executing the commands for connection pools

When you execute the server management commands for connection pools, you must specify the connection pool that you want to target.

When you execute the following commands, you must specify the connection definition identifier. You specify the connection definition identifier in the options of these commands.

cjclearpool command

For details, see

cjclearpool (Deleting the connections in the connection pool)

in the

uCosminexus Application

Server Command Reference Guide

.

cjlistpool

command

For details, see

cjlistpool (Displaying the list of connection pools)

in the

uCosminexus Application Server

Command Reference Guide

.

Reference note

The commands used for connection pool clustering are not applicable. The commands used for connection pool clustering can only be executed with the resource adapters provided by Application Server.

■ Processing for connection pool warming up

The processing for connection pool warming up is executed for each connection definition.

When you execute the processing for connection pool warming up, even if connection pool warming up fails for a specific connection definition, the warming up processing for the other connection pools continues.

(3) Points to remember when a transaction is recovered

You execute transaction recovery for each connection definition. Therefore, if multiple connection definitions are specified, a resource is registered for each connection definition in the OTS.

(4) Points to remember when a connection test is performed for resources

When you execute a connection test for a resource adapter, even if an error occurs in a connection test for a specific connection definition, the processing is not cancelled. The connection tests are executed for all the connection definitions. However, if an error occurs in one of the connection definitions, the return value of the command is a return value indicating an abnormal termination.

219

3. Resource Connections and Transaction Management

(5) Points to remember when the operation information and the information for resource depletion monitoring is output

When multiple connection definitions are specified, the operation information and the information for resource depletion monitoring are output as follows:

Operation information (information output to the operation information file)

Only the information for the first connection definition is output. The first connection definition is the connection definition that is defined first in the DD ( ra.xml

).

Operation information (information output by using the management commands)

This information cannot be output. If an attempt is made to output the operation information for the resource adapters conforming to the Connector 1.5 specifications, the output content is not guaranteed.

Information for resource depletion monitoring

The information for all the connection definitions specified in the resource adapter is output.

(6) Points to remember when the resource adapter operation log is output

When the operation log of the resource adapters conforming to the Connector 1.5 specifications is output, the name of the output file is in the following format: resource-adapter-display-name_

connection-definition-order

_

serial-number-of-log-file

.log

The

connection-definition-order

corresponds to the order in which the corresponding

<connectiondefinition> occurs (1, 2, ...) in the DD ( ra.xml

).

3.16.7 Application Server-specific Connector 1.5 API specifications

This subsection describes the Application Server-specific specifications for the interfaces of the Connector 1.5

specifications.

(1) javax.resource.spi.endpoint.MessageEndpointFactory interface

Application Server provides specifications for two methods.

(a) createEndpoint method

Format

public MessageEndpoint createEndpoint(XAResource xaResource) throws

UnavailableException

Application Server-specific specifications

If this method is invoked after you start the stop processing of a J2EE application containing the EJBs, javax.resource.spi.UnavailableException

is thrown.

The processing to obtain the Message-driven Bean instances is executed in this method. If the upper limit of the Message-driven Bean instance pool is reached, the Message-driven Bean instances can be obtained, or the method is not returned until the J2EE application stops.

Exception

The following table describes the exception operations provided with Application Server.

Exception javax.resource.spi.UnavailableException

Exception timing

When this method is invoked after you start the stop processing of a J2EE application containing the EJBs

When an attempt to obtain the Message-driven Bean instances fails

220

3. Resource Connections and Transaction Management

(b) isDeliveryTransacted method

Format

public boolean isDeliveryTransacted(Method method) throws

NoSuchMethodException

Application Server-specific specifications

If you specify true in the ejbserver.distributedtx.XATransaction.enabled

property of the user property file for J2EE servers, true

is returned when

Required

is specified for CMT in the transaction attribute of the method passed by the argument.

(2) javax.resource.spi.endpoint.MessageEndpoint interface

Application Server provides specifications for three methods.

(a) beforeDelivery method

Format

public void beforeDelivery(Method method) throws NoSuchMethodException,

ResourceException

Application Server-specific specifications

The specifications provide for exceptions.

Exception

The following table describes the exception operations provided with Application Server.

Exception java.lang.IllegalStateException

javax.resource.spi.IllegalStateException

javax.resource.spi.UnavailableException

Exception timing

When you invoke the message listener method after you start the stop processing of the J2EE application containing the EJBs

When the release()

method has already been invoked

When the methods are invoked in an invalid order (when the beforeDelivery

method is invoked again after invoking the beforeDelivery

method or when the beforeDelivery

method is invoked after invoking the message listener method)

When an unexpected exception occurs

(b) afterDelivery method

Format

public void afterDelivery() throws ResourceException

Application Server-specific specifications

The specifications provide for exceptions.

Exception

The following table describes the exception operations provided with Application Server.

Exception java.lang.IllegalStateException

Exception timing

When you invoke the message listener method after you start the stop processing of the J2EE application containing the EJBs

When the release()

method has already been invoked

221

3. Resource Connections and Transaction Management

Exception Exception timing javax.resource.spi.IllegalStateException

When the methods are invoked in an invalid order (when afterDelivery()

is invoked at a different time after the message listener method Option B

#

is invoked) javax.resource.spi.UnavailableException

When an unexpected exception occurs

#: A message delivery option coded in the Connector 1.5 specifications.

(c) release method

Format

public void release()

Application Server-specific specifications

If you invoke this method, the Message-driven Bean instance associated with the endpoint is released and returns to the instance pool.

When you finish using the endpoint, make sure you invoke this method and return the Message-driven Beans to the instance pool.

Exception

The following table describes the exception operations provided with Application Server.

Exception java.lang.IllegalStateException

Exception timing

When you invoke the message listener method after you start the stop processing of the J2EE application containing the EJBs

When the release()

method has already been invoked

(3) Message listener method

The interface is defined with the message listener interface. The following table describes the exception operations provided with Application Server.

Exception Exception timing

Exception specified in the message listener interface javax.ejb.EJBException

Message-driven Bean execution time (other than when the system exception occurs)

Message-driven Bean execution time (when the system exception occurs) java.lang.IllegalStateException

When you invoke the message listener method after you start the stop processing of the J2EE application containing the EJBs

When the release()

method has already been invoked

When the methods are invoked in an invalid order (the message listener method is invoked continuously after invoking the message listener method in the message delivery of Option B

#

,)

#: A message delivery option coded in the Connector 1.5 specifications.

3.16.8 Settings for using the resource adapters conforming to the

Connector 1.5 specifications

This subsection describes the J2EE application and resource adapter settings for using the resource adapters conforming to the Connector 1.5 specifications.

222

3. Resource Connections and Transaction Management

You specify the settings in the HITACHI Application Integrated Property File

#

and HITACHI Connector Property file respectively.

#

The description in this section is entirely based on the use of HITACHI Application Integrated Property File. If you use the cjgetappprop

command to obtain the Message-driven Bean property file, you can specify the settings in the Message-driven Bean property file. If you are using the Message-driven Bean property file, read

"beneath the

<hitachi-connector-property>

tag in HITACHI Application Integrated Property File" as

"Message-driven Bean property file".

(1) Items that can be set up

This section describes the items that can be set up when you use the resource adapters conforming to the Connector

1.5 specifications.

(a) J2EE application settings

The following table describes the content that can be set up in a J2EE application.

Table 3

69: J2EE application settings (for using the resource adapters conforming to the Connector 1.5

specifications)

Functionality Item Target Settings

Looking up

Administered objects

Message inflow

#

Information used for looking up

Administered objects

Mapping with the resource adapter

Interfaces used by the

Message-driven Beans

WAR, Session Bean,

Entity Bean, and

Message-driven Bean

Message-driven Bean

Message-driven Bean

Specify the settings in the following tags beneath the

<resource-env-ref>

tag:

In the <resource-env-ref-name> tag, specify the name to be used for lookup.

In the

<resource-env-ref-type>

tag, specify the type of the Administered object.

In the

<linked-adminobject>-

<resourceadapter-name>

tag, specify the display name of the resource adapter in which the

Administered object is included.

In the

<linked-adminobject>-

<adminobject-name> tag, specify the object name of the Administered object.

In the

<resource-adapter>

tag beneath the

<message-ref>-<connectiondestination> tag, specify the mapped resource adapter display name.

In the

<messaging-type>

tag, specify the interfaces implemented by the Message-driven

Beans.

ActivationSpec settings

Message-driven Bean In the

<activation-config-propertyname>

tag and

<activation-configproperty-value>

tag beneath the

<activation-config>-<activationconfig-property>

tag, specify the properties to be set for

ActivationSpec

.

#: Some of the set values must match the values set for the resource adapter to be used.

(b) Resource adapter settings

From among the items specified as the resource adapter properties, this section describes the main items that can be set up for the resource adapters conforming to the Connector 1.5 specifications and how to set up these items. Note that this section describes content specific to the resource adapters conforming to the Connector 1.5 specifications.

The following table describes the content that can be set up as the properties of the resource adapters conforming to the Connector 1.5 specifications.

223

3. Resource Connections and Transaction Management

Table 3

70: Content that can be set up in the property definitions of the resource adapters conforming to the Connector 1.5 specifications

Category Item Settings

Administered object

Administered object names

#1 In the

<adminobject>-<adminobjectname> tag

#2

, specify the object name to be used for lookup. Make sure you specify this item when you want to look up an Administered object. You cannot include continuous underscores " __ " in the object name.

Note that you must also specify the J2EE application settings to look up an Administered object. See

(a)

J2EE application settings

.

Interfaces

Implementation classes and properties

In the

<adminobject>-<adminobjectinterface>

tag, specify the interface to be used.

Specify items such as javax.jms.Queue

or javax.jms.Topic

.

In the

<adminobject-class>

tag, specify the implementation class.

Specify the Administered object properties beneath the

<config-property>

tag.

#1: This need not be specified for the Administered objects used with message inflow.

#2: This tag does not exist in the DD ( ra.xml

).

(2) Setting up the Administered objects

You code the settings for the Administered objects to be used with the message inflow in the HITACHI Connector

Property file.

The content set up for the Administered object depends on the resource adapter. See the documentation for the resource adapter in use.

You map the Administered objects to the Message-driven Beans. For details on the mapping, see

(5) ActivationSpec settings

.

(3) Settings for mapping the Message-driven Beans and resource adapters

You specify the mapping between the Message-driven Beans and resource adapters in the

<resource-adapter> tag of HITACHI Application Integrated Property File. Specify the resource adapter display name.

The hierarchy of

<resource-adapter>

is as follows:

<hitachi-message-bean-property>

<message-ref>

<connection-destination>

<resource-adapter>

These tags are elements that do not exist in the DD ( ejb-jar.xml

). However,

<hitachi-message-beanproperty>

corresponds to

<message-driven>

in the DD.

The mapping with the resource adapters is executed when you start the J2EE applications containing the Messagedriven Beans. Note that the J2EE applications containing the Message-driven Beans fail to start in the following cases.

In this case, the KDJE42359-E message is output:

When the resource adapter display name is not specified in the

<resource-adapter>

tag

When the resource adapter with the display name specified in the

<resource-adapter>

tag has not been started

When the resource adapter with the display name specified in the

<resource-adapter>

tag is not found

The Message-driven Beans must be mapped to the Administered objects as well. For details on the mapping, see

(5)

ActivationSpec settings

.

224

3. Resource Connections and Transaction Management

Reference note

You cannot specify the information of the

<message-driven>-<message-destination-link>

tag with

Application Server.

(4) Setting up the interfaces used by the Message-driven Beans

You code the interfaces used by the Message-driven Beans in the

<messaging-type>

tag of HITACHI

Application Integrated Property File. Specify the names of the interfaces implemented by the Message-driven Beans.

The hierarchy of <messaging-type> is as follows:

<hitachi-message-bean-property>

<messaging-type>

The

<hitachi-message-bean-property>

tag corresponds to

<message-driven>

in the DD ( ejbjar.xml

).

You must specify the interfaces supported by the resource adapter as the interfaces used by the Message-driven Beans.

The interfaces supported by the resource adapter are specified in the

<messagelistener-type>

tag of the DD

( ra.xml

) for the resource adapter. If you specify an interface other than that specified in this tag, the J2EE application containing the Message-driven Beans fails to start. In this case, the KDJE43167-E message is output.

You can also check the interfaces supported by the resource adapter with the following server management commands. Execute these commands by specifying -resname and -inbound in the arguments.

cjlistres

command

For details, see

cjlistres (Displaying a list of resources)

in the

uCosminexus Application Server Command

Reference Guide

.

cjlistrar

command

For details, see

cjlistrar (Displaying a list of resource adapters)

in the

uCosminexus Application Server Command

Reference Guide

.

cjlistapp command

For details, see

cjlistapp (Displaying a list of applications)

in the

uCosminexus Application Server Command

Reference Guide

.

Note that if no value is specified in the <messaging-type> tag, the javax.jms.MessageListener

interface is used as the default value.

Reference note

The javax.jms.MessageListener

interface was used as a specific message listener interface until EJB 2.0.

(5) ActivationSpec settings

ActivationSpec is a JavaBean that contains settings required for activating the Message-driven Beans.

ActivationSpec contains properties that must be set up according to the resource adapter settings.

(a) Overview of the ActivationSpec settings

You code the values to be set up for

ActivationSpec

beneath the

<activation-config>

tag of HITACHI

Application Integrated Property File. Specify the property name and the property value. You can specify multiple values.

The hierarchy of

<activation-config>

is as follows:

<hitachi-message-bean-property>

<activation-config>

<activation-config-property>

<activation-config-property-name>

<activation-config-property-value>

225

3. Resource Connections and Transaction Management

You can specify the default ActivationSpec settings in the DD ( ra.xml

) for the resource adapter. The value set in the

<resourceadapter>-<config-property>

tag is used as the default value. When the default value is mentioned and if you set the

ActivationSpec

value in HITACHI Application Integrated Property File, the value is overwritten by the value specified beneath the

<hitachi-message-bean-property>

tag.

The properties that you must set up as the

ActivationSpec

properties are described in

(b) Properties that must be set up

.

(b) Properties that must be set up

With the ActivationSpec settings, you must set up the values of the properties specified in the

<activationspec>-<required-config-property>

tag in the DD ( ra.xml

) for the resource adapter.

You can also use the following server management commands to check the properties that must be set up. Execute these commands by specifying

-resname

and

-listenertype

in the arguments:

cjlistres

command cjlistrar

command cjlistapp

command

The other properties that can be set up for

ActivationSpec

depend on the resource adapter. See the documentation for the resource adapter in use.

(c) Properties that must be set up when a message listener supporting the JMS is used

When you use a message listener (message listener that uses the javax.jms.MessageListener

interface) that supports the JMS, the following properties must be specified in

ActivationSpec

. Specify the properties beneath the

<activation-config>

tag.

destination

destinationType

Note that Application Server does not check whether these properties are specified. You check whether the property settings are appropriate with the

ActivationSpec#validate

method provided by the resource adapter.

Reference note

The following items specified as elements beneath the

<message-driven>

tag in EJB 2.0 have been deleted in EJB version 2.1 and later:

<message-selector>

<acknowledge-mode>

<message-driven-destination>-<subscription-durability>

The Connector 1.5 specifications recommend that these elements can be specified as properties beneath the

<activation-config>

. However, whether these elements can be specified depends on the resource adapter in use.

For details on the

ActivationSpec

specifications when you use a message listener that supports the JMS, see the documentation for the Connector 1.5 specifications.

(d) Errors that occur during ActivationSpec generation and setup

When you generate and set up ActivationSpec , errors occur when the states described in the following table are reached. If an error occurs, the J2EE application fails to start.

The following table describes the cases in which errors occur and the messages that are output.

Table 3

71: Mapping the cases in which errors occur and the output messages

Cases in which errors occur Output messages

An attempt to generate an instance of the ActivationSpec implementation class fails

KDJE43168-E

226

3. Resource Connections and Transaction Management

Cases in which errors occur Output messages

If the javax.resource.spi.ActivationSpec

interface is not implemented for a class specified in

ActivationSpec

If the setter

method of the property corresponding to the

<activation-config-property-name>

tag does not exist in

ActivationSpec

If an exception is thrown in the invocation of the method that checks whether the settings are appropriate (

ActivationSpec#validate method), after the properties are set up in

ActivationSpec

If the settings corresponding to the property

<required-configproperty> tag specified in the DD ( ra.xml

) for the resource adapter are not coded as the

<activation-config>

tag of HITACHI Application

Integrated Property File

KDJE43172-E

KDJE43169-E

KDJE43170-E

KDJE43171-E

If an exception is thrown in the setResourceAdapter

method of

ActivationSpec

#

KDJE43173-E

#: The setResourceAdapter

method is a method defined in the javax.resource.spi.ResourceAdapterAssociation

interface. The javax.resource.spi.ResourceAdapterAssociation

interface is a super interface of the javax.resource.spi.ActivationSpec

interface.

3.16.9 Examples of property file specification

This subsection uses examples to describe how to specify the property files when you execute the message inflow.

The settings with the HITACHI Connector Property file and HITACHI Application Integrated Property File must match the settings at the locations shown in the following figure.

Figure 3

54: Locations specifying the same values in the HITACHI Connector Property file and HITACHI

Application Integrated Property File

227

3. Resource Connections and Transaction Management

The specified contents are as follows:

In a, you specify the interfaces used by the Message-driven Beans.

In b, you specify the mapping of

ActivationSpec

and Administered objects.

In c, you specify the mapping of the Message-driven Beans and resource adapters.

The following points are described based on the content specified from a to c:

(1) For the Message-driven Beans and resource adapters using the javax.jms.MessageListener interface

The examples of property file specification when you use the javax.jms.MessageListener

interface as the message listener interface are as follows.

The description uses the configuration shown in the following figure as an example. In this example, two Messagedriven Beans corresponding to the JMS receive messages from different Administered objects ( javax.jms.Queue

) respectively.

Figure 3

55: Example configuration of the Message-driven Beans and resource adapter using the javax.jms.MessageListener interface

The following is an example specification of HITACHI Application Integrated Property File.

228

3. Resource Connections and Transaction Management

Figure 3

56: Example specification of HITACHI Application Integrated Property File (for using the javax.jms.MessageListener interface)

The following is a description of the figure:

The points (3) to (5) in the figure correspond to the item numbers described in

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

. Also, a, b-1, b-2, and c indicate the following

settings respectively:

a: Interfaces used by the Message-driven Beans

b-1, b-2: Mapping of ActivationSpec and Administered object c: Mapping of the Message-driven Beans and resource adapter

Note that the values set up for a, b-1, b-2, and c correspond to Figure 3-56.

The following figure shows an example specification of the HITACHI Connector Property file.

229

3. Resource Connections and Transaction Management

Figure 3

57: Example specification of the HITACHI Connector Property file (for using the javax.jms.MessageListener interface)

The following is a description of the figure:

The points (2) to (4) in the figure correspond to the item numbers described in

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

. Also, a, b-1, b-2, and c indicate the following

settings respectively:

a: Interfaces used by the Message-driven Beans b-1, b-2: Mapping of ActivationSpec and Administered object

c: Mapping of the Message-driven Beans and resource adapter

Note that the values set up for a, b-1, b-2, and c correspond to Figure 3-57.

(2) For the Message-driven Beans and resource adapters using any message listener interface

The examples of property file specification when you use any interface as the message listener interface are as follows.

The description uses the configuration shown in the following figure as an example.

230

3. Resource Connections and Transaction Management

Figure 3

58: Example configuration of the Message-driven Beans and resource adapter using any message listener interface

In this example, the resource adapter supports the following two unique interfaces:

examples.Listener1 is a message listener interface used independently of the Administered objects.

examples.Listener2 is a message listener interface used in association with the Administered objects.

The following figure shows an example specification of HITACHI Application Integrated Property File.

Figure 3

59: Example specification of HITACHI Application Integrated Property File (for using any message listener interface)

231

3. Resource Connections and Transaction Management

The following is a description of the figure:

The points (3) to (5) in the figure correspond to the item numbers described in

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

. Also, a-1, a-2, b, and c indicate the following

settings respectively:

a-1, a-2: Interfaces used by the Message-driven Beans b: Mapping of ActivationSpec and Administered object

c: Mapping of the Message-driven Beans and resource adapter

Note that the values set up for a-1, a-2, b, and c correspond to Figure 3-59.

The following figure shows an example specification of the HITACHI Connector Property file.

Figure 3

60: Example specification of the HITACHI Connector Property file (for using any message listener interface)

232

The following is a description of the figure:

The points (2) to (4) in the figure correspond to the item numbers described in

3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

. Also, a-1, a-2, b, and c indicate the following

settings respectively:

a-1, a-2: Interfaces used by the Message-driven Beans b: Mapping of ActivationSpec and Administered object

c: Mapping of the Message-driven Beans and resource adapter

Note that the values set up for a-1, a-2, b, and c correspond to Figure 3-60.

3. Resource Connections and Transaction Management

3.16.10 Notes on using the resource adapters conforming to the

Connector 1.5 specifications

The notes on using the resource adapters conforming to the Connector 1.5 specifications are as follows. The notes vary depending on how you use the resource adapters.

(1) Common notes

You cannot obtain operation information related to the resource adapters conforming to the Connector 1.5

specifications even if you use the management portal or the mngsvrutil

command.

If you use the management portal or the mngsvrutil

command to obtain status information of the resource adapters conforming to the Connector 1.5 specifications, information indicating that the resource adapter is stopped is returned even if the resource adapter is running.

If you execute the cmx_stop_resource

command for the resource adapters conforming to the Connector 1.5

specifications, the resource adapter is not stopped even if the command is always successful.

(2) When you deploy and use the resource adapter as a J2EE resource adapter (when the resource adapter is not included in the J2EE application)

When you specify an Administered object in an annotation, you must add the Administered object interface in the container extension library.

For details on the container extension library, see

14. Container Extension Library

.

(3) When you include and use the resource adapter in the J2EE application

When you use the reload functionality, you must add the following classes (interfaces) in the container extension library:

Implementation class of the javax.resource.spi.ActivationSpec

Message listener interface supported by the resource adapter

interface

When you specify an Administered object in an annotation, you must add the Administered object interface in the container extension library.

The global transaction is not available when you use the Inbound resource adapter.

For details on the container extension library, see

14. Container Extension Library

.

233

3. Resource Connections and Transaction Management

3.17 Functionality for connection pool clustering

This section describes the connection pool clustering functionality.

The following table describes the organization of this section.

Table 3

72: Organization of this section (Connection pool clustering functionality )

Category Title Reference location

Explanation Connecting to Oracle using Oracle RAC

Overview of connection pool clustering

Resource adapters used

Connection pool clustering operations

Procedure for stopping or starting a connection pool manually

Settings Settings required for clustering a connection pool

Note: The functionality-specific explanation is not available for "Implementation" and "Operations".

3.17.6

3.17.1

3.17.2

3.17.3

3.17.4

3.17.5

The connection pool clustering functionality optimizes the operations in a system where the database is used in a cluster configuration. You can use this functionality when you connect to Oracle using Oracle RAC. By using the connection pool clustering functionality, you can prevent the drop in system availability during errors and during maintenance. The following points describe the operations when an error occurs in the database node and when maintenance is performed for the database node while you are using the connection pool clustering functionality.

• When an error occurs in the database node

When a connection cannot be obtained, such as during an OS, hardware, or software error, you can automatically suspend the connection pool connected to the database node where the error occurred (auto-suspension functionality). Even when a connection request is sent from the J2EE application to the resource adapter, no connection request is sent to the suspended connection pool, so the processing is not cancelled until a TCP/IP timeout occurs. This enables the J2EE application to continue business by obtaining a connection from a connection pool connected to another normal database node.

Also, when the database node error is recovered, you can automatically restart the connection pool (auto-restart functionality). If the connection pool is restarted, the automatically recovered database node is accessed again, so you need not execute the cjclearpool

command to delete the connection pool for recovering the database node.

• When maintenance is performed for the database node

When you perform maintenance for a database node, you can use commands to suspend the member connection pool at any time (manual suspension functionality). Due to this, you can separate that database node and perform maintenance.

Also, when you restart the database node after maintenance finishes, you can use commands to restart the connection pool at any time (manual restart functionality).

This section describes how to connect to Oracle clustered by using the Oracle RAC functionality, and the features and functionality of a connection pool when the connection pool is clustered (connection pool clustering).

3.17.1 Connecting to Oracle using Oracle RAC

The method of connecting to Oracle using Oracle RAC differs depending on the Oracle version or the functionality used for load balancing. Note that the connectable transaction type is a local transaction.

For details on the Oracle versions, the functionality used for load balancing, and the mapping of the RAR files used,

see

3.6.6 Preconditions and notes on connecting to Oracle

.

This subsection describes the Oracle connection method for each functionality used for load balancing.

234

3. Resource Connections and Transaction Management

(1) Connections using the Application Server functionality

You use the connection pool clustering functionality of Application Server to connect to Oracle RAC. Application

Server distributes the load of database access.

For details on the connection pool clustering functionality, see the description in section

3.17.2

and later.

(a) Load balancing procedure and settings

The following figure shows the load balancing procedure and settings when you use the connection pool clustering functionality.

Figure 3

61: Connection using the connection pool clustering functionality

This figure shows an Oracle RAC system with a 3-node configuration where the database node 1 contains instance 1, database node 2 contains instance 2, and database node 3 contains instance 3. The settings for connecting to the database are as follows:

1. Generate DB Connector M1, M2, and M3 for the member resource adapters mapped to instances 1, 2, and 3. Also, generate DB Connector R for the root resource adapter that contains the functionality for distribution to the member resource adapters.

2. Associate the J2EE applications with DB Connector R for the root resource adapter.

With these settings, the database access from the J2EE applications 1 and 2 is distributed to the database nodes 1, 2, and 3.

(b) Operations during database errors and recovery

When a database error occurs, Application Server detects the error. The member resource adapter mapped to the database where the error occurred is blocked and the processing is continued with the remaining instances.

When the database error is recovered, Application Server automatically releases the blockade. You can also release the blockade manually.

(2) Connections using the Oracle functionality

You connect to Oracle RAC from DB Connector and distribute the database access load with the Oracle RAC functionality.

(a) Load balancing procedure and settings

The following figure shows the load balancing procedure and settings when you use the Oracle RAC functionality.

235

3. Resource Connections and Transaction Management

Figure 3

62: Connection using the Oracle RAC functionality

This figure shows an Oracle RAC system with a 3-node configuration where the database node 1 contains instance 1, database node 2 contains instance 2, and database node 3 contains instance 3. The settings for connecting to the database are as follows:

1. Generate DB Connector A that distributes and connects to each instance.

2. Set up DB Connector A to use a global database name or service name.

3. Associate J2EE application 1 and 2 with DB Connector A.

With these settings, the database access from the J2EE applications 1 and 2 is distributed to the database nodes 1, 2, and 3.

(b) Operations during database errors and recovery

When a database error occurs, the Oracle RAC functionality separates the instance where the error occurred and the processing is continued with the remaining instances.

If you are using an Application Server connection pool, execute one of the following operations during database recovery. The connection pool is cleared and the subsequent access is distributed normally.

Execute the cjclearpool

command.

Restart the J2EE server.

3.17.2 Overview of connection pool clustering

A connection pool that is clustered is called

connection pool clustering

. This subsection describes the connection pool clustering configuration and the functionality available with connection pool clustering.

(1) Connection pool clustering configuration

The member resource adapters connected to each database node and the root resource adapter that bundles these multiple member resource adapters together configure a clustered connection pool. A description of the root resource adapter and member resource adapter is as follows:

• Root resource adapter

This resource adapter is accessed from the J2EE applications when a clustered connection pool (connection pool clustering) is used. The root resource adapter bundles the member resource adapters together. With the root

236

3. Resource Connections and Transaction Management resource adapter, the processing requests to the root resource adapter are distributed to the member resource adapters. Note that the root resource adapter does not have a connection pool.

• Member resource adapter

This resource adapter is connected to clustered individual database nodes. A member resource adapter is necessarily accessed via the root resource adapter. The connection pool of a member resource adapter is called a

member connection pool

.

The following figure shows the flow of processing for obtaining a connection when the connection pool is clustered.

Figure 3

63: Flow of processing for obtaining a connection

1. The J2EE application makes a connection request to the root resource adapter.

2. The root resource adapter selects one member connection pool and sends the connection request.

3. A connection is selected from the member connection pool and returned to the J2EE application.

(2) Preconditions

The database that can use the connection pool clustering functionality is Oracle11g only when the RAC functionality is used. The available JDBC driver is Oracle JDBC Thin Driver.

(3) J2EE components and functionality available for database connections

The following table describes the J2EE components and functionality available for database connections when the connection pool clustering functionality is used.

Table 3

73: J2EE components and functionality available for database connections (Connection pool clustering functionality)

Items

Oracle11g (when the connection pool clustering functionality is used)

J2EE components Servlet/JSP Y

237

3. Resource Connections and Transaction Management

J2EE components

Available functionality

Items

Stateless Session Bean

Stateful Session Bean

Singleton Session Bean

Entity Bean (BMP)

Entity Bean (CMP 1.1)

Entity Bean (CMP 2.0)

Message-driven Bean

Connection pooling

Connection pool warming up

Displaying the connection pool information

( cjlistpool

command)

Clearing the connection pool

Connection test for resources

Detecting the connection errors

Statement pooling

Statement cancellation

Statement setQueryTimeout

method

PRF trace output for the connection ID

Output of the SQL statement for troubleshooting

Oracle11g (when the connection pool clustering functionality is used)

N

N

N

Y

Y

Y

Y

Y

Y

Y

Y

#

Y

#

Y

Y

Y

Y

Y

Y

Legend:

Y: Available

N: Not available

# Precautions need to be taken when you connect to Oracle. For details, see

3.6.6 Preconditions and notes on connecting to Oracle

.

!

Important note

To use a resource adapter, you must resolve the references from the J2EE application to the resource adapter. When you customize a J2EE application that uses the resource adapters, resolve the references from the J2EE application to the resource adapter.

(4) Available resource connection and transaction management functionality

For details on the functionality available with the root resource adapter and member resource adapter, see

3.3.4

Resource adapter functionality

.

3.17.3 Resource adapters used

This subsection describes the commands that can be executed with the root resource adapter and member resource adapter, gives an overview of the settings, and describes the notes.

238

3. Resource Connections and Transaction Management

(1) Executable commands

The following table describes the executability of commands for the root resource adapter and member resource adapter. Note that the commands other than those listed in the table can be executed with any resource adapter.

Table 3

74: Executability of commands in root resource adapter and member resource adapter

Types of resource adapters

Command

Root resource adapter Member resource adapter cjstartrar cjstoprar cjtestres cjlistrar cjclearpool cjlistpool cjsuspendpool cjresumepool

N

N

N

N

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Legend:

Y: Can be executed

N: Cannot be executed

(2) DB Connector settings

The following table describes the items specified in DB Connector for the root resource adapter and member resource adapter.

Table 3

75: Items specified in DB Connector for the root resource adapter and member resource adapter

Types of resource adapters

Settings

Root resource adapter Member resource adapter

Transaction support level N

Can the log be collected

Database connection information

DB Connector-specific settings (such as the statement pool)

Security information (user name and password)

Y

--

--

N

Y

#1

Y

Y

Y

Connection pool size

Connection pool clustering-specific settings

N

Y

Y

#2

Y

--

Legend:

Y: Settings must be specified

N: Settings need not be specified

--: There are no settings

#1: The transaction support levels of all the member resource adapters configuring one clustered connection pool must be the same.

#2: The user names of all the member resource adapters configuring one clustered connection pool must be the same.

For details on the DB Connector settings, see

4.2 Settings for connecting to a database

in the

uCosminexus

Application Server Application Setup Guide

, or

4.1 HITACHI Connector Property file

in the

uCosminexus Application

Server Application and Resource Definition Reference Guide

.

239

3. Resource Connections and Transaction Management

(3) Notes on the root resource adapters

You cannot execute the cjclearpool

command. If the command is executed, a message is output and the command terminates abnormally. To clear the connections in a clustered connection pool with the cjclearpool

command, execute the command for the member resource adapter.

You cannot execute the cjlistpool

command. If the command is executed, a message is output and the command terminates abnormally. If you want to display the information of a connection pool within the clustered connection pool, execute the cjlistpool command by specifying the member resource adapter display name in

-resname

, or by specifying

-resall

.

You cannot mix and use a container-managed sign-on and component-managed sign-on in one clustered connection pool. When you use a component-managed sign-on, leave the user names of all the member resource adapters belonging to the root resource adapter blank.

You can start a root resource adapter when all the member resource adapters belonging to the root resource adapter are running. If you start the root resource adapter in the other cases, an error message is displayed on the console or on the screen, and the resource adapter fails to start.

(4) Notes on the member resource adapters

With the member resource adapters, the prerequisite functionalities are as follows. These functionalities are enabled by default and cannot be disabled.

Connection pooling

Specify a value greater than 0 as the maximum connection pool value. If 0 or less is specified, the operations are performed assuming that the default values are specified for the maximum and minimum connection pool values.

Detecting the connection errors when connections are obtained

Detecting the connection errors when connections are obtained and timeout for detecting the connection errors are enabled regardless of the set values.

Waiting for a connection when connections deplete

Waiting for a connection when connections deplete is enabled regardless of the set value.

loginTimeout

Specify a value greater than 0 in the loginTimeout property. If 0 or less is specified, the operations are performed assuming that the default value is specified.

The following functionalities cannot be used with the member resource adapters. These functionalities are disabled by default and cannot be enabled.

Retrying to obtain a connection

User-specified Namespace for the J2EE resources

All the connections in the member connection pool must be connected to the same database node; therefore, do not use the functionality to change the connection destination for a database. The examples of these functionalities are as follows. For the settings on disabling the functionality, see the Oracle documentation.

Client load balancing functionality

Connection failover functionality

Database service

Listener-based load balancing functionality

The member resource adapters are necessarily accessed via the root resource adapter. Therefore, you cannot specify the member resource adapters in the following locations:

Resource references of the J2EE applications

Mapping definitions of the CMP Entity Bean

You can stop a member resource adapter when the root resource adapter to which the member resource adapter belongs is stopped. If you stop a member resource adapter when the root resource adapter is running, an error message is displayed on the console or on the screen, and the resource adapter fails to stop.

When a member connection pool is blocked and suspended, to destroy the connections the unused connections are removed from the connection pool. At this time, if you restart the connection pool when the destruction of

240

3. Resource Connections and Transaction Management connections is not yet complete, the total number of connections in the connection pool and the unused connections removed from the connection pool might temporarily exceed the maximum number of connections in the connection pool.

3.17.4 Connection pool clustering operations

This subsection describes the available functionality and operations when a connection pool is clustered. You can execute the following functionality with a clustered connection pool:

Suspending a connection pool

Restarting a connection pool

This subsection also describes the connection pool states and how to select a connection pool when a connection request is received.

(1) Suspending a connection pool

You can block and suspend a member connection pool. If you execute suspend, a member connection pool is blocked and suspended.

When a J2EE application sends a connection request to the root resource adapter, no connection request is sent to a blocked or suspended member connection pool.

You suspend the member connection pool in the following cases:

When an error occurs in a database node

When maintenance is performed for a database node

Note that the suspension methods include the following two methods:

Auto-suspension

Manual suspension

Reference note

With the suspension processing, the connections that the J2EE application has finished using are destroyed, all the connections in the connection pool are destroyed, and then the connection pool is suspended. When a network error or a database node error occurs, a connection is destroyed after waiting for the network to timeout, so the processing from blocking to suspending the connection pool might take time.

(a) Auto-suspension

You can automatically suspend the member connection pool when a database node error occurs. When an error is detected, the member connection pool is automatically blocked and then suspended.

If the following events occur when a connection is obtained, a database node error is determined, and the member connection pool is automatically suspended:

When a timeout occurs during the detection of the connection errors while a connection is being obtained

When a physical connection cannot be obtained

When the obtaining of a physical connection times out

When the connection management threads deplete

This functionality is enabled by default. Specify the settings for enabling or disabling this functionality as a root resource adapter property. For details on the resource adapter settings, see

5.4 Resource adapter property definitions

in the

uCosminexus Application Server Application Setup Guide

.

(b) Manual suspension

When you perform operations such as database node maintenance, you execute the cjsuspendpool

command to manually suspend a connection pool. You can execute manual suspension when the status of a member connection pool is Start, Reserved Start, Auto-suspend, and Reserved Auto-suspend. If you execute the cjsuspendpool

241

3. Resource Connections and Transaction Management command when the member connection pool is in an auto-suspension state, the status changes to manual suspension.

Due to this, you can execute operations so that the member connection pool is not restarted automatically after auto-

suspension. For details on the manual suspension procedure, see

3.17.5(2) Suspending a connection pool

. For

command details, see

cjsuspendpool (Suspending a member connection pool)

in the

uCosminexus Application Server

Command Reference Guide

.

!

Important note

A connection pool that is suspended manually with the cjsuspendpool

command is not restarted automatically. Restart the connection pool manually.

(2) Restarting a connection pool

You can restart a suspended member connection pool. When the J2EE application makes a connection request to the root resource adapter, the connection requests are now sent to the restarted member connection pool again.

Note that to restart a connection pool, the number of unused connection management threads must be equal to or more than the maximum number of connections in the connection pool.

You restart the connection pool in the following cases:

When the database node error is recovered

When the maintenance of the database node finishes

The restart methods include the following two methods:

Auto-restart

Manual restart

Reference note

If the number of unused connection management threads becomes equal to the maximum number of connections in the connection pool when the connection pool is stopped, a message is output. When the execution of the cjresumepool command fails, check the displayed message and then re-execute the command.

When the connection pool warming up functionality is enabled, the member connection pool starts after the minimum number of connections defined in the connection pool settings is pooled. If an attempt to generate a connection fails while the connections are being pooled, the member connection pool returns to the suspended state.

Also, if the connection pool warming up functionality is disabled, the member connection pool starts immediately.

(a) Auto-restart

You can automatically restart an auto-suspended member connection pool.

The auto-suspended member connection pool sends a physical connection request at regular intervals to check the state of the database node. At this time, if a connection is obtained successfully, the database node is determined to have recovered, and the restart processing is performed automatically. Also, if you do not want to automatically restart an auto-suspended member connection pool, manually suspend the member connection pool after the pool is suspended automatically. To restart the pool, use manual restart.

Note that if the root resource adapter is stopped, the auto-restart processing is not performed. However, if you stop the root resource adapter while the member connection pool is auto-restarting, the running auto-restart processing is continued.

This functionality is enabled by default. Specify the settings for switching between enabling and disabling and for the interval to check the database node state as the root resource adapter properties. For details on the resource adapter settings, see

5.4 Resource adapter property definitions

in the

uCosminexus Application Server Application Setup

Guide

.

(b) Manual restart

You can manually restart an auto-suspended or manually suspended connection pool. To restart manually, use the cjresumepool

command. You can execute manual restart when the status of the connection pool is as follows:

Auto-suspension

Manual suspension

242

3. Resource Connections and Transaction Management

Reserved auto-suspension

Reserved manual suspension

For details on the manual restart procedure, see

3.17.5(3) Restarting a connection pool

. For the command details, see

cjresumepool (Restarting a member connection pool)

in the

uCosminexus Application Server Command Reference

Guide

.

(3) States of the connection pool

A connection pool state only exists for the member connection pools. Note that the connection pool state is maintained even after you restart the J2EE server and resource adapter.

You can check the state of the member connection pool with the following methods. When you execute manual suspension or manual restart, check the connection pool state before you execute the commands.

cjlistrar

command

The cjlistrar

command outputs the names and states of all the deployed resource adapters to the standard output. If you specify -clusterpool , you can also display the states of the member connection pools.

For the command details, see

cjlistrar (Displaying a list of resource adapters)

in the

uCosminexus Application

Server Command Reference Guide

.

cjlistpool

command

The cjlistpool

command displays the connection pool information. The command can also display the states of the member connection pools for the member resource adapters. For the examples on displaying the connection

information for the member resource adapters, see

3.15.4 Displaying the connection pool information

.

For the command details, see

cjlistpool (Displaying the list of connection pools)

in the

uCosminexus Application

Server Command Reference Guide

.

This subsection describes the states of the member connection pools.

The state of the member connection pool is maintained even if you restart the J2EE server and member resource adapter. For the procedure for checking the connection pool states, see

3.17.5(1) Checking the connection pool states

.

Note that the connection pools other than those for the member resource adapters do not have a state.

(a) Transition of the connection pool state

The following figure shows the transition of the member connection pool state.

243

3. Resource Connections and Transaction Management

Figure 3

64: Transition of the member connection pool state (when the pool is suspended manually)

Figure 3

65: Transition of the member connection pool state (when the pool is suspended automatically)

244

Note that when the J2EE server starts, if the status of the connection pool is Resuming or Blocked, the connection pool status transits to Suspended.

The following table describes each status.

3. Resource Connections and Transaction Management

1

2

3

4

5

6

7

8

9

10

No.

Table 3

76: Status of the member connection pools

Status

Start status

Reserved Start status

Auto-restarting status

Manual Restarting status

Automatically Blocked status

Manually Blocked status

Auto-suspension status

Manual Suspension status

Reserved Auto-suspension status

Reserved Manual Suspension status

Explanation

A state in which the connection pool receives processing. When a connection request is made to the root resource adapter, the processing is only performed for a started connection pool.

A state in which the resource adapter is stopped when the connection pool has the

Start status. The status of a connection pool with the Reserved Start status changes to the Start status when you start the resource adapter. This status is reached immediately after the resource adapter is deployed.

A state in which the connection pool performs the restart processing using the auto-restart functionality. If the restart processing is successful, the status changes to the Start status. If the restart processing fails, the status returns to the Autosuspension status. No request is sent to a connection pool with the Auto-restarting status when a connection request is sent to the root resource adapter.

A state in which the connection pool performs the restart processing by executing the cjresumepool

command in the Auto-suspension status or Manual

Suspension status. If the restart processing is successful, the status changes to the

Start status. If the restart processing fails, the status returns to the one before the command was executed. No request is sent to a connection pool with the Manual

Restarting status when a connection request is sent to the root resource adapter.

A state in which the auto-suspension functionality is used to block a connection pool and perform the suspension processing. When the suspension processing finishes, the status changes to the Auto-suspension status. No request is sent to a connection pool with the Automatically Blocked status when a connection request is sent to the root resource adapter.

A state in which the cjsuspendpool command is used to block a connection pool and perform the suspension processing. When the suspension processing finishes, the status changes to the Manual Suspension status. No request is sent to a connection pool with the Manually Blocked status when a connection request is sent to the root resource adapter.

A state in which the auto-suspension functionality is used to suspend the connection pool. There are no connections in the connection pool. No request is sent to a connection pool with the Auto-suspension status when a connection request is sent to the root resource adapter.

A state in which the cjsuspendpool command is used to suspend the connection pool. There are no connections in the connection pool. No request is sent to a connection pool with the Manual Suspension status when a connection request is sent to the root resource adapter.

A state in which the resource adapter is stopped when the connection pool is in the Auto-suspension status. A connection pool with the Reserved Autosuspension status changes to the Auto-suspension status when the resource adapter is started. Note that at this time the connection pool warming up functionality is disabled.

A state in which the resource adapter is stopped when the connection pool is in the Manual Suspension status. A connection pool with the Reserved Manual

Suspension status changes to the Manual Suspension status when the resource adapter is started. Note that at this time the connection pool warming up functionality is disabled.

Note: The numbers indicate the numbers in Figure 3-64 and Figure 3-65.

(b) Executability of commands based on the connection pool status

Depending on the state of the connection pool, some commands can be executed and some cannot be executed. The following table describes whether the commands can be executed for each connection pool state.

245

3. Resource Connections and Transaction Management

Table 3

77: Executability of commands based on the connection pool status

Connection pool status

Command

Start

Reserve d Start

Autorestarting

/ Manual

Restartin g

Automati cally

Blocked/

Manually

Blocked

Autosuspensi on

Manual

Suspensi on

N

Y

Y

N

N

Y

N

Y cjstartrar cjstoprar cjclearpool cjlistrar cjsuspendpool cjresumepool cjstopsv (for a normal termination) cjstopsv

(for a forced termination)

Y

Y

Y

N

Y

Y

N

Y

Y

N

Y

Y

N

R

#1

N

Y

N

N

R

#1

Y

N

R

#2

N

Y

N

N

R

#2

Y

N

Y

Y

Y

Y

Y Y

N

Y

N

Y

Y

Legend:

Y: Can be executed

R: Restricted

N: Cannot be executed

#1: The command is received, but the processing is executed when the status changes to Start or Suspend.

#2: The command is received, but the processing is executed when the status changes to Suspend.

Reserve d Autosuspensi on

Reserve d Manual

Suspensi on

N

Y

Y

Y

Y

Y

N

Y Y

N

Y

N

Y

Y

Y

N

(4) How to select a connection pool

When the J2EE application sends a connection request to the root resource adapter, one member connection pool is selected. The method by which the member connection pool is selected at this time is the round-robin method.

The connection pool that is selected is a member connection pool with the Start status. A member connection pool that has free connections is selected on priority.

However, if only a member connection pool with depleted connections is available, the connection request changes to pending. Furthermore, if a timeout occurs in a pending connection, the connection cannot be obtained. Also, if a connection pool is blocked when a connection request is pending, the connection request is restarted and an attempt is made to obtain a connection from the member connection pool that is next in the priority order. If a connection cannot be obtained from any of the member connection pools, the attempt to obtain the connection fails.

Note that if there is a connection request when a member connection pool with the Start status does not exist, the attempt to obtain the connection fails.

To specify the maximum size of each member connection pool, use the following guideline:

Maximum-size-of -the-member-connection-pool-(number)

=

Maximum-number-of-concurrent-connectionspermitted-for-the-system

/

number-of-database-nodes

3.17.5 Procedure for stopping or starting a connection pool manually

This subsection describes the procedure for connection pool clustering. By manually stopping and restarting some of the connection pools when you handle the errors occurring in a database and when you perform database maintenance, you can perform database maintenance without stopping the entire system. To perform database maintenance by manually stopping and restarting some of the connection pools:

1. Check the connection pool status (see

3.17.5(1)

)

Use the server management commands to execute the operation.

246

3. Resource Connections and Transaction Management

2. Suspend the connection pool (see

3.17.5(2)

)

Use the server management commands to execute the operation.

3. Restart the connection pool (see

3.17.5(3)

)

Use the server management commands to execute the operation.

4. Check the connection pool status (see

3.17.5(1)

)

Use the server management commands to execute the operation.

(1) Checking the connection pool state

You check the connection pool state before and after you perform maintenance for a database in a cluster configuration.

For details on the connection pool states, see

3.17.4(3) States of the connection pool

.

You check the connection pool state with the cjlistrar

command.

The format and example of execution of the cjlistrar

command are as follows:

Format of execution

cjlistrar

server-name

-clusterpool

Example of execution

cjlistrar MyServer -clusterpool

(2) Suspending the connection pool

This section describes the procedure for suspending the connection pool.

You can suspend a connection pool with the cjsuspendpool

command. When you execute the cjsuspendpool command, the connection pool is blocked and suspended and the connection requests are no longer received.

You can execute the cjsuspendpool command when the status of the connection pool is as follows:

Start

Reserved Start

Auto-suspension

Reserved Auto-suspension

For details on how to check the state of the connection pool, see

(1) Checking the connection pool state

.

The format and example of execution of the cjsuspendpool

command are as follows:

Format of execution

cjsuspendpool

server-name

-resname

display-name-of-member-resource-adapter-to-be-suspended

Example of execution

cjsuspendpool MyServer -resname DB_Connector_for_Oracle_ClusterPool_Member

(3) Restarting the connection pool

This section describes the procedure for restarting the connection pool.

You can restart the connection pool with the cjresumepool

command. When you execute the cjresumepool command, the connection pool status changes to Manual Restarting and the restart processing is executed. When the restart processing finishes, the connection pool status changes to Start and the connection requests are received.

You can execute the cjresumepool

command when the state of the connection pool is as follows:

The number of unused connection management threads is equal to the maximum number of connections in the connection pool or more

The status of the connection pool is Manual Suspension, Reserved Manual Suspension, Auto-suspension, or

Reserved Auto-suspension

247

3. Resource Connections and Transaction Management

For details on how to check the state of the connection pool, see

(1) Checking the connection pool state

.

The format and example of execution of the cjresumepool command are as follows:

Format of execution

cjresumepool

server-name

-resname

display-name-of-member-resource-adapter-to-be-restarted

Example of execution

cjresumepool MyServer -resname DB_Connector_for_Oracle_ClusterPool_Member

Note that after you execute the cjresumepool

command, you must check the status of the connection pool to check whether the restart processing was executed correctly. For details on how to check the state of the connection pool, see

(1) Checking the connection pool state

.

3.17.6 Settings required for clustering a connection pool

To cluster a connection pool, you must set up the DB Connector properties. For details on setting up the DB

Connector properties, see

4.3 Settings for connecting to the database (for connection pool clustering)

in the

uCosminexus Application Server Application Setup Guide

.

248

3. Resource Connections and Transaction Management

3.18 Connection test for resources

After you set up the resource adapter properties, you can verify whether the set up content is correct. This is called the

connection test functionality

. The content verified by a connection test differs for each connected resource. The following table describes the content to be verified in the connection test for each resource.

For details on the procedure for executing the connection test and resource adapter settings, see

3.3.8 Procedure for resource adapter settings (To deploy and use the resource adapter as a J2EE resource adapter)

and

3.3.9 Procedure for resource adapter settings (To include and use the resource adapter in a J2EE application)

.

Table 3

78: Content to be verified in the connection test

Resource type Connection method

Content to be verified in the connection test

Database DB Connector

Database queue

DB Connector (Root resource adapter when the connection pool clustering functionality is used)

DB Connector (Member resource adapter when the connection pool clustering functionality is used)

Cosminexus RM

The mode is the 1.4 mode

The specified transaction support level is available.

#1, #2

The DB Connector settings are correct.

The settings for the JDBC driver to be used are correct.

A connection can be established with the database.

The SQL statement was issued successfully.

The mode is the 1.4 mode.

The specified transaction support level is available.

#1

The DB Connector settings are correct.

The settings required for starting the root resource adapter are specified.

#3

The mode is the 1.4 mode.

The specified transaction support level is available.

#1

The DB Connector settings are correct.

The Oracle JDBC Thin Driver settings are correct.

A connection can be established with the database.

The SQL statement was issued successfully.

The prerequisite functionality for the member resource adapter is being used.

#4

The functionality that is not available with the member resource adapters is not used.

#4

The mode is the 1.4 mode.

The specified transaction support level is available.

#1

The settings for Cosminexus RM are correct.

DB Connector for Cosminexus RM to be integrated is running.

The settings for DB Connector for

Cosminexus RM to be integrated are correct.

249

3. Resource Connections and Transaction Management

Resource type

Database queue

OpenTP1

CJMSP Broker

SMTP server

Other

Connection method

Cosminexus RM

DB Connector for Cosminexus RM

TP1/Message Queue - Access uCosminexus TP1 Connector

TP1 inbound adapter

CJMSP resource adapter

Mail configuration

Resource adapters from other companies

Content to be verified in the connection test

A connection can be established with the database to be used.

The settings for DB Connector for

Cosminexus RM are correct.

DB Connector for Cosminexus RM is running.

The settings for Cosminexus RM to be integrated are correct.

Cosminexus RM to be integrated is running.

The settings for the JDBC driver to be used are correct.

A connection can be established with the database to be used.

The SQL statement was issued successfully.

The mode is the 1.4 mode.

The specified transaction support level is available.

#1

The settings for TP1/Message Queue -

Access are correct.

TP1/Message Queue - Access can establish a connection to TP1/Message

Queue.

The mode is the 1.4 mode.

The specified transaction support level is available.

#1

The settings for uCosminexus TP1

Connector are correct.

A connection test cannot be performed because of the communication with

Inbound. If a connection test is attempted, the KDJE48606-E message is output.

The mode is the 1.4 mode.

A connection can be established with

CJMSP Broker.

A connection can be established with the

SMTP server.

The mode is the 1.4 mode.

A connection can be established with the resource

#5

(if the createManagedConnection method of the implementation class of javax.resource.spi.ManagedCo

nnectionFactory

is invoked successfully, the connection with the resource is assumed to have been established).

The resource adapters conforming to

Connector 1.5 can be started and stopped when the resource adapter is not running

(if the start

method and stop

method of the implementation class of

250

3. Resource Connections and Transaction Management

Other

Resource type Connection method

Resource adapters from other companies

Content to be verified in the connection test javax.resource.spi.ResourceA

dapter are invoked successfully, the resource adapter is assumed to have been started or stopped).

#1: Available if a global transaction ( XATransaction ) is specified as the transaction support level for a resource adapter and the ejbserver.distributedtx.XATransaction.enabled

key in usrconf.properties

is true

. For details on the transaction support levels, see

3.4.3 Transaction types available for each resource

.

#2: You cannot use a global transaction ( XATransaction ) when the database to be connected to is XDM/RD E2. The physical connection for transaction recovery cannot be obtained, so DB Connector cannot be started.

#3: For details on the settings required for starting the root resource adapter, see

4.3.3 DB Connector settings for the root resource adapter

in the

uCosminexus Application Server Application Setup Guide

.

#4: For details on the prerequisite functionality and the functionality that is not available with member resource adapters, see

3.17.3

Resource adapters used

.

#5: If the connection definition required for connecting to a resource does not exist when you perform Outbound communication, the message KDJE48606-E is output and the test fails.

251

3. Resource Connections and Transaction Management

3.19 Functionality for operations in the firewall environment

When you embed the firewall in a system, you must fix the port to be used for communication, and permit communication using the fixed port only.

The following table describes the organization of this section.

Table 3

79: Organization of this section (Functionality for operations in the firewall environment)

Category Title reference location

Explanation Communication port for transaction recovery

3.19.1

Settings

Communication port used by Smart Agent

Settings for operations in the firewall environment

Note: The functionality-specific explanation is not available for "Implementation" and "Operations".

3.19.2

3.19.3

Reference note

Preventing the deterioration of communication performance using connection sweeper

A firewall has a functionality to forcefully disconnect a session that has not communicated for a fixed period of time or more. A firewall is allocated between Application Server and the database server, and when the connection pool is enabled, the connections that are not used for a while might be disconnected by the firewall. There is a long waiting period for the subsequent use of the disconnected connection. You can prevent this event by specifying settings in the connection sweeper functionality to destroy the unused connections faster than the time taken by the firewall to disconnect a non-communicating session.

3.19.1 Communication port for transaction recovery

When you use a global transaction, you use the communication port for the transaction recovery processing. When you embed a firewall in the system, you must permit communication from this port depending on the firewall configuration. By default, 20302 is used as the port number, but you can change this number.

You specify the settings of the communication port for transaction recovery by customizing the J2EE server properties. For details on customizing the settings for the J2EE server operations, see

3.19.3 Settings for operations in the firewall environment

.

3.19.2 Communication port used by Smart Agent

The TPBroker Smart Agent (OSAgent) uses a communication port. When you embed a firewall in the system, you must permit communication using this port depending on the firewall configuration.

You specify the settings for the communication port used by Smart Agent by customizing the J2EE server properties.

For details on customizing the settings for the J2EE server operations, see

3.19.3 Settings for operations in the firewall environment

.

Note that the communication port specified in the J2EE server properties must also be specified in the environment variable

OSAGENT_PORT

. Make sure you specify the same value in the J2EE server properties and the environment variable

OSAGENT_PORT

.

3.19.3 Settings for operations in the firewall environment

To perform operations in the firewall environment, you must specify the J2EE server settings. You specify the items listed in the following table in the <configuration> tag of the logical J2EE server ( j2ee-server ) in the Easy

Setup definition file.

252

3. Resource Connections and Transaction Management

Table 3

80: Settings for operations in the firewall environment in the Easy Setup definition file

Items Specified parameters Settings

Transaction recovery

Communication port used by Smart

Agent ejbserver.distributedtx.recove

ry.port

vbroker.agent.port

Specifies the fixed port number to be used for transaction recovery.

Specifies the communication port used by

Smart Agent.

253

3. Resource Connections and Transaction Management

3.20 Notes on starting a transaction with the EJB client applications

This section describes the notes on starting transactions with the EJB client applications.

Tip

You can start a transaction with an EJB client application when Application Server is installed on the EJB client computer.

You cannot start a transaction with an EJB client application when uCosminexus Client is installed on the EJB client computer.

When you start a transaction with an EJB client application, you use a global transaction to invoke the EJBs on

Application Server. At this time, the transaction manager and transaction service propagate the transaction between the EJB client and Application Server and finally execute a two-phase commit.

A transaction started using an EJB client application can invoke multiple EJBs existing on Application Server.

Multiple resources can be accessed with Application Server. Note that you cannot access the resources directly from an EJB client application.

This section describes the notes on starting a transaction with the EJB client applications.

3.20.1 Notes on application development

This subsection describes the notes on application development when you start a transaction with an EJB client application. For details on implementing transactions with the EJB client applications, see

3.5 Implementing transactions with the EJB client applications

in the

uCosminexus Application Server EJB Container Functionality

Guide

.

To use a global transaction with an EJB client application, immediately after starting the EJB client application, you must invoke the processing for initializing the services to be used with the EJB client application, from the user program. By invoking this initialization processing, the transaction manager and transaction service are initialized. As the initialization processing, invoke the initialize()

method of the

EJBClientInitializer

class.

By invoking service initialization from the user program even when the EJB client application terminates abnormally during the transaction processing, you can start the transaction recovery. Note that the recovery processing is executed in the background, so the initialize()

method is returned without waiting for the recovery processing to finish. Design the EJB client application so that the recovery of a global transaction starts by restarting the EJB client application.

If transactions are started in an EJB client application, specify the design so that all the transactions are concluded and then the EJB client application stops. If the EJB client application stops without waiting for the transactions to conclude, the unconcluded transactions might remain in the transaction. In this state, you might not be able to terminate Application Server normally, stop the resource adapter, or release the resource lock.

3.20.2 Notes on system setup

This subsection describes the notes on system setup and the settings.

(1) Notes on system setup

This section describes the notes on system setup when you start a transaction with an EJB client application. For details on the settings of the EJB client application transactions, see

(2) Settings for using a transaction with an EJB client application

.

When you start a transaction with an EJB client application, to use a global transaction, the light transaction functionality must be disabled on Application Server (enabled by default).

If the EJB to be invoked is specified in the attributes such as the

Mandatory

attribute,

Required

attribute, or

Supports

attribute in an EJB container-managed transaction (CMT), the EJB is executed within the scope of the transaction started with the EJB client application.

254

3. Resource Connections and Transaction Management

(2) Settings for using a transaction with an EJB client application

This section describes the settings for using a transaction with an EJB client application.

!

Important note

When you use uCosminexus Client to set up the EJB client environment, the EJB client application transactions are not available.

To use transactions with the EJB client applications, you must specify the following settings:

JAR file settings

Property settings

Settings for obtaining

UserTransaction

The settings for obtaining

UserTransaction

are the settings used for developing the J2EE applications. To use transactions with the EJB client applications, you must specify settings to obtain

UserTransaction

( javax.transaction.UserTransaction

) from the EJB client application. For details on how to specify the settings, see

3.5 Implementing transactions with the EJB client applications

in the

uCosminexus Application Server

EJB Container Functionality Guide

.

This subsection describes the JAR file and property settings for using transactions with the EJB client applications.

(3) JAR file settings

To use transactions with the EJB client applications, specify the following JAR files in the class path:

In Windows

Cosminexus-installation-directory

\TPB\lib\tpotsinproc.jar

Cosminexus-installation-directory \CC\lib\ejbserver.jar

#

In UNIX

/opt/Cosminexus/TPB/lib/tpotsinproc.jar

/opt/Cosminexus/CC/lib/ejbserver.jar

#

#: In the class path settings, specify ejbserver.jar

after

HiEJBClientStatic.jar

.

For details on specifying the JAR file in the class path, see

3.7.4 Specifying the JAR file in the class path of the EJB client application

in the

uCosminexus Application Server EJB Container Functionality Guide

.

(4) Property settings

This section describes the keys that must be set up to use transactions with the EJB client applications. For details on the property settings, see

3.3.5 Setting up the EJB client application properties

in the

uCosminexus Application Server

EJB Container Functionality Guide

. For details on the keys, see

14.3 usrconf.properties (User property file for Java applications)

in the

uCosminexus Application Server Definition Reference Guide

.

To use transactions with the EJB client applications, you set up the following keys:

(a) Mandatory properties

ejbserver.client.transaction.enabled

Specify true

to enable the use of transactions with the EJB client applications.

ejbserver.distributedtx.recovery.port

Specifies the fixed port number to be used for transaction recovery when a global transaction is used. Specify a different port number for each EJB client process. Also, specify a port number different from the port number for the recovery of Application Server operating on the same computer.

ejbserver.client.transaction.clientName

255

3. Resource Connections and Transaction Management

Specifies the client name to be used by the transaction service. Specify a different name for each EJB client process in this property. Also, specify a name different from the name of the J2EE server operating on the same computer.

ejbserver.distributedtx.ots.status.directory1

Specifies the directory for allocating the status file to be used by the transaction service and the backup of the status file. Specify a different directory for each EJB client process. Also, specify a directory different from the status file directory specified for the J2EE server.

(b) Optional properties

ejbserver.jta.TransactionManager.defaultTimeOut

Specifies the time until a transaction timeout occurs.

ejbserver.distributedtx.ots.status.directory2

Specify the second directory for allocating the status file to be used by the transaction service and the backup of the status file. Specify a different directory for each EJB client process. Also, specify a directory different from the status file directory specified for the J2EE server.

(5) Notes

This section describes the notes on specifying the settings for the EJB client application transactions.

To use a global transaction, you must disable the light transaction functionality on Application Server. By default, the light transaction functionality is enabled. If you specify true

in the ejbserver.distributedtx.XATransaction.enabled

key of usrconf.properties

for the J2EE servers, the light transaction functionality is disabled and the global transaction can be used.

3.20.3 Notes on system operations

This subsection describes the notes on operations when transactions are started with the EJB client applications.

After you stop the EJB client application, if you cannot stop Application Server and resource adapter, the unconcluded transactions might remain in the transaction. In this case, restart the EJB client application and recover the global transaction.

Note that the recovery processing is executed by invoking service initialization in the EJB client application after the application is restarted.

If the EJB client computer is down due to reasons such as errors during transaction processing, you must restart the EJB client application and then recover the global transaction.

The transactions started with the EJB client applications cannot be forcefully concluded by using the method cancellation functionality.

If an exception occurs during service initialization, the items such as the system properties for executing the EJB client applications might be specified incorrectly. Take action according to the exception message.

When transactions are started with the EJB client applications, the root application information and client application information is not included in the trace based performance analysis output by the JTA and OTS. To trace a request, use the hash code and the XID information of the thread.

Also, the message output when a transaction timeout occurs includes the hash code of the thread that started the transaction, instead of the root application information. You can also use this information to trace a request.

256

4

Invoking Application Server from

OpenTP1 (TP1 Inbound Integrated

Function) (INTENTIONALLY

DELETED)

INTENTIONALLY DELETED

257

4. Invoking Application Server from OpenTP1 (TP1 Inbound Integrated Function) (INTENTIONALLY DELETED)

4.1 INTENTIONALLY DELETED

INTENTIONALLY DELETED

258

5

How to Use JPA with Application

Server

This chapter gives an overview of the JPA and describes how to use JPA with

Application Server.

259

5. How to Use JPA with Application Server

5.1 Organization of this chapter

The JPA is a specification aimed at simplifying the designing and coding of the database-related processing and is used for mapping Java objects and relational database (O/R mapping). By using the JPA, you can operate the database information as a Java object (entity), and set up a system efficiently.

This chapter gives an overview of JPA and describes the JPA usage with Application Server. The following table describes the organization of this chapter.

Table 5

1: Organization of this chapter (Using JPA with Application Server)

Category Title Reference location

Explanation

Implementation

Features of JPA

JPA functionality that can be used with Application Server

EntityManager

Persistence context

How to obtain a container-managed EntityManager

How to obtain an application-managed EntityManager

Definitions in persistence.xml

Allocating persistence.xml

Notes

JPA interfaces

Notes on setting up applications

Note: The functionality-specific explanation is not available for

Settings

and

Operations

.

5.2

5.7

5.8

5.9

5.3

5.4

5.5

5.6

5.10

5.11

260

5. How to Use JPA with Application Server

5.2 Features of JPA

This section describes features of the applications using JPA.

5.2.1 Advantages of applications using JPA

The following contents can be realized, if you use an application using JPA:

By concealing the O/R mapping and database access processing, the user programming becomes easy.

By using annotations, the cost of creating the definition file is reduced and coding is implemented using POJO

(Plain Old Java Object).

By setting up the default values, the amount of coding by the user can be reduced.

Cosminexus JPA provider conforms to the JPA specifications, and therefore, you can merge the applications used with other JPA providers.

This subsection compares the data access models when the JPA is not used and when the JPA is used, and describe the advantages of applications using the JPA.

(1) Data access model when the JPA is not used

To access a database from a J2EE application when the JPA is not used, you can use the data access model shown in the following figure to create an application.

Figure 5

1: Database access model when JPA is not used

This subsection describes the above figure.

With the data access model shown in the figure, you create a class called

DAO

corresponding to the table to hide the

SQL statement from the business logic. With the DAO class, you create a process to issue an SQL statement using the

JDBC interface. The flow of processing shown in the figure is as follows:

1. With an EJB where the business logic is coded, DAO is used to read the data from a database.

2. The acquired data is stored in an object called

DTO

.

3. The DTO object returns to the Web component. With the Web component, the data acquired from the database is output to a Web page.

With such a data access model, if the data model of the database becomes more complex, the number of DAO, SQL, and DTO classes that must be created also increases. The creation of DAO, SQL, and DTO involves monotonous manual work, so this decreases the productivity of an application development.

261

5. How to Use JPA with Application Server

(2) Data access model when the JPA is used

The following figure shows a data access model when the JPA is used.

Figure 5

2: Database access model when the JPA is used

When the JPA is used, you create a class corresponding to the lines in the database table. This class is called an

entity class

. With an EJB where the business logic is coded, you can code the processing as if the object of this entity class is directly stored in the database.

The description of the figure is as follows:

1. The JPA engine called the JPA provider issues an SQL statement for the database. Also, the JPA provider automatically synchronizes the status of the entity object and the database table.

2. The entity object can pass the obtained data to the Web component as is.

If you use the JPA, you need not create DTO. Furthermore, the entity class can also be automatically generated from the database table schema by using a development tool such as Eclipse. Because you do not need to create the DAO,

SQL, and DTO classes that were the reason of decreased productivity in the past data access models, you can further improve the productivity of the applications.

For details about the entity classes and the JPA providers, see

5.2.2 Entity class

and

5.2.3 JPA provider

.

5.2.2 Entity class

When you use the JPA, you create a class that forms a data container with applications. This class is called the

entity class

. Normally, you create the entity class so that one object of the entity class corresponds to one line in the database table. You create an entity class using the normal Java class (POJO). Special interfaces need not be implemented.

You specify the mapping for the values of the entity class fields and the columns of the database table where the values are stored, using annotations in the items such as the entity class fields. However, the CoC concept has been introduced in JPA in order to improve the easy development. If you do not specify mapping explicitly, the default mapping rules are applied. For example, if the mapping of fields is not explicitly specified, the corresponding column is presumed from the field name and mapped.

5.2.3 JPA provider

The

JPA provider

is a JPA implementation that provides the following mapping functionality, API, and query language. The following functionality is provided with the JPA provider:

Functionality for mapping Java objects and a database

API encapsulating the database processing

Query language that can be commonly used in the JPA specifications

The advantage of using the JPA provider is that you can design an application without knowing the processing related to database exchanges. Also, by using the query language JPQL available with the JPA provider, you can also send a query even if you are unfamiliar with the database.

262

5. How to Use JPA with Application Server

The following figure shows the mapping functionality provided by JPA providers.

Figure 5

3: Overview of the mapping functionality provided by JPA providers

This subsection describes the above figure.

An entity class is prepared in the application and an entity object is generated from the entity class. By changing the contents of the entity object, the user changes the database contents. As a result, the user can update the database contents without knowing the database processing.

The JPA provider maps the entity objects to the database records. The JPA provider also executes the search, insert, delete, or update processing implemented by the user for the database.

The generated entity object is managed by EntityManager. If the value of an entity object field is changed,

EntityManager automatically detects the change and applies the change to the database table.

During the following processing, EntityManager is invoked:

To add the data of the entity class object in the database table.

To search the data already stored in the database and to extract the data as an entity class object.

For details on EntityManager, see

5.4 EntityManager

.

263

5. How to Use JPA with Application Server

5.3 JPA functionality that can be used with Application

Server

This section describes the JPA providers, components, and resource adapters that can be used with Application Server, when the JPA is used.

5.3.1 Available JPA providers

The

JPA provider

is an engine that provides the EntityManager functionality. The JPA providers that can be used with

Application Server include Cosminexus JPA provider and the JPA providers provided by other vendors. The following points describe the usage of each of these JPA providers:

(1) When Cosminexus JPA provider is used

Cosminexus JPA provider is a JPA provider provided with Application Server. Cosminexus JPA provider provides the

Cosminexus JPA provider-specific functionality in addition to the functionality based on the JPA 1.0 specifications.

For an overview of Cosminexus JPA provider, notes on application implementation, and the usage methods of

Cosminexus JPA provider, see

6. Cosminexus JPA provider

.

(2) When the JPA providers from other vendors are used

The JPA providers are provided by other vendors. The JPA specifications clearly specify the interfaces between JPA providers and Application Server, and therefore you can also use JPA providers provided by other vendors and conforming to the JPA 1.0 specifications with Application Server.

When you use the other JPA providers from Application Server, you must specify the following settings:

• Specifying JAR files

You use one of the following methods to specify the JAR file containing the JPA provider implementation:

Specify the JAR file under the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the

Easy Setup definition file. To specify a JAR file, you specify add.class.path

in the <param-name> tag and the JAR file in the

<param-value>

tag. For details on the Easy Setup definition file and the parameters to be specified, see

4.6 Easy Setup definition file

in the

uCosminexus Application Server Definition

Reference Guide

.

Include JAR files in J2EE applications as a library.

• Definitions in persistence.xml

In the <provider> tag of persistence.xml

, specify the implementation class name of javax.persistence.PersistenceProvider

provided by the used JPA provider. For details, see

5.8.2(2) <provider> tag

.

To use the functionality for monitoring the J2EE application execution time provided with Application Server, you must add the JPA provider classes and entity classes into the protected area list. For details on how to add a class into the protected area list, see

2.6 criticalList.cfg (Protected area list file)

in the

uCosminexus Application Server

Definition Reference Guide

.

Reference note

With the execution of applications using the JPA, you can use the trace based performance analysis functionality provided with Application Server.

When Cosminexus JPA provider is used as the JPA provider

The trace based performance analysis can be output with both Application Server and Cosminexus JPA provider.

When a JPA provider from other vendors is used

You can only use the trace based performance analysis output by Application Server.

Note that with Application Server, the trace based performance analysis is output by the EntityManagerFactory,

EntityManager, EntityTransaction, and Query APIs of the javax.persistence

package. Furthermore, the trace based performance analysis related to the entity life cycle callback is output with the JPA provider.

264

5. How to Use JPA with Application Server

For an overview of the trace based performance analysis, see

7.2.1 Overview of the trace based performance analysis of

Application Server

in the

uCosminexus Application Server Maintenance and Migration Guide

. For details on the points at which the trace based performance analysis is output, see

8. Trace Collection Points and PRF Trace Collection Levels of the

Trace Based Performance Analysis

in the

uCosminexus Application Server Maintenance and Migration Guide

.

5.3.2 Available components

With Application Server, you can use the JPA with EJBs and Web applications. You can also use the JPA when user threads are used from Web applications. Note that you cannot use the JPA in the following environments or libraries:

EJB

EJB client application environment

J2EE application client environment

Container extension library

The following table lists the components that can use the JPA.

Table 5

2: Components that can use the JPA

Components

Web application

Stateless Session Bean (EJB 3.0 and later)

#1

Stateful Session Bean (EJB 3.0 and later)

#1

Stateless Session Bean (earlier than EJB 3.0)

Stateful Session Bean (earlier than EJB 3.0)

Interceptor

Message-driven Bean

Entity Bean

Servlet, filter, event listener (Servlet 2.5 and later)

JSP, JSP tag handler, JSP event listener, JSP tag library event listener

#2

(Servlet 2.5 and later)

Servlet, filter, event listener (earlier than Servlet 2.5)

JSP, JSP tag handler, JSP event listener, JSP tag library event listener (earlier than Servlet 2.5)

JPA usage

Y

Y

N

Y

Y

N

Y

N

N

N

N

Legend:

Y: Available

N: Not available

#1: With Application Server, you cannot specify the JPA definition using EJB 3.0 ejb-jar.xml

. Therefore, you use annotations such as

@PersistenceUnit

and

@PersistenceContext

to define the references for the persistence units and persistence contexts.

#2 With Application Server, you cannot use annotations in the JSP tag library event listener. To use the JPA functionality in the JSP tag library event listener, you use

<persistence-unit-ref>

tag and the

<persistence-context-ref>

tag of web.xml

to define the references for the persistence units and persistence contexts.

!

Important note

If true is specified in the metadata-complete attribute of web.xml

in Servlet 2.5 and later, the Web component annotations are not read. Therefore, you cannot use annotations to define the references for the persistence contexts or persistence units. However, you can define the references in web.xml

.

265

5. How to Use JPA with Application Server

5.3.3 Supported application formats

A J2EE application using the JPA is deployed on Application Server in one of the following formats:

• Archive-format J2EE applications

• Exploded-archive format J2EE applications

You can also replace a J2EE application that uses a deployed JPA. For the archive format, use the redeploy functionality and for the exploded archive format, use the reload functionality.

Note that when you use the reload functionality, updates are not detected for the O/R mapping file. However, the O/R mapping file is re-read when the file is reloaded. The following table describes the targets for update detection and the re-reading during reload.

Table 5

3: Targets for update detection and re-reading when reload is executed

Target classes and files Update detection Re-reading

Entity class

Mapped super class

Embedded class persistence.xml

O/R mapping file

(When orm.xml

is allocated under

META-INF

)

O/R mapping file

(When orm.xml

is allocated to the location specified in the

<mapping-file>

tag of persistence.xml

)

Y

Y

N

Y

Y

Y

Y

Y

Y

Y

Y

Y

Legend:

Y: Target

N: Not a target

For details on the J2EE applications in the archive-format and the exploded archive-format, see

13. Formats and

Deployment of J2EE Applications

.

!

Important note

When you use an application with the JPA in the exploded archive format, do not delete the class or library JAR while the application is running. If the class or library JAR is deleted, Application Server and JPA provider might perform unexpected operations.

5.3.4 Supported class loader configuration

The J2EE applications using the JPA support the class loaders listed in the following table.

Table 5

4: Class loaders supported in a J2EE application using the JPA

Class loaders

Default class loader configuration

Class loader configuration used when local call optimization is performed

#

Class loader configuration for downward compatibility

Legend:

Y: Supported

N: Not supported

Support

Y

Y

N

266

5. How to Use JPA with Application Server

Note: The class loader configuration for the downward compatibility is used only in the basic mode and therefore, not supported.

#: Indicates the following specification in the

<configuration>

tag of the logical J2EE server ( j2ee-server

) in the Easy

Setup definition file:

<param-name>ejbserver.rmi.localinvocation.scope</param-name>

<param-value>all</param-value>

5.3.5 available resource adapters

When you execute a J2EE application that uses the JPA, with Application Server, you can use a resource adapter with the connection factory interface javax.sql.DataSource

. You can use DB Connector as the resource adapter provided with Application Server.

Also, you must deploy the resource adapter you want to use as the J2EE resource adapter. In the case of the J2EE applications using the JPA, you cannot include and deploy the resource adapter in the J2EE application.

The following table lists the resource adapters available with Application Server.

Table 5

5: Resource adapters available with Application Server

Connection factory interface Deploy format of the resource adapter Usage from the JPA javax.sql.DataSource

Other than javax.sql.DataSource

Deployed as a J2EE resource adapter

Included and deployed in the J2EE application

--

Y

N

N

Legend:

Y: Available

N: Not available

--: Not applicable

For details on the resource adapters available when you use Cosminexus JPA provider, see

6.2.3(3) Available DB

Connectors

.

267

5. How to Use JPA with Application Server

5.4 EntityManager

The

EntityManager

is an object that has an interface for registering and deleting entities for the database. This section gives an overview of EntityManager.

5.4.1 Methods provided with EntityManager

The EntityManager provides methods. The typical methods are as follows:

persist

method (equivalent to SQL

INSERT

)

The method used to add an entity object that executes new

in the application, into the database.

find

method (equivalent to SQL

SELECT

)

The method used to search an entity object from the database.

remove

method (equivalent to SQL

DELETE

)

The method used to delete an entity object from the database.

The entity objects searched using the find

method from EntityManager and the entity objects passed to

EntityManager using the persist method are managed by EntityManager. If a field value of an entity object managed by EntityManager is changed, EntityManager automatically detects the change and applies the change to the database table.

With the JPA, an entity object managed by EntityManager is called a

managed entity

. By default, when a transaction is concluded, the entity is no longer managed by EntityManager. An entity that is no longer managed by

EntityManager is called a

detached entity

.

5.4.2 Types of EntityManager

The types of EntityManager include the container-managed EntityManager and the application-managed

EntityManager. The following is a description of each type:

(1) Container-managed EntityManager

The method entrusts the creation and destruction of EntityManager to the container. If you use a container-managed

EntityManager, you can code an application without being aware of the generation and destruction of EntityManager.

The following points describe how to obtain and how to destroy the container-managed EntityManager.

• How to obtain the container-managed EntityManager

To obtain the container-managed EntityManager, you use the DI or JNDI lookup in the application.

EntityManager obtained using this method is EntityManager created by the container. You can use EntityManager obtained from a container as it is during the application coding.

For details on how to obtain the container-managed EntityManager from an application, see

5.6 How to obtain the container-managed EntityManager

.

• How to destroy the container-managed EntityManager

The creation and destruction of EntityManager need not be coded in the application.

(2) Application-managed EntityManager

In this method, the application explicitly creates and destroys EntityManager. The life cycle is managed explicitly by application coding. The following points describe how to obtain and how to destroy the application-managed

EntityManager.

• How to obtain the application-managed EntityManager

You use EntityManagerFactory to create EntityManager in the application. To obtain EntityManagerFactory, you use the DI or JNDI lookup in the application.

For details on how to obtain the application-managed EntityManager, see

5.7 How to obtain the applicationmanaged EntityManager

.

268

5. How to Use JPA with Application Server

• How to destroy the application-managed EntityManager

You invoke the close

method of EntityManager to destroy EntityManager.

5.4.3 Transaction control and EntityManager

The following two types of EntityManager are available depending on how the transactions are controlled:

• JTA entity manager

EntityManager in which the transactions are controlled by the JTA.

• Resource local entity manager

EntityManager in which the transactions are controlled by the EntityTransaction API.

The following table describes the relationship between the types of EntityManager and the transaction control methods.

Table 5

6: Relationship between types of EntityManager and transaction control methods

Transaction control method

Types of EntityManager

JTA Resource local

Container-managed EntityManager N

Application-managed EntityManager

#2

Y

#1

Y Y

Legend:

Y: Transaction can be controlled

N: Transaction cannot be controlled

JTA: JTA entity manager

Resource local: Resource local entity manager

#1 The transaction is necessarily controlled by the JTA.

#2 You can select whether to control the transaction using the JTA or whether the application controls the transaction, by explicitly using the

EntityTransaction

API. When the

EntityTransaction

API is used, the transaction becomes a resource local transaction. Even if the JTA transaction exists, the transaction is controlled regardless of the JTA transaction.

You specify whether you want to use the JTA entity manager or the resource local entity manager in the definition of the persistence unit. For details on how to specify definitions in the persistence unit, see

5.8.1(2) transaction-type attribute

.

5.4.4 Persistence unit

You must define the following information, when the JPA is used from the application:

Information about the entity classes in the application

Information about the mapping between the entity classes and the database tables

Information about the data source for the JPA provider to obtain the database connection

The unit that defines this information is called the

persistence unit

.

You define the persistence unit in persistence.xml

. When the JPA is used in the Java EE environment, persistence.xml

is allocated in the determined location in the EJB-JAR, WAR, or EAR files when the user packages the application.

You can include multiple persistence unit definitions in the persistence.xml

file. You can also include multiple persistence.xml

files in one application. As a result, you can define multiple persistence units in one application. When multiple persistence units are defined in an application, you specify the persistence unit to be used by the application in the unitName

attribute of

@PersistenceContext

. Note that when the persistence unit to be used can be identified uniquely, such as when only one persistence unit is defined in the application, you can omit the unitName attribute.

269

5. How to Use JPA with Application Server

5.5 Persistence context

The EntityManager caches the entity objects to be updated and the searched entity objects. The persistence context is the cache of the entity objects cached by EntityManager.

5.5.1 EntityManager and persistence context

The following figure shows a relationship between EntityManager and persistence context.

Figure 5

4: Relationship between EntityManager and persistence context

The EntityManager inserts the managed entity object in the persistence context and manages the entity objects. When the application passes the entity object to the persist method or updates the field value of the managed entity object, the status of the entity object in the persistence context is changed. EntityManager synchronizes the statuses of the entity objects in the persistence context and the database table just before the transaction is committed. In order to apply the statuses of the entity objects within the persistence context to the database table, the update SQL statements are issued collectively at this time. As a result, the database locking time is shortened, and therefore you can improve the concurrent executability and update the data efficiently.

(1) Types of EntityManager

You decide whether to use the container-managed EntityManager or the application-managed EntityManager depending on the relationship between the persistence context and transaction.

• When the persistence context needs to be automatically propagated along with the JTA transaction

You use the container-managed EntityManager. If you use the container-managed EntityManager, the persistence context is automatically propagated along with the JTA transaction. Therefore, when multiple components are invoked in one JTA transaction, EntityManager used in the same JTA transaction can be associated with the same persistence context.

As a result, the application need not pass the EntityManager references to the arguments used when the references are invoked from one component in another component.

• When the application needs to use the persistence context independently from the JTA transaction

You use the application-managed EntityManager. If you use the application-managed EntityManager, when you use another EntityManager in the same JTA transaction also, this EntityManager does not share the persistence context and has an independent persistence context.

(2) Types of persistence context

The persistence contexts are of two types depending on the lifetime:

• Transaction scope persistence context

• Extended persistence context

270

5. How to Use JPA with Application Server

For the container-managed EntityManager, you can choose the type of persistence context. You specify the type of persistence context in the type

attribute of

@PersistenceContext

. The default type is the transaction scope persistence context.

Note that the extended persistence context is always used for the application-managed EntityManager. You cannot choose the type of persistence context.

5.5.2 Persistence context when the container-managed EntityManager is used

When you use the container-managed EntityManager, the life cycle of the persistence context is managed by the container and the persistence context is automatically propagated along with the JTA transaction. You can choose the transaction scope persistence context or the extended persistence context as the type of the persistence context life cycle.

The following subsections describe the respective persistence contexts:

(1) Transaction scope persistence context

With the JPA specifications, the persistence context having the same life cycle as the transaction is called the

transaction scope persistence context

.

The EntityManager has the same life cycle as that of the transaction by default. Therefore, the updates cached in the persistence context of EntityManager are applied to the database when the transaction is committed.

(a) Life cycle of persistence context

The life cycle of the transaction scope persistence context is as follows:

• Creating the persistence context

The transaction scope persistence context is created when the container-managed EntityManager is first invoked in a JTA transaction.

The created persistence context is associated with the JTA transaction.

After that, when the container-managed EntityManager is used in the same JTA transaction, this persistence context is used.

• Destroying the persistence context

When the JTA transaction is committed or rolled back, the transaction scope persistence context is destroyed.

If the container-managed EntityManager is invoked outside the transaction, all the entities loaded from the database are immediately detached when the invocation of the EntityManager method ends.

(2) Extended persistence context

With the Java EE environment, if EntityManager is used from the Stateful Session Bean, you can set the same persistence context lifetime as the Stateful Session Bean lifetime. In this case, the updates are applied to the database every time the transaction is committed, but the entity objects managed in the persistence context are stored in the managed status as are across multiple transactions. The persistence context with the same life cycle as the Stateful

Session Bean is called the

extended persistence context

in the JPA.

The extended persistence context is created simultaneously when the Stateful Session Bean is created and is associated with that Stateful Session Bean. Thereafter, the extended persistence context is destroyed simultaneously when the

Stateful Session Bean is destroyed.

When the Stateful Session Bean creates another Stateful Session Bean and when the definition is such that the creating

Stateful Session Bean and the created Stateful Session Bean both use the extended persistence context, the persistence context on the creating side is inherited on the created machine. The persistence context is inherited regardless of whether the transaction is active when the Stateful Session Bean is created. If the persistence context is inherited when the Stateful Session Bean is created, the persistence context is destroyed when all the Stateful Session Beans sharing that persistence context are destroyed.

271

5. How to Use JPA with Application Server

(3) Extended persistence context and transactions

The extended persistence context exists from the time the EntityManager instance is created until the instance is closed. The extended persistence context supports multiple transactions and the invocation outside the EntityManager transaction.

The relationship with transactions is as follows:

If EntityManager is invoked within the transaction scope or if the stateful session beans bound by the persistence context are invoked in the transaction scope, the entities managed by EntityManager participate in the transaction.

Regardless of whether the transaction is running, the persist

, remove

, merge

, and refresh

operations might be performed. In this case, EntityManager participates in the transaction and the updates are applied in the database when the transaction is committed.

Even after the transaction is committed, the references to the entity object are stored. The entity object is managed by EntityManager and is updated as an object managed between transactions (managed entity).

(4) Propagation of persistence context

When the container-managed EntityManager is used, the persistence context is propagated using the JTA transaction and might be associated with multiple EntityManager. However, the persistence context is only propagated with the same Application Server. The persistence context is not propagated in a remote Application Server.

The following points separately describe the propagation of the persistence context for the states when a component is invoked:

If the JTA transaction does not exist or the persistence context is not associated with the JTA transaction when the component is invoked

The persistence context is not propagated. The operations when EntityManager is invoked from this component are as follows:

When EntityManager using the transaction scope persistence context is invoked, a new persistence context is created.

When EntityManager using the extended persistence context is invoked, the extended persistence context associated with the invoked Stateful Session Bean is used.

If the JTA transaction is propagated and the persistence context is associated with the JTA transaction when the component is invoked

The operations when EntityManager is invoked from this component are as follows:

If the JTA transaction exists when EntityManager is invoked, the persistence context is associated with the

JTA transaction.

If another persistence context is associated with the JTA transaction although the component is the Stateful

Session Bean that already has the extended persistence context, the container throws

EJBException

.

When EntityManager using the transaction scope persistence context is invoked, the persistence context associated with the propagated JTA transaction is used.

5.5.3 Persistence context when the application-managed EntityManager is used

When you use the application-managed EntityManager, the application directly invokes EntityManagerFactory of the

JPA provider and manages the EntityManager life cycle and the creation and destruction of the persistence context.

The life cycle of the application-managed persistence context can manage life cycles across multiple transactions.

(1) Managing the EntityManager life cycle

With the application, you use the close

and isOpen

methods of EntityManager to manage the life cycle of the application-managed EntityManager. If you invoke the close

method of EntityManager, EntityManager, persistence context associated with EntityManager, and the other resources are released. After the close

method is invoked, do not invoke methods other than EntityManager getTransaction method and isOpen method with the application.

If other methods are invoked,

IllegalStateException

is thrown. If the close

method is invoked when the

272

5. How to Use JPA with Application Server transaction is active, the persistence context remains stored until the transaction is concluded. The isOpen

method of

EntityManager returns true

until EntityManager is closed and false

after EntityManager is closed.

(2) Life cycle of persistence context

The life cycle of the application-managed persistence context is as follows:

• Creating the persistence context

The persistence context is created when the createEntityManager

method of EntityManagerFactory is invoked.

• Destroying the persistence context

The persistence context is destroyed when the close

method of EntityManager is invoked.

The application-managed persistence context is independent of the transaction. Therefore, this persistence context is not propagated along with the JTA transaction.

(3) Notes on using the JTA entity manager

When the JTA entity manager is used in the application-managed EntityManager, the invocation of joinTransaction

of EntityManager when the application creates EntityManager outside the JTA transaction scope is the responsibility of the application. The application must report EntityManager that the transaction has started, so invoke the joinTransaction

method of EntityManager after the transaction starts.

273

5. How to Use JPA with Application Server

5.6 How to obtain the container-managed EntityManager

To obtain the container-managed EntityManager from the J2EE application, use one of the following methods:

• Method of injecting EntityManager in the application field and

setter

method by using the DI

• Method of looking up EntityManager by using the JNDI from the application

The following subsections describe each of the methods.

5.6.1 Method of injecting EntityManager in the application

The following two more methods are available for injecting EntityManager in the application fields and in the setter

method:

1. Method of adding

@PersistenceContext

in the field or method at the inject destination

2. Method of specifying definitions in the

<persistence-context-ref>

tag of a DD ( web.xml

)

However, you cannot specify the JPA definition using EJB 3.0 ejb-jar.xml

with Application Server. Therefore, if you want to use the JPA in an EJB, use the method specified in point 1.

The following is a description of the methods:

(1) Method of using @PersistenceContext

When you use

@PersistenceContext

to inject EntityManager, you add

@PersistenceContext

in the field and setter

method where EntityManager is to be injected. The attributes that can be specified in

@PersistenceContext are as follows:

(a) unitName attribute

In the unitName

attribute, you specify the name of the persistence unit defined in persistence.xml

. However, when the persistence unit to be used can be uniquely identified, such as when only one persistence unit is defined in the EJB-JAR and WAR or EAR file, you can omit the unitName

attribute. For details on the persistence unit used when the unitName

attribute is omitted, see

5.11.2 Reference scope of the persistence unit name

.

(b) type attribute

In the type

attribute, you specify the life cycle type of the persistence context. You can specify

PersistenceContextType.TRANSACTION

or

PersistenceContextType.EXTENDED

.

• When

PersistenceContextType.TRANSACTION

is specified

The transaction scope persistence context is used and the transaction lifetime and the persistence context lifetime becomes the same.

• When

PersistenceContextType.EXTENDED

is specified

The extended persistence context is used and the Stateful Session Bean lifetime and the persistence context lifetime becomes the same.

Note that @PersistenceContext in which PersistenceContextType.EXTENDED

is specified in the type

attribute can only be added in the field or method of the Stateful Session Bean.

When the type

attribute is omitted, the default value is

PersistenceContextType.TRANSACTION

.

(c) properties attribute

In the properties

attribute, you can specify the properties for the JPA provider used for setting up a persistence unit. The properties specified here are passed to the JPA provider when EntityManager is obtained from the JPA provider.

274

5. How to Use JPA with Application Server

(d) name attribute

When you use injection, normally you need not specify the name attribute, but if specified, EntityManager is registered in the JNDI Namespace ( java:comp/env

) with the name specified in the name

attribute. An example of using

@PersistenceContext

to inject EntityManager is as follows:

@Stateless public class InventoryManagerBean implements InventoryManager {

@PersistenceContext(unitName="myUnit")

private EntityManager em;

...

}

(2) Method of using the <persistence-context-ref> tag of the DD

When you use a DD to inject EntityManager, you define the following tags in the

<persistence-contextref>

tag of the DD:

(a) <description> tag

In the

<description>

tag, the user can freely code the explanation for the EntityManager references to be defined.

Even if this tag is specified, the specified contents do not affect the operations of the application. You can also omit this tag.

(b) <persistence-context-ref-name> tag

In the

<persistence-context-ref-name>

tag, specify the name with which EntityManager is registered in the JNDI Namespace. The specified name is the relative path from java:comp/env

. The JNDI registration name of

EntityManager is not mandatory, but JPA specifications recommend that the name be set under java:comp/env/ persistence .

(c) <persistence-unit-name> tag

In the

<persistence-unit-name>

tag, you specify the name of the persistence unit defined in persistence.xml

. However, when the persistence unit to be used can be uniquely identified, such as when only one persistence unit is defined in the EJB-JAR and WAR or EAR, you can omit the

<persistence-unit-name> tag. For details on the persistence unit used when the

<persistence-unit-name>

tag is omitted, see

5.11.2

Reference scope of the persistence unit name

.

(d) <persistence-context-type> tag

In the

<persistence-context-type>

tag, you specify the life cycle type of the persistence context. You specify

Transaction

or

Extended

.

• When

Transaction

is specified

The transaction scope persistence context is used and the transaction lifetime and the persistence context lifetime becomes the same.

• When

Extended

is specified

The extended persistence context is used and the Stateful Session Bean lifetime and the persistence context lifetime becomes the same.

Note that the

<persistence-context-ref>

tag in which

Extended

is specified in the

<persistence-context-type>

tag can only be defined for the Stateful Session Bean.

When the <persistence-context-type> tag is omitted, the default value is Transaction

.

(e) <persistence-property> tag

In the

<persistence-property>

tag, you can specify the properties for the JPA provider used for setting up the persistence unit. The properties specified here are passed to the JPA provider when EntityManager factory is obtained from the JPA provider. You can omit this tag.

275

5. How to Use JPA with Application Server

(f) <injection-target> tag

In the <injection-target-class> tag of the <injection-target> tag, you specify the inject destination class. In the

<injection-target-name>

tag of the

<injection-target>

tag, you specify the field name or setter

method name at the inject destination. An example of defining the

<persistence-context-ref>

tag in web.xml

and injecting EntityManager is as follows:

...

<web-app>

...

<servlet>

<display-name>InventoryManagerServlet</display-name>

<servlet-name>InventoryManagerServlet</servlet-name>

<servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>

</servlet>

...

<persistence-context-ref>

<description>

Persistence context for the inventory management application.

</description>

<persistence-context-ref-name>persistence/InventoryAppMgr

</persistence-context-ref-name>

<persistence-unit-name>InventoryManagement</persistence-unit-name>

<persistence-context-type>Transaction</persistence-context-type>

<injection-target>

<injection-target-class>

com.hitachi.InventoryManagerServlet

</injection-target-class>

<injection-target-name>em</injection-target-name>

</injection-target>

</persistence-context-ref>

...

</web-app>

...

5.6.2 Method of looking up EntityManager from the application

The following two more methods are available for using the JNDI to look up EntityManager from the application:

1. Method of adding

@PersistenceContext

in the class for looking up EntityManager and defining the

EntityManager references

2. Method of defining the

<persistence-context-ref>

tag in the DD ( web.xml

) and defining the

EntityManager references

However, you cannot specify the JPA definition using EJB 3.0 ejb-jar.xml

with Application Server. Therefore, if you want to use the JPA in an EJB, use the method specified in point 1.

The following subsections describe the methods:

(1) Method of using @PersistenceContext

When you use

@PersistenceContext

to define the EntityManager references, add

@PersistenceContext in the class that executes lookup.

The attributes that can be specified in

@PersistenceContext

are as follows:

(a) name attribute

In the name attribute, you specify the lookup name with which the application code will look up EntityManager. The specified lookup name is the relative path from java:comp/env

. The lookup name of EntityManager is not mandatory, but the JPA specifications recommend that the name be set up under java:comp/env/ persistence

.

For

@PersistenceContext

the same attributes are used that are used as other attributes in

5.6.1 Method of injecting EntityManager in the application

. Note that only the Stateful Session Bean can look up EntityManager in the

extended scope. Also, for adding multiple

@PersistenceContext

in one class, you add

@PersistenceContexts

in the class and specify the array of

@PersistenceContext

as the value

276

5. How to Use JPA with Application Server attribute. An example of using

@PersistenceContext

to look up EntityManager from

SessionContext

is as follows:

@Stateless

@PersistenceContext(name="persistence/OrderEM") public class MySessionBean implements MyInterface {

@Resource SessionContext ctx;

public void doSomething() {

...

EntityManager em = (EntityManager)ctx.lookup("persistence/OrderEM");

...

}

}

An example of using

@PersistenceContext

to look up EntityManager from

InitialContext

is as follows:

@Stateless

@PersistenceContext(name="persistence/InventoryAppMgr") public class InventoryManagerBean implements InventoryManager {

public void updateInventory(...) {

...

Context initCtx = new InitialContext();

EntityManager em = (EntityManager)

initCtx.lookup("java:comp/env/persistence/InventoryAppMgr");

...

}

}

(2) Method of using the <persistence-context-ref> tag of the DD

When you use the DD to define the EntityManager references, define the following tags in the

<persistencecontext-ref>

tag of the DD:

(a) <persistence-context-ref-name> tag

In the <persistence-context-ref-name> tag, specify the lookup name with which the application code will look up EntityManager. The specified lookup name is the relative path from java:comp/env

. The lookup name of

EntityManager is not mandatory, but the JPA specifications recommend that the name be set under java:comp/env/persistence

.

For the

<persistence-context-ref>

tag, the same tags are used that are used as other tags in

5.6.1 Method of injecting EntityManager in the application

. However, when EntityManager is obtained with the JNDI lookup, you

cannot specify

<injection-target>

. Note that only the Stateful Session Bean can look up EntityManager in the extended scope.

An example of defining <persistence-context-ref> in web.xml

is as follows:

...

<web-app>

...

<servlet>

<display-name>InventoryManagerServlet</display-name>

<servlet-name>InventoryManagerServlet</servlet-name>

<servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>

</servlet>

...

<persistence-context-ref>

<description>

Persistence context for the inventory management application.

</description>

<persistence-context-ref-name>

persistence/InventoryAppMgr

</persistence-context-ref-name>

<persistence-unit-name>InventoryManagement</persistence-unit-name>

<persistence-context-type>Transaction</persistence-context-type>

</persistence-context-ref>

...

</web-app>

...

277

5. How to Use JPA with Application Server

5.6.3 Overriding the @PersistenceContext definition using the DD

If the

<persistence-context-ref>

tag is defined in the DD when

@PersistenceContext

is mentioned in the application, the contents defined in the annotation are overwritten by the contents defined in the DD. In this case, the mapping between the annotations and DD is determined with the mapping between the name

attribute of

@PersistenceContext

and the

<persistence-context-ref-name>

tag present under the

<persistence-context-ref>

tag of the DD. Note that even if the name

attribute is not explicitly specified in

@PersistenceContext

, the name

attribute contains the default value.

The precautions to be taken when the attributes specified in

@PersistenceContext

are overridden with the DD tags are as follows:

(1) <persistence-unit-name> tag and unitName attribute

The

<persistence-unit-name>

tag of the DD overrides the unitName

attribute of

@PersistenceContext . Normally, if you change the persistence unit name, the application stops operating, so take care when you define the DD and annotations.

(2) <persistence-context-type> tag and type attribute

The <persistence-context-type> tag of the DD overrides the type attribute of

@PersistenceContext

. Normally, if you change the life cycle type of the persistence context, the application stops operating, so take care when you define the DD and annotations.

(3) <persistence-property> tag and properties attribute

The properties specified in the

<persistence-property>

tag of the DD are added to the properties specified in the properties

attribute of

@PersistenceContext

. However, if the property name is the same, the property value is overridden.

(4) <injection-target> tag

The injection target cannot be overridden. Note that when the

<injection-target>

tag is coded in the DD, accurately specify the fields and methods in which @PersistenceContext is added.

278

5. How to Use JPA with Application Server

5.7 How to obtain the application-managed

EntityManager

When the application-managed EntityManager is used, the application uses EntityManagerFactory to create

EntityManager. There are two methods by which the application obtains EntityManagerFactory:

Method of using the DI to inject EntityManagerFactory in the application field and setter

method

Method of using the JNDI from the application to look up EntityManagerFactory

The following is a description of the methods:

5.7.1 Method of injecting EntityManagerFactory in the application

The following two more methods are available for injecting EntityManagerFactory in the application fields and setter

method:

1. Method of adding

@PersistenceUnit

in the field or method at the inject destination

2. Method of specifying a definition in the

<persistence-unit-ref>

tag of the DD ( web.xml

)

However, you cannot specify the JPA definition using EJB 3.0 ejb-jar.xml

with Application Server. Therefore, if you want to use the JPA in an EJB, use the method specified in point 1.

The following subsections describe the methods:

(1) Method of using @PersistenceUnit

When you use

@PersistenceUnit

to inject EntityManagerFactory, add

@PersistenceUnit

in the field and setter

method where EntityManagerFactory is to be injected. The attributes that can be specified in

@PersistenceUnit

are as follows:

(a) unitName attribute

In the unitName

attribute, you specify the name of the persistence unit defined in persistence.xml

. However, when the persistence unit to be used can be uniquely identified, such as when only one persistence unit is defined in the EJB-JAR and WAR or EAR, you can omit the unitName

attribute. For details on the persistence unit used when the unitName

attribute is omitted, see

5.11.2 Reference scope of the persistence unit name

.

(b) name attribute

When you use injection, normally you need not specify the name

attribute, but if you specify, EntityManager is registered in the JNDI Namespace ( java:comp/env ) with the name specified in the name attribute. An example of using @PersistenceUnit to inject EntityManagerFactory is as follows:

@Stateless public class InventoryManagerBean implements InventoryManager {

@PersistenceUnit(unitName="myUnit")

private EntityManagerFactory emf;

...

}

(2) Method of using the <persistence-unit-ref> tag of the DD

When you use the DD to inject EntityManagerFactory, define the following tags in the

<persistence-unitref> tag of the DD:

(a) <persistence-unit-ref-name> tag

In the

<persistence-unit-ref-name>

tag, you specify the name with which EntityManagerFactory is registered in the JNDI Namespace. The specified name is the relative path from java:comp/env

.

279

5. How to Use JPA with Application Server

The JNDI registration name of EntityManagerFactory is not mandatory, but the JPA specifications recommend that the name be set under java:comp/env/persistence

.

(b) <description> tag

In the

<description>

tag, you can freely code the EntityManagerFactory references to be defined. Even if this element is specified, the specified contents do not affect the operations of the application. You can also omit this tag.

(c) <persistence-unit-name> tag

In the

<persistence-unit-name>

tag, you specify the name of the persistence unit defined in persistence.xml

. However, when the persistence unit to be used can be uniquely identified, such as when only one persistence unit is defined in the EJB-JAR and WAR or EAR, you can omit the

<persistence-unit-name> tag. For details on the persistence unit used when the

<persistence-unit-name>

tag is omitted, see

5.11.2

Reference scope of the persistence unit name

.

(d) <injection-target> tag

In the

<injection-target-class>

tag of the

<injection-target>

tag, you specify the inject destination class. In the

<injection-target-name>

tag of the

<injection-target>

tag, you specify the field name or setter

method name at the inject destination. An example of defining the

<persistence-unit-ref>

tag in web.xml

and injecting EntityManagerFactory is as follows:

...

<web-app>

...

<servlet>

<display-name>InventoryManagerServlet</display-name>

<servlet-name>InventoryManagerServlet</servlet-name>

<servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>

</servlet>

...

<persistence-unit-ref>

<description>

Persistence unit for the inventory management application.

</description>

<persistence-unit-ref-name>persistence/InventoryAppDB

</persistence-unit-ref-name>

<persistence-unit-name>InventoryManagement</persistence-unit-name>

<injection-target>

<injection-target-class>

com.hitachi.InventoryManagerServlet

</injection-target-class>

<injection-target-name>emf</injection-target-name>

</injection-target>

</persistence-unit-ref>

...

</web-app>

...

5.7.2 Method of looking up EntityManagerFactory from the application

The following two more methods are available for using the JNDI to look up EntityManagerFactory from the application:

1. Method of adding

@PersistenceUnit

in the class for looking up EntityManagerFactory and defining the

EntityManagerFactory references

2. Method of defining the <persistence-unit-ref> tag in the DD ( web.xml

) and defining the

EntityManagerFactory references

However, you cannot specify the JPA definition using EJB 3.0 ejb-jar.xml

with Application Server. Therefore, if you want to use the JPA in an EJB, use the method specified in 1.

The following subsections describe the methods:

280

5. How to Use JPA with Application Server

(1) Method of using @PersistenceUnit

When you use

@PersistenceUnit

to define the EntityManagerFactory references, you add

@PersistenceUnit

in the class that executes lookup. The attributes that can be specified in

@PersistenceUnit

are as follows:

(a) name attribute

In the name

attribute, you specify the lookup name with which the application code will look up

EntityManagerFactory. The specified lookup name is the relative path from java:comp/env . The lookup name of

EntityManagerFactory is not required, but the JPA specifications recommend that the name be set up under java:comp/env/persistence

.

For

@PersistenceUnit

, the same attributes are used that are used as the other attributes in

5.7.1 Method of injecting EntityManagerFactory in the application

. Note that to add multiple

@PersistenceUnit

in one class, you add

@PersistenceUnits

in the class and specify the array of

@PersistenceUnit

as the value

attribute. An example of using

@PersistenceUnit

to look up EntityManagerFactory from

SessionContext

is as follows:

@Stateless

@PersistenceUnit(name="persistence/InventoryAppDB") public class InventoryManagerBean implements InventoryManager {

@Resource SessionContext ctx;

public void updateInventory(...) {

...

EntityManagerFactory emf = (EntityManagerFactory)

ctx.lookup("persistence/InventoryAppDB");

EntityManager em = emf.createEntityManager();

...

}

}

An example of using

@PersistenceUnit

to look up EntityManagerFactory from

InitialContext

is as follows:

@Stateless

@PersistenceUnit(name="persistence/InventoryAppDB") public class InventoryManagerBean implements InventoryManager {

public void updateInventory(...) {

Context initCtx = new InitialContext();

EntityManagerFactory emf = (EntityManagerFactory)

initCtx.lookup("java:comp/env/persistence/InventoryAppDB");

EntityManager em = emf.createEntityManager();

...

}

}

(2) Method of using the <persistence-unit-ref> tag of the DD

When you use the DD to define the EntityManagerFactory references, define the

<persistence-unit-ref>

tag of the DD:

(a) <persistence-unit-ref-name> tag

In the

<persistence-unit-ref-name>

tag, specify the lookup name with which the application code will look up EntityManagerFactory. The specified lookup name is the relative path from java:comp/env

. The lookup name of EntityManagerFactory is not mandatory, but the JPA specifications recommend that the name be set under java:comp/env/persistence

.

For the

<persistence-unit-ref>

tag, the same tags are used that are used as the other tags in

5.7.1 Method of injecting EntityManagerFactory in the application

. However, when EntityManagerFactory is obtained with the JNDI lookup, you cannot specify

<injection-target>

tag. An example of defining

<persistence-unit-ref> in web.xml

is as follows:

...

<web-app>

...

<servlet>

<display-name>InventoryManagerServlet</display-name>

281

5. How to Use JPA with Application Server

<servlet-name>InventoryManagerServlet</servlet-name>

<servlet-class>com.hitachi.InventoryManagerServlet</servlet-class>

</servlet>

...

<persistence-unit-ref>

<description>

Persistence unit for the inventory management application.

</description>

<persistence-unit-ref-name>

persistence/InventoryAppDB

</persistence-unit-ref-name>

<persistence-unit-name>InventoryManagement</persistence-unit-name>

</persistence-unit-ref>

...

</web-app>

...

5.7.3 Overriding the @PersistenceUnit definition using the DD

If the

<persistence-unit-ref>

tag is defined in the DD when

@PersistenceUnit

is mentioned in the application, the contents defined in the annotation are overwritten by the contents defined in the DD. In this case, the mapping between the annotations and DD is determined with the mapping between the name attribute of

@PersistenceUnit and the <persistence-unit-ref-name> tag present under the <persistenceunit-ref>

tag of the DD. Note that even if the name

attribute is not explicitly specified in

@PersistenceUnit

, the name

attribute contains the default value.

The precautions to be taken when the attributes specified in

@PersistenceUnit

are overridden with the DD tags are as follows:

(1) <persistence-unit-name> and unitName attribute

The

<persistence-unit-name>

tag of the DD overrides the unitName

attribute of

@PersistenceUnit

.

Normally, if you change the persistence unit name, the application stops operating, so take care when you make changes.

(2) <injection-target> tag

The injection target cannot be overridden with the DD. Note that when the

<injection-target>

tag is coded in the DD, you must accurately specify the fields and methods in which @PersistenceContext is added.

282

5. How to Use JPA with Application Server

5.8 Definitions in persistence.xml

You define the persistence unit information by using the

<persistence-unit>

tag of persistence.xml

.

This section describes the attributes of the

<persistence-unit>

tag and the tags specified under the

<persistence-unit>

tag.

Note that the space and linefeed characters added at the beginning and end of values specified in the attributes of the

<persistence-unit>

tag and in the tags specified under the

<persistence-unit>

tag are ignored.

For details on the tags in persistence.xml

, see

6.2 persistence.xml

in the

uCosminexus Application Server

Definition Reference Guide

.

5.8.1 Attributes specified in the <persistence-unit> tag

In the

<persistence-unit>

tag, you specify the name

attribute and transaction-type

attribute.

(1) name attribute

You specify the name of the persistence unit to be defined. The name specified here is referenced from the unitName

attribute of

@PersistenceUnit

or

@PersistenceContext

in the case of annotations. Also, in the case of the DD, the name specified here is referenced from the

<persistence-unit-name>

tag under the

<persistence-context-ref>

tag or under the

<persistence-unit-ref>

tag.

You cannot omit the name

attribute. Also, when the JPA is used with Application Server, you cannot specify null in the name

attribute. Specify a string of at least 1 character.

(2) transaction-type attribute

In the persistence unit to be defined, you specify whether the JTA will control the transaction or whether the application will control the transaction by using javax.persistence.EntityTransaction

.

• When the transaction is controlled by the JTA

Specify

JTA

in the transaction-type

attribute. When you specify

JTA

, you must also specify the

<jtadata-source>

tag at the same time.

• When the application controls the transaction by using EntityTransaction

Specify

RESOURCE_LOCAL

in the transaction-type

attribute. When you specify

RESOURCE_LOCAL

, you must also specify the <non-jta-data-source> tag at the same time.

Note that if the transaction-type

attribute is omitted, the default value is

JTA

.

5.8.2 Tags specified under the <persistence-unit> tag

The tags listed in the following table are specified under the <persistence-unit> tag.

Table 5

7: Tags specified under the <persistence-unit> tag

Specified tags Settings

<description> tag

<provider> tag

<jta-data-source> tag

<non-jta-data-source>

tag

<mapping-file>

tag

<jar-file>

tag

Describes the persistence unit.

Specifies the JPA provider used.

Specifies the JTA data source or non-JTA data source used in the

JPA provider.

Specifies the O/R mapping file used.

Specifies the name of the JAR file containing the entity

class, embeddable

class, and mappedsuper

class.

283

5. How to Use JPA with Application Server

1

2

3

<class> tag

Specified tags

<exclude-unlisted-classes>

tag

<properties>

tag

The following points describe respective tags:

Settings

Specifies the entity class, embeddable class, and mappedsuper

class.

Specifies whether to handle the class as a Persistence class.

Specifies the JPA provider-specific properties.

(1) <description> tag

The user can freely code the explanation about the persistence unit. The contents specified here do not affect the operations of the application. Note that you can omit this tag.

(2) <provider> tag

Specifies the JPA provider used in the persistence unit. You specify the implementation class name of the javax.persistence.spi.PersistenceProvider

interface of the JPA provider with the fully qualified name containing the package name. You can omit this tag.

If this tag is omitted, the default JPA provider specified in the Easy Setup definition file is used. Also, when this tag is omitted and the default JPA provider is not specified in the Easy Setup definition file, Cosminexus JPA provider is used as the JPA provider.

If the application depends on a specific JPA provider functionality and behavior, make sure to specify the

<provider>

tag.

Tip

To specify the default JPA provider in the Easy Setup definition file, specify ejbserver.jpa.defaultProviderClassName

in the

<param-name>

tag of the logical J2EE server and specify the name of the default JPA provider class in the

<param-value>

tag.

Note that if the ejbserver.jpa.overrideProvider

parameter is specified in the

<param-name>

tag of the logical J2EE server in the Easy Setup definition file, the name of the JPA provider class specified in the <param-value> tag of the ejbserver.jpa.overrideProvider

parameter is used on a higher priority than the value specified in the

<provider>

tag and the ejbserver.jpa.defaultProviderClassName

parameter.

For details on the parameters to be specified in the Easy Setup definition file, see

4.6.2 Contents specified in the Easy Setup definition file

in the

uCosminexus Application Server Definition Reference Guide

.

The following table describes the priority for determining the JPA provider used in the persistence unit.

Table 5

8: Priority for determining the JPA provider used in the persistence unit

Priority JPA provider to be used

Value specified in ejbserver.jpa.overrideProvider

property of the Easy Setup definition file

Value specified in the

<provider>

tag of persistence.xml

Cosminexus JPA provider

(The JPA provider can also be changed by using the ejbserver.jpa.defaultProviderClassName

parameter of the Easy Setup definition file)

(3) <jta-data-source> tag and <non-jta-data-source> tag

Specifies the JTA data source or non-JTA data source used by the JPA provider. The value specified here is productdependent as per the JPA specifications, but define the data source references with Application Server as follows:

• When referencing a resource adapter conforming to Connector 1.0

Specify the '

Display-name-of-resource-adapter

' or '

Optional-name-of-resource-adapter

'.

• When referencing a resource adapter conforming to Connector 1.5

284

5. How to Use JPA with Application Server

1

2

3

Specify the '

Display-name-of-resource-adapter

!

Connection-definition-identifier

' or '

Optional-name-of-resourceadapter

'.

The specified value is interpreted as '

display-name-of-resource-adapter

' or '

display-name-of-resource-adapter

!

Connection-definition-identifier

' and the relevant resource adapter is searched. If the relevant resource adapter does not exist, the specified value is interpreted as '

Optional-name-of-resource-adapter

' and the relevant resource adapter is searched.

The resource adapter to be referenced must be deployed as a J2EE resource adapter (method of deploying the resource adapter as a standalone module). Start the resource adapter before starting the application containing the persistence unit.

You can omit the

<jta-data-source>

tag and

<non-jta-data-source>

tag. If the tags are omitted, the value specified in the ejbserver.jpa.defaultJtaDsName

parameter or ejbserver.jpa.defaultNonJtaDsName

parameter of the Easy Setup definition file is used. However, these properties do not have default values.

If a value is specified in the ejbserver.jpa.overrideJtaDsName

parameter or ejbserver.jpa.overrideNonJtaDsName

parameter, this value is used on higher priority than the value specified in the

<jta-data-source>

tag and

<non-jta-data-source>

tag and the value specified in the ejbserver.jpa.defaultJtaDsName

parameter and ejbserver.jpa.defaultNonJtaDsName

parameter.

You must specify LocalTransaction or XATransaction in the transaction support level of the resource adapter specified in the

<jta-data-source>

tag. You must also specify

NoTransaction

in the transaction support level of the resource adapter specified in

<non-jta-data-source>

.

The following table lists the priority for determining the JTA data source and non-JTA data source used in the persistence unit.

Table 5

9: Priority for determining the JTA data source and non-JTA data source used in the persistence unit

Priority JPA provider to be used

Value specified in the ejbserver.jpa.overrideJtaDsName

property or ejbserver.jpa.overrideNonJtaDsName

property of the Easy Setup definition file

Value specified in the

<jta-data-source>

or

<non-jta-data-source>

element of persistence.xml

Value specified in the ejbserver.jpa.defaultJtaDsName

property or ejbserver.jpa.defaultNonJtaDsName

property of the Easy Setup definition file

!

Important note

If a resource adapter display name containing characters other than one-byte alphanumeric characters and underscore (_) is specified in the <jta-data-source> tag or <non-jta-data-source> tag of persistence.xml

, replace that character with an underscore (_). However, if the replaced display name is duplicated with another resource adapter display name or optional name, note that the persistence unit might perform operations using an unintended data source.

(4) <mapping-file>, <jar-file>, <class>, and <exclude-unlisted-classes> tag

The following two methods are available for specifying the entity class, embeddable class, mapped superclass included in the persistence unit:

1. Method specified explicitly by using the O/R mapping file and the

<class>

tag

2. Method that is not specified explicitly and uses auto-search by JPA provider

A description of method 1 is as follows:

(a) Specifying the classes using the O/R mapping file

If an XML file named orm.xml

is allocated under

META-INF

at the persistence unit root or under

META-INF

in another JAR file referenced with the

<jar-file>

tag from the persistence unit, the file is automatically handled as

285

5. How to Use JPA with Application Server an O/R mapping file even if the file is not specified in the

<mapping-file>

tag. Furthermore, if the name of the

XML file that can be loaded on the class path is specified in the

<mapping-file>

tag, that XML file is also handled as an O/R mapping file. If one persistence unit contains multiple O/R mapping files, the mapping information is read from all the O/R mapping files. However, the operations for duplicate mapping defined between multiple O/R mapping files are not provided.

(b) Specifying the JAR file that searches the persistence class

In the

<jar-file>

tag, you can specify the JAR file containing the persistence class and O/R mapping file. From the JAR file specified in the

<jar-file>

tag, the class in which

@Entity

,

@Embeddable

, and

@MappedSuperclass

are added is searched and the mapping information is obtained automatically. If

META-

INF/orm.xml

exists in the specified JAR file, the mapping information is also obtained from orm.xml

. Note that you can also use the <jar-file> tag and the <mapping-file> tag together.

The JAR files that can be specified in the

<jar-file>

tag must be included in the class path. The following JAR files can be specified:

JAR file placed in the EAR root

JAR file placed in the library directory of the EAR file

EJB-JAR

JAR file placed in

WEB-INF/lib

in the WAR

However, you cannot specify the JAR file placed in

WEB-INF/lib

in the WAR in the

<jar-file>

tag of the persistence unit defined in the EAR level or EJB-JAR level. This is because the JAR file placed in

WEB-INF/lib

in the WAR is loaded using the WEB application class loader and, therefore, can only be referenced from the components in the WAR.

Also, you can only specify the JAR file included in the same WAR from the

<jar-file>

tag of the persistence unit defined in the WAR level. This is because the classes included in the JAR file allocated to a location other than the same WAR might be loaded using the class loader before the deployment of the persistence unit defined in the WAR level. In such cases, the conversion of the byte code by the JPA provider might not be performed correctly.

In the

<jar-file>

tag, specify the relative path from the persistence unit root to the JAR file. The following is an example of specification:

Example 1

The specification of the relative path shown in the following figure is described below:

286

The EAR lib contains myEntities.jar

that stores the entity class.

Specify myEntities.jar

in the <jar-file> tag of META-INF/persistence.xml

of EJB-JAR placed in the EAR root.

In this figure, the persistence unit root becomes EJB-JAR, so specify the relative path from EJB-JAR to myEntities.jar

. The relative path is lib/myEntities.jar

. Therefore, specify lib/ myEntities.jar

in the

<jar-file>

tag.

Example 2

The specification of the relative path shown in the following figure is described below:

5. How to Use JPA with Application Server

The EAR root contains myEntities.jar

that stores the entity class.

Specify myEntities.jar

in the

<jar-file>

tag of

META-INF/persistence.xml

of lib/ myPersistenceUnit.jar

in EAR.

In this figure, the persistence unit root becomes myPersistenceUnit.jar

, so specify the relative path from myPersistenceUnit.jar

to myEntities.jar

. The relative path is

../myEntities.jar

. Therefore, specify

../myEntities.jar

in the

<jar-file>

tag.

Example 3

The specification of the relative path shown in the following figure is described below:

WEB-INF/lib of the WAR contains myEntities.jar

that stores the entity class.

Specify myEntities.jar

in the <jar-file> tag of WEB-INF/classes/META-INF/ persistence.xml

of the WAR.

In this figure, the persistence unit root becomes WEB-INF/classes of the WAR, so specify the relative path from

WEB-INF/classes

to myEntities.jar

. The relative path is

../lib/myEntities.jar

.

Therefore, specify

../lib/myEntities.jar

in the

<jar-file>

tag.

(c) Specifying the persistence class list explicitly

If you use the

<class>

tag, you can explicitly specify the persistence class list. The mapping information is obtained from the annotation added in the specified class. Note that you can also use the

<class>

tag in combination with the

<mapping-file> tag and <jar-file> tag.

(d) Allocating the persistence class with the added annotation to the persistence unit root

From the persistence unit root, the persistence class in which

@Entity

,

@Embeddable

, and

@MappedSuperclass

are added is automatically searched. The mapping information is obtained from the annotation added in the class. If you do not want to add the annotation-added class, which is allocated to the persistence unit root, in the persistence unit, you must specify the <exclude-unlisted-classes> tag beforehand.

(5) <properties> tag

You can specify the vendor-specific properties of the JPA provider. If you specify properties that cannot be understood by the JPA provider, the properties are ignored. Note that you cannot specify properties beginning with javax.persistence

in

<properties>

.

If you specify properties with property names beginning with the prefix ejbserver.jpa.emfprop.

as the system properties, the properties with the prefix removed are added in the persistence unit properties.

287

5. How to Use JPA with Application Server

5.9 Allocating persistence.xml

You allocate persistence.xml

in the EJB-JAR, WAR, or EAR. Make sure that you place persistence.xml

under

META-INF

. The path with persistence.xml

under

META-INF

is called the

persistence unit root

.

The locations in which persistence.xml

can be allocated are as follows:

META-INF/persistence.xml

of EJB-JAR

WEB-INF/classes/META-INF/persistence.xml

of the WAR

META-INF/persistence.xml

in the jar

file placed under

WEB-INF/lib

of the WAR

META-INF/persistence.xml

in the jar

file placed in the EAR root directory

META-INF/persistence.xml

in the jar

file placed in the EAR library directory

You can define multiple persistence units in one persistence.xml

. You must name the persistence unit.

However, you cannot define multiple persistence units with duplicated names in one EJB-JAR, WAR, or EAR.

The class managed with the persistence unit defined in EAR is loaded using the application class loader and can be referenced from all the components in the application.

Furthermore, when the same entity class is referenced from the components in different EJB-JAR and WAR, the referenced class is the same unique class even if the persistence units are different.

288

5. How to Use JPA with Application Server

5.10 JPA interfaces

This section introduces the JPA interfaces and describes the javax.persistence.EntityManager

interface and javax.persistence.EntityManagerFactory

interface.

5.10.1 javax.persistence.EntityManager interface

This subsection describes the interface definition and the notes on the javax.persistence.EntityManager

interface.

(1) Definition of the interface

package javax.persistence;

/**

* Interface for operating the persistence context.

*

* EntityManager instance is associated with the persistence context.

* The persistence context is a set of entity instances and

* the entity instance is unique for each

* perpetuated entity.

* The entity instances and their life cycles

* are managed in the persistence context.

* The EntityManager interface defines the methods for operating the * persistence context and is used for

* creating or deleting the perpetuated entity instances,

* searching the entity based on the primary key, and for executing

* the entity query.

*

* Define the set of entities that can be managed by EntityManager

* using the persistence unit.

* The persistence unit defines the group of entity classes used

* by the application and also defines the mapping between the entity

* classes and the database.

*/ public interface EntityManager {

/**

* The instance is set to managed and is perpetuated.

* @param entity instance of the persistent entity

* @throws EntityExistsException When the entity already exists

* (When persist method is invoked, EntityExistsException is thrown

* or EntityExistsException or another PersistenceException

* is thrown during flush or commit)

* @throws IllegalArgumentException When the argument is not an entity

* @throws TransactionRequiredException When the container-managed

* EntityManager specifying PersistenceContextType.TRANSACTION

* is invoked when the transaction does not exist

*/

public void persist(Object entity) ;

/**

* The entity status is merged with the current persistence context

* @param entity Entity

* @return instance where the status is merged with the persistence context

* @throws IllegalArgumentException When the instance is not an entity

* or is a removed entity

* @throws TransactionRequiredException When the container-managed

* EntityManager specifying PersistenceContextType.TRANSACTION

* is invoked when the transaction does not exist.

*/

public <T> T merge(T entity) ;

/**

* entity instance is deleted.

* @param entity Entity

* @throws IllegalArgumentException Instance is not an entity

* or is a detached entity

289

5. How to Use JPA with Application Server

* @throws TransactionRequiredException When the container-managed

* EntityManager specifying PersistenceContextType.TRANSACTION

* is invoked when the transaction does not exist.

*/

public void remove(Object entity) ;

/**

* Searches the primary key.

* @param entityClass Entity class

* @param primaryKey Primary key

* @return Instance of the searched entity

* null when the entity does not exist

* @throws IllegalArgumentException When the entityClass argument

* is not an entity type or if the primaryKey argument is not the

* valid type as the primary key of that entity

*/

public <T> T find(Class<T> entityClass, Object primaryKey) ;

/**

* The status obtains the delayed fetch instance.

* When the requested entity does not exist in the database,

* When the instance status is accessed for the first time

* EntityNotFoundException is thrown.

* (when getReference is invoked, the JPA provider is also allowed

* to throw EntityNotFoundException)

* If the application does not access the instance while

* Entity Manager is open, do not expect that the instance status

* can be accessed during detach

* @param entityClass Entity class

* @param primaryKey Primary key

* @return Instance of the searched entity

* @throws IllegalArgumentException When the entityClass argument

* is not an entity type or the primaryKey argument is not a

* valid type as the primary key of that entity

* @throws EntityNotFoundException When the entity status cannot

* be accessed

*/

public <T> T getReference(Class<T> entityClass, Object primaryKey) ;

/**

* The persistence context status is flushed in the database.

* @throws TransactionRequiredException When the transaction does

* not exist

* @throws PersistenceException When flush fails

*/

public void flush() ;

/**

* Specifies the flush mode applied to all the objects

* included in the persistence context.

* @param flushMode Flush mode

*/

public void setFlushMode(FlushModeType flushMode) ;

/**

* Obtains the flush mode applied to all the objects

* included in the persistence context.

* @return flushMode Flush mode

*/

public FlushModeType getFlushMode() ;

/**

* Sets the lock mode of the entity objects

* included in the persistence context.

* @param entity Entity

* @param lockMode Lock mode

* @throws PersistenceException When an unsupported

* lock invocation is performed

* @throws IllegalArgumentException When the instance is not an entity

* or is a detached entity

* @throws TransactionRequiredException When the transaction

* does not exist

*/

public void lock(Object entity, LockModeType lockMode) ;

290

5. How to Use JPA with Application Server

/**

* Instance status is refreshed to the database status.

* If the instance status is changed, the status is

* overwritten by the database status.

* @param entity Entity

* @throws IllegalArgumentException When the argument is not an entity

* or does not have the managed status

* @throws TransactionRequiredException When the container-managed

* EntityManager specifying PersistenceContextType.TRANSACTION

* is invoked when the transaction does not exist

* @throws EntityNotFoundException When the entity already

* does not exist in the database

*/

public void refresh(Object entity) ;

/**

* Clears the persistence context and all the managed entities

* are detached.

* If the entity has changes that were not flushed in the database

* the entity is not perpetuated.

*/

public void clear() ;

/**

* Checks if the instance is included in the current

* persistence context.

* @param entity Entity

* @return true if included

* @throws IllegalArgumentException When the argument is not an entity

*/

public boolean contains(Object entity) ;

/**

* Creates a Query instance for executing

* JPQL(Java Persistence Query language) statement

* @param qlString Java Persistence Query statement

* @return New Query instance

* @throws IllegalArgumentException When the query statement is not valid

*/

public Query createQuery(String qlString) ;

/**

* Creates a Query instance for executing the named query

* (JPQL or native SQL).

* @param name Name of the query defined in the Meta data

* @return New Query instance

* @throws IllegalArgumentException If the query with the specified

* name is not defined.

*/

public Query createNamedQuery(String name) ;

/**

* Creates a Query instance for executing the native SQL statement

* (update statement and delete statement)

* @param sqlString Native SQL statement

* @return New Query instance

*/

public Query createNativeQuery(String sqlString) ;

/**

* Creates a Query instance for executing the native SQL query.

* @param sqlString Native SQL statement

* @param resultClass Class of the instance that forms the

* return value

* @return New Query instance

*/

public Query createNativeQuery(String sqlString, Class result-

Class) ;

/**

* Creates a Query instance for executing the native SQL query.

* @param sqlString Native SQL statement

* @param resultSetMapping Result set mapping name

291

5. How to Use JPA with Application Server

* @return New Query instance

*/

public Query createNativeQuery(String sqlString, String result-

SetMapping) ;

/**

* Reports EntityManager that the JTA transaction is active.

* This method is invoked by the application

* to associate the application-managed JTA entity manager that was

* created outside the transaction scope

* with the current JTA transaction.

* @throws TransactionRequiredException When the transaction

* does not exist

*/

public void joinTransaction() ;

/**

* Returned when the lower provider objects exist.

* The return value of this method depends on the implementation,

* but when the container-managed EntityManager is used in

* Cosminexus Component Container,

* the EntityManager object of the JPA provider is returned.

* @return EntityManager object of the JPA provider

* /

public Object getDelegate() ;

/**

* Closes the application-managed EntityManager.

* After the close method is invoked, all the methods other than

* getTransaction and isOpen (returning false) of the Query object

* obtained from EntityManager instance and EntityManager

* throw IllegalStateException.

* If this method is invoked when EntityManager

* is associated with an active transaction, the persistence context

* continues to exist until the transaction is concluded.

* @throws IllegalStateException For the container-managed

* EntityManager

*/

public void close() ;

/**

* Returns whether EntityManager is open.

* @return Returns true until EntityManager closes.

*/

public boolean isOpen() ;

/**

* Returns the resource level transaction object.

* Used by the EntityTransaction instance to start and commit

* multiple transactions serially.

* @return EntityTransaction instance

* @throws IllegalStateException When this method is invoked with

* the JTA entity manager

*/

public EntityTransaction getTransaction() ;

}

(2) Notes

When the transaction scope persistence context is used, the persist

, merge

, remove

, and refresh

methods must be invoked in the transaction context. If the transaction context does not exist, javax.persistence.TransactionRequiredException

is thrown.

The find and getReference methods can also be invoked outside the transaction context. When the transaction scope persistence context is used, the resulting entity has a detached status. When the extended persistence context is used, the resulting entity has a managed status.

The

Query

and

EntityTransaction

objects obtained from EntityManager can be used while EntityManager is open.

292

5. How to Use JPA with Application Server

If the argument of the createQuery

method is not a valid JPQL (Java Persistence Query Language),

IllegalArgumentException

is thrown or the execution of the query fails. If the native query is incorrect and if the definition of the result set is not compatible with the query result,

PersistenceException

is thrown when the query is executed and the execution of the query fails. When possible,

PersistenceException

wraps the database exceptions.

If a runtime exception is thrown in the method of the

EntityManager

interface, the transaction is rolled back.

The close

, isOpen

, joinTransaction

, and getTransaction

methods are used for managing the application-managed EntityManager.

With the EJB specifications, the following methods can invoke the EntityManager methods in the Stateless

Session Bean:

Business method of the business interface or component interface

Business method

Interceptor method

Timeout callback method

The EntityManager methods cannot be invoked with the constructor, the setter

method (including setSessionContext

method) of the DI, and the life cycle callback method (

PostConstruct

and

PreDestroy ). If the EntityManager methods are invoked in the unpermitted locations, the KDJE56538-E message is displayed and java.lang.IllegalStateException

is thrown.

With the EJB specifications, the following methods can invoke the EntityManager methods in the Stateful Session

Bean:

Life cycle callback method (

Business method of the business interface or component interface

Business method

Interceptor method afterBegin and

PostConstruct beforeCompletion

and

PreDestroy

methods of

)

SessionSynchronization

The EntityManager methods cannot be invoked with the constructor, the setter method of the DI, and afterCompletion

method of

SessionSynchronization

. If the EntityManager methods are invoked in unpermitted locations, the KDJE56538-E message is displayed and java.lang.IllegalStateException

is thrown.

Note the following points as well when you use the JPA with Application Server:

EntityManager that the application obtains by using inject, JNDI lookup, and EntityManagerFactory becomes the proxy class of EntityManager provided by Application Server and not the EntityManager object provided by the JPA provider. If you use the getDelegate()

method of this proxy class, you can obtain the

EntityManager

object provided by the JPA provider. However, when the container-managed EntityManager is used, the container manages the EntityManager life cycle, so do not invoke the close()

method of the

EntityManager

object obtained by using the getDelegate()

method, from the application.

If the getDelegate()

method of EntityManager is invoked when the transaction scope persistence context is used and when transaction does not exist, the container cannot close the returned EntityManager. In this case, you must invoke EntityManager.close() with the application.

5.10.2 javax.persistence.EntityManagerFactory interface

This subsection describes the interface definition and the notes on the javax.persistence.EntityManagerFactory

interface.

(1) Definition of the interface

package javax.persistence;

/**

* The EntityManagerFactory interface is used

293

5. How to Use JPA with Application Server

* to obtain the application-managed EntityManager by the application.

* When the application ends the use of EntityManagerFactory,

* the application must close EntityManagerFactory.

* After EntityManagerFactory is closed,

* all EntityManagers created from EntityManagerFactory are

* treated as closed.

*/ public interface EntityManagerFactory {

/**

* Creates a new EntityManager.

* Whenever this method is invoked, a new EntityManager instance

* is returned.

* The isOpen method of EntityManager returned by this method returns

* true.

* @return New EntityManager

*/

public EntityManager createEntityManager() ;

/**

* A new EntityManager is created by using the specified property

* map.

* Whenever this method is invoked, a new EntityManager instance

* is returned.

* The isOpen method of EntityManager returned by this method returns

* true.

* @param map Map storing the EntityManager properties

* @return New EntityManager

*/

public EntityManager createEntityManager(Map map) ;

/**

* Closes factory and releases all the resources

* stored in factory.

* After factory is closed, if method other than isOpen is invoked,

* IllegalStateException is thrown. The isOpen method returns

* false.

* If EntityManagerFactory is closed, all EntityManagers created

* from factory are also treated as closed.

*/

public void close() ;

/**

* Returns whether factory is open.

* @return True until factory is closed

}

*/

public boolean isOpen() ;

(2) Notes

You can include vendor-specific properties of the JPA provider in the map passed to createEntityManager

.

The properties that cannot be recognized by the JPA provider are ignored.

With the EJB specifications, the following methods can invoke the EntityManagerFactory methods in the Stateless

Session Bean:

Life cycle callback method (

Business method

Interceptor method

Timeout callback method

PostConstruct

and

PreDestroy

Business method of the business interface or component interface

)

The EntityManagerFactory methods cannot be invoked with the constructor and the setter

method (including the setSessionContext

method) of the DI.

With the EJB specifications, the following methods can invoke the EntityManagerFactory methods in the Stateful

Session Bean:

Life cycle callback method (

PostConstruct

and

PreDestroy

)

294

5. How to Use JPA with Application Server

Business method of business interface or component interface

Business method

Interceptor method

The afterBegin and beforeCompletion methods of SessionSynchronization .

The EntityManagerFactory methods cannot be invoked with the constructor, the setter

method of the dependency injection, and the afterCompletion method of SessionSynchronization .

295

5. How to Use JPA with Application Server

5.11 Notes on setting up applications

This section describes the notes on setting up the applications running on Application Server and using the JPA.

5.11.1 Notes on allocating the entity classes

With Application Server, package the entity classes in the EARs, EJB-JARs, or WARs, at the locations decided in the

JPA specifications. Do not add the entity classes in the system class path.

When an entity class is loaded with the application class loader or the Web application class loader, the byte code of the class is converted using the JPA provider in order to implement operations such as Lazy fetch. If the entity class is included in the system class path, the byte code conversion does not work because the entity class is loaded with the system class loader. Therefore, the JPA provider does not operate properly.

5.11.2 Reference scope of the persistence unit name

The components, such as the EJBs and servlets, included in the application, reference the used persistence unit by specifying the persistence unit name in the unitName attribute of @PersistenceUnit and

@PersistenceContex t and in the

<persistence-unit-name>

tag under the

<persistencecontext-ref>

tag or under the

<persistence-unit-ref>

tag defined in the DD. However, the persistence unit scope that can be referenced from each component is as follows:

The persistence units defined in the EJB-JARs or WARs can be referenced from the components included in the

EJB-JARs or WARs.

The persistence unit defined in the EAR file can be referenced from all the components included in the EAR file.

If the name of the persistence unit defined in the EAR file and the name of the persistence unit defined in the EJB-

JARs or WARs are duplicated, from the components in the EJB-JAR or WAR, the persistence units defined with a narrower scope are given priority. For example, if persistence units with the same name are defined in the EAR and

WAR files, from the components included in the WAR file, the persistence unit defined in the WAR file is visible on priority. The persistence unit existing in the EAR file is not visible.

(1) Persistence unit used when the persistence unit name is omitted

If you omit the persistence unit name referenced by the components when the JPA is used with Application Server, the persistence unit used is determined with the following rules:

If only one persistence unit is defined in the EJB-JAR or WAR that contains components, that persistence unit is used.

If persistence unit is not defined in the EJB-JAR or WAR that contains components and only one persistence unit is defined in the EAR, the persistence unit in the EAR is used.

Note that if the following conditions are fulfilled, one persistence unit cannot be identified, so the persistence unit name cannot be omitted:

When two or more persistence units are defined in the EJB-JAR or WAR that contains components

If persistence unit is not defined in the EJB-JAR or WAR that contains components and two or more persistence units are defined in the EAR

(2) Explicitly referencing the EAR-level persistence unit using '#' syntax

If the name of the persistence unit defined in the EAR and the name of the persistence unit defined in the EJB-JAR or

WAR are duplicated, from the components in the EJB-JAR or WAR, the persistence units defined with a narrower scope are visible on priority. However, by using '#' syntax in the reference name of the persistence unit, you can explicitly reference the persistence unit defined in the EAR. When you use '#' syntax, specify the persistence unit name as follows:

296

5. How to Use JPA with Application Server

Relative-path-from-the-EJB-JAR-or-WAR-containing-components-to-the-persistence-unit-root

#

Name-of-thepersistence-unit

For example, when the persistence unit myPersistenceUnit

included in lib/persistenceUnitRoot.jar

of the EAR file is referenced from the EJB included in ejbs/myEjbs.jar

of the EAR file, the referenced persistence unit name is

../lib/persistenceUnitRoot.jar#myPersistenceUnit

.

5.11.3 Items checked when the application is deployed

The following items are checked when an application using the JPA is deployed on the J2EE server:

Checking the persistence unit definitions

Checking the EntityManager and EntityManagerFactory references

The following is a description of the checks:

(1) Checking of the persistence unit definition

The following points describe the contents checked in the persistence unit definition:

(a) Validation of persistence.xml

Validates whether persistence.xml

included in the application is in accordance with the persistence_1_0.xsd

schema. If an error is found during the validation, the error message KDJE56526-E is output and the deployment is cancelled.

(b) Checking of the persistence unit name

Checks whether the persistence unit name is null. If the persistence unit name is null, the error message KDJE56505-E is output and the deployment is cancelled.

Also, checks whether persistence units with duplicated names are defined in the application EAR files or in one EJB-

JAR or WAR. If persistence units with duplicated names are defined, a warning message KDJE56500-W is output and the deployment continues. Note that in this case, only one persistence unit is actually deployed.

(c) Checking whether the data source referenced by the persistence unit exists

The contents checked differ depending on the transaction type of the persistence unit.

• When the transaction type of the persistence unit is the JTA

The following table lists the contents checked and the operations to be performed when an error occurs during the check.

Table 5

10: Checked contents and operations to be performed when an error occurs during the check

(for the JTA transaction type)

Checked contents Operations when an error occurs during the check

The JTA data source (the data source specified in the

<jtadata-source>

tag of persistence.xml

or the default value specified in the system properties) used in the persistence unit is specified.

The resource adapter that provides the JTA data source exists.

The resource adapter that provides the JTA data source is running.

The transaction support level of the resource adapter is

LocalTransaction or XATransaction .

The connection factory interface of the resource adapter is javax.sql.DataSource

.

The error message KDJE56527-E is output and the deployment is cancelled.

The error message KDJE56529-E is output and the deployment is cancelled.

The error message KDJE56531-E is output and the deployment is cancelled.

The error message KDJE56533-E is output and the deployment is cancelled.

• When the transaction type of the persistence unit is RESOURCE_LOCAL

297

5. How to Use JPA with Application Server

The following table lists the contents checked and the operations to be performed when an error occurs during the check.

Table 5

11: Checked contents and operations to be performed when an error occurs during the check

(for the RESOURCE_LOCAL transaction type)

Checked contents Operations when an error occurs during the check

The error message KDJE56528-E is output and the deployment is cancelled.

The non-JTA data source (the data source specified in the

<nonjta-data-source> tag of persistence.xml

or the default value specified in the system properties) used in the persistence unit is specified.

The resource adapter that provides the non-JTA data source exists.

The resource adapter that provides the non-JTA data source is running.

The transaction support level of the resource adapter is

NoTransaction

.

The connection factory interface of the resource adapter is javax.sql.DataSource

.

The error message KDJE56530-E is output and the deployment is cancelled.

The error message KDJE56532-E is output and the deployment is cancelled.

The error message KDJE56533-E is output and the deployment is cancelled.

(d) Checking the provider class specified in the persistence unit

Checks whether the JPA provider class (class specified in the

<provider>

tag of persistence.xml

) used by the persistence unit can be loaded from the application. If the loading of the class fails, the error message KDJE56503-

E is output and the deployment is cancelled.

(e) Checking whether the JAR file referenced by the persistence unit exists

Checks whether the JAR file (JAR file specified in the

<jar-file>

tag of persistence.xml

) referenced by the persistence unit exists. If the JAR file does not exist, the error message KDJE56506-E is output and the deployment is cancelled.

(f) Checking the contents defined in the persistence unit using the JPA provider

The JPA provider generates the persistence unit from the contents of persistence.xml

parsed by the JPA container. If the persistence unit definition has a problem and if the JPA provider returns an error, the error message

(KDJE56539-E) is displayed and the deployment is cancelled.

(2) Checking the EntityManager and EntityManagerFactory references

The following points describe the contents checked in the EntityManager and EntityManagerFactory references:

(a) Checking the existence of the persistence unit

In the EntityManager and EntityManagerFactory references defined in the EJB and Web components, check whether the specified persistence unit name is an actually referable persistence unit name. Also, if the persistence unit name is omitted, check whether the persistence unit to be used can be identified. If an error is found in this check, the error message KDJE56501-E is output and the deployment is cancelled.

(b) Checking the transaction type for the container-managed EntityManager

Check whether the transaction type of the persistence unit is the JTA when the container-managed EntityManager is used. If an error occurs in this check, the error message KDJE56534-E is output and the deployment is cancelled.

(c) Checking if the extended persistence context is used from outside the Stateful Session Bean

When

EXTENDED

is specified as the persistence context type with the EntityManager references, check whether the location where the references are defined is the Stateful Session Bean. If the references are defined in a location other than the Stateful Session Beans, the error message KDJE56535-E is output and the deployment is cancelled.

298

5. How to Use JPA with Application Server

5.11.4 Notes on using the JPA with Application Server

The EntityManager type that the application can obtain is the proxy class of EntityManager provided by Application

Server and not the EntityManager object provided by the JPA provider.

The EntityManager object can be obtained by using injection, JNDI lookup, or EntityManagerFactory.

Note that to use injection for obtaining EntityManager, you set up javax.persistence.EntityManager

as the field or method argument type that injects EntityManager.

Also, you cannot cast EntityManager obtained with injection, JNDI lookup, or EntityManagerFactory in the

EntityManager implementation class of the JPA provider.

If you need to obtain the

EntityManager

object of the JPA provider, use the getDelegate

method of the

EntityManager proxy object obtained with injection, JNDI lookup, or EntityManagerFactory.

5.11.5 Notes when the Cosminexus JPA functionality is not used

With the Cosminexus JPA functionality, when persistence.xml

is included in an application, persistence.xml

is read by default regardless of whether the Cosminexus JPA functionality is used. If persistence.xml

cannot be interpreted with Application Server, the application fails to start.

To avoid this situation, when persistence.xml

is included in the application and you do not want to use the

Cosminexus JPA functionality, specify true in the ejbserver.jpa.disable

property of the J2EE server.

As a result, persistence.xml

is no longer read with Application Server.

Also, regardless of the value specified in the ejbserver.jpa.disable

property, the JPA version that can be used with Application Server is JPA 1.0.

299

6

Cosminexus JPA Provider

This chapter gives an overview of the Cosminexus JPA Provider functionality, describes the application implementation methods, and the execution environment settings.

301

6. Cosminexus JPA Provider

6.1 Organization of this chapter

Cosminexus JPA Provider is a JPA provider that implements API functions and the internal processing determined in the JPA specifications and is provided by Application Server provided to the user in the library format.

This chapter describes the Cosminexus JPA Provider functionality. The following table describes the organization of this chapter.

Table 6

1: Organization of this chapter (Cosminexus JPA Provider functionality)

Category Title

Reference location

Explanation

Implementation

Cosminexus JPA Provider

Updating a database using entities

Entity operations by

EntityManager

Defining the mapping information between the database and Java objects

Entity relationships

Cache functionality of the entity objects

Auto-numbering of the primary key values

Database operations based on the query language

Optimistic lock

Pessimistic lock in JPQL

Creating an entity class

Procedure for inheriting an entity class

Procedure for using

EntityManager

and

EntityManagerFactory

Procedure for specifying the callback method

Procedure for referencing and updating the database with the query language

JPQL coding method

Defining persistence.xml

Settings Settings in the execution environment

Note: The functionality-specific explanation is not available for

Operations

.

6.10

6.11

6.12

6.13

6.14

6.15

6.16

6.5

6.6

6.7

6.8

6.9

6.2

6.3

6.4

6.17

6.18

6.19

302

6. Cosminexus JPA Provider

6.2 Cosminexus JPA Provider

Cosminexus JPA Provider is the JPA provider provided by Application Server. The following figure shows the positioning of Cosminexus JPA Provider.

Figure 6

1: Positioning of Cosminexus JPA Provider

Cosminexus JPA Provider is the J2EE server functionality and uses JTA and JNDI to operate the database. The following subsections give an overview of the Cosminexus JPA Provider functionality.

6.2.1 Processing in Cosminexus JPA Provider

Cosminexus JPA Provider provides the following functionality:

Mapping of the entity objects and database

Managing the entity objects

Data operations using JPQL

Accessing the database through JDBC

To use JPA, you operate the interfaces provided by Cosminexus JPA Provider by using the user-created applications.

The following figure shows the processing executed in Cosminexus JPA Provider.

303

6. Cosminexus JPA Provider

Figure 6

2: Processing executed in Cosminexus JPA Provider

A description of the figure is as follows:

1. Cosminexus JPA Provider generates

EntityManagerFactory

from the persistence unit information defined in persistence.xml

.

A persistence unit is a logical group that collects information such as the classes to be mapped, O/R mapping

information, and the data sources. For details on a persistence unit, see

5.4.4 Persistence unit

.

2.

3.

EntityManager

is generated from the generated

EntityManagerFactory

EntityManager

, query, or transaction is operated from the user application.

.

4. The entity object is operated through the persistence context from

EntityManager

, query, or transaction.

5. The changes in the entity object are applied to the database through the JDBC driver.

Note that there are two types of EntityManager :

Container-managed

EntityManager

EntityManager

managed by the J2EE container

Application-managed

EntityManager

EntityManager

managed by an application

For details on the types of

EntityManager

, see

5.5.1 EntityManager and persistence context

.

Furthermore, a transaction manages operations such as the transaction commit and rollback. With Cosminexus JPA

Provider, you can use the resource local transaction as the transaction. To integrate with JTA transactions, use the functionality provided by the J2EE container.

6.2.2 Functionality provided by Cosminexus JPA Provider

The following functionality is provided by Cosminexus JPA Provider.

304

6. Cosminexus JPA Provider

Table 6

2: Functionality provided by Cosminexus JPA Provider

Functionality

Updating a database using entities

Defining the mapping information between the database and Java objects

Entity relationship settings

Entity object cache

Auto-numbering of primary key

Database operations based on the query language

Optimistic lock

Pessimistic lock in JPQL

Overview of functionality

Updates the data in the database using the entities generated from the user applications.

The mapping information between the database and Java objects can be defined with annotations or the O/R mapping file.

Sets up the relationship between the database tables by using entities.

This functionality stores the content of the entity object of

EntityManager

in the memory. When an entity object with the same content is invoked, the entity object in the memory is used.

Cosminexus JPA Provider automatically stores the primary key when the entity object is used to insert the data in the database. Even if the user does not specify the primary key, a unique value is stored.

The database can be operated using the query language.

With Cosminexus JPA Provider, you can use JPQL or SQL as the query language.

This is one of the database locking methods. The data is updated after confirming that the data in the database is not being updated by another transaction. An optimistic lock does not lock the data, so a deadlock does not occur.

This is one of the database locking methods. A dedicated lock is set for the record so that the record is not updated by another transaction. A pessimistic lock is executed only when JPQL is used.

Standard/

Extended

#

Standard

Standard

Reference location

6.3

6.4

6.5

Standard

Extended

Standard

Standard

Standard

Extended

6.6

6.7

6.8

6.9

6.10

6.11

# Indicates whether the functionality is based on the JPA 1.0 specifications.

Standard: Indicates that the functionality is based on the JPA 1.0 specifications.

Extended: Indicates that the functionality is unique to Cosminexus JPA Provider.

For details on the functionality, see the sections mentioned in the

Reference location

column in the above table.

Also, you can collect the PRF trace in Cosminexus JPA Provider. For details on the PRF trace collection points, see

8.

Trace Collection Points and PRF Trace Collection Levels of the Trace Based Performance Analysis

in the

uCosminexus Application Server Maintenance and Migration Guide

.

6.2.3 Preconditions for using Cosminexus JPA Provider

This subsection describes the preconditions for using Cosminexus JPA Provider.

(1) Available components

The components that use Cosminexus JPA Provider are EJB 3.0 and later in the case of EJBs and Servlet 2.5 and later in the case of Web components. For details on the available components, see

5.3.2 Available components

.

(2) Connectable databases

You can connect to the following databases when you use Cosminexus JPA Provider:

Oracle10g

Oracle11g

305

6. Cosminexus JPA Provider

HiRDB Version 8

HiRDB Version 9

(3) Available DB Connectors

Cosminexus JPA Provider uses DB Connector to update the database. You can use DB Connectors listed in the following table with Cosminexus JPA Provider.

Table 6

3: DB Connectors available with Cosminexus JPA Provider

Database used Transaction type Available DB Connector

Oracle DBConnector_Oracle_CP.rar

Oracle RAC

HiRDB

LocalTransaction

NoTransaction

XATransaction

LocalTransaction

NoTransaction

DBConnector_Oracle_XA.rar

DBConnector_Oracle_CP.rar

DBConnector_CP_ClusterPool_Root.rar

DBConnector_Oracle_CP_ClusterPool_Member.rar

DBConnector_HiRDB_Type4_CP.rar

LocalTransaction

NoTransaction

XATransaction DBConnector_HiRDB_Type4_XA.rar

(4) Environment that cannot be used

You cannot use Cosminexus JPA Provider in the following environment:

Execution environment for the batch applications

Execution environment for the EJB client applications

(5) Using the method cancellation functionality

With Cosminexus JPA Provider, a unique binary code is embedded in the accessor method for OneToOne and

ManyToOne LAZY fetch. As a result, the accessor method is subject to method cancellation. Therefore, when LAZY fetch is specified for the OneToOne relationship or ManyToOne relationship, the entity class, embeddable class, and mapped super-class must be registered in the protected area.

Note that if the classes are not registered in the protected area, method cancellation might occur on the embedded binary code. The operations when the classes are not registered in the protected area might not function properly.

Whether the classes are registered or not registered in the protected area, the following stack trace is output due to method timeout. However, if the classes are registered in the protected area, method cancellation does not occur.

In the following example, the embedded

EntityClass1._toplink_getmappingClass2

is invoked by extending the

EntityClass1.getMappingClass2

method invoked by the user. Consequently, a method timeout occurs, but method cancellation does not occur.

message-id message(LANG=ja)

KDJE52703-W A timeout occurred while the user program was executing. (threadID =

23794987, rootAPInfo = 10.209.11.124/5964/0x4828eb62000128e0, application = JPA_JavaEE_TP, bean = TestBean, method = doTest) jpa.test.annotation.onetoone.entity.EntityClass1._toplink_getmappingClass2(EntityClass1.java

)

locals:

(jpa.test.annotation.onetoone.entity.EntityClass1) this =

<0x11e35878> (jpa.test.annotation.onetoone.entity.EntityClass1)

at jpa.test.annotation.onetoone.entity.EntityClass1.getMappingClass2(EntityClass1.java:34)

locals:

(jpa.test.annotation.onetoone.entity.EntityClass1) this =

<0x11e35878> (jpa.test.annotation.onetoone.entity.EntityClass1)

306

6. Cosminexus JPA Provider

For details on registering the classes in the protected area, see

2.6 criticalList.cfg (Protected area list file)

in the

uCosminexus Application Server Definition Reference Guide

.

(6) Using the annotation reference control functionality

When you use Cosminexus JPA Provider, you cannot use the annotation reference control functionality. If the annotation reference control functionality is enabled, you cannot define the persistence context and persistence unit references.

6.2.4 Estimating the number of DB Connector connections

This subsection describes the estimation of the DB Connector resources required for using Cosminexus JPA Provider.

With Cosminexus JPA Provider, you obtain the DB Connector connections. The formula for estimating the number of connections used by Cosminexus JPA Provider is as follows:

Formula for estimating the number of connections

Number of connections used by the Cosminexus JPA Provider applications

= Number of concurrent executions of applications using the JPA functionality

#

# In the applications using the JPA functionality, when EntityManager of multiple persistence units is used or when the transactions used by

EntityManager

for invoking the business methods are different, a connection is required for each

EntityManager

.

!

Important note

When the user acquires a connection separately from the JPA functionality, the number of connections can be reduced by using the connection sharing functionality. For details on connection sharing, see

3.14.3 Connection sharing or association

.

307

6. Cosminexus JPA Provider

6.3 Updating a database using entities

With Cosminexus JPA Provider, you can update a database using entities.

To use the JPA, the user must create an entity class for handling the database tables as Java objects. If you use the entity class, the data in the database is operated through Cosminexus JPA Provider. At this time, you operate the database through the

EntityManager

interface provided by Cosminexus JPA Provider.

The database operations using the entity class are as follows:

1. Generating the entity class instance (entity object).

2. Passing the entity object to the argument of the

EntityManager

interface to operate the database.

To perform these operations, an entity class must be created.

EntityManager

is an object used for operating the entities and controlling the states. The entity operations include the persist

operation, remove

operation, merge

operation, flush

operation, and refresh

operation. For

details on these operations, see

6.4.1 Transition of entity states

.

308

6. Cosminexus JPA Provider

6.4 Entity operations by EntityManager

The state of the entity is controlled by

EntityManager

provided with Cosminexus JPA Provider. This section describes the entity operations in

EntityManager

.

6.4.1 Transition of entity states

An entity has a state. When you perform operations for an entity, the state of the entity changes. This subsection describes the types of entity states, the operations executed for the entity, and the entity operations and state transition.

(1) Types of entity states

An entity has four types of states, namely new , managed , detached , and removed . The entity state is changed by using the

EntityManager

method to operate an entity.

The following table lists and describes each entity state.

Table 6

4: Entity state

State of entity instances Explanation new managed detached removed

A state in which the entity is newly generated.

A newly generated entity instance does not have a persistence identity, and is, therefore, not associated with the persistence context.

A state in which the entity has a persistence identity associated with the persistence context and is managed with the persistence context.

A state in which the entity has a persistence identity that is not associated with the persistence context.

A state in which the entity has a persistence identity and is associated with the persistence context.

Also, includes the state in which the entity instance is scheduled for deletion from the database.

(2) Operations for the entities

If the user searches the database records, Cosminexus JPA Provider stores the obtained data in the entity fields. Also, when the user updates the database contents, the entity state is applied to the database by changing the state of the entity registered in the persistence context and by committing the transaction. Thus, by executing operations for the entity, the database information is updated.

The following table lists and describes the types of operations for the entities.

Table 6

5: Types of operations for the entities

Operations Explanation flush merge persist refresh remove

This operation applies the content of the entity object to the database.

In this operation, the entity object that was not managed by

EntityManager

is managed by

EntityManager .

This operation manages and perpetuates the entity object.

This operation applies the database content to the entity object.

This operation sets the entity object to the state of scheduled deletion.

(3) Operations and state transition for the entities

The following figure shows the operations and the state transition for the entity instances.

309

6. Cosminexus JPA Provider

Figure 6

3: Operations and state transition for the entity instances

The following table describes the operations and state transition for the entities.

Table 6

6: Transition of entity states

State

Operations new managed detached persist managed remove merge refresh commit rollback flush clear managed

#1 new

Copy source new

Copy destination managed

Exception

#2, #4

--

--

--

-removed

Copy source managed

Copy destination managed managed

#5

#6 detached managed detached managed

#1

Exception

#2, #3

Copy source detached

Copy destination managed

Exception

#2, #4

--

--

--

-removed managed removed

Exception

#3, #4

Exception

#2, #4 detached detached detached detached

Legend:

--: Not applicable

#1 If an exception occurs in the persist operation, the state enters the original state without being changed.

#2 The exception that occurs is

IllegalArgumentException

.

#3 If the corresponding line does not exist in the database, the operation is ignored.

#4 If an exception occurs, the state does not change and remains as the original.

#5 If the corresponding line does not exist in the database,

EntityNotFoundException

occurs.

#6 For a persistence context in the transaction scope, the state is detached

. For an extended persistence context, the state is managed .

Furthermore, the operations when persist

, remove

, merge

, and refresh

are executed outside the transaction vary according to the type of the persistence context.

310

6. Cosminexus JPA Provider

For a persistence context in the transaction scope

TransactionRequiredException

occurs.

For an extended persistence context

The state changes and the states are applied to the database when the next transaction is concluded.

(4) Propagation of operations to the entities

When the entities have a relationship and if you specify the cascade

attribute of the annotation indicating the relationship, the operations for the entity are propagated to the related entities. You can specify the values listed in the following table in the cascade

attribute.

Table 6

7: Types of cascade attributes

Types of cascade attributes Explanation

CascadeType.ALL

CascadeType.PERSIST

CascadeType.REMOVE

CascadeType.MERGE

CascadeType.REFRESH

The persist

, remove

, merge

, and refresh

operations are propagated to the relation destination.

The persist

operation is propagated to the relation destination.

The remove

operation is propagated to the relation destination.

The merge

operation is propagated to the relation destination.

The refresh

operation is propagated to the relation destination.

6.4.2 persist operation for the entities

To execute the persist

operation for the entities, invoke the persist

method of

EntityManager

. If the persist

method of

EntityManager

is invoked and the persist

processing is cascaded, the entity is managed in the persistence and persistence context of the database.

The following table describes the state of the entity after the persist

operation, for each entity state.

Table 6

8: State of the entities in the persist operation

State of the entity State of the entity after the persist operation new

# managed detached

# removed

The state changes to managed

. The entity changed to managed

is added into the database during or before transaction commit or is added into the database as a result of the execution of the flush

operation.

The persist operation is ignored. However, if PERSIST or ALL is specified in the cascade attribute for the relationship from one entity to another entity, the persist operation is propagated to the entities referenced by this entity.

If the line corresponding to the entity does not exist in the database, the state changes to managed

. If the corresponding line exists,

EntityExistsException

occurs.

The state changes to managed

.

# For Cosminexus JPA Provider, when the state of an entity is new

or detached

, the results of the transition of entity states differ according to whether the data corresponding to the entity exists on the database. Note the following for Cosminexus JPA Provider:

If an entity that is not perpetuated in the database is specified in the argument, the state changes to managed

.

If a line duplicating with the entity passed in an argument exists on the database and if that entity is managed with the persistence context,

EntityExistsException

occurs during the persist

processing.

If a line duplicating with the entity passed in an argument exists on the database, but if the entity is not managed with the persistence context,

EntityExistsException

or another

PersistenceException

occurs during flush

and commit.

!

Important note

The entity is registered in the persistence context when the entity is perpetuated in the database and when the entity information is read from the database. Note that after the entity state is changed to managed

, if the persistence processing is rolled back, the entity is not managed with the persistence context.

311

6. Cosminexus JPA Provider

6.4.3 remove operation for the entities

To execute the remove

operation for the entities, invoke the remove

method of EntityManager. If the remove method of EntityManager is invoked and the remove processing is cascaded, the state of the entity becomes removed

. A removed

entity is deleted from the database by the transaction commit processing.

The following table describes the state of the entity after the remove operation, for each entity state.

Table 6

9: State of entity in the remove operation

State of the entity Result of state transition new

The remove operation is ignored. However, if REMOVE or ALL is specified in the cascade attribute for the relationship from one entity to another entity, the remove

operation is propagated to the entities referenced by this entity.

managed The state changes to removed

. If

REMOVE

or

ALL

is specified in the cascade

attribute for the relationship from one entity to another entity, the remove

operation is propagated to the entities referenced by this entity.

The state changes as follows: detached

If the line corresponding to the detached

entity passed in the argument exists in the database,

IllegalArgumentException

is thrown during the remove

operation.

For Cosminexus JPA Provider, if the corresponding line does not exist in the database, the remove operation is ignored. However, if REMOVE or ALL is specified in the cascade attribute for the relationship with other entities, the remove

operation is propagated to the entities referenced by this entity.

removed The remove

operation is ignored. The operation is also not propagated to other entities.

Note 1: A removed

entity is deleted from the database as a result of the execution of operations during transaction commit, before transaction commit, or during flush operations.

Note 2: After the entity is deleted, the entity contents change to the contents immediately after the remove

processing was invoked, however, excluding the content immediately after the entity was generated.

6.4.4 Obtaining the entities from the database

By invoking the find method or getReference method of EntityManager , you can obtain the entities corresponding to the primary key specified in the argument, from the database.

The entities returned by the find

method or getReference

method of

EntityManager

use the persistence context of the transaction scope. Therefore, when the method is invoked within the transaction, the state changes to managed

. Also, if the find

method or getReference

method is invoked outside the transaction, the state changes to detached

.

The following table describes the state of entities obtained with the find

operation or getReference

operation.

Table 6

10: State of entities obtained with the

find

operation or

getReference

operation

Persistence context State of the obtained entity

Persistence context of the transaction scope (outside the transaction)

Persistence context of the transaction scope (within the transaction)

Extended persistence context (outside the transaction)

Extended persistence context (within the transaction) detached managed managed managed

Note that for Cosminexus JPA Provider, the following points differ from the JPA specifications in the find operation or getReference

operation. Note that apart from these differences, there are no other functionality differences with the JPA specifications.

With the JPA specifications, in the getReference method of EntityManager , you can return Proxy to the entity corresponding to the primary key given in the argument and not in the actual instance. However, with

312

6. Cosminexus JPA Provider

Cosminexus JPA Provider, Lazy loading is not supported for

@Basic

. Therefore, with Cosminexus JPA

Provider, entity instance is returned as the return value of getReference

instead of

Proxy

.

For details on the supported range of Lazy loading for a relationship, see

6.4.5(2) Reading the entity information from the database

.

With Cosminexus JPA Provider, if an entity that does not exist between the find method and getReference method is specified in the argument, a null value is returned with the find

method. Also,

EntityNotFoundException

is thrown with the getReference

method.

6.4.5 Synchronization with the database

When the transaction commit or flush

method is executed, the state of the entity is written to the database. On the other hand, unless refresh

is invoked explicitly, the state of the entity loaded in the memory is not refreshed.

This subsection describes writing of the entity information to the database and reading of the entity information from the database.

(1) Writing the entity information to the database

This section describes the transition of entity states in the flush operation or transaction commit. The following table describes the state transition results for each entity A state.

Table 6

11: State transition of entity instances in the flush operation or transaction commit

State of entity A Result of state transition new managed removed detached

The flush operation is ignored.

Entity A is synchronized with the database.

Entity A is deleted from the database.

The flush

operation is ignored.

Also, if entity A with the managed

state has a relationship to entity B, the persist

operation is cascaded according to the conditions described in the following table by extending the flush

processing.

Table 6

12: Cascading of the flush processing and persist operation in commit for the related entity B

Specification of the cascade attribute of the relationship to entity B

State of entity B Results

PERSIST or ALL is specified

PERSIST or ALL is not specified

-new managed removed detached

The persist operation is cascaded to entity B.

In the flush operation

IllegalStateException

occurs and the transaction is marked for rollback.

In the commit processing

IllegalStateException

occurs and the transaction commit operation fails.

Entity B is synchronized with the database.

In the flush operation

IllegalStateException

occurs and the transaction is marked for rollback.

In the commit processing

IllegalStateException

occurs and the transaction commit operation fails.

When entity A is the owner of the relationship

The change in the relationship is synchronized with the database.

313

6. Cosminexus JPA Provider

Specification of the cascade attribute of the relationship to entity B

PERSIST or ALL is not specified

State of entity B Results detached

When entity B is the owner of the relationship

An exception occurs. With Cosminexus JPA Provider, the operations in this case are not supported.

Legend:

--: Not applicable

Note that if the flush

method is invoked outside the transaction,

TransactionRequiredException

occurs.

Tip

Persistence relation for relationship and database

A managed

entity having a bi-directional relationship is perpetuated on the basis of the reference stored in the owner side of the relationship. The application developer must create an application so that when changes occur, the entity is stored in the owner side and the non-owner side respectively without conflicting with the state of the entity on the memory.

For unidirectional OneToOne and OneToMany, it is the developer's responsibility to guarantee that the relation of the relationships defined in the entity and the relation between the database tables is matching.

(2) Reading the entity information from the database

If the refresh

method of

EntityManager

is invoked, the changes performed in the entity until then are destroyed and the state of the entity is overwritten by the database contents. At this time, if the corresponding line does not exist in the database,

EntityNotFoundException

occurs.

If you invoke the refresh

method of

EntityManager

when the state of entity is not managed

,

IllegalArgumentException

occurs.

(a) Timing when the entity information is read from the database

The entity is read from the database when the refresh method or find method is executed or when a query is issued. The related entities can also be read at this time. This is called the

fetch strategy

. Specify the fetch strategy in the fetch

attribute of each relationship. Specify one of the following types in the fetch

attribute:

• FetchType.EAGER

When the entity information is read from the database, the related field and entity information is read.

• FetchType.LAZY

When the field or relation destination is accessed for the first time, the entity is read from the database. This is called

Lazy loading

.

If you specify FetchType.EAGER

, the related field and entity information is read every time the entity information is read from the database. Therefore, specify

FetchType.LAZY

to prevent the obtaining of unnecessary relation destination entities.

The following table describes the supported range of the fetch

attribute in Cosminexus JPA Provider.

Table 6

13: Supported range of the fetch attribute for each relationship

Relationship annotation Supported range

@ManyToMany

@OneToMany

@OneToOne

@ManyToOne

@Basic

The default value is

FetchType.LAZY

.

The default value is

FetchType.LAZY

.

The default value is

FetchType.EAGER

. Note that if LAZY is specified, see

(b)

.

The default value is

FetchType.EAGER

. Note that if LAZY is specified, see

(b)

.

The fetch

attribute is ignored. The default

FetchType.EAGER

is always applied.

314

6. Cosminexus JPA Provider

(b) LAZY fetch in @OneToOne and @ManyToOne

If you specify

LAZY

in the fetch strategy for a @OneToOne and @ManyToOne relationship, when the entity class is loaded, the binary code is embedded in the getter

method for the field specifying

LAZY

.

If you invoke the getter

method, the relation destination entity is obtained from the database through the processing of the embedded binary code. Because the binary code is embedded in the getter

method, the getter

method used for accessing the field that forms the target of relation must be set up. Furthermore,

@OneToOne

or

@ManyToOne

must be specified in that getter

method.

!

Important note

The getter method determines the type of the relation destination entity from the targetEntity type of the relationship. The type of class specified in targetEntity

must be castable in the field or property type.

6.4.6 Separate and merge operations of an entity from the persistence context

An entity separated from the persistence context is called a detached

entity. The entity state becomes detached at the following times:

When a transaction in the persistence context of the transaction scope is committed

When a transaction is rolled back

When the persistence context is cleared (when

EntityManager.clear()

is invoked)

When

EntityManager

is closed

When the entity is serialized and the entity value is passed

The instance of the separated entity continues to exist outside the persistence context that is perpetuated and obtained.

The states of the entity and the database are not synchronized.

(1) Accessing a detached entity

An application can access the detached

entity even after the persistence context ends. In this case, the entity fields and relation destinations must already be fetched. The fields and the relation destination entities that are not fetched by the detached

entity cannot be accessed. Note that

FetchType.EAGER

is always applied to

@Basic

specified in the field, so the relation destination entity and field information are already obtained.

To access a relationship from the detached

entity, one of the following conditions must be satisfied:

The entity instance is obtained using find()

The entity is obtained by using a query or the entity is explicitly requested using the

FETCH JOIN

clause

The persistence instance that is not a primary key is already accessed with the application

The entity is already obtained from another valid entity by tracing the relation specified as fetch=EAGER

If unavailable instances are accessed and if available instances are accessed in a disabled state, an exception occurs.

However, when FetchType.LAZY

is specified with Cosminexus JPA Provider, if you access un-fetched fields and relation destination entities even if the entity is detached after

EntityManager

terminates, sometimes the value is obtained from the database and the contents can be referenced.

(2) merge processing of an entity

By invoking the merge

method of

EntityManager

or by cascading the merge

processing, you can merge the detached

entity with the persistence context managed by

EntityManager

.

The following table describes the transition of entity states in the merge

processing for each state of entity A.

315

6. Cosminexus JPA Provider

Table 6

14: Results of transition of entity states in the merge processing

State of entity A Results of state transition new managed

A new entity A' is created with managed

state and the state of entity A is copied to entity A'. Note that the entity of the merge

argument remains new

.

The merge

operation is ignored. However, if

MERGE

or

ALL

is specified in the cascade

attribute for the relationship from entity A to other entities, the merge

operation is propagated to the entities referenced by entity A.

detached The state of entity A is copied to entity A' that has the same ID and already exists and is being managed, or a new managed

entity is created that is a copy of entity A. Note that the entity of the merge

argument remains detached .

removed

IllegalArgumentException is thrown by the merge operation, or transaction commit fails. Note that the state of entity A remains removed

.

Note 1 If the relation from entity A to entity B is specified with cascade=MERGE

or cascade=ALL

, all the entity B are recursively merged as entity B'. Entity B' is set in entity A'. Note that if entity A is in the managed

state, entity A and entity A' are the same.

Note 2 If entity B is referenced when cascade=MERGE

or cascade=ALL

is not specified in the relation of entity A, when entity

A is merged with entity A' and if you trace the relation from entity A', you will finally reach the reference of the managed entity B' with the same persistence identity as entity B.

With the JPA specifications, the fields marked as LAZY to imply that the field is not fetched, are ignored during merge. However, with Cosminexus JPA Provider,

@Basic

operates as

EAGER

, therefore, all the fields that are not relationships are subject to the merge processing.

Also, if the

Version

string is used in the entity, the version of the entity is checked during the merge operation and during the flush and commit processing invoked after the merge operation. If the

Version

string does not exist, the version of the entity is not checked with the merge

operation. For details, see

6.10.1 Optimistic lock processing

.

Note that Cosminexus JPA Provider does not support the processing to return to the persistence context using the entity merge processing between vendors.

(3) Notes

In Cosminexus JPA Provider, the managed entity becomes a detached entity due to transaction commit with the persistence context of the transaction scope. On the other hand, with the extended persistence context, the managed

entity remains managed.

If the transaction is rolled back in the transaction scope and in the extended persistence context, all the existing managed

instances and removed

instances become detached

. The state of the instance is the state existing when the transaction is rolled back.

If the transaction is rolled back, the state of the persistence context becomes the state existing at rollback, so the state conflicts with the database state. Note that in Cosminexus JPA Provider, the version attribute state and the generated state form conflicting states, therefore, if the merge operation is performed, an exception might occur.

6.4.7 managed entity

You can use the contains()

method of

EntityManager

to obtain information about whether the entity instance is being managed with the current persistence context.

This subsection describes the conditions for the return value of the contains()

method.

• Conditions when the contains() method returns true

When the entity is acquired from the database and is not deleted from

EntityManager

, or is not separated

When the entity instance is generated and the persist method is executed for that entity or the persist operation is propagated to that entity

• Conditions when the contains() method returns false

When the entity instance is separated

316

6. Cosminexus JPA Provider

When the remove

method is executed for the entity or the remove

operation is propagated to the entity

When the entity instance is generated and the persist method is not executed for that entity or the persist

operation is not propagated to that entity

The actual insert

and delete

processing in the database is delayed until the conclusion of the transaction. At the same time, note that the propagation of persist and remove is applied immediately with the contains method.

Make sure that the entity instance is only managed using a single persistence context in the application. With

Cosminexus JPA Provider, the operations do not function properly when the same Java instance is managed with multiple persistence contexts.

317

6. Cosminexus JPA Provider

6.5 Defining the mapping information between the database and Java objects

With Cosminexus JPA Provider, you can define the information for mapping the database and the Java objects. You define the mapping information with an annotation or the O/R mapping file.

• Definition using an annotation

You define the mapping information directly in the entity class of the application.

• Definition using an O/R mapping file

An O/R mapping file is an XML file used for describing the mapping information. You use tags to define the mapping information.

If the mapping information is defined in both annotations and O/R mapping file, the definition in the O/R mapping file is given priority. Therefore, if you use the O/R mapping file to change the mapping information defined by using annotations, you can change the mapping information without changing the application.

Determine whether you want to use an annotation or an O/R mapping file or you want to use the annotation and O/R mapping file together, in accordance with the application creation policy.

318

6. Cosminexus JPA Provider

6.6 Entity relationships

With an entity, the relation between the database tables can be expressed using a relationship. With Cosminexus JPA

Provider, you can set an entity relationship.

6.6.1 Relationship types

A relationship consists of a relation and a direction. The possible relations are OneToOne, ManyToOne, OneToMany, and ManyToMany. Furthermore, the possible directions of each relation are unidirectional and bi-directional. The relations and directions are combined to form the following seven types of relationship:

Unidirectional OneToOne relationship

Unidirectional ManyToOne relationship

Unidirectional OneToMany relationship

Unidirectional ManyToMany relationship

Bi-directional OneToOne relationship

Bi-directional ManyToOne/OneToMany relationship

Bi-directional ManyToMany relationship

This subsection describes relationships using the employees and departments of a company as an example. The relation between the employees and departments is as follows:

The entity expresses the employees and departments respectively.

The employees are assumed to belong to some department.

A department maintains multiple employees.

The departments are referenced from employees and the employees are referenced from departments.

This example expresses the bi-directional ManyToOne/ OneToMany relationship of entities. In this case, Many stands for the employees and One stands for the department. The following figure shows the relation between the employee entity and the department entity.

Figure 6

4: Relation between the employee entity and the department entity

Note that in an entity, you can specify settings to propagate the operations to the relation destination entity. These settings are called

cascade

. When you perform an operation for an entity and if cascade is specified, similar operations are automatically executed even in the entities that have a relationship with the operated entity. If cascade is used, the user can save the effort of performing operations for the relation destination entity.

6.6.2 Annotations for relationships

The entities handle the relation between tables as a relationship. When you handle a relationship with an entity, the reference to another entity is stored as a field in the entity. In addition, set the following relationship annotations in the persistence property or instance variable that references an entity:

OneToOne (One-to-one)

OneToMany (One-to-many)

ManyToOne (Many-To-One)

ManyToMany (Many-To-Many)

319

6. Cosminexus JPA Provider

The following figure shows the relationship between entities and the relation between tables.

Figure 6

5: Relationship between entities and relation between tables

If the relationship annotation is not specified for referencing the entity, the operations will not function properly. Note that if the generic

type is not used in the reference where collection is used, the target entity must be specified as the relationship target.

Instead of using an annotation, you can also define a relationship using the O/R mapping file. However, note that when a relationship is defined in the O/R mapping file and if the same definition is specified in the annotation, the definition in the annotation is overwritten.

Default mapping in the relationship annotations

When the annotations for the OneToOne, OneToMany, ManyToOne, and ManyToMany relationships are applied, the default mapping rules are applied. Similarly when a relationship is specified in the O/R mapping file, the default mapping is applied.

When you use the default mapping of the relationship annotations, if the database tables and relations differ from

the default values specified in

6.6.4 Default mapping (bi-directional relationship)

or

6.6.5 Default mapping

(unidirectional relationship)

, the SQL statement cannot be created correctly in the database query during

execution. An exception occurs.

6.6.3 Direction of relationships

A relationship includes a bi-directional relationship and a unidirectional relationship. When a bi-directional relationship is handled, a relationship has an owner and a non-owner. A unidirectional relationship only has an owner.

The owner of a relationship can take decisions on updating a database relationship.

The following rules are applied to a bi-directional relationship:

The non-owner of a bi-directional relationship specifies the owner based on the mappedBy

element of

@OneToOne

,

@OneToMany

, and

@ManyToMany

. With the mappedBy

element, you specify the properties or field names that reference the non-owner side using the owner entity.

With the ManyToOne/ OneToMany bi-directional relationship, set many

as the owner. Therefore, the mappedBy element cannot be specified in

@ManyToOne

.

With the OneToOne bi-directional relationship, the entity on the side containing the external key becomes the owner.

In the ManyToMany bi-directional relationship, any entity might be set as the owner.

A relationship annotation has a cascade

attribute. If you specify the cascade

attribute, you can propagate the operations for the entities even for the reference destination entities. However, you can specify

REMOVE

in the

320

6. Cosminexus JPA Provider cascade

attribute of the relationship annotation only for OneToOne or OneToMany. If cascade=REMOVE

is applied for other relations, the operations might not function properly. For details on the cascade

attribute when the

entities have relationships, see

6.4.1(4) Propagation of operations to the entities

.

!

Important note

Cosminexus JPA Provider does not implement the check for maintaining the consistency of relationships during execution.

Therefore, when you update the relationships during the execution of an application, even if the update causes an inconsistency in the relationships, no warning or exception occurs.

Note that when a value is fetched from the database with collection relationships such as OneToMany or

ManyToMany, an empty collection is returned as the relationship value if the related entity does not exist.

6.6.4 Default mapping (bi-directional relationship)

This subsection describes the default mapping of a bi-directional relationship.

(1) Bi-directional OneToOne relationship

This section describes the default mapping of a bi-directional OneToOne relationship applied in the following conditions:

Conditions

Entity A references the stand-alone instance of entity B and sets

@OneToOne

.

Entity B references the stand-alone instance of entity A and sets

@OneToOne

. The persistence property (or field) name that references entity B using entity A is specified in the mappedBy

attribute of

@OneToOne

.

Entity A is the relationship owner.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Table A must have the external key for table B. The name of the external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key string of table B

Note Italics indicate a variable value.

Also, the external key string has the same type as the primary key of table B and is a unique key constraint.

321

6. Cosminexus JPA Provider

Figure 6

6: Default mapping in a bi-directional OneToOne relationship

(2) Bi-directional ManyToOne/ OneToMany relationship

This section describes the default mapping of a bi-directional ManyToOne/ OneToMany relationship applied in the following conditions:

Conditions

Entity A references the stand-alone instance of entity B and sets tags in the O/R mapping file).

@ManyToOne

(or the corresponding XML

Entity B references the entity A collection and sets

@OneToMany

(or the corresponding XML tags in the O/R mapping file). The mappedBy

attribute is specified in

@OneToMany

. The mappedBy

attribute specifies the persistent property (or field) name set for referencing entity B with entity A.

Entity A is the relationship owner.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Table A must have the external key for table B. The name of the external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key string of table B

Note Italics indicate a variable value.

The external key string has the same type as the primary key of table B.

322

6. Cosminexus JPA Provider

Figure 6

7: Default mapping in a bi-directional ManyToOne/ OneToMany relationship

(3) Bi-directional ManyToMany relationship

This section describes the default mapping of a bi-directional ManyToMany relationship applied in the following conditions:

Conditions

Entity A references the entity B collection. mapping file) is set in the collection.

@ManyToMany

(or the corresponding XML element in the O/R

Entity B references the entity A collection.

@ManyToMany

(or the corresponding XML tags in the O/R mapping file) is set in the collection and the mappedBy

attribute is specified. The mappedBy

attribute specifies the persistent property (or field) name set for referencing entity B with entity A.

Entity A is the relationship owner.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Apart from table A and B, a junction table named A_B where the name of the owner table appears at the beginning, is necessary. This junction table has two external key strings.

The first external key string references table A and has the same type as the primary key of table A. The name of this external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity B_ Name of the primary key of table A

The other external key string references table B and has the same type as the primary key of table B. The name of this external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key of table B

Note Italics indicate a variable value.

323

6. Cosminexus JPA Provider

Figure 6

8: Default mapping in a bi-directional ManyToMany relationship

6.6.5 Default mapping (unidirectional relationship)

A unidirectional relationship includes a Single-Valued relationship and a Multi-Valued relationship. The following points describe each relationship:

• Unidirectional Single-Valued relationship

A unidirectional Single-Valued relationship is a relationship that references the stand-alone instance and where only the owner exists.

Possible unidirectional Single-Valued relationships are unidirectional OneToOne relationships and unidirectional

ManyToOne relationships.

• Unidirectional Multi-Valued relationship

A unidirectional Multi-Valued relationship is a relationship that references the entity in the collection format and where only the owner exists.

Possible unidirectional Multi-Valued relationships are unidirectional OneToMany relationships and unidirectional

ManyToMany relationships.

This subsection describes the default mapping of a unidirectional relationship.

(1) Unidirectional Single-Valued relationship

This section describes the default mapping of a unidirectional OneToOne relationship and a unidirectional

ManyToOne relationship.

(a) Unidirectional OneToOne relationship

This section describes the default mapping of a unidirectional OneToOne relationship applied in the following conditions:

Conditions

Entity A references the stand-alone instance of entity B and sets tags in the O/R mapping file).

@OneToOne (or the corresponding XML

Entity A is not referenced from entity B.

Entity A is the relationship owner.

324

6. Cosminexus JPA Provider

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Table A must have the external key for table B. The name of the external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key string of table B

Note Italics indicate a variable value.

The external key string has the same type as the primary key of table B and is a unique key constraint.

Figure 6

9: Default mapping in a unidirectional OneToOne relationship

(b) Unidirectional ManyToOne relationship

This section describes the default mapping of a unidirectional ManyToOne relationship applied in the following conditions:

Conditions

Entity A references the stand-alone instance of entity B and sets tags in the O/R mapping file).

@ManyToOne

(or the corresponding XML

Entity A is not referenced from entity B.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Table A must have the external key for table B. The name of the external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key string of table B

Note Italics indicate a variable value.

The external key string must have the same type as the primary key of table B.

325

6. Cosminexus JPA Provider

Figure 6

10: Default mapping in a unidirectional ManyToOne relationship

(2) Unidirectional Multi-Valued relationship

This section describes the default mapping of a unidirectional OneToMany relationship and a unidirectional

ManyToMany relationship.

(a) Unidirectional OneToMany relationship

This section describes the default mapping of a unidirectional OneToMany relationship applied in the following conditions:

Conditions

Entity A references the entity B collection. mapping file) is set in the collection.

@OneToMany (or the corresponding XML tags in the O/R

Entity A is not referenced from entity B.

Entity A is the relationship owner.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Apart from table A and B, a junction table named A_B where the name of the owner table appears at the beginning, is necessary. This junction table has two external key strings.

The first external key string references table A and has the same type as the primary key of table A. The name of this external key string is as follows:

Name of the external key string

Name of entity A_ Name of the primary key string of table A

The other external key string references table B, has the same type as the external key of table B, and is a unique key constraint. The name of this external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key string of table B

Note Italics indicate a variable value.

326

6. Cosminexus JPA Provider

!

Important note

A unidirectional OneToMany relationship that uses a junction table as described in this example might not be supported with JPA Providers other than Cosminexus JPA Provider. Note this when you operate applications created with a unidirectional OneToMany relationship using JPA Providers other than Cosminexus JPA Provider.

Figure 6

11: Default mapping in a unidirectional OneToMany relationship

(b) Unidirectional ManyToMany relationship

This section describes the default mapping of a unidirectional ManyToMany relationship applied in the following conditions:

Conditions

Entity A references the entity B collection. mapping file) is set in the collection.

@ManyToMany

(or the corresponding XML tags in the O/R

Entity B does not reference entity A.

The owner is entity A.

Applied default mapping

Entity A is mapped to table A.

Entity B is mapped to table B.

Apart from table A and B, a junction table named A_B where the name of the owner table appears at the beginning, is necessary. This junction table has two external key strings.

One of the external key strings references table A and has the same type as the external key of table A. The name of this external key string is as follows:

Name of the external key string

Name of entity A_Name of the primary key of table A

The other external key string references table B and has the same type as the primary key of table B. The name of this external key string is as follows:

Name of the external key string

Name of the relationship property (or field) of entity A_ Name of the primary key of table B

Note Italics indicate a variable value.

327

6. Cosminexus JPA Provider

Figure 6

12: Default mapping in a unidirectional ManyToMany relationship

328

6. Cosminexus JPA Provider

6.7 Cache functionality of the entity objects

The cache functionality of the entity objects is a functionality that stores the entity objects used by an application in the memory. When you use the cache functionality of the entity objects, the entity objects cached in Cosminexus JPA

Provider are used if the same entity objects are operated. The data is not read from the database again, so the access to the database is minimized and the load on the processing performance can be reduced. Note that this functionality is unique to Cosminexus JPA Provider.

This section describes the cache functionality of the entity objects.

6.7.1 Processing of the cache functionality

If you use the cache functionality, when the same entity is read, the data is obtained from the cache instead of the database. This subsection describes the procedure for processing the cache functionality, the cache registration and update timing, and the procedure for updating the cache.

(1) Procedure for processing the cache functionality

The following figure shows the flow of processing of the cache functionality.

Figure 6

13: Flow of processing of the cache functionality

A description of the above figure is as follows:

• Reading of the entity

When an entity is first read with methods such as find

, the flow of processing is as follows:

1. The entity is read.

2. The data is obtained from the database.

3. The entity object of the obtained data is registered in the cache.

When the entity has a relationship and when you obtain the relationship destination entity, if the target entity exists in the cache, the entity in the cache is referenced without accessing the database.

A cache exists for each persistence context.

(2) Cache registration and update timing

Registration and update in a cache is implemented at the following times:

Cache registration timing

During the reading of an entity object ( find

operation) when the target cache does not exist

Cache update timing

When the entity is refreshed ( refresh

operation)

329

6. Cosminexus JPA Provider

When a transaction is committed

When an exception occurs in the optimistic lock processing

Note that when the

OptimisticLockException

exception occurs in the optimistic lock processing, the entity objects registered in the cache are deleted.

(3) Procedure for updating the cache

The following figure shows the flow of updating the cache.

Figure 6

14: Updating the cache

A description of the figure is as follows:

1. The following operations are implemented for the entity object:

refresh operation

Transaction commit

2. During the refresh

operation, the database is accessed.

3. The data existing in the persistence context is registered in the cache and the cache data is updated.

Note that the cache is registered even when JPQL is executed. The cache is registered if JPQL is executed when the target cache does not exist. The cache data is used in JPQL as well, but the database is accessed irrespective of the presence or absence of the cache data. Therefore, the cache-based processing performance cannot be expected to improve. For details, see point

(4)

.

The cache stores information for the entity objects; therefore, if the object returned during the execution of the query is the entity itself, the cache is updated. The cache is not updated when other fields are specified. The JPQL examples when the cache update is valid and when the update is invalid are as follows:

JPQL example when the cache is updated

SELECT emp FROM Employee AS emp

JPQL example when the cache is not updated

SELECT emp.id, emp.name, emp.address FROM Employee AS emp

(4) Relation between JPQL and cache

When all the entity objects are obtained with JPQL, if there is information registered in the cache, the cache information is obtained. The cache functionality of Cosminexus JPA Provider requires a primary key that is the ID for identifying the target entity. To obtain the primary key, the JPQL result must be obtained and at this time, the database is accessed. The primary key is extracted from the database access results and the entity object is obtained from the cache. Also, if the target data does not exist in the cache, the entity is created from the database information.

330

6. Cosminexus JPA Provider

With JPQL, the database is accessed regardless of the presence or absence of the cache data. Therefore, for JPQL, cache-based performance improvement cannot be expected.

6.7.2 Cache reference forms and cache types

There are three types of cache reference forms:

• Hard reference

This reference is not collected by garbage collection.

• Weak reference (java.lang.ref.WeakReference)

If the reference is weakly reachable, the reference is collected by garbage collection. Note that whether the cache reference is weakly reachable depends on the specifications in java.lang.ref.WeakReference

.

The examples of weak reference cache that are not collected with Cosminexus JPA Provider are as follows:

Cache of an entity object registered in the persistence context

Cache that references a non-weakly reachable cache using a relationship

Cache wherein the cache of another entity object with an inheritance relationship is not weakly reachable, when the entity inheritance strategy is used

• Soft reference (java.lang.ref.SoftReference)

This is a reference form that caches out when the remaining amount of memory decreases.

A soft reference is collected by garbage collection depending on the consumption rate and survival time of a resource. The specifications such as the collection timing and the selection of objects for collection depend on

JavaVM.

The cache types differ depending on which form is used to reference the cache. The following table describes the mapping of the cache reference forms and cache types.

Table 6

15: Mapping of the cache reference forms and cache types

Cache reference forms Cache types

Full

HardWeak

Hard reference

Hard reference + Weak reference

#1

Weak reference + Soft reference

#1

Weak reference

None

#2

#1 The reference forms are combined.

#2 The entity object is not cached.

SoftWeak

Weak

None

With Cosminexus JPA Provider, you can choose the cache type. Choose the type based on the application design and environment. Specify the cache type in persistence.xml

. For details on persistence.xml

, see

6.2

persistence.xml

in the

uCosminexus Application Server Definition Reference Guide

.

The following points describe the cache types.

(1) Full

All the entities are cached with a hard reference.

If you specify

Full

in the cache type, the access to the database decreases, so the processing load decreases.

However, the memory continues to be occupied, therefore, the load on the memory increases.

Specify

Full

when the duration of the entity object is long and when the reference is created for a few entity objects that require frequent access. Furthermore, when several entity objects are read, the memory load increases, so we do not recommend using

Full

to update multiple records in a batch.

331

6. Cosminexus JPA Provider

When

Full

is specified, the hard reference area is allocated with the specified cache size. If the hard reference area exceeds the defined size, the area is increased based on the Hashtable specifications. The following figure shows the image in the cache when

Full

is specified.

Figure 6

15: Cache image for Full

(2) HardWeak

The entities are cached with a hard reference and weak reference.

When you want to store the entity object in a list, use a hard reference. Create the hard reference area with a fixed length only up to the value specified in the cache size. If the cache size reaches the specified value, the old entity objects are moved to the weak reference. At this time, the entity objects for which cache registration has not been used for the longest time are moved sequentially to the weak reference. If the entity objects moved to the weak reference are used, the entity objects are once again stored in the hard reference area.

If you specify

HardWeak

, you can use the entity objects with a long duration to efficiently control the memory used in the cache.

If the state of insufficient memory occurs frequently in a system where

SoftWeak

is used, you cannot take advantage of the soft reference; therefore, use

HardWeak

. The following figure shows the image in the cache for

HardWeak

.

Figure 6

16: Cache image for HardWeak

In the case of

HardWeak

, the cache is stored with a hard reference in the hard reference cache area. Also, the cache is stored with a weak reference in the weak reference cache area.

(3) SoftWeak

The entities are cached with a soft reference and weak reference.

332

6. Cosminexus JPA Provider

You use the soft reference to store the entity objects in a list and create a soft reference area of a fixed length only up to the value specified in the cache size. If the cache size reaches the specified value, the old entity objects are moved to the weak reference area. At this time, the entity objects for which cache registration has not been used for the longest time are moved sequentially to the weak reference. If the entity objects moved to the weak reference are used, the entity objects are once again stored in the hard reference area.

If you specify

SoftWeak

, you can use the entity objects with a long duration to efficiently control the memory used in the cache. Therefore, when you use the cache functionality, we recommend that you specify SoftWeak . The following figure shows the image in the cache for

SoftWeak

.

Figure 6

17: Cache image for SoftWeak

In the case of SoftWeak , the cache is stored with a soft reference in the soft reference cache area. Also, the cache is stored with a weak reference in the weak reference cache area.

(4) Weak

All the entities are cached with a weak reference.

Therefore, all the entity objects are subject to garbage collection. If you specify weak, the memory load decreases, but the cache might be deleted due to garbage collection. Use the

Weak

cache type in systems that do not place significance on the cache functionality of the entity objects. The following figure shows the image in the cache for weak.

Figure 6

18: Cache image for Weak

In the weak cache type, the entities are cached with a weak reference.

(5) NONE

No entity objects are cached. Use the

None

cache type if you want to destroy an entity object immediately after the entity object is read from the database.

333

6. Cosminexus JPA Provider

6.7.3 Scope of the cache functionality

The cache data is stored for each persistence context. Therefore, the data cannot be obtained from the cache even if the entity object is invoked in another persistence context.

Note that the cache data is stored for the duration from the generation of the persistence context until the persistence context is destroyed.

6.7.4 Notes on using the cache functionality

This subsection describes the notes on using the cache functionality of the entity objects.

(1) Notes on updating or deleting the data in a query

When JPQL and native query are used in the application to update and delete the data, the cache contents are not updated. Execute operations such as the refresh

operation to obtain the database contents again.

The cache data is read in the following operations; therefore, the data is not updated in the database:

1. The data is read into the entity object.

The entity data is registered in the cache as well.

2. The delete query containing the data read in 1 is executed.

The data is deleted by the execution of the delete query, but the cache is not deleted.

3. The same data as in 1 is read into the entity object.

Because the data is the same as 1, the data existing in the cache is read.

4. The data in 3 is flushed.

The applicable line does not exist in the database, so the add or update processing cannot be performed.

(2) Notes on multiple persistence contexts using a cache

By using the cache, you can reduce the database access frequency. However, on the other hand, a time lag occurs in the data due to the cache and the frequency of optimistic lock exception might increase.

A cache exists for each persistence context. Therefore, multiple

EntityManagers

existing in pairs with the persistence contexts are generated simultaneously, and if the entities with the same primary keys are operated at the same time, even if the data is updated, the user might not be able to reference the updated data in a timely manner.

Due to this, the optimistic lock exception occurs easily.

The following points describe the mechanism and action for the occurrence of the optimistic lock exception.

(a) Example of optimistic lock exception

This section describes an example of cache for each persistence context in the environment shown in the following figure.

334

Figure 6

19: Environment described in this example

6. Cosminexus JPA Provider

In the figure, the cache and the database are consistent and data A is already stored in the cache.

1. In persistence context 1, the data is changed from A to B.

At this time, the contents of the cache and the database are identical, so an exception does not occur.

Figure 6

20: Changes in data in persistence context 1

2. After the processing of 1 ends, A data is changed in persistence context 2.

The cache data is not changed; so the database data and the cache are inconsistent. Therefore, an exception is thrown due to the optimistic lock.

335

6. Cosminexus JPA Provider

Figure 6

21: Changes in data in persistence context 2

In such an environment, if you use the cache, the non-updated cache is left behind and an exception might occur due to the optimistic lock.

(b) Action

When an optimistic lock exception occurs, the relevant objects in the cache are deleted. Therefore, execute the find method or the refresh

method to obtain all the related data from the database once again. With this, you can synchronize the cache data and the database.

(3) Notes on the cache registration and update timing

When you use JPQL to obtain the pessimistic lock, the entity object returned when the query is executed is not registered in the cache.

When a native query is used to execute the query that sets the entity as the return value in

@SqlResultSetMapping

, the entity object of the return value is stored in the cache.

During the refresh

operation of an entity, if

OptimisticLockException

occurs in another thread after the entity object is read and the cache is deleted, the entity object is not registered in the cache even if the refresh processing is executed.

336

6. Cosminexus JPA Provider

6.8 Auto-numbering of the primary key values

The primary key numbering functionality automatically generates the primary key value when the entity object is used to insert a record. Due to this functionality, even if the user does not specify the primary key value, a unique value is stored. Cosminexus JPA Provider provides the primary key numbering functionality.

How to generate the primary key value

There are four methods for generating the primary key values:

TABLE

In this method, you generate the primary key values by using a table to store the primary key values.

SEQUENCE

In this method, you use the database sequence objects to generate the primary key values. However, if HiRDB is used as the database, implement the same processing as that of

TABLE

with Cosminexus JPA Provider.

IDENTITY

In this method, you use the identity

column of the database to generate the primary key values. However, with Cosminexus JPA Provider, the operations differ depending on the database type used.

In HiRDB, you implement the same processing as that of

TABLE

.

In Oracle, you implement the same processing as that of

SEQUENCE

.

AUTO

You choose the generation method suitable for the database used. With Cosminexus JPA Provider, choose

TABLE

for both HiRDB and Oracle.

Timing when the primary key values are numbered

In Cosminexus JPA Provider, the primary key values are numbered during the flush operation or when a transaction is committed.

Example of SEQUENCE as the primary key value generation method

The following is an example of using SEQUENCE as the generation method of the primary key values. In this example, a sequence object named EMP_SEQ is assumed to have been created beforehand.

@Entity public class Employee {

...

@SequenceGenerator(

name="EMPLOYEE_GENERATOR",

sequenceName="EMP_SEQ"

)

@Id

@GeneratedValue(strategy=GenerationType.SEQUENCE,

generator="EMPLOYEE_GENERATOR")

@Column(name="EMPLOYEE_ID")

public Integer getId() {

return id;

}

...

}

337

6. Cosminexus JPA Provider

6.9 Database operations based on the query language

To use the JPA for operating the database data, implement the operation through the javax.persistence.Query

interface. Using the javax.persistence.Query

interface enables you to execute operations, such as search, update, and delete, for multiple records at the same time. To use the javax.persistence.Query

interface, the user uses the query language to operate the database.

With Cosminexus JPA Provider, you can use JPQL and SQL as the query language. A description of JPQL and SQL is as follows:

• JPQL

JPQL is a query language defined in the JPA specifications. This language does not depend on the database and operates for the entity class.

• SQL

SQL is a database-dependent query language. SQL is also called a native query. This language operates for the database data.

For details on the database operations based on JPQL and SQL, see

6.16 Procedure for referencing and updating the database with the query language

. Furthermore, for details on the JPQL syntax, see

6.17 JPQL coding method

.

338

6. Cosminexus JPA Provider

6.10 Optimistic lock

With Cosminexus JPA Provider, you use

EntityManager

and persistence context to manage the entities to be persisted. The changed entity information is applied to the database when the flush

method or transaction commit processing is executed. When the same line of the database might be updated at the same time in multiple transactions, the data integrity must be ensured. Cosminexus JPA Provider provides the optimistic lock to ensure data integrity.

The optimistic lock is a lock functionality for making sure that the data is not updated by other applications from the beginning of the data update processing until the update processing is complete. The optimistic lock does not lock the database, and therefore, has the advantage that deadlocks do not occur.

This section describes the optimistic lock.

6.10.1 Optimistic lock processing

If you use the optimistic lock, Cosminexus JPA Provider checks whether the database data is being updated by other applications, instead of the user. If the database data is being updated by other applications, Cosminexus JPA Provider throws an exception and notifies the user that the data is being updated. Furthermore, Cosminexus JPA Provider marks the transaction for rollback.

(1) Procedure for checking whether the data is updated

Whether the data is updated is checked by the presence or absence of update of the version column prepared in the database table. If the data in the database is updated, the version number of the version column is updated. As a result, the user understands that the database was updated by another application. The following table describes the states and operations of the version column when the database is updated.

Table 6

16: States and operations of the version column when the database is updated

State of the version column in the table

Operation

When the value of the version column is not updated

When the value of the version column is updated

Cosminexus JPA Provider applies the entity information to the database. At this time, the value of the version column in the database is updated.

Indicates that the database data is being updated by another application. Therefore, Cosminexus

JPA Provider throws OptimisticLockException and marks the transaction for rollback.

In this way, using the state of the version column, you can ensure that another transaction does not update the data during the period from the reading of the entity until the database is updated.

(2) Checking the versions of the persistence fields and relationships

To use the optimistic lock, you check the versions of both persistence fields and relationships of the entities. To check the versions, set the

Version

field (property) corresponding to the version column for the entity. Set the Version field

by using

@Version

or the

version

tag of the O/R mapping file.

The version of the entity is checked at one of the following timings:

When the entity state is changed and that change is written to the database

When the entity state is changed to managed

by the merge

processing

#

#

The version is not only checked during the execution of merge

, but also during flush

or when the transaction is committed.

When the version of the entity is determined to be old by the version check,

OptimisticLockException

occurs.

The transaction is also marked for rollback.

339

6. Cosminexus JPA Provider

(3) Checking the versions during the flush operation or transaction conclusion

You can check the version of the entity during the flush

operation or transaction conclusion. To check the version, specify the entity in the lock

method of

EntityManager

. By using the lock

method of

EntityManager

, you can add the entity as a target for version check in the transaction and change the update policy of the version column.

Cosminexus JPA Provider supports

LockModeType.READ

and

LockModeType.WRITE

as the timing for updating the version column (

LockModeType

of the lock

method). Regardless of the content specified in the update timing for the version column, Cosminexus JPA Provider ensures that the following two events do not occur during transaction conclusion:

Dirty Read

Transaction T1 changes a line. Then, before T1 executes commit and rollback, another transaction T2 reads the same line and obtains the changed value. Finally, T2 succeeds in commit.

Whether T1 executes commit or rollback is no longer important, but whether T1 performs commit or rollback before or after commit by T2 becomes important.

Un-Repeatable Read

Transaction T1 reads a line. Then, before T1 executes commit, another transaction T2 changes or deletes that line.

Finally, both the transactions succeed in commit.

If you specify

LockModeType.WRITE

as the

LockModeType

, the version column is forcefully updated even when there is no change in the entity state. The version column is updated when flush

or transaction commit is invoked. Note that if the entity is deleted before the version column is updated, the update of the version column might be omitted.

6.10.2 Exception processing when optimistic lock fails

If you want to check the execution of an optimistic lock explicitly, invoke the flush()

method. If an optimistic lock exception occurs during the invocation of the flush()

method, you can catch the exception processing and perform the recovery processing. If the optimistic lock has no problems, the entity version is checked and the Version column is updated by the flush() method.

A coding example of the exception processing is as follows: try{

em.flush();

} catch (OptimisticLockException e){

// Exception processing

}

As shown in this example, by wrapping

OptimisticLockException

during the exception processing, you can show the optimistic lock exception as an application exception. However, note that the transaction in this case is marked for rollback and cannot be committed.

Note that with Cosminexus JPA Provider, the entity that causes the exception is not stored in

OptimisticLockException . The getEntity() method of OptimisticLockException always returns a null value.

6.10.3 Notes on using the optimistic lock

This subsection describes the notes on using the optimistic lock.

(1) Notes on the Version field settings

The notes on the

Version

field settings are as follows:

If the

Version

field is not set, the version of that entity is not checked. In this case, the user shall create an application that maintains the consistency between the entity and the database.

340

6. Cosminexus JPA Provider

If the transaction contains entities for which the

Version

field is set and entities for which the

Version

field is not set, the version is only checked for the entities where the

Version

field is set. Note that the non-inclusion of a version in the entity does not affect the transaction conclusion processing.

The user can reference the

Version

field value, but must not update the value. However, the user can update the

Version

field value during bulk update processing.

(2) Notes on using the lock method

The notes on using the lock

method are as follows:

The lock

method of

EntityManager

is not supported for entities that do not have the

Version

field

(property). If an entity that does not have a

Version

field (property) is specified and the lock(entity,

LockModeType.READ)

or lock(entity, LockModeType.WRITE)

is invoked,

PersistenceException

occurs.

When the state of an entity that has a

Version

field (property) is updated, regardless of whether the lock method is invoked, the dirty read and un-repeatable read events do not occur.

When you specify

LockModeType.READ

with Cosminexus JPA Provider, the UPDATE statement is issued to check whether the database value corresponding to the entity is changed. Therefore, the UPDATE statement sets a lock for the database. The UPDATE statement is issued during the execution of flush processing and when the transaction is committed. The UPDATE statement is also issued when there is no change in the state of the entity object. However, the statement is not issued if the entity is deleted.

(3) Exclusive control of clients in HiRDB

The optimistic lock of Cosminexus JPA Provider is a locking method that assumes that the database Isolation level is accessed with

Read Committed

. If the database is HiRDB, the Isolation level is

Repeatable Read

by default; therefore, you must change the level to

Read Committed

.

Set the Isolation level for each client in the

PDISLLVL

parameter of the data guarantee level of the client environment variable. The default value is

Repeatable Read (2)

. Therefore, change the value to

Read

Committed (1) . An example of a change in setting is as follows:

Example of change: PDISLLVL=1

Specify the client environment variable in the value of the environmentVariables

property with the

configproperty

tag of the HITACHI Connector Property file or add the client environment variable in the configuration file for the client environment variable group of HiRDB.

If the data guarantee level of the client environment variable is operated with the default

Repeatable Read

, a lock is set in the shared mode. Therefore, note that if you combine the issue of reference series SQL such as the find method and the issue of update series SQL such as the flush

method, a deadlock occurs easily.

341

6. Cosminexus JPA Provider

6.11 Pessimistic lock in JPQL

The pessimistic lock is the method of exclusively locking the target records when multiple transactions update the same record on the database. If a transaction sets a pessimistic lock for a particular record, another transaction cannot reference or update that record (however, in Oracle, the record can be referenced). A pessimistic lock is only available when JPQL is used.

If you use a pessimistic lock, until the transaction that obtained the lock terminates, the lock awaits release. Therefore, though the concurrent executions are not more than the optimistic lock, you can prevent the transaction commit errors that occur in the optimistic lock.

How to specify a pessimistic lock

Implement the pessimistic lock by using the query hint supported by Cosminexus JPA Provider. Execute the pessimistic lock by specifying the setHint()

method of the

Query

method or by specifying

@QueryHint

in the

@NamedQuery

attribute.

Example of implementing the pessimistic lock functionality

An example of implementing the pessimistic lock functionality is as follows:

Example of implementation 1

An example of specifying the pessimistic lock in the setHint()

method of the

Query

method is as follows:

Query query = manager.createQuery("SELECT emp FROM Employee AS emp"); query.setHint("cosminexus.jpa.pessimistic-lock","Lock");

Example of implementation 2

An example of specifying the pessimistic lock in

@QueryHint

of the

@NamedQuery

attribute is as follows:

@NamedQuery( name="employee_list", query="SELECT emp FROM Employee AS emp", hints={ @QueryHint(name="cosminexus.jpa.pessimistic-lock", value="Lock") }

)

@Entity public class Employee{

...

}

!

Important note

The pessimistic lock is only available for JPQL. The pessimistic lock is not enabled even by specifying the createNativeQuery method or by specifying @QueryHint in the hints attribute of

@NamedNativeQuery

. The pessimistic lock is also not enabled by specifying the hint

attribute of the

namednative-query

tag in the O/R mapping file. Note that the locking specifications for the pessimistic lock in

Cosminexus JPA Provider conform to the specifications of the database used.

342

6. Cosminexus JPA Provider

6.12 Creating an entity class

To create an application that uses the JPA, you define the entity class in the application. An entity class is used for handling the database table records as Java objects. When a user performs the new

operation in the application, an entity class instance is generated.

This section describes the creation of a JPA application.

6.12.1 Defining the mapping between an entity class and database

An entity class is mapped to a line in the database table. The fields stored in the entity class are mapped to the values in the table columns. If the user updates a field value for an entity class instance, Cosminexus JPA Provider also updates the corresponding column of the database table. Therefore, the user can change the database state without issuing an SQL statement for the database.

The following figure shows the mapping between an entity class and a database table.

Figure 6

22: Mapping between the entity class and database table

You define the correspondence relationship between the entity fields and database columns in an annotation or the

O/R mapping file. You can define the correspondence in either an annotation or the O/R mapping file. However, if the definition is specified in both, the settings in the O/R mapping file are given priority over the annotation. If different values are specified for the same settings in the annotation and the O/R mapping file, the value in the annotation is overwritten with the value in the O/R mapping file.

6.12.2 Requirements for creating entity classes

When you create an application that uses the JPA, you must follow the requirements for creating the entity classes and the requirements for database mapping determined in the JPA specifications. The requirements for creating entity classes are as follows:

The entity class must be specified in

@Entity

or in the

entity

tag of the O/R mapping file.

The entity class has a constructor without an argument.

Do not set enum

and interfaces as entity classes.

The entity or the mapped super-class that form the root of the class hierarchy of the entity class must have a primary key. Make sure that you define one primary key in the entity hierarchy.

When the entity class instance is passed as a method argument with pass by value, you must implement the

Serializable

interface.

343

6. Cosminexus JPA Provider

The state of the database column is expressed by the instance variable of the entity and the instance variable corresponds to the JavaBean property. Do not change the value of the instance variable by direct access from the client. Change the value through the accessor method ( getter

/ setter

method) or the business method.

Set the persistent instance variable of the entity to an access level that can be referenced from private

, protected

, or package

.

Declare the constructor without an argument as public

or protected

.

Do not set the entity class to final

. Also, do not set the persistence instance variable of the entity class and all the methods to final

.

With Cosminexus JPA Provider, if these condition