Oracle Application Server TopLink Application Developer's Guide -- Index

addConversionValue() method, 3-13

addDirectMapping() method, 3-9

addField() method, A-20

addFieldTransformation() method, 3-69

addForeignKeyConstraint() method, A-20

addIdentityField() method, A-20

addPrimaryKeyField() method, A-20

addPrimaryKeyFieldName, 3-94

addTableName method, 3-102

addToAttributeOnlyConversionValue() method, 3-13

after load methods

using, 3-82

aggregate collection mappings

and EJBs, 3-24

aggregate collections

and inheritance, 3-23

working with, 3-22

aggregate object mapping

example, 3-19

in Java, 3-19

aggregate object mappings, 3-19

and ejbs, 3-20

working with, 3-19

AggregateObjectMapping class, 3-19

AllFieldsLockingPolicy, 5-29

amendment methods, 3-81, 6-50

OracleAS TopLink descriptors, customizing, 3-82

static, 3-82

application development

deployment, 1-15

mapping, 1-13

overview, 1-12

packaging, 1-15

performance tuning, 1-15

querying, 1-14

session management, 1-13

transactions, 1-14

application development tools, A-1

array mappings

about, 3-73

implementing in Java, 3-74

asynchronous update mode

overview, 8-5

attributes

described, 3-60

in Java objects, 3-60

batch reading, 10-9

in query objects, 6-70

batch writing, 5-17, 10-17

BEA WebLogic

configuring OracleAS TopLink for, B-7

modifying persistence descriptor, 9-11

setting class path, B-6, B-8

setting shared library, B-6, B-8

using a security manager, B-6

bean instance

defined, 3-60

beans

entity bean model, 3-55

mapping under EJB1.1, 3-15

mapping under EJB2.0, 3-15

session beans, 2-14

stateful beans, 2-14

stateless, 2-14

bidirectional relationship

in one-to-one mappings, 3-17

bidirectional relationships, 3-17

maintaining, one-to-many relationships, 3-62

maintaining, overview, 3-61

binding, 5-17

binding and parameterized SQL

binding string data, 5-17

binding using parameters, 5-17

binding using streams, 5-17

explained, 5-17

BLOB fields in databases, 3-71

boolean logic in expressions, 6-14

branch class, 3-52

bridge

JDBC-ODBC, 5-10

other than Sun JDBC-ODBC, 5-10

Builder Exception, C-38

build.properties, Web Client, A-3

cache

architecture, 8-2

configuring, 8-5

disabling during read query, 6-65

internal query object cache, 6-7, 6-76

isolation, 8-5

locking in clustering, 5-20

object cascading refresh, 6-66

object refresh, 6-66

queries, 6-61

refresh, 6-66

refresh, described, 6-7

session cache, 8-2

stale data, overview, 8-3

storing query object results, 6-7, 6-76

storing query results, 6-67

synchronization

in clustering, B-10

Unit of Work, 8-3

usage in queries, 6-61

usage of in-memory queries, 6-62

using identity maps, 4-48

cache identity map, 10-9

cache locking

overview, 8-3

cache locking, in clustering, 5-20

cache synchronization

asynchronous update, 8-5

clusters, 8-4

configuring, 8-7

configuring in the sessions.xml file, 4-19

discovery, 8-4

in clustering, B-10

message transport, 8-4

name service, 8-4

overview, 8-3

synchronous update, 8-4

cache, session

clearing, A-7

caching

overview, 1-8

three-tier, 4-64

using the readObject ( ) method, 6-38

Call Finders

creating, 6-88

executing, 6-88

using, 6-88

cascading write queries

compared to non-cascading, 6-68

ChangedFieldsLockingPolicy, 5-29

class extraction method

described, 3-53

class hierarchy

branch class, 3-52

leaf class, 3-52

root class, 3-51

class indicator

class indicator field, 3-52

described, 3-52

class indicators

and mappings, 3-52

class loader

loading session, 4-30

resolving exceptions, 5-15

class loader in conversion manager, 5-15

class path

setting for BEA WebLogic, B-6, B-8

setting for IBM WebSphere, B-4

setting for Oracle Application Server Containers for J2EE, B-3

class types

defined, 3-51

class, persistent, 3-60

classes

AggregateObjectMapping, 3-19

CursoredStream

optimizing, 6-84

Database Exception, 6-101

Database Session

creating, 4-48

creating tables on database, A-21

described, 4-48

public methods, 4-52

session query operations, 6-37

DatabaseLogin

creating the sequence table, A-21

described, 5-8

DataModifyQuery

described, 6-42

DataReadQuery

described, 6-42

DeleteObjectQuery, 6-68

described, 6-42

DirectCollectionMapping, 3-25

DirectReadQuery

described, 6-42

DirectToFieldMapping, 3-9

ExpressionBuilder, 6-17

InsertObjectQuery, 6-68

and Unit of Work, 7-9

described, 6-42

NestedTableMapping, 3-78

ObjectRelationalDescriptor, 3-93

ObjectTypeMapping, 3-13

OneToManyMapping, 3-21

OneToOneMapping, 3-17

OptimisticLockException, 5-29

Performance Profiler, 10-4

ReadAllQuery

described, 6-42

ReadObjectQuery

described, 6-42

ReportQuery

described, 6-42

SerializedObjectMapping, 3-71

session

logging SQL and messages, 4-65

Table Definition, A-20

TransformationMapping, 3-68

TypeConversionMapping, 3-12

Unit of Work

using to modify databases, 6-37

UpdateObjectQuery, 6-68

described, 6-42

example, 6-68, 6-69

ValueReadQuery

described, 6-42

VariableOneToOneMapping, 3-72

WriteObjectQuery

described, 6-42

Clear button, A-7

clearProfiler() method, 10-4

Client Session

architecture, 4-6

client sessions, 4-38

cluster

overview, 8-4

clustering

cache locking, 5-20

cache synchronization, B-10

explicit query refreshes, 8-13

clusters

configuring, 8-8

collection class, 6-6, 6-46, 6-60

specifying in query objects, 6-46

collections

as query results, 6-60

collocation

described, B-8

in BEA WebLogic Server cluster, B-8

pinning, B-9

static partitioning, B-9

commit

and Java Transaction API, 7-9, 7-10

overview, 7-9

common deployment errors, C-118

composite primary key, 3-18

concurrency, 4-42

Concurrency Exception, C-47

configuring, 4-53

development environment, A-15

Oracle JDeveloper, A-15

conform results option

described, 6-9

Connect button, A-7

connection policies, 4-45

connection pooling

described, 4-43

Server Session, 4-44

container configuration file

described, 9-11

container-managed persistence

concepts, 3-59

configuring for BEA WebLogic, B-7

configuring OracleAS TopLink, B-7

software requirements, B-2

container-managed persistent entity beans, 3-59

Conversion Exception, C-49

conversion manager, 5-14

assigning a custom conversion manager to a session, 5-15

assigning a custom conversion manager to all subsequent sessions, 5-15

class loader, 5-15

described, 5-14

using, 5-14

using custom types, 5-14

copy policy

implementing, 3-87

implementing in Java, 3-101

CORBA

message optimization, 10-8

OracleAS TopLink transport layer support, 4-60

Create tab (OracleAS TopLink Web Client), A-11

createObject() method, A-21

Creating a redirect finder, 6-54

creating in Java

mappings, 3-89

OracleAS TopLink descriptors, 3-89

cursor output

in stored procedures, 6-30

cursored streams

example, 6-84

optimizing, 6-84

ReadAllQuery methods, 6-46

usage example, 4-62

using, 6-81

cursors, scrollable

traversing, 6-82

custom query objects

creating, 6-70

custom SQL, 4-35

data level queries, 6-28

SQL queries, 6-27

using, 6-27

custom SQL queries

in OracleAS TopLink query framework, 4-35

custom types

assigning to a OracleAS TopLink session, 5-15

custom types, using with conversion manager, 5-14

customization

DatabaseLogin, 4-46

descriptors and mappings, 3-81

OracleAS TopLink descriptors using amendment methods, 3-82

Server Session, 4-46

customizing

descriptors using amendment methods, 3-82

data access

overview, 1-8

data level queries

in expressions, 6-23

using custom SQL, 6-28

data optimization, 5-16

database

reading from using session, 6-38

writing to using session, 6-39

database access

using stored procedures, A-24

database and Java type conversion tables, A-22

Database Exception, C-50

database exceptions, 6-101

database login, 5-8

Database Session

architecture, 4-6

database session

defining in the sessions.xml file, 4-13

database sessions, defined, 4-48

database, logging out, 4-49

DatabaseException class, 6-101

DatabaseLogin class, using to store login information, 5-8

DatabaseLogin described, 4-47

DatabaseRow, 3-69

DatabaseSession class

creating tables on a database, A-21

described, 4-48

instantiating, 4-48

logging SQL and messages, 4-65

public methods, 4-52

session queries, 6-37

data-level query

example, 6-24, 6-28

DataModifyQuery, 6-42

DataReadQuery, 6-42

Datasource

login in the sessions.xml, 4-15

DataSources, using JDBC2.0, 5-13

DB Access (Web Client), A-12

delete operation, 6-41

DeleteObjectQuery

defined, 6-42

example, 6-68

dependent objects

merging with SessionAccessor, 3-63

merging without SessionAccessor, 3-65

dependent objects, managing under EJB 1.1, 3-62

Deploy Tool

using with WebSphere Studio Application Developer, A-18

deploy tool for WebSphere, A-17

deployment

as part of the application development process, 1-15

modifying BEA WebLogic persistence descriptor, 9-11

XML files, non-application server, 9-3

deployment descriptors

customizing using amendment methods, 3-82

described, 3-56

for entity beans, 9-4

deployment errors, solutions, C-118

Deployment Exception, C-103

deployment JARs, troubleshooting, C-118

deployment overview, entity beans, 9-2

deployment, hot, 9-23

DeploymentXMLGenerator, 9-4

descriptor copy policy

implementing, 3-87

descriptor events

receiving, 3-83

registering with a descriptor, 3-84

supported events, 3-86

using, 3-83

Descriptor Exception, C-54

descriptor exceptions, error codes, C-4

descriptors

described, 3-3

OracleAS TopLink, 1-11

searching with OracleAS TopLink Web Client, A-8

descriptors (OracleAS TopLink)

creating in Java, 3-89

customizing with amendment methods, 3-82

development components, 1-4

development environment, configuring, A-15

development exceptions, C-1

builder exception, C-38

development services

described, A-23

development tools

profiler

using, 10-3

schema manager

described, A-19

direct collection mappings

example, 3-25

in Java code, 3-25

working with, 3-25

direct connect drivers, 5-13

direct mapping

described, 3-5

direct mappings

described, 3-8

direct-to-field, 3-9

objects type, 3-13

type conversion, 3-12

using, 3-8

DirectCollectionMapping class, 3-25

DirectReadQuery, 6-42

direct-to-field mappings, 3-9

in Java code, 3-9

DirectToFieldMapping class, 3-9

Disconnect button, A-7

discovery

configuring, 8-8

overview, 8-4

Discovery Exception, C-113

distributed cache synchronization

overview, 8-3

does exist write object, 10-17

domain.jar.path, Web Client, A-4

drivers, direct connect, 5-13

dynamic finders

creating, 6-93

using, 6-92

EJB 1.1

mappings between beans, 3-15

EJB 2.0

mapping restrictions not enforced by OracleAS TopLink, 3-15

mappings between beans, 3-15

EJB container, described, 3-56

EJB deployment, hot, 9-23

EJB Entity bean deployment

configuring descriptors, 9-10

overview, 9-2

EJB entity beans

relationships under EJB 2.0, 3-15

EJB finders

defining, 6-86

described, 6-11

ejb-jar.xml options, 6-86

using, 6-85

EJB JAR XML Exception, C-116

EJB Primary Key

defined, 3-61

EJB QL

in queries, 6-31

in sessions, 6-33

limitations, 6-33

ReadAllQuery, 6-32

using finders, 6-89

using with OracleAS TopLink, 6-32

EJB redirect finders

using, 6-53

EJB server, described, 3-56

EJB Session Beans, 4-60

EJB specification

inheritance, 3-55

sequencing, 3-44

EJBHome

defined, 3-60

ejb-jar.xml

EJB finder options, 6-86

ejb-jar.xml file

configuring, 9-11

overview, 9-10

synchronization under EJB 2.0, 9-11

EJBLocalHome

defined, 3-61

EJBLocalObject

defined, 3-60

EJBObject

defined, 3-60

EJBSelect

understanding, 6-95

using in a finder, 6-95

encryption, password, 4-14

Enterprise JavaBeans

2.0 support, 3-59

container, 3-56

deployment descriptors, 3-56

described, 3-56

Entity beans, 3-57

message-driven beans, 3-57

server, 3-56

Session Beans, 3-57

Entity bean deployment

configuring descriptors, 9-10

overview, 9-2

entity bean inheritance restrictions, 3-55

entity bean model, 3-55

entity beans

bean instance, 3-60

container managed, 3-59

defined, 3-60

deployment overview, 9-2

described, 3-57

EJB Home, 3-60

EJB Object, 3-60

EJB Primary Key, 3-61

EJBLocalHome, 3-61

EJBLocalObject, 3-60

importing 2.0 relationship metadata into the OracleAS TopLink Mapping Workbench, 3-16

in the OracleAS TopLink Mapping Workbench, 3-47

inheritance, 3-55

mappings, 3-15, 3-16

persistent state, 3-60

primary keys, 3-37

relationships between, 3-14

relationships between beans and Java objects, 3-16

relationships under EJB 1.1, 3-14

sequencing with, 3-44

with OracleAS TopLink Mapping Workbench, 3-47

entity beans and relationships, 3-14

entity deployment

troubleshooting, C-117

error codes, C-4

10001-10047, C-91

1001-1042, C-39

1-176, C-4, C-5

12000-12004, C-97

13000-13020, C-98

14001-14027, C-103

15001-15024, C-106

16001-16006, C-108

17001-17006, C-109

18001-18002, C-111

19001-19003, C-112

20001-20004, C-113

2001-2004, C-48

22001-22004, C-114

22101-22105, C-115

25001, C-116

3001-3007, C-49

4002-4018, C-51

5001-5008, C-54

6001-6098, C-56

7001-7104, C-72

72000-72023, C-117

8001-8010, C-87

9000-9009, C-89

error codes and descriptions, C-4

event

implementing in Java, 4-70

Event Manager, 3-83, 4-69

events

about, 3-83

events, session, 4-67

examples

cursored streams, 6-83

expression framework, 6-51

multiple tables, 3-106

named finders, 6-50, 6-52

optimistic locking, 3-108

performance optimization, 10-12, 10-15

read query, 10-5

READALL finders, 6-88, 6-89, 6-94

report query, 6-74

scrollable cursors, 6-82

serialized object mapping, 3-71

session broker, 4-54

session event manager, 4-69

SQL queries, 6-27

stored procedure call, 6-29

stored procedures, generating, A-24, A-25

transformation mapping, 3-69

type conversion mapping, 3-13

Unit of Work, 7-7, 7-20

variable one-to-one mapping, 3-72, 3-73

write, write all, 6-40

exception handlers, 4-67

exception handling

in queries, 6-101

exceptions

about, C-2

builder exceptions, C-39

chained, 4-65

communication exceptions, C-97

concurrency exceptions, C-48

conversion exceptions, C-49

database, 6-101

database exceptions, C-51

deployment exceptions, C-103

descriptor exceptions, C-4, C-5

development, C-2

discovery exceptions, C-114

EJB exceptions factory, C-91

EJB JAR XML exceptions, C-117

EJB QL exceptions, C-87

java.security.AccessControlException, C-123, C-124

JDO exceptions, C-108

JMS processing exceptions, C-111

optimistic lock exceptions, C-54

OracleAS TopLink Exception class, C-2

query exceptions, C-56

remote command manager exceptions, C-115

runtime, C-2

SDK data store exceptions, C-109

SDK descriptor exceptions, C-112

SDK query exceptions, C-113

session loader exceptions, C-89

synchronization exceptions, C-106

validation exceptions, C-72

XML conversion exception, C-116

XML data store exceptions, C-98

expression components, 6-13

EXPRESSION finders

using, 6-89

expression framework, 6-51

ExpressionBuilder, 6-17

expressions

components, 6-13

data level queries, 6-23

outer joins, 6-72

parallel expressions, 6-19

platform functions, 6-22

query keys, 6-24

subqueries and subselects, 6-18

user-defined functions, 6-22

using, 6-12

using Boolean logic, 6-14

with query by example, 6-36

field locking policies, 3-107, 3-108, 5-21

field types

Oracle, 5-4, A-22

findAll

using, 6-93

findByPrimaryKey

using, 6-93

Finder Libraries, using, 6-86

finders

advanced options, 6-96

caching options, 6-97

choosing, 6-94

disabling cache, 6-98

managing large result sets, 6-99

refreshing results, 6-98

foreign keys, 6-20

addForeignKeyConstraint(), A-20

direct collection mappings, 3-25

one-to-one mappings, 3-17

working with, 3-46

full identity map, 10-9

generating deployment JARs, troubleshooting, C-118

getInheritancePolicy(), 3-95

getWrapperPolicy(), 3-89

hierarchical queries

described, 6-78

home interface, inheritance, 3-55

Home tab (Web Client), A-2, A-6

hot deployment, described, 9-23

IBM Informix

using native sequencing, 5-12

IBM WebSphere

configuring module visibility, B-4

setting class path, B-4

IBM WebSphere Server, troubleshooting, C-122

IBM WebSphere Studio Application Developer

Deploy Tool, A-18

identity map cache

disabling during a write query, 6-69

refresh in read query, 6-66

identity maps, 4-28, 4-48

cache identity map, 10-9

cascading refresh during read query, 6-66

example, 6-66

full identity map, 10-9

refreshing during read query, 6-66

soft cache identity map, 10-9

soft cache weak identity map, 10-9

weak identity map, 10-9

Indirection

ValueHolder indirection, 3-28

indirection, 4-62, 10-8

choosing the correct type, 3-32

described, 3-6, 3-33

EJBs, entity beans, 3-33

implementing in Java, 3-100

in transformation mapping, 3-70

example, 3-70

one-to-many mappings, 3-17

proxy indirection, 3-29

resolving issues with serialization, 3-35

transparent indirection, 3-32

working with, 3-27

Informix

using native sequencing, 5-12

inheritance

creating hierarchy in Java, 3-95

described, 3-5, 3-47

EJBs, entity beans, 3-55

entity bean restrictions, 3-55

home interface, 3-55

implementing in Java, 3-95

leaf classes, 6-81

querying on hierarchy, 6-81

transformed to relational model, 10-24

working with, 3-47

inheritance hierarchies

querying on, 6-81

InheritancePolicy method, 3-100

in-memory queries

described, 6-7

in-memory query, 6-62

check cache using exact primary key, 6-62

check cache using primary key, 6-62

check database if not in cache, 6-62

conform results in Unit of Work, 6-62

using, 6-62

insert operation, 6-39, 6-40

InsertObjectQuery, 6-42

instantiation policy

implementing in Java, 3-88

methods, 3-88

overriding in Java, 3-88

integrity checker, 4-66

interfaces

implementing in Java, 3-101

querying on, 6-81

internal query object cache, 6-7, 6-76

isolation

cache, 8-5

Iterator interface, 6-82

J2EE containers

non-CMP configuration, B-2

jars

common deployment errors, C-118

Java and database type conversion tables, A-22

Java database

managing type conversions with Schema Manager, A-22

Java iterators

described, 6-82

Java objects

described, 3-60

merging changes under EJB1.1, 3-63

serializing between client and server under EJB 1.1, 3-63

Java streams

described, 6-83

optimizing, 6-84

support for, 6-83

Java Transaction API

and Unit of Work, 7-3

and Unit of Work commit, 7-9, 7-10

and Unit of Work Rollback, 7-10

Java Transaction Service (JTS), 5-8

java.security.AccessControlException, C-123, C-124

JavaSourceGenerator, 9-10

JConnect (Sybase), 4-49

JDBC

login in the sessions.xml file, 4-14

JDBC 2.0 DataSources, 5-13

JDBC-ODBC bridge, 5-10

JMS Processing Exception, C-111

join reading

in query objects, 6-72

joining, 10-9

joins, outer, 6-72

JTA

OracleAS TopLink support, 7-46

JTA (Java Transaction API)

OracleAS TopLink integration, 5-8

keys

foreign, 3-17, A-20

primary, A-20

primary, composite, 3-18

large result sets, managing in finders, 6-99

leaf class, 3-52

leaf classes, 6-81

locking

pessimistic, 5-24

locking policies

implementing in Java, 3-107

logging into the database, 5-8

logging out, 4-49

login class

creating for projects created in OracleAS TopLink Mapping Workbench, 5-9

creating for projects not created in OracleAS TopLink Mapping Workbench, 5-8

login parameters

setting in code, 5-10

logs

chained exceptions, 4-65

manager, session events, 4-69

manual transactions, 4-49

many-to-many mappings, 3-27

with EJBs, 3-27

working with, 3-26

mapping

aggregate collection mappings and EJBs, 3-24

as part of the application development process, 1-13

attribute, 3-20

bidirectional relationships, 3-17

described, 3-3

direct, described, 3-5

EJB 2.0 restrictions not enforced by OracleAS TopLink, 3-15

object type, 3-14

relationship, 3-20

relationship, described, 3-5

serialized object, 3-71

transformation, 3-69

type conversion, 3-13

mappings

aggregate collections, 3-22

aggregate object, 3-19

aggregate object, with EJBs, 3-20

between entity beans, 3-15

between entity beans and Java objects, 3-16

BLOB fields, 3-71

creating, 3-7

creating in Java, 3-89

described, 3-7

direct, 3-8

direct collection, 3-25

direct mappings, 3-8

direct-to-field, 3-9

many-to-many, 3-26, 3-27

many-to-many, with EJBs, 3-27

object type, 3-13

one-to-many, 3-21

one-to-many object, with EJBs, 3-22

one-to-one, 3-17

one-to-one with EJBs, 3-19

OracleAS TopLink metadata, 1-11

relationship, 3-14

serialized object, 3-71

type conversion, 3-12

message transport

overview, 8-4

Message-driven beans, described, 3-57

messages, error, C-4

metadata

project.xml file, 1-11

metadata model, described, 3-3

methods

addDirectMapping(), 3-9

addField(), A-20

addForeignKeyConstraint(), A-20

addIdentityField(), A-20

addPrimaryKeyField(), A-20

addTableName, 3-102

addToAttributeOnlyConversionValue(), 3-13

clearProfiler(), 10-4, 10-5

copy policy, 3-101

createObject(), A-21

described, 3-60

in Java objects, 3-60

instantiation, 3-88

replaceObject(), A-21

setDefaultAttributeValue(), 3-13

setName(), A-20

setProfiler(), 10-4, 10-5

wrapper policy, 3-89

Microsoft SQL Server

native sequencing, 5-12

module visibility

in IBM WebSphere, B-4

multiple read connections

overview, 4-44

Multiple Table Mappings

using, 3-46

multiple tables

implementing in Java, 3-102

implementing in Java when primary keys are named differently, 3-103

implementing in Java when primary keys match, 3-102

implementing in Java when related by foreign key, 3-104

implementing in Java, non-standard table relationships, 3-105

multi-processing, 10-20

name service

configuring, 8-9

overview, 8-4

named finders

using, 6-50

named queries

defining, overview, 6-50

using, 6-48

native sequencing, 3-43, 5-12

configuring in the sessions.xml file, 4-18

Microsoft SQL Server, A-21

Oracle, 3-40, 3-41, A-22

Oracle SEQUENCE object, 3-42

Sybase, A-21

nested table mappings

about, 3-78

Java, 3-78

NestedTableMapping class, 3-78

non-cascading write queries

compared to cascading, 6-68

creating using dontCascadeParts ( ) method, 6-68

non-standard table relationships

implementing in Java, 3-105

object array mapping

about, 3-75

object array mappings

implementing in Java, 3-75

object identity, 4-28, 4-48

object indirection, 10-8

object model, 4-33, 6-37, 10-21

object reading, partial, 10-9

object relationships

working with, 3-46

object type mapping

example, 3-14

object type mappings

using, 3-13

object, cache, 5-29

object-relational descriptors

implementing in Java, 3-93

ObjectRelationalDescriptor class, 3-93

objects

as query results, 6-60

cascading refresh in cache, 6-66

creating and editing in Web Client, A-11

query, 6-34

refreshing in cache, 6-66

searching with OracleAS TopLink Web Client, A-8

ObjectTypeMapping class, 3-13

one-to-many mapping

example, 3-21

Java, 3-21

one-to-many mappings, 3-21

OneToManyMapping class, 3-21

one-to-one mapping

example, 3-18

Java, 3-17

one-to-one mappings

with EJBs, 3-19

working with, 3-17

OneToOneMapping class, 3-17

operators

boolean logic, 6-14

optimistic lock

overview, 5-20

Optimistic Lock Exception, C-54

optimistic locking, 5-21, C-54

database exception, 6-101

field locking policy, 5-29

optimistic read lock

overview, 5-20

OptimisticLockException class, 5-29

optimization

data, 5-16

performance, 10-1

schema, 10-21

Oracle

field types, 5-4, A-22

remote session support, 4-60

using native sequencing, 5-12

Oracle Application Server Containers for J2EE

setting class path, B-3

Oracle extensions

hierarchical queries, 6-78

Oracle Hints, 6-77

support, 6-76

Oracle Hints

described, 6-77

Oracle JDeveloper, configuring with OracleAS TopLink, A-15

Oracle native sequencing, 3-40, 3-41

SEQUENCE object, 3-42

OracleAS TopLink, 1-4

advantages, 1-3

application development overview, 1-12

problem space, 1-2

OracleAS TopLink container-managed persistence

configuring, B-7

configuring for BEA WebLogic, B-7

software requirements, B-2

OracleAS TopLink deploy tool for IBM WebSphere, A-17

OracleAS TopLink descriptors

creating in Java, 3-89

customizing with amendment methods, 3-82

OracleAS TopLink Exceptions

development exceptions, C-2

runtime exceptions, C-2

OracleAS TopLink Expression Framework

defining named queries, 6-50

described, 6-5

using, 6-51

OracleAS TopLink file

metadata, 1-11

OracleAS TopLink Foundation Library

overview, 1-7

OracleAS TopLink Mapping Workbench

defined queries, 6-56

overview, 1-5

using with entity beans, 3-47

OracleAS TopLink metadata

descriptors, 1-11

mappings, 1-11

OracleAS TopLink sessions

OracleAS TopLink Web Client, A-6

OracleAS TopLink Sessions Editor

overview, 1-6

OracleAS TopLink Web Client

executing SQL, A-12

searching objects, A-8

OracleAS TopLink with containers

software requirements, B-2

OrbixWeb, 4-60

outer joins, 6-72

in expressions, 6-72

output parameter event

in stored procedures, 6-30

packaging

as part of the application development process, 1-15

parameter binding, 5-17

parameterized expressions

example, 6-21

parameterized SQL

described, 5-17

enabling on queries, 6-45

in query objects, 6-45

OracleAS TopLink optimization features, 10-17

partial attribute reading

query objects, 6-76

partial object reading, 10-9

performance optimization

described, 10-1

examples, 10-9

using Performance Profiler, 10-3

Performance Profiler, 10-3

class, 10-4

performance tuning

as part of the application development process, 1-15

persistence descriptor, 9-11

persistence descriptor, in BEA WebLogic deployment, 9-11

persistent classes

registering events, 3-84

persistent classes in Java objects, 3-60

persistent entities, described, 3-3

persistent entity beans, 3-59

persistent state, 3-60

pessimistic lock

overview, 5-20

pessimistic locking

described, 5-24

example, 5-26

pinning

overview, B-9

with session beans, B-10

with user transactions, B-9

platform functions, in expressions, 6-22

pooling, connection, 4-43

preallocation, in sequencing, 3-39

predefined queries

described, 6-10

EJBs and finders, 6-53

named finders, 6-50

named queries, 6-48

redirect queries, 6-52

using, 6-48

preferences

Web Client, A-14

Preferences tab (Web Client), A-15

primary key

addPrimaryKeyField(), A-20

composite, 3-18

implementing in Java, 3-94

primary keys

defined, 3-6

entity beans, 3-37

Profiler, 4-66

profiler development tool, 10-3

Profiler tab (OracleAS TopLink Web Client), A-14

project

deployment overview, 9-2

projects

described, 3-3

proxy indirection, 3-29

descriptor configuration, 3-30

implementing, 3-30

implementing in Java, 3-29

model configuration, 3-30

queries

advanced options, 6-79

basics, 6-12

cache, 6-61

cascading, 6-68

concepts, 6-3

cursored streams, 6-81

defined in OracleAS TopLink Mapping Workbench, 6-56

exception handling, 6-101

on inheritance hierarchies, 6-81

on interfaces, 6-81

overview, 1-8

query keys, creating, 6-79

scrollable cursor, 6-81

session queries, 6-37

SQL, 6-27

variable one-to-one mappings, 6-85

queries, named

defining, 6-50

defining under EJB QL, 6-50

defining under OracleAS TopLink framework

defining named queries, 6-50

defining under SQL, 6-50

query

report, 10-9

query basics

custom SQL, 6-27

EJB QL, 6-31

expressions, 6-12

query by example, 6-34

stored procedures, 6-29

query by example, 6-34

combining with expressions, 6-36

described, 6-5

example policy, 6-35

sample instance, 6-34

Query Exception, C-56

query keys

creating, 6-79

implementing in Java, 6-80

in expressions, 6-24

query mechanisms

EJB finders, 6-11

predefined queries, 6-10

query methods, 6-37

query objects

batch reading, 6-70

caching results, 6-7, 6-76

components, 6-41

creating, 6-42

creating, overview, 6-42

cursoring and ReadAll queries, 6-46

DataModifyQuery

described, 6-42

DataReadQuery

described, 6-42

DeleteObjectQuery

described, 6-42

DirectReadQuery

described, 6-42

examples, 6-43, 6-44

executing, 6-41

executing queries in, 6-42

InsertObjectQuery

described, 6-42

join reading, 6-72

ordering for ReadAll queries, 6-44

parameterized SQL, 6-45

partial attribute reading, 6-76

performance, 6-70

query optimization, 6-46

query types, 6-42

read query objects, 6-42

ReadAllQuery

described, 6-42

ReadObjectQuery

described, 6-42

relationship to database, 4-49

report query, 6-73, 10-11

ReportQuery

described, 6-42

specifying collection class, 6-46

UpdateObjectQuery

described, 6-42

using in place of session methods, 6-67

ValueReadQuery

described, 6-42

WriteObjectQuery

described, 6-42

query results

caching, 6-67

collections, 6-60

objects, 6-60

reports, 6-61

streams, 6-60

using, 6-60

query timeout example, 6-48

query, report, 6-61, 6-73, 10-11

querying

as part of the application development process, 1-14

read all operation, 4-34, 6-39

read connections

multiple, 4-44

read operation, 4-34, 6-38

read queries

identity map cache refresh, 6-66

read query

cascading refresh of identity maps, 6-66

refreshing identity maps, 6-66

read query example, 10-5

read query objects, described, 6-42

ReadAll finders, 6-94

creating, 6-94

executing, 6-94

using, 6-94

ReadAll queries

cursoring in query objects, 6-46

ordering in query objects, 6-44

readAllObjects()

example, 4-35, 6-39

ReadAllQuery

in EJB QL, 6-32

reading, batch, 10-9

readObject()

example, 4-35, 6-38

redeployment, 9-23

redirect finders

using, 6-53

redirect queries

EJB finders, 6-53

using, 6-52

reference mapping

example, 3-78

in Java, 3-77

ReferenceMapping class, 3-77

refresh cache

described, 6-7

refresh operation, 6-39

relational mappings

about, 3-73

relationship

bidirectional, 3-17

relationship mapping

described, 3-5

EJB 2.0, 3-15

with EJBs, 3-14

relationship mappings

aggregate object, 3-19

described, 3-14

direct collection, 3-25

EJB 1.1, 3-15

EJB 2.0, 3-15

many-to-many, 3-26

one-to-many, 3-21

one-to-one, 3-17

with entity beans, 3-14

relationships

described, 3-60

relationships and entity beans, 3-14

Remote Command Manager Exception, C-114

remote connection using RMI

example, 4-62

Remote Session

architecture, 4-6

remote session, 4-58

replaceObject() method, A-21

report query

query objects, 6-73, 10-11

use case, 10-9

using, 6-61, 6-73, 10-11

ReportQuery, 6-42

reports

query results, 6-61

RMI

message optimization, 10-8

remote session support, 4-60

rollback

and Java Transaction API, 7-10

overview, 7-10

root class, 3-51

runtime exceptions, C-1, C-2

run-time issues

maintaining bidirectional relationships, 3-61

runtime problems, troubleshooting, C-126

runtime services

described, A-23

Schema Manager

creating tables, A-20

managing Java database type conversions, A-22

overview, A-19

schema manager, A-22

schema manager development tool, A-19

schema, optimization, 10-21

scrollable cursor

traversing, 6-82

using, 6-81

using for ReadAllQuery, 6-46, 6-82

SDK Data Store Exception, C-109

SDK Descriptor Exception, C-111

SDK Query Exception, C-112

Search tab (Web Client), A-8

searching

objects in sessions, A-8

security, 4-14

with BEA WebLogic, B-6

select methods

using, 6-95

SelectedFieldsLockingPolicy, 5-29

SEQ_COUNT column in sequence table, 3-40

sequence numbers

implementing in Java, 3-107

Microsoft SQL Server, A-21

preallocation, 10-19

specifying, 5-11

Sybase, A-21

write optimization features, 10-17

SEQUENCE objects in Oracle native sequencing, 3-42

sequence table, 5-12

sequencing

configuring in the sessions.xml file, 4-17, 4-18

defined, 3-6

described, 3-37

implementing class tables, 3-38

native, 3-43

native Oracle, 3-40

preallocation, 3-39

SEQ_COUNT, 3-40

table, 3-39

with BEA WebLogic, 3-44

with entity beans, 3-44

with IBM WebSphere, 3-44

with stored procedures, 3-45

serialization

defined, 3-6

limitations, 3-36

resolving indirection issues, 3-35

serialization, described, 3-34

serialized object mappings

about, 3-71

example, 3-71

Java, 3-71

SerializedObjectMapping class, 3-71

server layer, 4-61

Server Session

architecture, 4-5

defining in the sessions.xml file, 4-13

described, 4-38

overview of use, 4-37

Server Session connection options, 4-44

session

concepts, 4-2

loading with alternative class loader, 4-30

session bean model, 2-14

session beans

described, 2-14

model, 2-14

remote session support for, 4-60

session beans, described, 3-57

Session Broker

overview, 4-7

session broker, 4-53

adding sessions, 4-54

multiple sessions, 4-53

two-phase commits, 4-55

two-stage commits, 4-55

using, 4-53

session cache

overview, 8-2

session configuration file

loading alternative, 4-31

reparsing, 4-32

session described, 4-38

session event manager, 4-69

session listener class

described, 4-47

session management

as part of the application development process, 1-13

development services, A-23

runtime services, A-23

Session management services

described, A-22

Session Manager

destroying sessions, 4-33

retrieving a session, 4-29

session location, 4-29

storing sessions, 4-32

session queries, 6-37

executing, 6-37

in OracleAS TopLink query framework, 6-37

reading from database, 6-38

writing to database, 6-39

session query

using EJB QL, 6-33

session, remote, 4-58

SessionAccessor

merging dependent objects under EJB 1.1, 3-63

sessions

adding to session broker, 4-54

architectures, 4-4

caching, 4-4

Client Session, 4-2

Client Session architecture, 4-6

connecting to with OracleAS TopLink Web Client, A-6

connection pool, 4-4

Database Session, 4-3

Database Session architecture, 4-6

destroying in Session Manager, 4-33

multiple, 4-53

overview, 1-8

profiling, 4-4

Remote Session, 4-3

Remote Session architecture, 4-6

searching, A-8

Server Session, 4-2

Server Session architecture, 4-5

Session Broker, 4-3, 4-7

Session Manager, 4-3

session types, 4-2

sessions.xml, 4-2, 4-8

storing in Session Manager, 4-32

sessions, database, 4-48

sessions, logging out, 4-49

sessions.xml

cache-synchronization-manager element, 4-19

configuring sequence table, 4-18

connection-pool element, 4-23

defining a Database Session, 4-13

defining a Server Session, 4-13

enable-logging element, 4-25

event-listener-class element, 4-21

exception-handler-class element, 4-23

external-transaction-controller-class element, 4-22

loading alternative configuration file, 4-31

login element, 4-13

login using JDBC, 4-14

overview, 4-2, 4-8

profiler-class element, 4-22

reparsing, 4-32

reusing with XMLLoader, 4-31

sequencing elements, 4-17

session element, 4-10

session-type element, 4-12

toplink-configuration element, 4-10

using DataSource, 4-15

XML header, 4-10

setAttributeClassification(), 3-12

setAttributeName(), 3-12, 3-13, 3-68, 3-71

setAttributeTransformation(), 3-69

setDefaultAttributeValue(), 3-13

setFieldClassification(), 3-12

setFieldName(), 3-9, 3-12, 3-13, 3-71

setGetMethodName(), 3-69, 3-71

setName() method, A-20

setPrimaryKeyFieldName, 3-94

setProfiler() method, 10-4, 10-5

setSequenceNumberFieldName, 3-107

setSetMethodName(), 3-69, 3-71

setWrapperPolicy(), 3-89

shared library

setting for BEA WebLogic, B-6, B-8

soft cache weak identity map, 10-9

SQL, 5-4

binding and parameterizing, 5-17

custom, 4-35

parameterized, 10-17

queries, 6-27

using in a finder, 6-95

SQL DISTINCT, 10-14

SQL Exception, C-50

SQL queries, 6-27

described, 6-6

in OracleAS TopLink query framework, 4-35

in OracleAS TopLink Web Client, A-12

SQL Server

native sequencing, 5-12

SQL, parameterized, 6-45

stale data

overview, 8-3

stateful and stateless beans compared, 2-14

stateful beans, 2-14

stateful, stateless Session Beans, 3-57

stateless and stateful beans compared, 2-14

stateless beans, 2-14

static amendment methods, 3-82

Stored Procedure Generator

described, A-24

using, A-24

stored procedures, 6-29

attaching to descriptors, A-25

cursor output parameters, 6-30

described, 6-5

generating, A-24

output parameter event, 6-30

output parameters, 6-29

using, 6-29

using for sequencing, 3-45

streams

as query results, 6-60

streams, cursored, 4-62, 6-84

structure mappings

Java, 3-76

StructureMapping class, 3-76

subqueries

in expressions, 6-18

subselects

in expressions, 6-18

Sybase

JConnect2.x, 4-49

using native sequencing, 5-12

synchronous update mode

overview, 8-4

Table Definition

class, A-20

table sequencing, 3-39

configuring in the sessions.xml file, 4-18

tables

creator/qualifier, 5-19

three-tier applications

migrating to scalable architecture, 4-48

TimestampLockingPolicy, 5-29

toplink-ejb-jar.xml

BEA WebLogic, 9-6

IBM WebSphere, 9-5

toplinkwc.ear

OracleAS TopLink Web Client, A-4

transactions

as part of the application development process, 1-14

in OracleAS TopLink, 7-3

overview, 1-9, 7-1

transactions, manual, 4-49

transformation mappings

example, 3-69

indirection, 3-70

TransformationMapping class, 3-68

transparent indirection

working with, 3-32

transport layer, 4-60

troubleshooting, Unit of Work, 7-41

two-phase commits, 4-55

two-phase/two-stage commits, 4-55

two-stage commits, 4-55

type conversion mappings, 3-13

example, 3-13

using, 3-12

type conversions

managing in Java databases, A-22

TypeConversionMapping class, 3-12

undeployment, 9-23

Unit of Work, 10-8, 10-16

acquiring, 7-13

and Java Transaction API, 7-3

basics, 7-5

cache, 8-3

class, 6-37

clones, 7-7

commit, 7-9

commit and Java Transaction API, 7-9, 7-10

conform results of in-memory query, 6-62

conform results, described, 6-9

creating objects, 7-13

deleting objects, 7-20

nested, 7-40

overview, 7-3

parallel, 7-40

pre-commit validation, 7-41

queries, 7-9

reading objects, 7-9

read-only classes, 7-33, 7-34

remote sessions, 4-62

resuming after commit, 7-39

resuming on failure after commit, 7-39

reverting, 7-39, 7-40

rollback, 7-10

rollback and Java Transaction API, 7-10

updating methods in, 3-86

validating objects, 7-41

validation, 7-41

update operation, 6-39, 6-41

UpdateObjectQuery, 6-42

useAllFieldsLocking, 3-108

useAllFieldsLocking, 3-107

useChangedFieldsLocking, 3-108

useChangedFieldsLocking, 3-107

useCloneCopyPolicy(), 3-101

useCloneCopyPolicy(String), 3-101

useConstructorCopyPolicy(), 3-101

useDefaultConstructorInstantiationPolicy(), 3-88

useFactoryInstantiationPolicy(), 3-88

useMethodInstantiationPolicy(), 3-88

useProxyIndirection(), 3-29

user-defined functions, in expressions, 6-22

useSelectedFieldsLocking, 3-108

useSelectedFieldsLocking, 3-107

useTimestampLocking, 3-108

useTimestampLocking, 3-107

useVersionLocking, 3-107, 3-108

validation, 7-41

Validation Exception, C-72

ValueHolder Indirection

working with, 3-28

valueholders

triggering before serialization, 3-35

ValueReadQuery, 6-42

variable one-to-one mapping

querying, 6-85

VariableOneToOneMapping class, 3-72

Varray (Oracle). see array mappings

version fields, 5-21, 5-30

version locking policies, 3-107, 3-108, 5-21

VersionLockingPolicy, 5-29

VisiBroker, 4-60

weak identity map, 10-9

weak identity map, soft cache, 10-9

Web Client

configuring, A-3

connecting to session, A-6

creating objects, A-11

described, A-2

editing objects, A-11

WebLogic, 4-60

weblogic-ejb-jar.xml

described, 9-11

modifying for OracleAS TopLink, 9-11

unsupported tags, 9-12

WebSphere Studio Application Developer

Deploy Tool, A-18

web.xml

OracleAS TopLink Web Client, A-3

working with, 3-29

wrapper policy

implementing in Java, 3-89

setting in Java, 3-89

write all operation, 6-40

write query

disabling identity map cache, 6-69

non-cascading, 6-68

overview, 6-68

write query objects, 6-68

WriteObjectQuery, 6-42

writing, batch, 5-17, 10-17

XML Conversion Exception, C-116

XML loader

loading alternative session, 4-31

XML parsers

modifying the sessions.xml file, 4-10

XMLLoader

reusing the configuration file, 4-31