Download JADE Java Developer`s Reference

Java Developer's Reference
VERSION 7.0.12
Copyright©2015 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 © 2015 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.
Contents
Contents
iii
Before You Begin
vii
Who Should Read this Reference
What's Included in this Reference
Related Documentation
Conventions
Chapter 1 Using the Java Framework
Overview
Starting with Java Classes
Starting with JADE Classes
The Java Framework
Java Persistence in JADE
How a Java Application Connects to JADE
Chapter 2 JADE Object Model and Java Persistence
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
Process Dumps
JADE Object Manager
What the JADE Object Manager Handles
Java Persistence in JADE API
EntityManager Class
Chapter 3 Annotating Java Classes
Overview
Annotation to Persist a Java Class
Required Property for Persistence
Unique Identifier
Types of Java Property that Can Be Persisted
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
JavaDev - 7.0.12
vii
vii
vii
viii
10
10
11
12
12
13
13
15
15
16
16
17
17
17
17
18
18
18
19
19
19
21
21
21
21
21
21
22
22
23
23
23
24
25
25
26
26
26
26
27
27
27
27
28
28
31
31
Java Developer's Reference
Contents
@OneToOne Annotation
inverse Attribute
relationshipType Attribute
updateMode Attribute
transientToPersistentAllowed Attribute
@OneToMany and @ManyToOne Annotations
inverse Attribute
exclusive Attribute
relationshipType Attribute
updateMode Attribute
transientToPersistentAllowed Attribute
constraint Attribute
inverseNotRequired Attribute
@ManyToMany Annotation
@Conditions and @Condition Annotations
@JadeMethod Annotation
JADE Method Calls
JADE Method Parameter Usage
io Usage Type
output Usage Type
Primitive Parameters
Multiple Parameters
Application and Global Classes
@ApplicationEntity Annotation
@GlobalEntity Annotation
Collections
@CollectionEntity Annotation
@DictionaryKey Annotation
Package Annotation
persistence.xml File
Chapter 4 Developing Applications in Java to Use Annotated Classes
Overview
How to Use Java Persisted Classes
Signing On To JADE
Subsequent Processing
Creating Objects
Working with Virtual Properties in the Database
Handling Lock Exceptions in Java
Signing Off From JADE
Persistence Class
createEntityManagerFactory
EntityManagerFactory Class
close
createEntityManager
isOpen
EntityAccess Class
getBLOBProperty
getBinaryProperty
getBooleanProperty
getByteProperty
getCharacterProperty
getDateProperty
getDecimalProperty
getInteger64Property
getIntegerProperty
getMemoryAddressProperty
getPointProperty
getRealProperty
JavaDev - 7.0.12
iv
32
32
33
34
36
37
37
38
39
40
41
42
43
44
45
46
46
47
47
48
48
48
48
48
49
49
50
50
51
52
54
56
56
56
56
57
57
58
58
59
59
59
59
59
60
60
60
60
60
61
61
61
62
62
62
62
63
63
Java Developer's Reference
Contents
getReferenceProperty
getSLOBProperty
getStringProperty
getStringUtf8Property
getTimeProperty
getTimeStampIntervalProperty
getTimeStampProperty
setBLOBProperty
setBinaryProperty
setBooleanProperty
setByteProperty
setCharacterProperty
setDateProperty
setDecimalProperty
setInteger64Property
setIntegerProperty
setMemoryAddressProperty
setPointProperty
setRealProperty
setReferenceProperty
setSLOBProperty
setStringProperty
setStringUtf8Property
setTimeProperty
setTimeStampIntervalProperty
setTimeStampProperty
EntityManager Class
addLockExceptionHandler
beginLoad
beginLock
beginNotification
causeEvent
clear
close
contains
createObject
edition
endLoad
endLock
endNotification
exclusiveLock
find
firstInstance
getApp
getGlobal
getLockExceptionHandlers
getNode
getProcess
getSystem
getTransaction
instances
isLockedByMe
isOpen
merge
persist
refresh
remove
removeLockExceptionHandler
sharedLock
EntityTransaction Class
JavaDev - 7.0.12
v
63
64
64
64
64
65
65
65
66
66
66
67
67
67
68
68
68
69
69
69
70
70
70
71
71
71
71
72
72
72
72
73
73
73
73
74
74
74
74
75
75
75
75
76
76
76
76
76
76
77
77
77
77
77
77
78
78
78
78
78
Java Developer's Reference
Contents
begin
commit
isActive
rollback
Collection Class
Array Class
Dictionary Class
Example of Reimplementing the getAtKey Method
Chapter 5 Creating a JADE Schema from Annotated Java Classes
Overview
userClasses Parameter
persistenceUnitName Parameter
validate Parameter
Output from the Annotation Processor
JavaDev - 7.0.12
vi
79
79
79
79
79
81
82
83
84
84
84
84
85
85
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 External interface Developer’s Reference
Developing JADE applications using external
interfaces
JADE .NET Developer’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
JavaDev - 7.0.12
Java Developer's Reference
Before You Begin
viii
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.
JavaDev - 7.0.12
Java Developer's Reference
Before You Begin
ix
In this document, the term Microsoft Windows refers to Windows 10, Windows 8, Windows 7, Windows Server
2012, Windows Server 2008, Windows Vista, or Windows Mobile. When there are differences between the
versions of Microsoft Windows, the specific version of Microsoft Windows is stated.
With the exception of the jade.exe program, when referring to program executables in this document, the .exe file
suffix is omitted; for example, jadclient refers to jadclient.exe. Similarly, the .dll (Dynamic Link Library) suffix is
omitted. For example, jomos refers to jomos.dll.
JavaDev - 7.0.12
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
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 1 Using the Java Framework
11
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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 1 Using the Java Framework
12
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 16 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
A javajom.dll 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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 1 Using the Java Framework
13
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
in conjunction with the persistence.xml configuration file. A full set of JADE binary files as for a standard client
installation must be present on the client PC. For more details about Java code that causes the sign-on, see
"Signing On To JADE", in Chapter 4.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 1 Using the Java Framework
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:\Jade\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:\Jade\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:\jade\bin" class_name
JavaDev - 7.0.12
14
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
ProcessDumps
JADE Object Manager
What the JADE Object Manager Handles
Java Persistence in JADE API
EntityManager Class
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
16
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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
17
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 14 of the 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 the 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).
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
18
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 the 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 the 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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
19
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 the 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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
20
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 the JADE
Development Environment User’s Guide.
The following diagram is an example of the schema hierarchy.
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 the 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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
21
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.
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 the 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 the 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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
22
Process Dumps
When a memory access violation is detected in a Java runtime DLL, the default behavior of the JADE Java
framework is to produce a process dump. When a memory access violation is detected in Just-In-Time (JIT)
generated code, the default behavior is to ignore it and not to produce a process dump. You can override the
default behavior for JIT code by setting the on_javaw_unnamed_ProcessDump parameter to true, and for a
specific DLL, by setting the on_javaw_<dllname>_ProcessDump parameter to false, where <dllname> is the
name of the DLL.
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.
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 2 JADE Object Model and Java Persistence
23
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.
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 - 7.0.12
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
25
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
com.jadeworld.jade.types
Internal packages containing the runtime annotation processing classes
used when an 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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
26
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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
27
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.
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
28
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.
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).
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
29
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
30
Type
Method to Be Used
char
setCharacterProperty
java.util.Calendar
setDateProperty or setTimeProperty
short
setByteProperty
String
setStringUTF8Property
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()
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
31
{
return (Customer) EntityAccess.getReferenceProperty(this, "myCustomer");
}
public void setMyCustomer(Customer myCustomer)
{
EntityAccess.setReferenceProperty(this, "myCustomer", myCustomer);
}
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
32
Attribute
Description
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.
@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);
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
33
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");
}
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
34
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()
// ...
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
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
35
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.
If you decide that the myDept reference in the Manager class is to be set manually, the following Java code
fragments show the annotations for the references.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager", updateMode=ReferenceUpdateMode.MANUAL)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToOne(inverse="myDept", updateMode=ReferenceUpdateMode.AUTOMATIC)
public Manager getMyManager()
// ...
Note If one reference is annotated with updateMode=ReferenceUpdateMode.MANUAL, the other end must be
annotated with updateMode=ReferenceUpdateMode.AUTOMATIC.
If you decide that either reference can be set manually, the following Java code fragments show the annotations
for the references.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager", updateMode=ReferenceUpdateMode.MAN_AUTO)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToOne(inverse="myDept", updateMode=ReferenceUpdateMode.MAN_AUTO)
public Manager getMyManager()
// ...
Note If one reference is annotated with updateMode=ReferenceUpdateMode.MAN_AUTO, the other end must
have the same annotation.
The ReferenceUpdateMode.DEFAULT value for the updateMode attribute in a peer-to-peer relationship is
ReferenceUpdateMode.MAN_AUTO, and in a parent-child relationship is ReferenceUpdateMode.AUTOMATIC
for the parent and ReferenceUpdateMode.MANUAL for the child.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
36
transientToPersistentAllowed Attribute
The value of the transientToPersistentAllowed attribute determines whether a transient JADE object is allowed
to reference a persistent JADE object when an inverse reference is defined.
Often relationships are established at run time between objects of the same lifetime, either both persistent or both
transient. If the objects have different lifetimes, there are conditions on whether they are allowed to reference each
other.
A persistent object cannot reference a transient object because if the transient object is deleted, the persistent
object would be left with an invalid reference (to an object that no longer exists).
Initially, there seems no reason why a transient object should not reference a persistent object. However,
establishing an inverse reference from the persistent object back to the transient object would result in an invalid
reference, as previously explained. By setting the transientToPersistentAllowed attribute to true, you can
suppress the inverse maintenance.
To allow a transient Manager object to set its myDept reference to a persistent Department object but suppress
setting the myManager inverse reference back to the transient object, the following Java code fragments show the
annotations for the references.
// In the Manager class
@DbProperty
@OneToOne(inverse="myManager", transientToPersistentAllowed=true)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToOne(inverse="myDept")
public Manager getMyManager()
// ...
The default value for the transientToPersistentAllowed attribute is false.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
37
@OneToMany and @ManyToOne Annotations
An @OneToMany annotation is required for a multi-valued reference property annotated with @DbProperty; that
is, for a property that is a reference to a class which inherits from com.jadeworld.jade.rootschema.Collection. If
the property with the @OneToMany annotation has an inverse, the inverse must be annotated with
@ManyToOne.
The attributes for an @OneToMany annotation are described using an example of implementing a relationship
between the Department class and the Employee class, modeling a department that has a number of employees.
inverse Attribute
Department objects could be associated with Employee objects through a reference property added to the
Department class. The following code fragment shows the annotated property reference.
// In the Department class
@DbProperty
@OneToMany
public Employees<Employee> getAllEmployees()
{
return (Employees<Employee>)
EntityAccess.getReferenceProperty(this, "allEmployees");
}
public void setAllEmployees(Employees<Employee> allEmployees)
{
EntityAccess.setReferenceProperty(this, "allEmployees", allEmployees);
}
The following code fragment shows that the single reference does not prevent the same Employee object
belonging to two Department objects.
Department department1 = new Department();
department1.setAllEmployees(new Employees());
Department department2 = new Department();
Department2.setAllEmployees(new Employees());
Employee employee = new Employee();
department1.getAllEmployees().add(employee);
department2.getAllEmployees().add(employee);
By adding an inverse reference to the Employee class (that is, a reference that refers back from the Employee
object to the Department object), the one department to many employees cardinality rule is enforced.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
38
To specify that a reference in one class is the inverse of a reference in another class, the inverse attribute in the
@OneToMany annotation is set to the name of the inverse property, as shown in the following code fragments.
// In the Department class
@DbProperty
@OneToMany(inverse="myDept")
public Employees<Employee> getAllEmployees()
{
return (Employees<Employee>)
EntityAccess.getReferenceProperty(this, "allEmployees");
}
// In the Employee class
@DbProperty
@ManyToOne(inverses={"allEmployees"})
public Department getMyDept()
{
return (Department) EntityAccess.getReferenceProperty(this, "myDept");
}
public void setMyDept(Department myDept)
{
EntityAccess.setReferenceProperty(this, "myDept", myDept);
}
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 adds the employee to
the collection as part of the automatic inverse maintenance when the myDept reference is updated in the
previous line.
//
Department department = new Department();
Employee employee = new Employee();
employee.setMyDept(department);
department.getAllEmployees().add(employee);
inverse auto maintained
exclusive Attribute
The value of the exclusive attribute for an @OneToMany annotation determines whether the collection is created
and destroyed automatically when the parent object is created and destroyed. If it is set to false, the collection is
an independent object.
If an inverse is not defined, the value of the exclusive attribute is false by default. With this setting, it is your
responsibility to create the collection object, as shown in the following code fragment.
Department department1 = new Department();
department1.setAllEmployees(new Employees());
If the value of the exclusive attribute is true, which is always the case when an inverse is defined, the collection is
created and destroyed automatically when the parent object is created and destroyed. In the above code
fragment, the second line would not be necessary and would actually raise an exception in JADE.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
39
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, and the 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 Department and Employee example, if you decide that deleting a Department object is to cause the
related Employee objects to be deleted (that is, Department is the parent and Employee is the child), the
following Java code fragments show the annotations for the references.
// In the Department class
@DbProperty
@OneToMany(inverse="myDept", relationshipType
=ReferenceRelationshipType.PARENT)
public Employees<Employee> getAllEmployees()
// ...
// In the Employee class
@DbProperty
@ManyToOne(inverses={"allEmployees"}, relationshipType
=ReferenceRelationshipType.CHILD)
public Department getMyDept()
// ...
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 Department object nor the Employee
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 Department class
@DbProperty
@OneToMany(inverse="myDept")
public Employees<Employee> getAllEmployees()
// ...
// In the Employee class
@DbProperty
@ManyToOne(inverses={"allEmployees"})
public Department getMyDept()
// ...
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.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
40
updateMode Attribute
The value of the updateMode attribute determines whether the inverse reference property is updated manually in
your 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
In the Department and Employee example, setting the myDept reference and adding an employee into the
allEmployees collection seems to require two lines of code.
employee.setMyDept(department);
department.getAllEmployees().add(employee);
However, as the references are inverses of each other, only one reference needs to be and should be set.
If you decide that the myDept reference in the Employee class is to be set manually, the following Java code
fragments show the annotations for the references.
// In the Employee class
@DbProperty
@ManyToOne(inverses={"allEmployees"}, updateMode=ReferenceUpdateMode.MANUAL)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToMany(inverse="myDept", updateMode=ReferenceUpdateMode.AUTOMATIC)
public Employees<Employee> getAllEmployees()
// ... MAN_AUTO
Note If one reference is annotated with updateMode=ReferenceUpdateMode.MANUAL, the other end must be
annotated with updateMode=ReferenceUpdateMode.AUTOMATIC.
If you decide that either reference can be set manually, the following Java code fragments show the annotations
for the references.
// In the Employee class
@DbProperty
@ManyToOne(inverses={"allEmployees"}, updateMode=ReferenceUpdateMode.MAN_AUTO)
public Department getMyDept()
// ...
// In the Department class
@DbProperty
@OneToMany(inverse="myDept", updateMode=ReferenceUpdateMode.MAN_AUTO)
public Employees<Employee> getAllEmployees()
// ...
Note If one reference is annotated with updateMode=ReferenceUpdateMode.MAN_AUTO, the other end must
be annotated with updateMode=ReferenceUpdateMode.MAN_AUTO.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
41
The ReferenceUpdateMode.DEFAULT value for the updateMode attribute in a peer-to-peer relationship is
ReferenceUpdateMode.MAN_AUTO, and in a parent-child relationship is ReferenceUpdateMode.AUTOMATIC
for the parent and ReferenceUpdateMode.MANUAL for the child.
transientToPersistentAllowed Attribute
The value of the transientToPersistentAllowed attribute determines whether a transient JADE object is allowed
to reference a persistent JADE object when an inverse reference is defined.
Often relationships are established at run time between objects of the same lifetime, either both persistent or both
transient. If the objects have different lifetimes, there are conditions on whether they are allowed to reference each
other.
The reason why a persistent object cannot reference a transient object is that when the transient object is deleted,
the persistent object would be left with an invalid reference (to an object that no longer exists).
Initially, there seems no reason why a transient object should not reference a persistent object. However,
establishing an inverse reference from the persistent object back to the transient object would result in an invalid
reference, as previously explained.
By setting the transientToPersistentAllowed attribute to true, you can suppress the inverse maintenance.
To allow a transient Employee object to set its myDept reference to a persistent Department object but suppress
the inverse maintenance of adding the transient employee to the persistent allEmployees collection, the following
Java code fragments show the annotations for the references.
// In the Employee class
{
@DbProperty
@ManyToOne(inverses={"allEmployees"}, transientToPersistent=true)
public Department getMyDept()
// ...
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
42
// In the Department class
{
@DbProperty
@OneToMany(inverse="myDept")
public Employees<Employee> getAllEmployees()
// ...
The default value for the transientToPersistentAllowed attribute is false.
constraint Attribute
The value of the constraint attribute specifies a condition that determines whether an object is added into a
collection through the inverse maintenance mechanism.
In the previous example, the relationship between the Employee and Department class has been implemented
by a Department object having a collection of Employee objects. A second relationship between the classes may
be required, in which a department has a collection of its waged employees (that is, employees who are paid on a
weekly basis and excluding employees who are salaried or paid on a contract basis).
Before implementing the relationship, the following Java code fragment shows the condition based on the
payFrequency property, which must be defined in the Employee class with an @Condition annotation.
// In the Employee class
@DbField
public int payFrequency;
public int getPayFrequency()
{
return payFrequency;
}
public void setPayFrequency(int payFrequency)
{
this.payFrequency = payFrequency;
}
@Conditions({@Condition(name="isWage", body={"return payFrequency = 7;"})})
@DbProperty
@ManyToOne(updateMode=ReferenceUpdateMode.MANUAL,inverses={"wageEmployees"})
public Department getMyDept()
// ...
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
43
The following Java code fragment shows the condition that is then used as a constraint on the automatic
maintenance of the wageEmployees collection in the Department class.
// In the Department class
@DbProperty
@OneToMany(inverse="myDept", updateMode=ReferenceUpdateMode.AUTOMATIC,
constraint="isWage")
public Employees<Employee> getWageEmployees()
{
return (Employees<Employee>)
EntityAccess.getReferenceProperty(this, "wageEmployees");
}
inverseNotRequired Attribute
The inverseNotRequired attribute determines whether JADE allows a reference to be set when it is not possible
for the inverse reference to be set. The reasons for not setting an inverse property are:
The constraint fails
The type of the object is not compatible with any of the inverse references
The default value of the inverseNotRequired attribute is false, which means that JADE expects to set an inverse
reference and if that is not possible, an exception is raised.
The following diagram shows the situation of the constraint failing.
If the only relationship between the Department and Employee classes is that a department has a number of
waged employees, setting the myDept reference for an employee who is not waged does not add the employee
to the collection in the Department class.
The following Java code fragment shows the annotation in the Employee class to allow the myDept reference to
be set.
// In the Employee class
@DbProperty
@ManyToOne(updateMode=ReferenceUpdateMode.MANUAL,inverses={"wageEmployees"},
inverseNotRequired=true)
public Department getMyDept()
// ...
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
44
The situation changes if there is another relationship between the classes.
Setting the myDept reference for an employee who is not waged adds the employee to one of the collections in
the Department class and so sets an inverse. In this case, the inverseNotRequired attribute does not need to be
changed from its default value of false.
The second situation when an inverse cannot be set happens when the class of an object is not compatible with
the membership of the collection.
The membership of the collection class for waged employees is of type WageEmployee; that is, only waged
employees can be added to the wageEmployees collection so that when the myDept reference is set for a
contract employee, it is not possible to establish an inverse reference.
@ManyToMany Annotation
An @ManyToMany annotation is required for a multi-valued reference property annotated with @DbProperty
(that is, for a property that is a reference to a class that inherits from com.jadeworld.jade.rootschema.Collection)
where the inverse property also inherits from com.jadeworld.jade.rootschema.Collection. In a many-to-many
relationship, the properties at both ends of the relationship have an @ManyToMany annotation.
The attributes for an @ManyToMany annotation are described using an example of implementing a relationship
between the Project class and the Employee class, modeling a project having a number of employees and each
employee being able to work on a number of projects.
The following Java code fragments show annotations for the references.
// In the Project class
@DbProperty
@ManyToMany(updateMode=ReferenceUpdateMode.MAN_AUTO,inverses={"allProjects"})
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
45
public Employees<Employee> getAllEmployees()
// ...
// In the Employee class
@DbProperty
@ManyToMany(updateMode=ReferenceUpdateMode.MAN_AUTO,inverses={"allEmployees"})
public Projects<Project> getAllProjects()
// ...
The attributes available for an @ManyToMany annotation are the same as those available for an @OneToMany
attribute. For details, see the previous section.
@Conditions and @Condition Annotations
Java permits only one annotation of a specific type for a class. The @Conditions annotation contains an array of
separate @Condition annotations, each of which defines a condition method that can be used as a constraint in a
relationship.
The format of an @Conditions annotation is as follows.
@Conditions({@Condition(), @Condition(), ...})
The attributes of an @Condition annotation are listed in the following table.
Attribute
Description
name
The name for the condition method in JADE (limited to 30 alphanumeric characters, with the first
character being a lowercase, alphabetic character)
constants
An optional string array of constants that can be used in the method body
body
A string array of each line of the condition method body
The Constants and Body attributes are specified as arrays of strings, to allow the method definitions to be split
easily over multiple lines in the Java source. Only if and return instructions are allowed in the body of a condition
method, and method content can refer only to local constants, properties of the class, and calls to other condition
methods.
Only the actual method content is specified in the body. The method signature and the begin and end; instructions
around the method body are automatically generated. The following example shows an @Conditions annotation
and the JADE condition method definition it produces.
@Conditions({@Condition(name="isWage", body={"return payFrequency = 7;"})})
isWage(): Boolean condition;
begin
return payFrequency = 7;
end;
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
46
@JadeMethod Annotation
The @JadeMethod annotation can be placed on Java methods that call JADE methods, to define the matching
JADE code. The attributes for the @JadeMethod annotation are listed in the following table.
Attribute
Description
signature
Full JADE method signature, including method name, parameters, return type, modifiers, and
terminating semicolon.
body
String array of each line of the JADE method body. The method must be specified in full, apart from
the signature.
In the following code fragment from a Java class, an @JadeMethod annotation defines a JADE method that is
subsequently called in the initShopJava method.
// ErewhonInvestmentsViewApp extends com.jadeworld.jade.rootschema.Application
@JadeMethod(signature=" initShopJava(client: Client): Boolean updating;",
body={"begin","
app.zMyClient := client;",
"
zErrorCode := 0;",
"
create zShoppingCart transient;",
"
create myTA transient;",
"
myCompany := Company.firstInstance;",
"
return true;",
"end;"})
public boolean initShopJava(Client client)
{
Object[] params = {client};
return EntityAccess.sendMsgGetBoolean(this, "initShopJava", params);
}
JADE Method Calls
You can call existing JADE methods, or those created using the @JadeMethod annotation introduced in the
previous section, from Java by defining an equivalent Java method in the class that corresponds to the JADE
class. The Java method calls the relevant sendMsgGetx method defined in the EntityManager class, where the x
value depends on the return type of the JADE method.
These methods take two or more parameters. The first parameter is this, the second is a string literal of the called
method name, and the remaining parameters are the variables, if any, to be passed to the JADE method. These
can be primitive type values or object references. For object references, the classes must be annotated with an
@Entity annotation (or with an equivalent @ApplicationEntity, @CollectionEntity or @GlobalEntity annotation)
and their class names must be listed in the class entities in the persistence.xml file.
In the first example, the getClient method from the ErewhonInvestmentViewApp class in the
ErewhonInvestmentsViewSchema schema is called. This JADE method takes no parameters and returns a
Client instance.
public Client getClient()
{
return (Client)EntityAccess.sendMsgGetReference(this, "getClient");
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
47
In the next example, the addToShoppingCart method is called. This JADE method takes two parameters (an
object and a primitive value) and has no return type.
public void addToShoppingCart(SaleItem saleItem,
java.math.BigDecimal tenderOffer)
{
EntityAccess.sendMsg(this, "addToShoppingCart", saleItem, tenderOffer);
}
JADE Method Parameter Usage
In the signature of a JADE method, the type of each parameter must be declared along with the usage value,
which can be constant, input, io (combination of input and output), or output.
If you do not specify a usage, a default of constant is assumed.
The parameter usages are as follows.
For constant and input parameters, the parameter value specified in the method call is passed to the
corresponding parameter in the called method.
Note You cannot assign to an input parameter.
For output parameters, the value is passed in the reverse direction, from the parameter of the called method
back to the corresponding parameter of the caller. This copying back of the parameter value occurs when the
called method returns, following any epilog that may be defined.
For io parameters, the parameter value is passed in both directions, as follows.
From the caller to the called method when the method begins
From the called method back to the caller when it returns, following any epilog that may be defined
In the following method signature, the date parameter has a usage of constant because the usage is not explicitly
specified. The numClosed parameter has a usage of output. When the method is executed, the value of the
numClosed parameter is passed back to the caller. This is a different and complementary mechanism to passing
back a value to the caller through the return value.
trxCloseTendersAtDate(date: Date; numClosed: Integer output): Integer;
Java passes parameters by value and consequently does not directly support the JADE usage types of io and
output. The following sections explain how these usage types are accommodated in Java.
io Usage Type
To call a JADE method that has an io parameter, the equivalent Java parameter must be wrapped in a
com.jadeworld.jade.ByRef class, as follows.
ByRef<Company> compRef = ByRef.io(company)
The JADE method is called and the compRef parameter is passed, by using the following syntax.
EntityAccess.sendMsg(this, "updateCompany", compRef);
The updated parameter value is accessed in the following way.
Company newCompany = compRef.get();
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
48
output Usage Type
To call a JADE method that has an output parameter, create a ByRef instance to take the value, as follows.
ByRef<Employee> empRef = ByRef<Employee>.out();
The JADE method is called and the empRef parameter is passed by using the following syntax.
EntityAccess.sendMsg(this, "getEmployee", empRef);
The updated parameter value is accessed in the following way.
Employee employee = empRef.get();
Primitive Parameters
For JADE methods with io or output primitive type parameters, use the equivalent Java primitive type classes. In
the following example, the boxed intRef reference of type Integer is created from the unboxed intValue, which is
of type int.
ByRef<Integer> intRef = ByRef.io(intValue);
Multiple Parameters
Create a separate ByRef instance for each io or output parameter in a JADE method.
Application and Global Classes
Each Java package must have:
One class that inherits from com.jadeworld.jade.rootschema.Application
One class that inherits from com.jadeworld.jade.rootschema.Global
@ApplicationEntity Annotation
The Application class must be annotated with an @ApplicationEntity annotation, which has the optional
attributes listed in the following table.
Attribute
Description
name
JADE class name, which defaults to the Java class name.
superclass
JADE superclass name, which defaults to Application. If the current Java package corresponds to
a JADE schema with a superschema other than RootSchema, the superclass must be the
Application subclass in the superschema.
You can define here any methods that the Java application calls. For details about method definition, see "JADE
Method Calls", earlier in this chapter. The following Java source defines a simple Application class.
package MyPackage;
import com.jadeworld.jade.persistence.*;
@ApplicationEntity
public class MyApplication extends com.jadeworld.jade.rootschema.Application
{
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
49
public MyApplication() {}
}
@GlobalEntity Annotation
The Global class must be annotated with an @GlobalEntity annotation, which has the optional attributes listed in
the following table.
Attribute
Description
name
JADE class name, which defaults to the Java class name.
superclass
JADE superclass name, which defaults to Global. If the current Java package corresponds to a
JADE schema with a superschema other than RootSchema, the superclass must be the Global
subclass in the superschema.
You can define here any methods that the Java application calls. For details about method definition, see "JADE
Method Calls", earlier in this chapter. The following Java source defines a simple Global class.
package MyPackage;
import com.jadeworld.jade.persistence.*;
@GlobalEntity
public class MyGlobal extends com.jadeworld.jade.rootschema.Global {
public MyGlobal() {}
}
Collections
Collection classes must inherit from a subclass of com.jadeworld.jade.rootschema.Collection listed in the
following table, to inherit the necessary behavior.
Collection
Description
ObjectArray
Array of persisted Java objects.
ObjectSet
Set of persisted Java objects.
MemberKeyDictionary
Dictionary of persisted Java objects with one or more keys that are in the collection
member class.
ExtKeyDictionary
Dictionary of persisted Java objects with one or more keys that are externally
supplied.
Each class implements the Java Collection and Iterator interfaces, and can be used like regular Java collections.
Specific collection classes are required only for collections of Java persisted classes; not for collections of
primitives or non-persisted classes, for which regular Java collections are used. JADE collection classes are built
for each class type stored in a collection.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
50
@CollectionEntity Annotation
The @CollectionEntity annotation has the attributes listed in the following table.
Attribute
Description
name
(Optional.) The name of the corresponding JADE class, which defaults to the Java
name.
memberClass
(Optional.) Java objects of this type populate the collection.
mapFile
(Optional.) Defaults to the member class map file. (For details, see "Annotation to
Persist a Java Class", earlier in this chapter.)
duplicatesAllowed
(MemberKeyDictionary and ExtKeyDictionary only.) true or false; default value is
false.
keys
(MemberKeyDictionary and ExtKeyDictionary only.) Array of @DictionaryKey
annotations.
The memberClass attribute is not needed if the member class is specified in the class definition using generics,
as shown in the following class definition.
class CDArray<CD> extends com.jadeworld.jade.rootschema.Array<CD>
The member class is CD from the generic definition and does not need to be specified in the @CollectionEntity
annotation.
In the next example, the member class is not specified in the class definition using generics.
class CDArray extends com.jadeworld.jade.rootschema.Array
In this case, the @CollectionEntity annotation requires the memberClass attribute to be defined.
If the member class is defined in both places, the class definition is used and the annotation definition is ignored.
@DictionaryKey Annotation
Keyed dictionaries have one or more keys that are specified in the keys array, in order from most significant to
least significant.
The attributes for the @DictionaryKey annotation are listed in the following table.
Attribute
Description
key
Name of the property within a member class that is the key.
sort
Key sort order, one of com.jadeworld.jade.persistence enum values
KeyOrder.ASCENDING (default) or KeyOrder.DESCENDING.
sortOrder
Applies only to String keys. Collating sequence to use. Defaults to Binary.
caseInsensitive
Applies only to String keys. Determines if the key ordering distinguishes between uppercase
and lowercase characters. Defaults to true.
The parent Collection classes in the com.jadeworld.jade.rootschema package are defined using Java generics;
for example, the ObjectArray class is defined as follows.
class ObjectArray<M extends Object> extends Array<M>
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
51
This enables the member class of the collection to be defined as part of the class definition of the CDArray<CD>
collection class.
class CDArray<CD> extends com.jadeworld.jade.rootschema.Array<CD>
The type of the property allCDs is the following collection class.
public CDArray<CD> getAllCDs
{
return (CDArray<CD>) EntityAccess.getReferenceProperty(this, "allCDs");
The following code fragments show the use of generics to read an array and to find an entry for a specific key
without needing to cast the returned object type.
for (CD cd: item.allCDs)
// Reading through collection
CD cd = item.getAtKey("key1", "key2");
// Finding an entry for a key
Collection classes that inherit from the ObjectArray and ObjectSet collection classes do not need to reimplement
any methods.
For more details about using collections, see "Collection Class", in Chapter 4.
Package Annotation
Each Java package that contains persisted classes must also be annotated. Do this by including a file named
package-info.java in the package. This file must contain the following.
@Schema annotation
Java package declaration for the current package name
Import of com.jadeworld.jade.persistence.Schema to make the annotation available to the Java compiler
The following example is typical of the contents of a package-info.java file.
@Schema(name="MySchema",applicationName="MyAppName",defaultMapFile="dbfile")
package MyPackage;
import com.jadeworld.jade.persistence.Schema;
The attributes for the @Schema annotation are listed in the following table.
Attribute
Description
name
(Required.) JADE schema name for these classes.
applicationName
(Optional.) Name of non-GUI JADE application to run when signing on to the schema.
Defaults to schema name.
superSchema
(Optional.) Name of superschema of this JADE schema. Defaults to RootSchema (the
top-most JADE schema).
defaultMapFile
(Optional.) Default map file to use for persisted classes. Defaults to a map file with same
name as the schema.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
52
persistence.xml File
The persistence.xml file is used in the same way as in the regular Java persistence in the JADE API. It has the
following purposes.
To list all classes that are persisted or used to communicate with the JADE system
To specify the values used to attach to and sign on to the JADE system
Each system must have this file, in a directory named META-INF at the same level as the other source packages.
The following contents are typical of a persistence.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0" >
<persistence-unit name="MyPU" >
<class>MyPackage.MyApplication</class>
<class>MyPackage.MyGlobal</class>
<class>MyPackage.Customer</class>
<properties>
<property name="jade.database.path" value="c:\jade\system"/>
<property name="jade.database.configuration"
value="c:\jade\system\jade.ini"/>
<property name="jade.database.multiuser" value="true"/>
<property name="jade.database.username" value="Fred"/>
<property name="jade.database.password" value="1234"/>
<property name="jade.database.schema" value="MySchema"/>
<property name="jade.database.application" value="MyAppName"/>
<property name="jade.debug.log" value="false"/>
</properties>
</persistence-unit>
</persistence>
The version attribute of the <persistence> element is not used at present, but the value in the preceding example
is recommended.
The file can contain multiple entries of <persistence-unit>, where the value of the name attribute is unique for
each. This name value is used when an EntityManagerFactory instance is created. The name is passed as a
parameter to the createEntityManagerFactory method, and the content of the file for this persistence-unit name
is processed.
Each Java class to be persisted must have a <class> entry specifying the name in fully-qualified Java form; that is,
package-name.class-name, as shown in the previous example. If the class name is not in this file, it is not
processed at run time. This requirement applies to all classes to be persisted, including array classes, dictionary
classes, and classes that inherit from Application, Global, and the Entity classes.
The <properties> entries are optional, as you can also set them by using the createEntityManager method of the
EntityManagerFactory class, which takes properties as parameters and allows the values to be set at run time.
The jade.database.path, jade.database.configuration, jade.database.schema, jade.database.application, and
jade.database.username properties must all be set to valid values before the EntityManagerFactory object can
be created correctly and connect to JADE using these values.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 3 Annotating Java Classes
53
The <property name …> values are listed in the following table.
Property Name
Description
jade.database.path
Full path to the JADE system directory; for example, C:\Jade\system.
jade.database.configuration
Full path to the JADE configuration file; for example, C:\Jade\system\jade.ini.
jade.database.multiuser
true if the JADE system is running in multiuser mode or false if it is to be started
in single user mode.
jade.database.username
User name used to sign on to JADE.
jade.database.password
(Optional.) Password if any associated with the user name.
jade.database.schema
JADE schema name to sign on to.
jade.database.application
Name of the non-GUI JADE application to sign on to.
jade.database.process_pool
(Optional.) The maximum number of concurrent JADE processes allowed.
Default is unlimited.
jade.debug.log
(Optional.) true if debug information is written to the JADE messages log file
(jommsg.log) or false if no debug information is written as the application runs.
JavaDev - 7.0.12
Chapter 4 Developing Applications in Java to
Use Annotated Classes
This chapter covers the following topics.
Overview
How to Use Java Persisted Classes
Signing On To JADE
Subsequent Processing
Creating Objects
Working with Virtual Properties in the Database
Handling Lock Exceptions in Java
Signing Off From JADE
Persistence Class
createEntityManagerFactory
EntityManagerFactory Class
close
createEntityManager
isOpen
EntityAccess Class
getProperty methods
setProperty methods
EntityManager Class
addLockExceptionHandler
beginLoad
beginLock
beginNotification
causeEvent
clear
close
contains
createObject
edition
endLoad
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
endLock
endNotification
exclusiveLock
find
firstInstance
getApp
getGlobal
getLockExceptionHandlers
getNode
getProcess
getSystem
getTransaction
instances
isLockedByMe
isOpen
merge
persist
refresh
remove
removeLockExceptionHandler
sharedLock
EntityTransaction Class
begin
commit
isActive
rollback
Collection Class
Array Class
Dictionary Class
Example of Reimplementing the getAtKey Method
JavaDev - 7.0.12
55
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
56
Overview
This chapter documents classes in the com.jadeworld.jade.entitymanager package and the application-related
Java code required to use the annotated classes documented in Chapter 3, "Annotating Java Classes".
How to Use Java Persisted Classes
The following classes in the com.jadeworld.jade.entitymanager package provide the link between a Java
application and a JADE system.
Persistence
EntityManagerFactory
EntityManager
EntityAccess
EntityTransaction
Signing On To JADE
The first step is to use the createEntityManagerFactory static method of the Persistence class to connect to the
JADE system and return an instance of the EntityManagerFactory class. The following Java instruction would
accomplish this, where the "name" string must match the value of the name attribute of the <persistence-unit>
element in the persistence.xml file.
EntityManagerFactory factory =
Persistence.createEntityManagerFactory("name");
The method can be overloaded with an additional userProperties parameter.
EntityManagerFactory factory =
Persistence.createEntityManagerFactory("name", userProperties);
The userProperties parameter is a java.utils.Properties list of properties that can override the value attributes for
the <property> elements within the <persistence-unit> element in the persistence.xml file.
This method connects to JADE using the properties from the persistence.xml file overwritten by any
userProperties. Any problem with connecting, such as the schema name or application name being invalid,
raises a Java AssertionError runtime exception. This method does the initial sign-on to JADE and starts up a
JADE standard client node.
Subsequent Processing
An EntityManager instance is created by calling the method createEntityManager on the EntityManagerFactory
instance.
EntityManager manager = factory.createEntityManager();
This EntityManager instance is used for all subsequent processing. More than one EntityManager instances can
be used during the lifetime of the program, and more than one instance at a time if required, but only one
EntityManagerFactory instance can be used for each JADE connection.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
57
Creating Objects
This section examines ways to create a Java object that is to be persisted in JADE. The object could be created in
the standard way, as follows.
Customer cust = new Customer();
The Java object now exists, and values of properties with @DbField annotations can be set.
cust.setName("Fred");
Before the values of properties with @DbProperty annotations can be set, the corresponding JADE object must
be created.
et.begin();
em.persist(cust);
cust.setMyCompany(company);
em.persist(cust);
et.commit();
// et is an EntityTransaction instance
// em is an EntityManager instance
Although this coding works, you can more-easily achieve the same results by using the method createObject
provided by the EntityManager class to create the Java and the JADE objects.
Customer cust = em.createObject(Customer.class,
JadeConstants.ObjectLifetime_PERSISTENT);
The method creates a Java Customer object and the corresponding JADE object. It sets the @Id value of the Java
object to the oid of the JADE object. You can then use the Java object to set properties with @DbField and
@DbProperty annotations before calling the persist method of the EntityManager class and the commit method
of the EntityTransaction class, to indicate that the instance is to be persisted.
Working with Virtual Properties in the Database
This section describes how data for a virtual property (that is, annotated with @DbProperty) is handled within the
Java application.
A property that is virtual in Java has its value stored in the corresponding persistent JADE object and not in the
Java object itself. The virtual property is manipulated in the Java program by using get and set methods (and is
methods for Boolean values) that directly access the property in the JADE object.
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.
For a String property, the value is accessed through a static get method on the EntityAccess class called
getStringProperty, as shown in the following code fragment.
@DbProperty(length=80)
public String getAddress()
{
return EntityAccess.getStringProperty(this, "address");
}
Each method has two parameters. The first parameter is this and the second is a string literal of the name of the
property in the JADE object.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
58
The set method annotated with @DbProperty uses the appropriate static method from the
com.jadeworld.jade.entitymanager.EntityAccess class for the type of the property. For a String property, the
value is modified through a static set method on the EntityAccess class called setStringProperty, as shown in
the following code fragment.
@DbProperty(length=80)
public void setAddress(String address)
{
EntityAccess.setStringProperty(this, "address", address);
}
Each method has three parameters. The first parameter is this, the second is a string literal of the name of the
property in the JADE object, and the third is the value of the parameter to the set method.
The main use of the @DbProperty annotation is for a reference property; that is, a non-primitive 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 property.
For details about handling virtual properties, see "@DbProperty Annotation", in Chapter 3.
Handling Lock Exceptions in Java
The EntityManager class provides the addLockExceptionHandler method to register an object to handle lock
exception retries in Java code, as follows.
em.addLockExceptionHandler(obj);
The class of the obj parameter must implement the com.jadeworld.jade.LockExceptionHandler interface, which
declares the method exceptionRaised.
This method returns a JadeConstants.ExceptionAction enum value of ExceptionAction.ABORT,
ExceptionAction.CONTINUE, or ExceptionAction.PASS_BACK.
When a lock exception is raised, the exceptionRaised method is called for the most-recent object to register as a
lock exception handler. The exceptionDetails parameter holds the details of the lock exception, and provides
methods to examine this information.
public JadeConstants.ExceptionAction exceptionRaised
(JadeException exceptionDetails){
return JadeConstants.ExceptionAction.PASS_BACK;
}
The exceptionRaised method can deal with the exception and return ExceptionAction.ABORT or
ExceptionAction.CONTINUE, or it can return ExceptionAction.PASS_BACK to let the next most-recently armed
handler deal with it.
If none of the handlers in the registered stack handle the exception (that is, there are no registered handlers or
they all return ExceptionAction.PASS_BACK), a regular JADE exception is raised.
The EntityManager class provides the removeLockExceptionHandler method to unregister an object as a lock
exception handler. It also provides the getLockExceptionHandlers method to return an array of currently armed
lock exception handlers.
Signing Off From JADE
At the end of the application, call the close method on the EntityManagerFactory instance to sign off and shut
down the JADE application.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
59
Persistence Class
The Persistence class provides the static method contained in the following subsection.
createEntityManagerFactory
Signature
public static EntityManagerFactory
createEntityManagerFactory(String name);
The createEntityManagerFactory method with the single name parameter creates an EntityManagerFactory
instance using the property details within the <persistence-unit> element of the persistence.xml file where the
name attribute of the <persistence-unit> element matches the name parameter.
Signature
public static EntityManagerFactory
createEntityManagerFactory(String name, Properties userProperties);
The createEntityManagerFactory method with the name parameter and the userProperties parameter creates
an EntityManagerFactory instance using property details that can be specified in two ways. They can be
specified in the <persistence-unit> element of the persistence.xml file where the name attribute of the
<persistence-unit> element matches the name parameter. Alternatively, they can be specified in the method
parameter userProperties, which is a java.util.Properties list of properties. These properties overwrite those in
the file with matching names.
import java.util.Properties;
Properties userProps = new Properties();
userProps.setProperty("jade.database.path", "c:\\jade\\system");
userProps.setProperty("jade.database.multiuser", "true");
EntityManagerFactory Class
The EntityManagerFactory class provides the following methods contained in the following subsections.
close
Signature
public void close();
The close method closes the EntityManagerFactory so it cannot be subsequently used to create new instances
of EntityManager. A sign off from the JADE system is performed.
createEntityManager
Signature
public EntityManager createEntityManager();
The createEntityManager method creates and returns a new EntityManager instance.
Each EntityManager instance runs in its own JADE process, which results from starting another copy of the
application in the schema as specified in the properties of the EntityManagerFactory instance. A pool of such
processes is maintained by the EntityManagerFactory instance.
The maximum number of processes in the pool is specified by the value of the jade.database.process_pool
property.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
60
isOpen
Signature
public boolean isOpen();
The isOpen method returns true if the EntityManagerFactory is open; that is, it has initialized correctly and has
not been closed subsequently.
EntityAccess Class
The EntityAccess class provides the static methods contained in the following subsections.
getBLOBProperty
Signature
public static byte[] getBLOBProperty(Object obj,
String propName);
The getBLOBProperty method returns a byte array, which is the content of the binary large object property (it can
store binary data with a maximum size over 540 bytes or an undefined size) called propName in the object
specified by the obj parameter.
The use of the getBLOBProperty method is shown in the following code fragment.
@DbProperty
public byte[] getPhoto()
{
return EntityAccess.getBLOBProperty(this, "photo");
}
getBinaryProperty
Signature
public static byte[] getBinaryProperty(Object obj,
String propName);
The getBinaryProperty method returns a byte array, which is the content of the binary property (it can store
binary data with a maximum size of 540 bytes or less) called propName in the object specified by the obj
parameter.
The use of the getBinaryProperty method is shown in the following code fragment.
@DbProperty
public byte[] getHashKey()
{
return EntityAccess.getBinaryProperty(this, "hashKey");
}
getBooleanProperty
Signature
public static boolean getBooleanProperty(Object obj,
String propName);
The getBooleanProperty method returns a Boolean value, which is the value of the property called propName in
the object specified by the obj parameter.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
61
The use of the getBooleanProperty method is shown in the following code fragment.
@DbProperty
public boolean isValid()
{
return EntityAccess.getBooleanProperty(this, "valid");
}
getByteProperty
Signature
public static short getByteProperty(Object obj,
String propName);
The getByteProperty method returns a short integer, which is the value of the property called propName in the
object specified by the obj parameter.
The use of the getByteProperty method is shown in the following code fragment.
@DbProperty
public short getIndex()
{
return EntityAccess.getByteProperty(this, "index");
}
getCharacterProperty
Signature
public static char getCharacterProperty(Object obj,
String propName);
The getCharacterProperty method returns a char value, which is the value of the property called propName in
the object specified by the obj parameter.
The use of the getCharacterProperty method is shown in the following code fragment.
@DbProperty
public String getLetter()
{
return EntityAccess.getCharacterProperty(this, "letter");
}
getDateProperty
Signature
public static Calendar getDateProperty(Object obj,
String propName);
The getDateProperty method returns a Calendar value, which is the value of the property called propName in
the object specified by the obj parameter.
The use of the getDateProperty method is shown in the following code fragment.
@DbProperty
public Calendar getSaleDate()
{
return EntityAccess.getDateProperty(this, "saleDate");
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
62
getDecimalProperty
Signature
public static BigDecimal getDecimalProperty(Object obj,
String propName);
The getDecimalProperty method returns a BigDecimal value, which is the value of the property called
propName in the object specified by the obj parameter.
The use of the getDecimalProperty method is shown in the following code fragment.
@DbProperty
public BigDecimal getGrandTotal()
{
return EntityAccess.getDecimalProperty(this, "grandTotal");
}
getInteger64Property
Signature
public static long getInteger64Property(Object obj,
String propName);
The getInteger64Property method returns a long integer value, which is the value of the property called
propName in the object specified by the obj parameter.
The use of the getInteger64Property method is shown in the following code fragment.
@DbProperty
public long getTotalCount()
{
return EntityAccess.getInteger64Property(this, "totalCount");
}
getIntegerProperty
Signature
public static int getIntegerProperty(Object obj,
String propName);
The getIntegerProperty method returns an int value, which is the value of the property called propName in the
object specified by the obj parameter.
The use of the getIntegerProperty method is shown in the following code fragment.
@DbProperty
public int getCount()
{
return EntityAccess.getIntegerProperty(this, "count");
}
getMemoryAddressProperty
Signature
public static MemoryAddress getMemoryAddressProperty(Object obj,
String propName);
The getMemoryAddressProperty method returns a MemoryAddress value, which is the value of the property
called propName in the object specified by the obj parameter.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
63
The use of the getMemoryAddressProperty method is shown in the following code fragment.
@DbProperty
public MemoryAddress getMemAddr()
{
return EntityAccess.getMemoryAddressProperty(this, "memAddr");
}
getPointProperty
Signature
public static Point getPointProperty(Object obj,
String propName);
The getPointProperty method returns a Point value, which is the value of the property called propName in the
object specified by the obj parameter.
The use of the getPointProperty method is shown in the following code fragment.
@DbProperty
public Point getOrigin()
{
return EntityAccess.getPointProperty(this, "origin");
}
getRealProperty
Signature
public static double getRealProperty(Object obj,
String propName);
The getRealProperty method returns a double value, which is the value of the property called propName in the
object specified by the obj parameter.
The use of the getRealProperty method is shown in the following code fragment.
@DbProperty
public double getCalcResult()
{
return EntityAccess.getRealProperty(this, "calcResult");
}
getReferenceProperty
Signature
public static Object getReferenceProperty(Object obj,
String propName);
The getReferenceProperty method returns an Object reference, which is the value of the property called
propName in the object specified by the obj parameter.
The use of the getReferenceProperty method is shown in the following code fragment.
@DbProperty
public Object getCust()
{
return EntityAccess.getReferenceProperty(this, "cust");
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
64
getSLOBProperty
Signature
public static String getSLOBProperty(Object obj,
String propName);
The getSLOBProperty method returns a String, which is the content of the string large object property (it can
store a string with a maximum size greater than 540 characters) called propName in the object specified by the
obj parameter.
The use of the getSLOBProperty method is shown in the following code fragment.
@DbProperty
public String getFullText()
{
return EntityAccess.getSLOBProperty(this, "fullText");
}
getStringProperty
Signature
public static String getStringProperty(Object obj,
String propName);
The getStringProperty method returns a String, which is the content of the string property (it can store a string
with a maximum size of 540 characters or less) called propName in the object specified by the obj parameter.
The use of the getStringProperty method is shown in the following code fragment.
@DbProperty
public String getDescription()
{
return EntityAccess.getStringProperty(this, "description");
}
getStringUtf8Property
Signature
public static String getStringUtf8Property(Object obj,
String propName);
The getStringUtf8Property method returns a UTF8-encoded String value, which is the content of the string
property called propName in the object specified by the obj parameter.
The use of the getStringUtf8Property method is shown in the following code fragment.
@DbProperty
public String getTranslation()
{
return EntityAccess.getStringUtf8Property(this, "translation");
}
getTimeProperty
Signature
public static Calendar getTimeProperty(Object obj,
String propName);
The getTimeProperty method returns a Calendar value, which is the value of the property called propName in
the object specified by the obj parameter.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
65
The use of the getTimeProperty method is shown in the following code fragment.
@DbProperty
public Calendar getStartTime()
{
return EntityAccess.getTimeProperty(this, "startTime");
}
getTimeStampIntervalProperty
Signature
public static long getTimeStampIntervalProperty(Object obj,
String propName);
The getTimeStampIntervalProperty method returns a long value, which is the value of the property called
propName in the object specified by the obj parameter.
The use of the getTimeStampIntervalProperty method is shown in the following code fragment.
@DbProperty
public Calendar getPeriod()
{
return EntityAccess.getTimeStampIntervalProperty(this, "period");
}
getTimeStampProperty
Signature
public static Calendar getTimeStampProperty(Object obj,
String propName);
The getTimeStampProperty method returns a Calendar value, which is the value of the property called
propName in the object specified by the obj parameter.
The use of the getTimeStampProperty method is shown in the following code fragment.
@DbProperty
public Calendar getBackupTS()
{
return EntityAccess.getTimeStampProperty(this, "backupTS");
}
setBLOBProperty
Signature
public static void setBLOBProperty(Object obj,
String propName,
byte[] propValue);
The setBLOBProperty sets the value of the property specified by the propName parameter in the object specified
by the obj parameter to the value of the propValue parameter, which contains a byte array that is not restricted in
size.
The use of the setBLOBProperty method is shown in the following code fragment.
@DbProperty
public void setPhoto(byte[] photo)
{
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
66
EntityAccess.setBLOBProperty(this, "photo", photo);
}
setBinaryProperty
Signature
public static void setBinaryProperty(Object obj,
String propName,
byte[] propValue);
The setBinaryProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a byte array that cannot
exceed 540 bytes.
The use of the setBinaryProperty method is shown in the following code fragment.
@DbProperty
public void setHashKey(byte[] hashKey)
{
EntityAccess.setBinaryProperty(this, "hashKey", hashKey);
}
setBooleanProperty
Signature
public static void setBooleanProperty(Object obj,
String propName,
boolean propValue);
The setBooleanProperty method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains a Boolean value.
The use of the setBooleanProperty method is shown in the following code fragment.
@DbProperty
public void setValid(boolean valid)
{
EntityAccess.setBooleanProperty(this, "valid", valid);
}
setByteProperty
Signature
public static void setByteProperty(Object obj,
String propName,
short propValue);
The setByteProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a short value.
The use of the setByteProperty method is shown in the following code fragment.
@DbProperty
public void setIndex(short index)
{
EntityAccess.setByteProperty(this, "index", index);
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
67
setCharacterProperty
Signature
public static void setCharacterProperty(Object obj,
String propName,
char propValue);
The setCharacterProperty method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains a char value.
The use of the setCharacterProperty method is shown in the following code fragment.
@DbProperty
public void setLetter(String letter)
{
EntityAccess.setCharacterProperty(this, "letter", letter);
}
setDateProperty
Signature
public static void setDateProperty(Object obj,
String propName,
Calendar propValue);
The setDateProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a Calendar value.
The use of the setDateProperty method is shown in the following code fragment.
@DbProperty
public void setSaleDate(Calendar saleDate)
{
EntityAccess.setDateProperty(this, "saleDate", saleDate);
}
setDecimalProperty
Signature
public static void setDecimalProperty(Object obj,
String propName,
BigDecimal propValue);
The setDecimalProperty method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter. The propValue parameter contains
a value, which contains a BigDecimal value.
The use of the setDecimalProperty method is shown in the following code fragment.
@DbProperty
public void setGrandTotal(BigDecimal grandTotal)
{
EntityAccess.setDecimalProperty(this, "grandTotal", grandTotal);
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
68
setInteger64Property
Signature
public static void setInteger64Property(Object obj,
String propName,
long propValue);
The setInteger64Property method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains a long value.
The use of the setInteger64Property method is shown in the following code fragment.
@DbProperty
public void setTotalCount(long totalCount)
{
EntityAccess.setInteger64Property(this, "totalCount", totalCount);
}
setIntegerProperty
Signature
public static void setIntegerProperty(Object obj,
String propName,
int propValue);
The setIntegerProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains an int value.
The use of the setIntegerProperty method is shown in the following code fragment.
@DbProperty
public void setCount(int count)
{
EntityAccess.setIntegerProperty(this, "count", count);
}
setMemoryAddressProperty
Signature
public static void setMemoryAddressProperty(Object obj,
String propName,
MemoryAddress propValue);
The setMemoryAddressProperty method sets the value of the property specified by the propName parameter in
the object specified by the obj parameter to the value of the propValue parameter, which contains a
MemoryAddress value.
The use of the setMemoryAddressProperty method is shown in the following code fragment.
@DbProperty
public void setMemAddr(MemoryAddress memAddr)
{
EntityAccess.setMemoryAddressProperty(this, "memAddr", memAddr);
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
69
setPointProperty
Signature
public static void setPointProperty(Object obj,
String propName,
Point propValue);
The setPointProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a Point value.
The use of the setPointProperty method is shown in the following code fragment.
@DbProperty
public void setOrigin(Point origin)
{
EntityAccess.setPointProperty(this, "origin", origin);
}
setRealProperty
Signature
public static void setRealProperty(Object obj,
String propName,
double propValue);
The setRealProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a double value.
The use of the setRealProperty method is shown in the following code fragment.
@DbProperty
public void setCalcResult(double calcResult)
{
EntityAccess.setRealProperty(this, "calcResult", calcResult);
}
setReferenceProperty
Signature
public static void setReferenceProperty(Object obj,
String propName,
Object propValue);
The setReferenceProperty method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains an Object
reference.
The use of the setReferenceProperty method is shown in the following code fragment.
@DbProperty
public void setCust(Object cust)
{
EntityAccess.setReferenceProperty(this, "cust", cust);
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
70
setSLOBProperty
Signature
public static void setSLOBProperty(Object obj,
String propName,
String propValue);
The setSLOBProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a String value of
unrestricted length.
The use of the setSLOBProperty method is shown in the following code fragment.
@DbProperty
public void setFullText(String fullText)
{
EntityAccess.setSLOBProperty(this, "fullText", fullText);
}
setStringProperty
Signature
public static void setStringProperty(Object obj,
String propName,
String propValue);
The setStringProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a String value that cannot
exceed 540 characters.
The use of the setStringProperty method is shown in the following code fragment.
@DbProperty
public void setDescription(String, description)
{
EntityAccess.setStringProperty(this, "description", description);
}
setStringUtf8Property
Signature
public static void setStringUtf8Property(Object obj,
String propName,
String propValue);
The setStringUtf8Property method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains a UTF8-encoded
String value.
The use of the setStringUtf8Property method is shown in the following code fragment.
@DbProperty
public void setTranslation(String translation)
{
EntityAccess.setStringUtf8Property(this, "translation", translation);
}
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
71
setTimeProperty
Signature
public static void setTimeProperty(Object obj,
String propName,
Calendar propValue);
The setTimeProperty method sets the value of the property specified by the propName parameter in the object
specified by the obj parameter to the value of the propValue parameter, which contains a Calendar value.
The use of the setTimeProperty method is shown in the following code fragment.
@DbProperty
public void setStartTime(Calendar startTime)
{
EntityAccess.setTimeProperty(this, "startTime", startTime);
}
setTimeStampIntervalProperty
Signature
public static void setTimeStampIntervalProperty(Object obj,
String propName,
long propValue);
The setTimeStampIntervalProperty method sets the value of the property specified by the propName parameter
in the object specified by the obj parameter to the value of the propValue parameter, which contains a long value.
The use of the setTimeStampIntervalProperty method is shown in the following code fragment.
@DbProperty
public void setPeriod(Calendar period)
{
EntityAccess.setTimeStampIntervalProperty(this, "period", period);
}
setTimeStampProperty
Signature
public static void setTimeStampProperty(Object obj,
String propName,
Calendar propValue);
The setTimeStampProperty method sets the value of the property specified by the propName parameter in the
object specified by the obj parameter to the value of the propValue parameter, which contains a Calendar value.
The use of the setTimeStampProperty method is shown in the following code fragment.
@DbProperty
public void setBackupTS(Calendar backupTS)
{
EntityAccess.setTimeStampProperty(this, "backupTS", backupTS);
}
EntityManager Class
The EntityManager class provides the methods contained in the following subsections.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
72
addLockExceptionHandler
Signature
public void addLockExceptionHandler(LockExceptionHandler obj);
The addLockExceptionHandler method registers the object specified by the obj parameter as a lock exception
handler; that is, to handle lock exception retry in the Java code. The class of the obj parameter must implement the
com.jadeworld.jade.LockExceptionHandler interface, which declares the method exceptionRaised.
For details about the registering and handling exceptions, see "Handling Lock Exceptions in Java", earlier in this
chapter. See also "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
beginLoad
Signature
public void beginLoad();
The beginLoad method is the equivalent of the JADE instruction beginLoad, which together with endLoad
brackets an atomic read-only transaction. In a transaction, all locks are held and unlocks are delayed until the end
of the transaction.
The beginLoad method does not cause objects to be automatically locked as they are referenced, but does
perform a single unlock operation at the end of the transaction on all objects for which shared locks had been
acquired.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
beginLock
Signature
public void beginLock();
The beginLock method is the equivalent of the JADE instruction beginLock, which together with endLock
brackets an atomic read-only transaction. In a transaction, all locks are held and unlocks delayed until the end of
the transaction.
After the beginLock method is executed, an implicit shared lock is acquired on each object as it is referenced.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
beginNotification
Signature
public void beginNotification(UserNotification subscriber,
Object receiver,
int eventType,
NotificationResponse responseType,
int eventTag);
The beginNotification method begins a user notification on the object specified by the subscriber parameter,
which registers it for notifications when a nominated user event occurs on the receiver object.
The subscriber object must implement the com.jadeworld.jade.UserNotification interface, which has a
userNotification method that is called when the notification is received.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
Signature
73
public void beginNotification(SystemNotification subscriber,
Object receiver,
NotificationEvent eventType,
NotificationResponse responseType,
int eventTag);
The beginNotification method begins a system notification on the object specified by the subscriber parameter,
which registers it for notifications when a nominated system event occurs on the receiver object.
The subscriber object must implement the com.jadeworld.jade.SystemNotification interface, which has a
systemNotification method that is called when the notification is received.
For more details, see Chapter 2, "Notifications", of the JADE Developer’s Reference.
causeEvent
Signature
public void causeEvent(Object receiver,
int eventType,
boolean immediate,
Object userInfo);
The causeEvent method triggers a user event notification of the type specified by the eventType parameter.
Signature
public void causeEvent(Object receiver,
NotificationEvent eventType,
boolean immediate,
Object userInfo);
The causeEvent method triggers a system event notification of the type specified by the eventType parameter.
For more details, see Chapter 2, "Notifications", of the JADE Developer’s Reference.
clear
Signature
public void clear();
The clear method clears an internal list of Java objects created from JADE access maintained by the
EntityManager. Subsequent accesses of the same JADE object do not create new Java objects but return the
same instance.
close
Signature
public void close();
The close method closes the EntityManager, which terminates the current JADE process. When the last active
process terminates, the connection to the JADE database is also closed.
contains
Signature
public boolean contains(Object entity);
The contains method returns true if the entity is managed (that is, the object is in the internal list of Java objects
created from accessing the JADE database); otherwise it returns false.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
74
createObject
Signature
public <T> T createObject(Class <T>,
JadeConstants.ObjectLifetime LifeTime);
The createObject method creates a Java object and the corresponding JADE object. It sets the @Id value of the
Java object to the object identifier (oid) of the JADE object. The following example creates a Java Customer
object and the corresponding JADE object.
Customer cust = em.createObject(Customer.class,
JadeConstants.ObjectLifetime_PERSISTENT);
You can then use the Java object to set properties with @DbField and @DbProperty annotations before calling
the persist method of the EntityManager class and the commit method of the EntityTransaction class, to
indicate that the instance is to be persisted.
The first parameter of the createObject method is the class of the object to be created. The second parameter is
an enum value in com.jadeworld.jade.JadeContants of ObjectLifetime.TRANSIENT, ObjectLifetime.SHARED_
TRANSIENT, or ObjectLifetime.PERSISTENT.
Signature
public <T> T createObject(Class <T>);
The createObject method with the single parameter of the class of the object to be created creates an object with
a lifetime of ObjectLifetime.PERSISTENT. The following example is equivalent to the previous example.
Customer cust = em.createObject(Customer.class);
edition
Signature
public int edition(Object target, Object entity);
The edition method returns the JADE edition number of the object specified by the entity parameter.
The target object parameter value is any valid entity instance. The edition of a JADE object is one (1) when it is
created, and it increments by one for each transaction that updates the object.
endLoad
Signature
public void endLoad();
The endLoad method is the equivalent of the JADE instruction endLoad, which signals the completion of an
atomic read-only transaction that was started with the beginLoad method and releases all locks held during the
transaction.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
endLock
Signature
public void endLock();
The endLock method is the equivalent of the JADE instruction endLock, which signals the completion of an
atomic read-only transaction that was started with the beginLock method and releases all locks held during the
transaction.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
75
endNotification
Signature
public void endNotification(UserNotification subscriber,
Object receiver,
int eventType);
The endNotification method ends a user notification on the subscriber object for the user-defined event specified
by the eventType parameter. The notifications must previously have been subscribed to by using the
beginNotification method.
Signature
public void endNotification(SystemNotification subscriber,
Object receiver,
int eventType);
The endNotification method ends system notifications on the subscriber for the system event specified by the
eventType parameter. The notifications must previously have been subscribed to by using the beginNotification
method.
For more details, see Chapter 2, "Notifications", of the JADE Developer’s Reference.
exclusiveLock
Signature
public void exclusiveLock(Object target, Object entity);
The exclusiveLock method attempts to acquire an exclusive lock on the object specified by the entity parameter.
The target object is any valid entity instance. If another process has a conflicting lock, the process waits until the
lock is released. The object is exclusively locked for the duration of the transaction.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
find
Signature
public <T> T find(<T> entityClass, Object primaryKey);
The find method returns the instance of the persisted class (that is, a class with an @Entity annotation) specified
by the entityClass parameter with the instance number specified by the second (primaryKey) parameter.
If an object with that instance number does not exist, a null reference is returned.
In the following code fragment, the instance of the class Employee, which has an @Entity annotation, with
instance number 1234 is returned, if it exists.
EntityManagerFactory fctry = Persistence.createEntityManagerFactory("name");
EntityManager entitymanager = fctry.createEntityManager();
Employee obj = em.find(Employee.class, new Long(1234));
firstInstance
Signature
public <T> T firstInstance (Class<T> class);
The firstInstance method returns the JADE object with the lowest instance id for the specified class, or null if there
are no instances. It is most commonly used to return the singleton instance of a class in the JADE system, which is
often called Root. The Root object holds collections of other objects and is a starting point for accessing an object
from one of these collections.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
76
The use of the firstInstance method is shown in the following code fragment.
Root root = em.firstInstance(Root.class);
getApp
Signature
public com.jadeworld.jade.rootschema.Application getApp();
The getApp method returns an object that is the equivalent of the JADE app system variable; that is, a reference to
the current transient application instance.
getGlobal
Signature
public com.jadeworld.jade.rootschema.Global getGlobal();
The getGlobal method returns an object that is the equivalent of the JADE global system variable; that is, a
reference to the single global object for each JADE schema, which is shared by all applications running from that
schema.
getLockExceptionHandlers
Signature
public LockExceptionHandler[] getLockExceptionHandlers();
The getLockExceptionHandlers method returns an array of lock exception handlers that are currently armed.
For details about registering and handling exceptions, see "Handling Lock Exceptions in Java", earlier in this
chapter. See also "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
getNode
Signature
public com.jadeworld.jade.rootschema.Node getNode();
The getNode method returns an object that is the equivalent of the JADE node system variable; that is, a
reference to the object that represents the workstation that hosts the execution of the current process.
getProcess
Signature
public com.jadeworld.jade.rootschema.Process getProcess();
The getProcess method returns an object that is the equivalent of the JADE process system variable; that is, a
reference to the object that represents the current thread of the EntityManager instance that is currently active.
getSystem
Signature
public com.jadeworld.jade.rootschema.System getSystem();
The getSystem method returns an object that is the equivalent of the JADE system system variable; that is, a
reference to the single object for each JADE system that represents the group of nodes to which the current node
belongs.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
77
getTransaction
Signature
public EntityTransaction getTransaction();
The getTransaction method returns the EntityTransaction instance that is associated with the receiving
EntityManager instance. The EntityTransaction instance is used for transaction control.
instances
Signature
public <T> Collection<T> instances(Class<T> class);
The instances method returns a collection of the JADE instances for the class. The collection is empty if there are
no instances.
The use of the instances method is shown in the following code fragment.
Collection<Client> allClients = em.instances(Client.class)
isLockedByMe
The isLockedByMe method returns true if the current process holds an exclusive lock on the object specified by
the entity parameter or it returns false if it does not hold an exclusive lock.
The target object is any valid entity instance.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
isOpen
Value Type public boolean isOpen();
The isOpen method returns true if the EntityManager is open, which is the normal state, or it returns false if it has
been closed by calling the close method.
merge
Signature
public <T> T merge(T entity);
The merge method re-attaches the Java entity with the equivalent JADE object, matching on the value of the
property of the Java object with the @Id annotation. If there is no equivalent JADE object, a new one is created
and attached.
This method is typically called for a persistent Java object that has been copied to or from another Java
application and is to be re-attached to JADE.
persist
Signature
public void persist(Object entity);
The persist method is called after creating a new Java object to persist it in JADE.
You must do this to create the matching JADE object before any actions are performed that call methods on the
JADE object; for example, accessing a property that has an @DbProperty annotation. It is also called to persist
any changes made to the object.
If the JADE object does not exist, it is created with a lifetime of JadeConstants.ObjectLifetime.PERSISTENT.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
Signature
78
public void persist(Object entity,
JadeConstants.ObjectLifetime Lifetime);
The persist method is called after creating a new Java object to persist it in JADE.
You must do this to create the matching JADE object before any actions are performed that call methods on the
JADE object; for example, accessing a property that has an @DbProperty annotation. It is also called to persist
any changes made to the object. If the JADE object does not exist, it is created with a lifetime specified by the
value of the Lifetime parameter, which can be JadeConstants.ObjectLifetime.PERSISTENT,
JadeConstants.ObjectLifetime.TRANSIENT, or JadeConstants.ObjectLifetime.SHARED_TRANSIENT.
If the JADE object already exists, the Lifetime parameter is ignored.
refresh
Signature
public void (Object o);
The refresh method updates all @DbField property values in the object from the corresponding JADE object
values.
remove
Signature
public void remove(Object entity);
The remove method deletes the corresponding JADE object from the JADE database and removes this Java
entity from the internal managed list. It does not delete the Java object.
removeLockExceptionHandler
Signature
public void removeLockExceptionHandler(LockExceptionHandler obj);
The removeLockExceptionHandler method deregisters the object specified by the obj parameter as a lock
exception handler; that is, it handles lock exception retries in the Java code. The class of the obj parameter must
implement the com.jadeworld.jade.LockExceptionHandler interface, which declares the method
exceptionRaised.
Note All registered lock exception handlers must be removed before the EntityManager instance is closed.
For details about the registering and handling exceptions, see "Handling Lock Exceptions in Java", earlier in this
chapter. See also "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
sharedLock
Signature
public void sharedLock(Object target, Object entity);
The sharedLock method attempts to acquire a shared lock on the object specified by the entity parameter. The
target object is any valid entity instance. If another process has a conflicting lock, the process waits until the lock
is released. If the process is in transaction state, the object remains locked for the duration of the transaction.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
EntityTransaction Class
The EntityTransaction class provides the methods contained in the following subsections.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
79
begin
Signature
public void begin();
The begin method enters transaction state, indicating the start of a transaction that can update persistent objects
in the JADE database. At run time, a Java IllegalStateException exception is raised if the application is already in
transaction state.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
commit
Signature
public void commit();
The commit method commits an active transaction. At run time, a Java AssertionError exception is raised if the
application is not already in transaction state.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
isActive
Signature
public boolean isActive();
The isActive method return true if the application is in transaction state; otherwise it returns false.
rollback
Signature
public void rollback();
The rollback method rolls back an active transaction. All changes made to the JADE object are discarded. For the
Java proxy object, all changes made to @DbProperty fields are discarded as their values are retrieved from the
corresponding JADE object, but changes made to @DbField properties are not discarded.
To refresh these properties from the corresponding JADE object, call the refresh method of the EntityManager
class, passing the object reference as a parameter.
At run time, a Java AssertionError exception is raised if the application is not already in transaction state.
For more details, see "Transaction and Concurrency Control Instructions", in the JADE Developer’s Reference.
Collection Class
The Collection class is the superclass for all collections. It implements the java.util.Collection interface as well as
a number of JADE-specific methods.
The java.util.Collection methods are listed in the following table.
Method
Description
boolean add(Object o)
Adds an object to the collection.
boolean addAll(Collection c)
Adds all of the elements in the specified collection to the
collection.
void clear()
Removes all of the elements from the collection.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
80
Method
Description
boolean contains(Object o)
Returns true if the collection contains the specified
element.
boolean containsAll(Collection c)
Returns true if the collection contains all of the elements
in the specified collection.
boolean isEmpty()
Returns true if the collection contains no elements.
Iterator iterator()
Returns an iterator over the elements in the collection.
This is an instance of the class
com.jadeworld.jade.LightIterator.
boolean remove(Object o)
Removes a single instance of the specified element from
the collection, if it is present.
boolean removeAll(Collection c)
Removes all the elements in the collection that are also
contained in the specified collection (not implemented).
boolean retainAll(Collection c)
Retains only the elements in the collection that are also
contained in the specified collection (not implemented).
int size()
Returns the number of elements in the collection.
Object[] toArray()
Returns an array containing all of the elements in the
collection.
The additional JADE methods are listed in the following table.
Method
Description
void copy(Collection toColl)
Copies entries from the receiver collection to a
compatible collection passed as the toColl parameter.
int countOf(java.lang.Object o)
Returns the number of times the entry specified in the
parameter occurs in the collection.
Iterator createIterator()
Returns an iterator for the collection. This is an instance
of the class com.jadeworld.jade.rootschema.Iterator.
M first()
Returns a reference to the first entry in the collection.
Object getOwner()
Returns a reference to the object that is the owner or
parent) of the collection
void getStatistics(ByRef<JadeDynamicObject> jdo)
Analyzes the collection and returns structural statistics in
the attributes of a JadeDynamicObject, representing
collection statistics
int indexOf(java.lang.Object o)
Returns the index of the entry specified in the parameter,
or zero (0).
void instantiate()
Ensures that the collection is created before it is used
(exclusive collections only).
M last()
Returns a reference to the last entry in the collection.
int maxSize()
Returns the maximum number of entries that a collection
can contain.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
Method
Description
void purge()
Deletes all objects in a collection and clears the
collection.
void setBlockSize(int blockSize)
Enables you to specify or change the block size of the
receiver in terms of entries in each block.
81
Array Class
The Array class inherits from the Collection class and is the superclass for all JADE array classes. It implements
the java.util.List interface as well as a number of JADE-specific methods.
The java.util.List methods are listed in the following table.
Method
Description
boolean add(Object o)
Adds an entry to the end of the array
boolean add(int i, Object o)
Adds an entry at the specified index
boolean addAll(Collection c)
Inserts all of the elements in the specified collection into the list at the
specified position (not implemented)
Object get(int i)
Returns the entry in the array at the specified position
int indexOf(Object o)
Returns the index of the specified element
int lastIndexOf(Object o)
Implemented the same way as the indexOf method
Object set(int i, Object o)
Replaces an existing entry in the array at the specified position
boolean remove(int i)
Removes the element at the specified index
boolean remove(Object o)
Removes the specified element from the array
Object[] toArray()
Returns an object array of the collection contents
subList(int from, int to)
Not implemented
listIterator() iter
Not implemented, use the iterator or createIterator methods
The additional JADE methods are listed in the following table.
Method
Description
M at(int index)
Same as the get method, which returns the array element at the
specified index.
void atPut(int index, M element)
Places the specified object at the specified index position.
void replace(int index, M element)
Replaces an existing entry in an array at the position specified by the
index parameter with the entry specified in the value parameter. If the
specified index does not exist, an exception is raised. This differs from
the set method in that it does not return the previous value. The set
method implements the java.util.List behavior and the replace method
implements the JADE behavior.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
82
Dictionary Class
The Dictionary class encapsulates the behavior required to store and retrieve objects in a collection by a userdefined key or keys.
Trailing spaces are trimmed from string keys when they are added to a dictionary or when string keys are passed
as parameters to dictionary methods.
The Dictionary methods are listed in the following table.
Method
Description
M getAtKey(java.lang.Object... keys)
Returns a reference to an object in the receiver
collection with a key equal to the value specified in
the keys parameter.
M getAtKeyGeq(java.lang.Object... keys)
Returns a reference to an object in the receiver
collection with a key equal to or greater than the
value specified in the keys parameter.
M getAtKeyGtr(java.lang.Object... keys)
Returns a reference to an object in the receiver
collection with a key greater than the value specified
in the keys parameter.
M getAtKeyLeq(java.lang.Object... keys)
Returns a reference to an object in the receiver
collection with a key equal to or less than the value
specified in the keys parameter.
M getAtKeyLss(java.lang.Object... keys)
Returns a reference to an object in the receiver
collection with a key less than the value specified in
the keys parameter.
void getIteratorKeys(Iterator iter, ByRef... keys)
Retrieves the keys from a dictionary at the current
position of the iterator while iterating through the
dictionary.
void putAtKey(M value, java.lang.Object... keys)
Adds the object specified in the value parameter to an
ExtKeyDictionary using the specified dictionary
keys.
void startKeyGeq(Iterator iter, java.lang.Object... keys)
Sets a start position within a dictionary for the
specified iterator.
void startKeyGtr(Iterator iter, java.lang.Object... keys)
Sets a start position within a dictionary for the
specified iterator at the next object after the specified
keys value.
void startKeyLeq(Iterator iter, java.lang.Object... keys)
Sets a start position within a dictionary for the
specified iterator at the object equal to or before the
specified keys value.
void startKeyLss(Iterator iter, java.lang.Object... keys)
Sets a start position within a dictionary for the
specified iterator at the object before the specified
keys value.
boolean includesKey(java.lang.Object... keys)
Returns true if the receiver contains an entry for the
specified keys value.
JavaDev - 7.0.12
Java Developer's Reference
Chapter 4 Developing Applications in Java to Use Annotated Classes
Method
Description
boolean includes(M element)
Returns true if the receiver contains the specified
element.
void removeKey(java.lang.Object... keys)
Removes an item with a specified keys value.
void removeKeyEntry(java.lang.Object entity,
java.lang.Object... keys)
Removes a duplicated key entry from a dictionary.
83
Example of Reimplementing the getAtKey Method
You can reimplement a Dictionary method with a parameter of the form java.lang.Object… keys in each member
key dictionary subclass, to specify the actual number and type of each key. For example, classes that inherit from
the MemberKeyDictionary and ExtKeyDictionary collection classes can reimplement the getAtKey method, as
this depends on the key definition that is specific to the class.
The getAtKey method provides direct access to the object based on the key values. The base implementation of
the method provides a general method definition (using the Java varargs … construct), which works provided that
the actual method parameters match the dictionary keys in number and type.
To enable the compiler to enforce correct usage, you can reimplement the method in a subclass, to specify the
actual number and type of each key.
In a MemberKeyDictionary subclass, the getAtKey method is reimplemented with parameters of the key
properties.
The following example shows the @CollectionEntity annotation and reimplementation of the getAtKey method
for a MemberKeyDictionary collection with keys of codePrefix and codeNumber.
@CollectionEntity(keys={@DictionaryKey(key="codePrefix"),
@DictionaryKey(key="codeNumber")})
public SaleItem getAtKey(String codePrefix, int codeNumber)
{
Object[] params = {codePrefix, codeNumber};
return (SaleItem) EntityAccess.sendMsgGetReference(this, "getAtKey",
params);
}
JavaDev - 7.0.12
Chapter 5 Creating a JADE Schema from
Annotated Java Classes
This chapter covers the following topics.
Overview
userClasses Parameter
persistenceUnitName Parameter
validate Parameter
Output from the Annotation Processor
Overview
When you have completed coding your Java system, create JADE schema files to load into JADE, to make the
JADE classes available.
Do this by using the com.jadeworld.jade.tool.AnnotationProcessor utility in the javajom.jar file. It reads two base
schema files stored in the jar file and the user class annotations and descriptions, to create full user schema
(.scm) and forms definitions (.ddb) files. An example of invoking the utility from the command line is as follows.
java –jar c:\jade\bin\javajom.jar –uc c:\build\classes –pun MyPU
The parameters for the com.jadeworld.jade.tool.AnnotationProcessor utility are described in the following
subsections.
userClasses Parameter
The userClasses parameter specifies the location of the directory that contains the package directory containing
the user-annotated Java classes. The classes can be separate .class files or packaged as a Java archive .jar file.
This parameter is required.
You can use -uc as a synonym for -userClasses.
persistenceUnitName Parameter
The persistenceUnitName parameter is the name of the <persistence-unit> entry in the persistence.xml file for
this system. This parameter is required.
You should locate the persistence.xml file in the META-INF directory, which is located in the directory specified
by the userClasses parameter, as shown in the following diagram.
The persistence.xml file lists the class names for the user classes, as follows.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0" >
JavaDev - 7.0.12
Java Developer's Reference
Chapter 5 Creating a JADE Schema from Annotated Java Classes
85
<persistence-unit name="MyPU" >
<class>MyPackage.MyApplication</class>
<class>MyPackage.MyGlobal</class>
<class>MyPackage.Customer</class>
<properties>
<property name="jade.database.path" value="c:\jade\system"/>
<property name="jade.database.configuration"
value="c:\jade\system\jade.ini"/>
<property name="jade.database.multiuser" value="true"/>
<property name="jade.database.username" value="Fred"/>
<property name="jade.database.password" value="1234"/>
<property name="jade.database.schema" value="MySchema"/>
<property name="jade.database.application" value="MyAppName"/>
</properties>
</persistence-unit>
</persistence>
You can use -pun as a synonym for -persistenceUnitName.
validate Parameter
The validate parameter produces a log of annotation errors using the standard Java logging feature, the
configuration of which is in a logging.properties file. The default configuration file is lib/logging.properties in the
Java runtime directory. You can specify a custom configuration file when this utility is run, by inserting the
configuration file name between java and jar on the command line, as shown in the following example.
java -Djava.util.logging.config.file=mylogging.properties
jar –uc c:\build\classes –pun MyPU
The validate parameter is optional. If you specify it, a report of all annotation errors is produced. If you do not
specify it, the first annotation error raises a runtime exception.
Output from the Annotation Processor
A JADE schema file and forms definition file is created for each JADE schema, corresponding to each Java
package containing persisted classes, to the directory specified by the userClasses parameter.
These files are called JADE-schema-name.scm and JADE-schema-name.ddb, respectively, where the JADEschema-name value is the name of the JADE schema.
The .scm file contains the JADE class definitions, including a Java exposure list containing details of these
classes. The .ddb file contains a single JADE non-GUI application, with the name specified by the
applicationName attribute of the @Schema annotation for the package.
You must then manually load the schema files into JADE before you can run the Java system against JADE. For
details about loading schemas, see Chapter 1 of the JADE Development Environment User’s Guide.
JavaDev - 7.0.12