Java Developer’s Reference

Arya MirΛογισμικό & κατασκευή λογ/κού

28 Μαρ 2012 (πριν από 5 χρόνια και 4 μήνες)

750 εμφανίσεις



Java Developer’s Reference
VERSI ON 6.3



Copyright © 2009
Jade Software Corporation Limited
All rights reserved


Jade Software Corporation Limited cannot accept any financial or other responsibilities that may be the result of your use of this information
or software material, including direct, indirect, special or consequential damages, or loss of profits. There are no warranties extended or
granted by this document or software material.
You should be very careful to ensure that the use of this software material and/or information complies with the laws, rules, and regulations of
the jurisdictions with respect to which it is used. No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of Jade Software Corporation Limited.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.
Copyright © 2009 Jade Software Corporation Limited.
All rights reserved.
JADE is a trademark of Jade Software Corporation Limited. All trade names referenced are the service mark, trademark, or registered
trademark of the respective manufacturer.
For details about other licensing agreements for third party products, you must read the JADE ReadMe.txt file.
____________________________________
JavaDev-6.3
Contents



Before You Begin viii

Who Should Read this Reference......................................................................................................... viii

What's Included in this Reference........................................................................................................ viii

Related Documentation........................................................................................................................ viii

Conventions........................................................................................................................................... ix

Chapter 1

Using the Java Framework 11

Overview................................................................................................................................................. 12

Starting with Java Classes....................................................................................................................... 13

Starting with JADE Classes.................................................................................................................... 13

The Java Framework.............................................................................................................................. 13

Java Persistence in JADE........................................................................................................................ 14

How a Java Application Connects to JADE.......................................................................................... 14

Chapter 2

JADE Object Model and Java Persistence 16

Overview................................................................................................................................................. 17

JADE Object Model............................................................................................................................... 17

Types....................................................................................................................................................... 18

Objects and Classes................................................................................................................................ 18

Object Lifetimes............................................................................................................................. 18

Features.................................................................................................................................................. 18

Properties............................................................................................................................................... 19

Methods.................................................................................................................................................. 19

Conditions...................................................................................................................................... 19

Constraints...................................................................................................................................... 20

Encapsulation......................................................................................................................................... 20

Inheritance and Polymorphism............................................................................................................ 21

Schemas.................................................................................................................................................. 21

Applications........................................................................................................................................... 22

Relationship between Schemas and Applications........................................................................ 22

JADE Language...................................................................................................................................... 22

Exception Handling.............................................................................................................................. 23

System Exceptions.......................................................................................................................... 23

User Exceptions............................................................................................................................. 23

JADE Java
Developer’s Reference
Contents iv
JavaDev-6.3
Chapter 2

JADE Object Model and Java Persistence, continued

JADE Object Manager........................................................................................................................... 23

What the JADE Object Manager Handles.................................................................................... 24

Java Persistence in JADE API......................................................................................................... 25

EntityManager Class....................................................................................................................... 25

Chapter 3

Annotating Java Classes 26

Overview................................................................................................................................................. 27

Annotation to Persist a Java Class......................................................................................................... 27

Required Property for Persistence........................................................................................................ 28

Unique Identifier........................................................................................................................... 28

Types of Java Property that Can Be Persisted....................................................................................... 28

Field................................................................................................................................................ 28

Virtual Property.............................................................................................................................. 29

Annotations to Persist a Java Property.................................................................................................. 29

@Id Annotation.............................................................................................................................. 29

@DbField Annotation.................................................................................................................... 29

@Lob Annotation........................................................................................................................... 30

@DbProperty Annotation.............................................................................................................. 30

Optional Attributes for the @DbField and @DbProperty Annotations...................................... 33

Relationship Annotations...................................................................................................................... 33

@OneToOne Annotation.............................................................................................................. 34

inverse Attribute..................................................................................................................... 34

relationshipType Attribute.................................................................................................... 35

updateMode Attribute........................................................................................................... 36

transientToPersistentAllowed Attribute................................................................................ 37

@OneToMany and @ManyToOne Annotations.......................................................................... 38

inverse Attribute..................................................................................................................... 39

exclusive Attribute.................................................................................................................. 40

relationshipType Attribute.................................................................................................... 40

updateMode Attribute........................................................................................................... 41

transientToPersistentAllowed Attribute................................................................................ 42

constraint Attribute................................................................................................................ 44

inverseNotRequired Attribute............................................................................................... 45

@ManyToMany Annotation.......................................................................................................... 46

@Conditions and @Condition Annotations................................................................................. 46

@JadeMethod Annotation............................................................................................................. 47

JADE Method Calls................................................................................................................................ 48

JADE Method Parameter Usage.................................................................................................... 48

io Usage Type......................................................................................................................... 49

output Usage Type................................................................................................................. 49

Primitive Parameters.............................................................................................................. 50

Multiple Parameters............................................................................................................... 50

Application and Global Classes............................................................................................................. 50

@ApplicationEntity Annotation.................................................................................................... 50

@GlobalEntity Annotation............................................................................................................ 50

Collections.............................................................................................................................................. 51

@CollectionEntity Annotation...................................................................................................... 51

@DictionaryKey Annotation.......................................................................................................... 52

JADE Java
Developer’s Reference
Contents v
JavaDev-6.3
Chapter 3

Annotating Java Classes, continued

Package Annotation............................................................................................................................... 52

persistence.xml File....................................................................................................................... 53

Chapter 4

Developing Applications in Java to Use Annotated Classes 55

Overview................................................................................................................................................. 57

How to Use Java Persisted Classes......................................................................................................... 57

Signing On To JADE...................................................................................................................... 57

Subsequent Processing.................................................................................................................. 57

Creating Objects............................................................................................................................. 58

Working with Virtual Properties in the Database........................................................................ 58

Handling Lock Exceptions in Java................................................................................................ 59

Signing Off From JADE................................................................................................................. 60

Persistence Class.................................................................................................................................... 60

createEntityManagerFactory.......................................................................................................... 60

EntityManagerFactory Class.................................................................................................................. 60

close................................................................................................................................................ 60

createEntityManager...................................................................................................................... 60

isOpen............................................................................................................................................. 61

EntityAccess Class.................................................................................................................................. 61

getBLOBProperty........................................................................................................................... 61

getBinaryProperty.......................................................................................................................... 61

getBooleanProperty....................................................................................................................... 62

getByteProperty.............................................................................................................................. 62

getCharacterProperty.................................................................................................................... 62

getDateProperty............................................................................................................................. 62

getDecimalProperty....................................................................................................................... 63

getInteger64Property..................................................................................................................... 63

getIntegerProperty......................................................................................................................... 63

getMemoryAddressProperty.......................................................................................................... 64

getPointProperty............................................................................................................................ 64

getRealProperty.............................................................................................................................. 64

getReferenceProperty.................................................................................................................... 64

getSLOBProperty........................................................................................................................... 65

getStringProperty........................................................................................................................... 65

getStringUtf8Property................................................................................................................... 65

getTimeProperty............................................................................................................................ 66

getTimeStampIntervalProperty..................................................................................................... 66

getTimeStampProperty.................................................................................................................. 66

setBLOBProperty........................................................................................................................... 66

setBinaryProperty........................................................................................................................... 67

setBooleanProperty........................................................................................................................ 67

setByteProperty.............................................................................................................................. 67

setCharacterProperty..................................................................................................................... 68

setDateProperty.............................................................................................................................. 68

setDecimalProperty........................................................................................................................ 68

setInteger64Property..................................................................................................................... 69

setIntegerProperty......................................................................................................................... 69

setMemoryAddressProperty........................................................................................................... 69

JADE Java
Developer’s Reference
Contents vi
JavaDev-6.3
Chapter 4

Developing Applications in Java to Use Annotated Classes, continued

setPointProperty............................................................................................................................. 70

setRealProperty.............................................................................................................................. 70

setReferenceProperty..................................................................................................................... 70

setSLOBProperty............................................................................................................................ 71

setStringProperty............................................................................................................................ 71

setStringUtf8Property.................................................................................................................... 71

setTimeProperty............................................................................................................................. 72

setTimeStampIntervalProperty..................................................................................................... 72

setTimeStampProperty.................................................................................................................. 72

EntityManager Class.............................................................................................................................. 73

addLockExceptionHandler........................................................................................................... 73

beginLoad....................................................................................................................................... 73

beginLock....................................................................................................................................... 73

beginNotification........................................................................................................................... 74

causeEvent...................................................................................................................................... 74

clear................................................................................................................................................. 74

close................................................................................................................................................ 75

contains........................................................................................................................................... 75

createObject................................................................................................................................... 75

edition............................................................................................................................................. 75

endLoad.......................................................................................................................................... 76

endLock.......................................................................................................................................... 76

endNotification.............................................................................................................................. 76

exclusiveLock................................................................................................................................. 76

find.................................................................................................................................................. 77

firstInstance.................................................................................................................................... 77

getApp............................................................................................................................................. 77

getGlobal........................................................................................................................................ 77

getLockExceptionHandlers........................................................................................................... 77

getNode.......................................................................................................................................... 78

getProcess....................................................................................................................................... 78

getSystem........................................................................................................................................ 78

getTransaction................................................................................................................................ 78

instances......................................................................................................................................... 78

isLockedByMe................................................................................................................................ 78

isOpen............................................................................................................................................. 79

merge.............................................................................................................................................. 79

persist.............................................................................................................................................. 79

refresh............................................................................................................................................. 79

remove............................................................................................................................................ 80

removeLockExceptionHandler..................................................................................................... 80

sharedLock..................................................................................................................................... 80

EntityTransaction Class......................................................................................................................... 80

begin............................................................................................................................................... 80

commit............................................................................................................................................ 81

isActive............................................................................................................................................ 81

rollback........................................................................................................................................... 81

Collection Class...................................................................................................................................... 81

JADE Java
Developer’s Reference
Contents vii
JavaDev-6.3
Chapter 4

Developing Applications in Java to Use Annotated Classes, continued

Array Class.............................................................................................................................................. 82

Dictionary Class...................................................................................................................................... 83

Example of Reimplementing the getAtKey Method.................................................................... 84

Chapter 5

Creating a JADE Schema from Annotated Java Classes 85

Overview................................................................................................................................................. 86

userClasses Parameter.................................................................................................................... 86

persistenceUnitName Parameter.................................................................................................. 86

validate Parameter......................................................................................................................... 87

Output from the Annotation Processor............................................................................................... 87

Index 88

____________________________________
JavaDev-6.3

Before You Begin
____________________________________
The JADE Java Developer’s Reference is intended as a major source of information when using the
Java class library to develop JADE applications from a Java integrated development environment.
Who Should Read this Reference
The main audience for the JADE Java Developer’s Reference is expected to be Java developers of
JADE applications.
What's Included in this Reference
The JADE Java Developer’s Reference has five chapters.
Chapter 1 Using Java to develop or maintain a JADE schema
Chapter 2 Gives a reference to JADE object model and Java persistence
Chapter 3 Gives a reference to Java annotated classes
Chapter 4 Developing applications in Java to use annotated classes
Chapter 5 Creating a JADE schema from Java annotated classes
Related Documentation
Other documents that are referred to in this reference, or that may be helpful, are listed in the
following table, with an indication of the JADE operation or tasks to which they relate.
Title Related to…
JADE Database Administration Guide Administering JADE databases
JADE Developer’s Reference Developing or maintaining JADE applications
JADE Development Environment Administration Guide Administering JADE development environments
JADE Development Environment User’s Guide Using the JADE development environment
JADE .NET Deveoper’s Reference Developing applications using .NET class libraries exposed in
JADE
JADE Encyclopaedia of Classes System classes (Volumes 1 and 2), Window classes (Volume 3)
JADE Encyclopaedia of Primitive Types Primitive types and global constants
JADE Installation and Configuration Guide Installing and configuring JADE
JADE Initialization File Reference Maintaining JADE initialization file parameter values
JADE Object Manager Guide JADE Object Manager administration
JADE Replication Framework User’s Guide Replicating selective activity between physically different but
logically similar JADE systems
JADE Java
Developer’s Reference
Before You Begin ix
JavaDev-6.3
Title Related to…
JADE Synchronized Database Service (SDS) Administration Guide Administering JADE Synchronized Database Services (SDS),
including Relational Population Services (RPS)
JADE Thin Client Guide Administering JADE thin client environments
JADE Web Application Guide Implementing, monitoring, and configuring Web applications
Conventions
The JADE Java Developer’s Reference uses consistent typographic conventions throughout.
Convention Description
Arrow bullet () Step-by-step procedures. You can complete procedural instructions by using either the mouse or the
keyboard.
Bold Items that must be typed exactly as shown. For example, if instructed to type foreach, type all the
bold characters exactly as they are printed.
File, class, primitive type, method, and property names, menu commands, and dialog controls are also
shown in bold type, as well as literal values stored, tested for, and sent by JADE instructions.
Italic Parameter values or placeholders for information that must be provided; for example, if instructed to
enter class-name, type the actual name of the class instead of the word or words shown in italic type.
Italic type also signals a new term. An explanation accompanies the italicized type.
Document titles and status and error messages are also shown in italic type.
Blue text Enables you to click anywhere on the cross-reference text (the cursor symbol changes from an open
hand to a hand with the index finger extended) to take you straight to that topic. For example, click on
the “Developing Applications in Java to Use Annotated Classes” cross-reference to display that topic.
Bracket symbols ( [ ] ) Indicate optional items.
Vertical bar ( | ) Separates alternative items.
Monospaced font Syntax, code examples, and error and status message text.
ALL CAPITALS Directory names, commands, and acronyms.
SMALL CAPITALS
Keyboard keys.
Key combinations and key sequences appear as follows.
Convention Description
KEY1+KEY2
Press and hold down the first key and then press the second key. For example, “press
SHIFT+F2

means to press and hold down the
SHIFT
key and press the
F2
key. Then release both keys.
KEY1,KEY2
Press and release the first key, then press and release the second key. For example, “press
ALT+F
,
X

means to hold down the
ALT
key, press the
F
key, and then release both keys before pressing and
releasing the
X
key.
In this document, the term Microsoft Windows refers to Windows 2003 Server, Windows Vista,
Windows XP, Windows 2000, or Windows CE. When there are differences between the versions of
Microsoft Windows, the specific version of Microsoft Windows is stated. This also applies to Linux,
which is a specific version of UNIX developed by SUSE or Red Hat. The term UNIX is used when
an issue is generic to all versions of UNIX and the term Linux is used if the issue is specific to the
SUSE or Red Hat implementation of UNIX.
JADE Java
Developer’s Reference
Before You Begin x
JavaDev-6.3
With the exception of the jade.exe program, when referring to Windows program executables in
this document, the .exe file suffix is omitted; for example, jadclient refers to jadclient.exe on
Windows and jadclient.sh on UNIX. Similarly, the Windows .dll (Dynamic Link Library) and
UNIX .so (shared object library) file suffixes are omitted. For example, jomos refers to jomos.dll
(Windows) and libjomos.so (Linux).
____________________________________
JavaDev-6.3
Chapter 1 Using the Java Framework
____________________________________
This chapter covers the following topics.

Overview

Starting with Java Classes

Starting with JADE Classes

The Java Framework

Java Persistence in JADE

How a Java Application Connects to JADE
JADE Java
Developer’s Reference
Chapter 1 Using the Java Framework 12
JavaDev-6.3
Overview
The purpose of the Java framework provided by JADE is to enable Java objects to be persisted in
JADE. A Java object acts as a proxy for its persisted JADE counterpart.

The term persistence usually implies that there are objects that continue to exist, even when the
application is not running. The above diagram shows a Java object that exists while the application
is running and the corresponding JADE object that has a more-permanent existence, as it is stored
in the JADE database.
However, the persistence mechanism allows for a Java class to be tagged as transient. In this case,
corresponding JADE objects exist but they are not stored in the persistent JADE database. A
more-accurate description of the persistence mechanism is that JADE objects (which correspond
to Java objects) exist but you can choose whether they are stored in the JADE database.
The class of a Java object to be persisted objects must exist within the Java environment and also
in the JADE environment, as shown in the following diagram.

In building an application, you can start at either end. You can build your system entirely in Java
and generate the JADE persistence classes from your Java system. Alternatively, you can start by
defining the classes that require persistence in JADE and generate the Java classes from your
JADE system. For more details, see the following sections.
user (package)
Sale «abstract»
RetailSale
TenderSale
annotate with @Entity
to persist a class in JADE
user (schema)
Sale «abstract»
RetailSale
TenderSale
proxy persisted
JADE Java
Developer’s Reference
Chapter 1 Using the Java Framework 13
JavaDev-6.3
Starting with Java Classes
The Java framework provides all of the functionality required to add persistence to an application
that has been developed in Java. This approach consists of the following steps.
1. Use Java to write the classes in your application in a standard way, and then add annotations
to indicate the classes and features that are to be persisted in JADE. For details, see
Chapter 3, “Annotating Java Classes”.
2. Add instructions to your Java code relating to persistence and transaction control. For
details, see Chapter 4, “Developing Applications in Java to Use Annotated Classes”.
3. Use the Annotation Processor utility to automatically generate JADE schema and forms
definition files from your Java classes. For details, see Chapter 5, “Creating a JADE Schema
from Java Annotated Classes”.
4. Load the generated files into JADE (for example, by using the batch JADE Schema Load
utility, documented under “Loading a Schema and Forms in Batch Mode”, in the JADE
Schema Load Utility User’s Guide).
As JADE methods can be called from Java, you can also use Java classes as method parameters and
return types. For details, see “Parameters” and “Return Type”, under “JADE Language Notation”,
in Chapter 1 of the JADE Developer’s Reference.
Starting with JADE Classes
If application development in Java has not started and the Java classes do not yet exist, you could
begin by defining the persistence classes in JADE. Essentially, you would use Java to write the
application-related components of your system and JADE for the database-related components.
The approach consists of the following steps.
1. Use JADE to define the classes for your Java application.
2. Define a Java exposure and generate Java source files as the starting point for building the
application in Java. The Java class definitions contain the fields and properties with all of
the required annotations for persistence in the JADE database. For more details, see “Using
the Java Exposure Wizard”, in Chapter 17 of the JADE Development Environment User’s Guide.
3. Copy the Java source files into your Java development environment and build the
application in the standard way.
4. Add instructions to your Java code relating to persistence and transaction control. For
details, see Chapter 4, “Developing Applications in Java to Use Annotated Classes”.
The Java Framework
The Java framework requires Java version 1.5 or higher, as it uses features such as annotations,
enums, and generics introduced in that version. It is implemented as a Java library that provides:

A set of Java classes released as a single Java Archive (.jar) file

The JADE Java API specification, which is released as a single Java Archive (.jar) file called
javajom-doc.jar and is installed in the \documentation directory

The Application Programming Interface (API) to Java and interfaces with a C++ DLL
JADE Java
Developer’s Reference
Chapter 1 Using the Java Framework 14
JavaDev-6.3

A javajom.dll (Windows) or javajom.so (UNIX) file that communicates with the JADE
system

A Java utility to generate a JADE schema from annotated Java classes to carry the class
descriptions across to JADE
The following diagram shows the relationship between these components.

Java Persistence in JADE
JADE has an object model including class hierarchies that is similar to that of Java.
Because of the common object-oriented approach, there is a natural fit between JADE and Java,
which enables Java objects to be persisted in the JADE database.
Object persistence is an integral part of the JADE product.
For a brief overview of object-oriented model followed by JADE and an introduction to the JADE
terminology that is used throughout this reference, see Chapter 2, “JADE Object Model and Java
Persistence”.
How a Java Application Connects to JADE
A Java runtime application connects to a JADE system as a standard JADE client using the
javajom.dll library file on Windows or javajom.so on UNIX in conjunction with the
persistence.xml configuration file. For more details about Java code that causes the sign-on, see
“Signing On To JADE”, in Chapter 4.

JADE IDE
Java IDE
Java App
Java JOM
JADE App
JADE Object
Manager
x.scm
x.java
C-API
JNI
Java Application
javajom.dll
JADE Database
JADE
Database
JADE jar
JADE Java
Developer’s Reference
Chapter 1 Using the Java Framework 15
JavaDev-6.3
The persistence.xml file, in addition to listing persisted classes, contains information used to attach
to and sign on to the JADE system. For more details, see “persistence.xml File”, in Chapter 3.
The javajom.dll file is one of the files installed as part of a standard JADE client installation, and is
located typically in a directory C:\ Jade63\bin. You must add this directory to the Windows PATH
variable. In addition, you must set the java.library.path Java system property to C:\ Jade63\bin by
using the –D option when invoking the application from the command line, as shown in the
following example.
java –Djava.library.path="C:\Jade63\bin" class_name
____________________________________
JavaDev-6.3
Chapter 2 JADE Object Model and Java Persistence
____________________________________
This chapter covers the following topics.

Overview

JADE Object Model

Types

Objects and Classes

Object Lifetimes

Features

Properties

Methods

Conditions

Constraints

Encapsulation

Inheritance and Polymorphism

Schemas

Applications

Relationship between Schemas and Applications

JADE Language

Exception Handling

System Exceptions

User Exceptions

JADE Object Manager

What the JADE Object Manager Handles

Java Persistence in JADE API

EntityManager Class
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 17
JavaDev-6.3
Overview
JADE has an object model including class hierarchies that is similar to that of Java. JADE also
provides object persistence as an integral part of the product.
As JADE and Java are both object-oriented, there is a natural fit between them and Java objects
can be persisted as JADE objects with none of the relational to object impedance mismatches
found using a relational database. Java objects can be persisted in a natural object-oriented way
using the underlying JADE database.
The JADE environment includes the following features.

Multiuser capability

Automatic reorganization of changed class definitions

Automatic database recovery

Automatic referential integrity
JADE Object Model
JADE enables you to model and construct your information systems in terms of a set of
self-contained components called objects.
The JADE definition of objects and the ways in which they are organized and interact with each
other together constitute the JADE object model.
The JADE object model:

Combines data and operations into objects

Uses messages to communicate between objects

Groups similar objects into classes

Maintains a class hierarchy to provide inheritance of data and procedures
The JADE object model consists of a set of abstract concepts and definitions. Its concrete
implementation is achieved primarily in terms of the JADE Object Manager.
The JADE Object Manager is a central and fundamental component of the overall JADE
architecture. It supports all aspects of the JADE object model, including:

Object creation and deletion

Message passing

Determining run time behavior based on the class of an object

Managing efficient storage and retrieval of objects and relationships in the database
For more details, see “JADE Object Manager”, later in this chapter.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 18
JavaDev-6.3
Types
In JADE, types characterize the behavior that can be applied to an instance or value. Types are:

Classes, which group similar objects, including a definition of the data those objects contain
(properties), and the actions they can perform (methods).
Classes encapsulate structure and operations into a cohesive software unit, which hides the
implementation details while exposing only the interface to the class; for example, Employee
would be a class in a human resources system.

Primitive types, which have a defined null value that can be tested for by using the null
language identifier.
Properties defined as primitive types represent a value, and not a reference to an object.

Interfaces, which enable non-related classes to be grouped to capture their similarities,
without the need to artificially force a class relationship.
This mechanism provides a set of methods that are guaranteed to be available on any
implementing class. (For more details, see, “Adding and Maintaining Interfaces”, in Chapter
15 of your JADE Development Environment User’s Guide.)
Objects and Classes
An object is any entity, either real or abstract, that exhibits some well-defined behavior and that has
a unique identity.
A class groups all objects that share the same set of properties and methods. Every object is an
instance of one, and only one, class. A class describes the common characteristics of a set of
objects. An object is often referred to as an instance of the class that describes it.
For details about defining your own classes, see “Defining Your Own Classes”, in Chapter 3 of your
JADE Development Environment User’s Guide.
Object Lifetimes
A persistent object is stored in the database and remains accessible after the end of the process that
created it.
A transient object is not stored in the database and is destroyed when it is explicitly deleted or when
the process terminates.
One of the primary applications of persistent object storage is that of sharing objects between
several applications. This information sharing occurs at a very high level of semantics, because the
objects are not merely passive data but carry with them their behavior definition. In this context,
the JADE Object Manager can be used as a common repository for shared objects. It enables you
to apply the same design methods to the persistent and transient segments of your application.
Features
Features say something about or do something to objects. Features include properties (or data)
and methods (or operations).
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 19
JavaDev-6.3
Properties
Properties (attributes and references) represent the internal data storage of an object. The state of an
object at any time is determined by the values stored in each of its properties. Properties can be:

Attributes
Primitive variables such as numbers, strings, or boolean values (for example, age, name, and
gender)

Single-valued references
References to other objects

Multiple-valued references
References to collections of other objects (for example, a collection of employees in a
company object)
Properties can be public, protected, read-only, virtual, or subschema-hidden. If properties are
protected, they are exclusive to that object and cannot be accessed by any other object. There is
one copy of a property for each instance of a class.
The Java persistence in JADE Application Program Interface (API) allows access to public,
read-only, and protected properties. A JADE schema generated from annotated Java classes has
all properties declared as public and a Java exposure of JADE classes allows all types of properties
to be exposed. The runtime get and set property methods allow access to public, read-only, and
protected properties. For details about defining your own properties, see “Defining Properties”, in
Chapter 4 of your JADE Development Environment User’s Guide.
Methods
A method (procedural code) implements an aspect of the behavior of an object. Methods constitute
the procedural interface of an object. An object can invoke methods of another object, by sending
that object a message.
Objects cannot perform any action by themselves. You use methods to send messages to objects to
perform the appropriate actions.
A method may require parameters, and may return a result. The method that is executed is
determined at run time, based on the class of the object to which the message is sent.
Methods can also be public or protected. Public (and read-only) features represent the interface
of an object or the set of services the object provides to other objects in the system.
For details about defining your own methods, see “Defining and Compiling JADE Methods and
Conditions”, in Chapter 4 of your JADE Development Environment User’s Guide.
Conditions
A condition is a declarative restricted method that returns a Boolean result. Conditions cannot be
reimplemented from a superschema or superclass; that is, they are not polymorphic.
The boolean-expression that is returned can contain only references to the properties of the class and
calls to other conditional expressions of that class or its superclass.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 20
JavaDev-6.3
Any parameters that you specify can be constant parameters only. Only if and return instructions
can be used in condition methods.
For details about defining conditions, see “Adding Conditions to Classes or Primitive Types” under
“Defining and Compiling JADE Methods and Conditions”, in Chapter 4 of your JADE Development
Environment User’s Guide.
Constraints
A constraint is a condition used to maintain automatic inverse references when the specified
condition is satisfied.
A condition that is used as a constraint cannot have parameters. Only if and return instructions
can be used in a constraint condition.
Only automatic references can have a constraint. When the manual side of the inverse reference is
set, the condition used as the constraint is evaluated and the automatic inverse is set only if the
value of the condition is true. If the automatic reference is a Collection type, the condition is
applied to the members of the collection.
For details about defining constraint conditions, see “Adding Conditions to Classes or Primitive
Types” under “Defining and Compiling JADE Methods and Conditions”, in Chapter 4 of your
JADE Development Environment User’s Guide.
Encapsulation
Encapsulation is the clear separation between the external interface of a class and its internal
implementation; that is, the packaging together of properties and methods (or data and
operations) for an object.
Encapsulation hides the implementation (internal structure) of an object from the surrounding
system. Other objects can access only properties and methods that define the external
characteristics of the object.
An object can hide some or all of its implementation from other objects, but can provide methods
by which other objects can manipulate its internal state.
An object is like the proverbial engineering “black box”. You can change the way a method is
implemented without changing the object’s interface or its relationships with other objects.
You can hide implementation details to:

Protect an object from arbitrary and unintended use, or from accidental corruption.

Hide the implementation details of an object from the users of that object, so those users
understand the class interface rather than its implementation. This enables you to change
the implementation of an object without affecting other users of the object.
Properties are protected, by default.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 21
JavaDev-6.3
Inheritance and Polymorphism
Much of the power of object-orientation comes from arranging classes in a hierarchy. Classes that
are:

Higher in the hierarchy represent more-general characteristics

Lower in the hierarchy represent more-specific characteristics
Inheritance enables new classes to be defined as subclasses (derived classes) of existing superclasses
(base or parent classes).
The subclass automatically inherits the properties and methods (features) of the superclass. You
can also define your own properties and methods for a subclass or reimplement existing superclass
methods, to extend or modify the inherited behavior. You cannot reimplement conditions.
In JADE, a message can be sent to any object and the method that is executed depends on the
class of the object to which the message is sent.
The ability of an object to respond differently to a specific message, depending on its type, is
known as polymorphism; that is, it has the ability to assume several forms.
Schemas
A schema is the highest-level organizational structure in JADE, and represents the object model for
a particular domain. A schema is a logical grouping of classes, together with their associated
methods and properties. These effectively define the object model upon which your applications
are based.
JADE provides the RootSchema, which is always at the top of the schema hierarchy. The
RootSchema provides essential system classes; for example, the Object class (the root of the class
hierarchy), Collection classes, and the File, Exception, and Form classes. Because these classes are
defined in the RootSchema, they can be accessed from all subschemas.
You can add subschemas to the RootSchema. You can also add new classes to a schema, methods,
properties, and constants to a schema class, or methods and constants to an existing class defined
in a superschema. For details about defining user-defined schemas, see “Defining Your Own
Schema”, in Chapter 3 of your JADE Development Environment User’s Guide.
The following diagram is an example of the schema hierarchy.

JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 22
JavaDev-6.3
The schema hierarchy is analogous to a class hierarchy, and similar terminology is used. For
example, A1 and A2 are subschemas of A, while A is a superschema of A1 and A2, in the above
example.
Subschemas inherit all of the classes, methods, and properties that are defined in their
superschemas. Therefore in the above example, schema A1 would have access not only to its own
classes but also to those defined in A and the RootSchema. However, schemas on separate
branches of the hierarchy (for example, A1 and A2) cannot see each other at all, unless you use
packages to expose functionality across the schema hierarchy. If you do not use imported packages,
no part of A1 is directly accessible to A2, nor any part of A2 to A1.
As well as adding entirely new classes to a schema, you can also add methods or constants to an
existing class defined in a superschema. For example, schema A might add methods to the File
class (which is defined in the RootSchema) to perform functions that are relevant only in that
schema. Any such methods would be visible only in schema A and its subschemas; they would not
be visible in the RootSchema. While you can add methods or constants in this way, you cannot add
properties to a class defined in a superschema.
When you begin developing a system using JADE, you would normally begin by adding a
subschema to the RootSchema and you would then define all your classes, properties, and methods
within that schema. (For details, see “Defining Your Own Schema”, in Chapter 3 of your JADE
Development Environment User’s Guide.) This ensures that your object model (class hierarchy) is
clearly packaged and is kept distinct from the system classes. For larger and more-complex
development efforts, a hierarchy of user schemas may be necessary to adequately represent the
object model.
Applications
An application is an end-user runtime system, defining a collection of forms and other runtime
information such as the start-up form and the location of the help file or files.
Relationship between Schemas and Applications
Within a single schema, there can be one or many application instances, each providing a different
view of the object model, with different forms allowing the data in that model to be displayed and
possibly updated.
While the various applications in a schema can differ in appearance and functionality, all share the
same underlying object model; that is, the object model defined by the schema.
JADE Language
The JADE language is the purpose-built programming language for the JADE environment. The
JADE language combines control structures and arithmetic expressions with an object-oriented
message-passing syntax.
In the JADE language, programs are organized as cooperative collections of objects.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 23
JavaDev-6.3
The JADE language is a strongly typed language; that is, the programmer enforces the class of an
object by specifying the type of each variable. This strong typing of the JADE language provides
the following benefits.

Reduces the risk of runtime errors due to invoking invalid methods

Early detection of errors for the programmer
You can write external methods (or routines) for JADE classes in any language that can create a
library. External methods are called from JADE as if they were system-provided methods. JADE
methods can invoke methods written in other languages and other languages can invoke JADE
methods.
For details about using the JADE language, see “JADE Language Reference”, in Chapter 1 of your
JADE Developer’s Reference.
Exception Handling
JADE exception handling provides a mechanism that enables you to construct JADE applications
that deal properly with exceptions that occur because of abnormal conditions. For details about
exception handling, see “Handling Exceptions”, in Chapter 3 of your JADE Developer’s Reference.
System Exceptions
System exceptions are error conditions that are handled automatically by JADE; for example, a
lock exception or an error that occurs when opening a file.
User Exceptions
You can define exceptions other than those automatically captured by the system. This enables you
to add new properties and methods specific to your own exception protocol or to override system
methods.
JADE Object Manager
The JADE Object Manager supports complex objects in an efficient form that is easy to use. A
complex object consists of data and operations to manipulate that data. (A process is the activation
of a single thread of control.)
A node is an installation of JADE that dynamically supports the client role and the server role on
the same workstation. A client node is a node initiating a request and a server node is the node
processing the request. Each node can take on client or server roles.
A node processing a request received from a server node can invoke a client role for a callback to
the initiating client. Nodes handle the multiple threading of processes.
There is only ever one JADE node from a Java application, whether Standard Edition (SE) or
Enterprise Edition (EE), but there can be multiple JADE processes. Each EntityManager instance
has a corresponding JADE process.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 24
JavaDev-6.3
Note
In the development architecture, the client and server can be nodes on the Local Area
Network (LAN), and not dedicated workstation functions. The JADE Object Manager provides a
more-flexible distributed processing environment, as you are not restricted to the rigid
client/server partitions enforced by other models.
The principal JADE Object Manager characteristics are:

Object model functionality

Seamless interface to the object model

Extensibility of schema and storage media

High performance

Automatic referential integrity support

Recovery

Configures, initiates, and controls multiple threads
The JADE Object Manager:

Encapsulates data and has class independence

Can store data and methods

Holds data that can be used only by the methods of the classes; that is, data is designed for
specific methods only

Contains active objects, whose methods are executed in response to requests

Contains classes that can be reused

Can reorganize classes without affecting the use of those classes

Can contain complex data structures whose complexity need not be known by the end-users
What the JADE Object Manager Handles
The JADE Object Manager is central to the JADE structure, and handles:

Storage

Transaction management (ACID-compliant database; that is, one that has atomicity,
consistency, isolation, and durability)

Cache management (more than one process shares a common object cache for persistent
objects in a single node)

Concurrency control

Dynamic binding
The JADE Object Manager arbitrates between multiple processes making requests, coordinates
multiple requests for locks, and maintains details of locked objects, based on lock requests by users.
JADE Java
Developer’s Reference
Chapter 2 JADE Object Model and Java Persistence 25
JavaDev-6.3
The JADE Object Manager also handles notifications, and maintains statistical information that
can be accessed by the JADE Monitor application, including:

Licence information


Details of locked objects and queued locks

Lodged notification requests

Users attached to the database

Operational statistics
Java Persistence in JADE API
The Java persistence in JADE API is packaged in the javajom.jar file. For a Java system to use the
Java persistence in JADE API, javajom.jar must be included as a dependent library.
The javajom.jar file contains the packages listed in the table under “Overview”, in Chapter 3.
EntityManager Class
The EntityManager class in the com.jadeworld.jade.entitymanager package is the main interface
between your Java code and the JADE system.
It uses native methods in the com.jadeworld.jade.entityManager.JavaJOM class to communicate to
the javajom.dll JADE library file.
The Java persistence in JADE API is packaged in the javajom.jar file. For a Java system to use the
Java persistence in JADE API, javajom.jar must be included as a dependent library.
____________________________________
JavaDev-6.3
Chapter 3 Annotating Java Classes
____________________________________
This chapter covers the following topics.

Overview

Annotation to Persist a Java Class

Field

Virtual Property

Annotations to Persist a Java Property

@Id Annotation

@DbField Annotation

@Lob Annotation

@DbProperty Annotation

Optional Attributes for the @DbField and @DbProperty Annotations

Relationship Annotations

@OneToOne Annotation

@OneToMany and @ManyToOne Annotations

@ManyToMany Annotation

@Conditions and @Condition Annotations

@JadeMethod Annotation

JADE Method Calls

Application and Global Classes

Collections

@CollectionEntity Annotation

@DictionaryKey Annotation

Package Annotation

persistence.xml File
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 27
JavaDev-6.3
Overview
The Java persistence in JADE API is packaged in the javajom.jar file. Any Java system using it
must include this as a dependent library. It contains the packages listed in the following table.
Package Contains …
com.jadeworld.jade.rootschema The Java classes corresponding to JADE RootSchema classes. The Application and
Global classes enable access to methods on user subclasses of these classes. The
System, Node, and Process classes enable access to methods on the corresponding
JADE RootSchema classes. The other classes (that is, ObjectArray, ObjectSet,
MemberKeyDictionary, and ExtKeyDictionary) are used when defining collections and
accessing them at run time.
com.jadeworld.jade.entitymanager The Persistence, EntityTransaction, EntityManagerFactory and EntityManager
classes, which are the primary classes that implement the persistence API. These classes
allow connection to the JADE system, persisting Java objects in JADE, accessing the
objects again, deleting persisted objects, transaction control, and so on.
The EntityManager class is the main interface between the user Java code and the JADE
system. It uses native methods in the com.jadeworld.jade.entityManager.JavaJOM
package to communicate with the JADE library file javajom.dll.
com.jadeworld.jade.persistence The annotations used to describe Java classes to be persisted.
com.jadeworld.jade.annotations Internal packages containing the runtime annotation processing classes used when an
com.jadeworld.jade.types EntityManager factory is created to build internal lists of the class and property details.
com.jadeworld.jade.util
com.jadeworld.jade.tool The utility that writes a JADE schema from your Java system, to load into JADE to create
the equivalent JADE system for the Java persisted classes.
Annotation to Persist a Java Class
Java classes that are to be persisted in JADE or passed between Java and JADE must be marked as
such and coded in a specific manner.
To mark a class for persistence, annotate it with @Entity (all annotations are in the package
com.jadeworld.jade.persistence). A class does not have to inherit from a specific class for
persistence, although it can inherit from the com.jadeworld.jade.rootschema.Object package.
For a class to be persisted, it must belong to a Java package. The corresponding JADE persistence
class is created in a schema with the same name as the package. Classes from several packages are
persisted in the corresponding JADE schemas.
Persisted classes can inherit from other Java classes. If a class is marked for persistence, all classes
that inherit from it must also be marked in the same way. A persisted class must have a no-
argument, default constructor.
The @Entity annotation has the following attributes, which are all optional.
Attribute Description
name The name of the corresponding JADE class. The default value is the Java name.
defaultStyle One of the com.jadeworld.jade.persistence enum values DefaultStyle.NONE, DefaultStyle.FIELD,
DefaultStyle.PROPERTY, or DefaultStyle.TRANSIENT. The default value is DefaultStyle.TRANSIENT.
mapFile Defaults to the schema default map file. For details about schemas, see “Package Annotation”, later in this
chapter.
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 28
JavaDev-6.3
The defaultStyle value allows properties within the class to default to a specified style, as shown in
the following table.
Value Properties without annotations are implicitly annotated with …
FIELD @DbField
PROPERTY @DbProperty
TRANSIENT @Transient
NONE Explicitly with @Transient, @DbField, or @DbProperty, explicitly
Required Property for Persistence
The property in the following subsection is required for a class to be persisted.
Unique Identifier
There must be a property of type long or Long that is annotated with @Id in the class hierarchy of
every persisted class. The identifier property can have any name. It holds a unique value that links
the Java instances of the class with the corresponding persistent JADE objects.
If the class inherits from com.jadeworld.jade.rootschema.Object, this property is inherited and
must not be separately defined.
The following code fragment declares the oid property with an @Id annotation.
@Id
protected long oid;
Types of Java Property that Can Be Persisted
The types of Java properties in the following subsections can be persisted.
Field
This familiar type of property is a regular Java instance variable that has an accessor, or get,
method and a mutator, or set, method. In Java, an instance variable need not have get and set
methods, but if the instance variable is to be persisted in JADE, the get and set methods are
compulsory.
A get method is formed by prefixing get to the name of the property with the first letter of the
property capitalized. For example, if a class has an instance variable address, the corresponding
get method is getAddress.
A set method is formed by prefixing set to the name of the property with the first letter of the
property capitalized.
For a Boolean property, the accessor method can be formed by prefixing is rather than get. For
example, if a class has an active property, the corresponding is method is isActive.
This type of property is persisted by annotating it with @DbField.
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 29
JavaDev-6.3
Virtual Property
A virtual property is one that has get and set methods without there being a corresponding
instance variable in the Java class. Although the property is virtual in the Java class, there is a
non-virtual property in the corresponding JADE class. The get and set methods access and change
this non-virtual property.
This type of property is persisted by annotating it with @DbProperty.
Annotations to Persist a Java Property
The following subsections describe the use of various annotations to persist Java properties.
The @Id annotation associates a Java object with its corresponding JADE object.
Each property to be persisted must be annotated with @DbField or @DbProperty.
Properties that are not to be persisted are annotated with @Transient. These are typically
properties whose values are derived from other properties and methods.
The @Lob annotation is required for String and byte[] properties that have been annotated with
@DbField where the length exceeds 540. (The corresponding JADE properties are stored as
String and Binary large objects; that is, as slobs and blobs, respectively.)
The annotation for a property can be implicit from the defaultStyle annotation for the class or it
can be explicit. An explicit annotation for a property overrides the default but only one of
@DbField, @DbProperty, or @Transient is valid (apart from the oid property, which has an @Id
annotation).
@Id Annotation
There must be a property of type long or Long, which can have any name and which is annotated
with @Id in the class hierarchy of every persisted class. This holds a unique value that links the
Java instances of this class with the corresponding persistent JADE objects. If the class inherits
from com.jadeworld.jade.rootschema.Object, this property is inherited and is called oid. You must
not separately define it. The following code fragment declares the oid property with its @Id
annotation.
@Id
protected long oid;
@DbField Annotation
Properties annotated with @DbField are regular Java properties (instance variables) that are used
to hold primitive values but not references. The annotation can be applied to the property itself or
to its corresponding get method. Both get and set methods are required, as they are called
internally when the object is populated or updated.
The property values for an existing persisted object are fetched when the Java object is first created
from the corresponding JADE object. For a new Java object, they are set from user code and
updated to the corresponding JADE object when the persist method of the EntityManager class is
called.
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 30
JavaDev-6.3
The type of the property is a built-in Java primitive type or a Java class that encapsulates a
primitive type value; for example, Integer, String, or Calendar. The property cannot be a reference
to another Java class or a collection.
The following code fragment declares an address instance variable with its @DbField annotation
and the required get and set methods.
@DbField(length=80)
public String address;
public String getAddress()
{
return address;
}
public void setAddress(String address)
{
this.address = address;
}
@Lob Annotation
JADE Binary and String properties can be stored in two ways. When the property has a declared
length that does not exceed 540 characters, the value is stored as part of the object in the JADE
database. When the declared length is greater than 540 characters or it is undefined, the value is
stored as a separate but linked object, often referred to as a string large object (slob) or a binary
large object (blob).
The @Lob annotation is required for String and byte[] properties that have been annotated with
@DbField where the length exceeds 540 characters or is undefined. It is ignored if the type of the
corresponding property in JADE is not Binary or String. This annotation overrides any length
value in the @DbField annotation.
The following code fragment declares an extraInfo instance variable with its @DbField and @Lob
annotations and the required get and set methods.
@Lob
@DbField(length=1000)
public String extraInfo;
public String getExtraInfo()
{
return extraInfo;
}
public void setExtraInfo(String extraInfo)
{
this.extraInfo = extraInfo;
}
@DbProperty Annotation
The main use of the @DbProperty annotation is for a reference property; that is, a non-primitive
type property that refers to an instance of another class or to a collection. The annotation can also
be used as an alternative to @DbField for a primitive type property.
In both cases, the property in Java is a virtual property; that is, there are get and set methods
without there being a corresponding instance variable in the Java class. As there is no instance
variable, the @DbProperty annotation is applied to the get method (or the is method for a
Boolean value).
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 31
JavaDev-6.3
The get method annotated with @DbProperty uses the appropriate static method from the
com.jadeworld.jade.entitymanager.EntityAccess class for the type of the property and enable access
to existing JADE properties with these types. The methods are listed in the following table.
Type Method to Be Used
boolean, Boolean getBooleanProperty
char, Character, short, Short, int, Integer getIntegerProperty
long, Long, java.math.BigInteger getInteger64Property
float, Float, real, Real getRealProperty
java.util.BigDecimal getDecimalProperty
java.util.Date, java.util.Calendar, java.util.GregorianCalendar getTimeStampProperty
String getStringProperty or getSLOBProperty
byte[] getBinaryProperty or getBLOBProperty
char getCharacterProperty
java.util.Calendar getDateProperty or getTimeProperty
short getByteProperty
String getStringUTF8Property
java.awt.Point getPointProperty
com.jadeworld.jade.MemoryAddress getMemoryAddressProperty
class reference getReferenceProperty
Each method has the same two parameters. The first parameter is this and the second is a string
literal of the variable name.
A JADE Date or Time primitive type property becomes a java.util.Calendar instance with a zero
time or date component, respectively. A JADE Byte primitive type property becomes a Java short,
as the JADE Byte primitive type is unsigned, whereas all Java numeric types are signed.
The corresponding set method uses the appropriate static method from the
com.jadeworld.jade.entitymanager.EntityAccess class for the type of the property and enables the
value of existing JADE properties with this type to be set. The methods are listed in the following
table.
Type Method to Be Used
boolean, Boolean setBooleanProperty
char, Character, short, Short, int, Integer setIntegerProperty
long, Long, java.math.BigInteger setInteger64Property
float, Float, real, Real setRealProperty
java.util.BigDecimal setDecimalProperty
java.util.Date, java.util.Calendar, java.util.GregorianCalendar setTimeStampProperty
String setStringProperty or setSLOBProperty
byte[] setBinaryProperty or setBLOBProperty
char setCharacterProperty
java.util.Calendar setDateProperty or setTimeProperty
short setByteProperty
String setStringUTF8Property
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 32
JavaDev-6.3
Type Method to Be Used
java.awt.Point setPointProperty
com.jadeworld.jade.MemoryAddress setMemoryAddressProperty
class reference setReferenceProperty
Each method has the same three properties. The first parameter is this, the second is a string
literal of the property name, and the third is the value of the parameter to the set method.
A JADE Date or Time primitive type property becomes a java.util.Calendar instance with a zero
time or date component, respectively. A JADE Byte primitive type property becomes a Java short,
as the JADE Byte primitive type is unsigned, whereas all Java numeric types are signed.
The following code fragment declares a virtual address property. It is virtual in that there is no
address instance variable but there are get and set methods. The @DbProperty annotation is
applied to the get method.
@DbProperty(length=80)
public String getAddress()
{
return EntityAccess.getStringProperty(this, "address");
}
public void setAddress(String address)
{
EntityAccess.setStringProperty(this, "address", address);
}
The following code fragment declares a virtual extraInfo property. The EntityAccess class methods
in the get and set methods differ from the previous example, because the corresponding JADE
property is a string large object (slob).
@DbProperty(length=1000)
public String getExtraInfo()
{
return EntityAccess.getSLOBProperty(this, "extraInfo");
}
public void setExtraInfo(String extraInfo)
{
EntityAccess.setSLOBProperty(this, "extraInfo", extraInfo);
}
The following code fragment declares a virtual myCustomer reference. In addition to the
@DbProperty annotation, there is an @OneToOne annotation describing the cardinality of the
association. (These cardinality annotations are described in “Relationship Annotations”, later in
this chapter.) In the get method, the getReferenceProperty method of the EntityAccess class
returns a reference of type Object. This reference is cast to the actual class of the returned object,
which is Customer.
@DbProperty
@OneToOne
public Customer getMyCustomer()
{
return (Customer) EntityAccess.getReferenceProperty(this, "myCustomer");
}
public void setMyCustomer(Customer myCustomer)
{
EntityAccess.setReferenceProperty(this, "myCustomer", myCustomer);
}
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 33
JavaDev-6.3
The following code fragment declares a virtual allSales reference, which corresponds to a JADE
collection. In addition to the @DbProperty annotation, there is an @OneToMany annotation
describing the cardinality of the association. JADE collection classes are defined using generics,
which allow the member type of the collection to be defined, so the type cast of the returned object
also uses generics.
@DbProperty
@OneToMany
public SalesByNumber<Sale> getAllSales()
{
return (SalesByNumber<Sale>)
EntityAccess.getReferenceProperty(this, "allSales");
}
Optional Attributes for the @DbField and @DbProperty Annotations
The attributes for the @DbField and @DbProperty annotations, which are all optional, are listed
in the following table.
Attribute Description
name Name of the corresponding JADE property, which is up to 30 characters long with a
lowercase first character. The default name is the Java name.
length Applies to properties which map to JADE Binary, Decimal, or String primitive types.
Decimal defaults to 12, Binary and String default to 30. The @Lob annotation overrides
this for Binary and String, to make them maximum length blobs or slobs.
scale Applies only to Decimal. Defaults to 2.
type Allows an alternative, but still valid, JADE type to be declared.
Relationship Annotations
The @OneToOne, @OneToMany, @ManyToOne, and @ManyToMany annotations are applied to
reference properties in addition to the @DbProperty annotation, to implement the endpoints of a
relationship between two classes.
These annotations have a number of optional attributes, which are listed in the following table.
Attribute Description
inverse Name of the inverse property in the referenced class
relationshipType Whether there is a cascading deletion of referenced objects at one end of the relationship
updateMode Whether the property is updated manually in Java code or automatically by JADE
exclusive (collection reference only) Whether the collection is automatically created and deleted
constraint (collection reference only) Name of a method that determines whether inverse maintenance is carried out
transientToPersistentAllowed Whether the inverse maintenance from the persistent object to the transient is suppressed
inverseNotRequired Whether an exception is raised when no inverse is set during automatic maintenance
The relationshipType, updateMode, constraint, transientToPersistentAllowed, and
inverseNotRequired attributes apply only if an inverse reference is defined.
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 34
JavaDev-6.3
@OneToOne Annotation
An @OneToOne annotation is required for a single-valued reference property annotated with
@DbProperty; that is, for a property that is not a primitive type and not a reference to a collection.
The attributes for an @OneToOne annotation are described using an example of implementing a
relationship between the Manager class and the Department class, modeling a single manager
being responsible for a single department.
inverse Attribute

Manager objects could be associated with Department objects through a reference property added
to the Manager class. The following code fragment shows the annotated property reference.
// In the Manager class
@DbProperty
@OneToOne
public Department getMyDept()
{
return (Department) EntityAccess.getReferenceProperty(this, "myDept");
}
public void setMyDept(Dept myDept)
{
EntityAccess.setReferenceProperty(this, "myDept", myDept);
}
The following code fragment shows that the single reference does not prevent two Manager objects
from referencing the same Department object.
Department department = new Department();
Manager manager1 = new Manager();
Manager manager2 = new Manager();
manager1.setMyDept(department);
manager2.setMyDept(department);
By adding an inverse reference to the Department class (that is, a reference that refers back from
the Department object to the Manager object), the one manager to one department cardinality
rule is enforced.

To specify that a reference in one class is the inverse of a reference in another class, the inverse
attribute in the @OneToOne annotation is set to the name of the inverse property, as shown in the
following Java code fragments.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager")
public Department getMyDept()
{
return (Department) EntityAccess.getReferenceProperty(this, "myDept");
}
Manager
myDept «virtual»
Department

Manager
myDept «virtual»
Department
myManager «virtual»
1 1
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 35
JavaDev-6.3
public void setMyDept(Department myDept)
{
EntityAccess.setReferenceProperty(this, "myDept", myDept);
}
// In the Department class
@DbProperty
@OneToOne(inverse="myDept")
public Manager getMyManager()
{
return (Manager) EntityAccess.getReferenceProperty(this, "myManager");
}
public void setMyManager(Manager myManager)
{
EntityAccess.setReferenceProperty(this, "myManager", myManager);
}
JADE maintains inverse references for you automatically, which saves you considerable coding and
enforces the integrity of references. In the following code fragment, the final line is commented
out because JADE automatically updates the myManager reference as part of the automatic inverse
maintenance when the myDept reference is updated in the previous line.
Department department = new Department();
Manager manager = new Manager();
manager.setMyDept(department);
// department.setMyManager(manager); inverse automatically maintained
relationshipType Attribute
The value of the relationshipType attribute determines whether deleting a parent object that has an
inverse reference to a child object triggers JADE to delete the child object, or whether the objects
should be regarded as peers, or equals, when deletion of one object should not trigger the deletion
of the other. The attribute can take one of the following enum values defined in the
com.jadeworld.jade.persistence package.

ReferenceRelationshipType.PARENT

ReferenceRelationshipType.CHILD

ReferenceRelationshipType.PEER
In the Manager and Department example, if you decide that deleting a Manager object is to cause
the related Department object to be deleted (that is, Manager is the parent and Department is the
child), the following Java code fragments show the annotations for the references.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager", relationshipType
=ReferenceRelationshipType.PARENT)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToOne(inverse="myDept", relationshipType
=ReferenceRelationshipType.CHILD)
public Manager getMyManager()
// ...
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 36
JavaDev-6.3
Note
If one reference is annotated with relationshipType=ReferenceRelationshipType.PARENT,
the other end must be annotated with relationshipType=ReferenceRelationshipType.CHILD.
If you decide that no automatic deleting should occur (that is, neither the Manager object nor the
Department object should be regarded as the parent in terms of triggering automatic deletion of
related objects), the following Java code fragments show the annotations for the references.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager")
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToOne(inverse="myDept")
public Manager getMyManager()
// ...
Note
If one reference is annotated with relationshipType=ReferenceRelationshipType.PEER, the
other end must have the same annotation.
The default value for the relationshipType attribute is ReferenceRelationshipType.PEER.
updateMode Attribute
The value of the updateMode attribute determines whether the inverse reference property is
updated manually in Java code or automatically by JADE. The attribute can take one of the
following enum values defined in the com.jadeworld.jade.persistence package.

ReferenceUpdateMode.AUTOMATIC

ReferenceUpdateMode.MANUAL

ReferenceUpdateMode.MAN_AUTO

ReferenceUpdateMode.DEFAULT
The ReferenceUpdateMode.MANUAL option specifies that the property is maintained by your
Java logic. The ReferenceUpdateMode.AUTOMATIC option specifies that the property is
maintained by JADE whenever the property at the other end of the relationship (the inverse) is
updated. Automatic references cannot be updated in user logic.
The ReferenceUpdateMode.MAN_AUTO option specifies that either end of the relationship can
be updated in your logic with the other side of the relationship being automatically maintained by
JADE.
In the Manager and Department example, setting the myDept reference and the myManager
reference seems to require two lines of code, as follows.
manager.setMyDept(department);
department.setMyManager(manager);
However, as the references are inverses of each other, only one reference needs to be and should
be set.
JADE Java
Developer’s Reference
Chapter 3 Annotating Java Classes 37