Package com.healthmarketscience.jackcess.expr

Jackcess has support for evaluating Access expressions. This functionality is enabled by default (as of the 3.5.0 release) but can be globally disabled via the system property "com.healthmarketscience.jackcess.enableExpressionEvaluation" or selectively disabled on a per database basis using Database.setEvaluateExpressions(Boolean).

The expression evaluation engine implementation does its best to follow all the warts and idiosyncracies of Access expression evaluation (both those that are documented as well as those discovered through experimentation). These include such things as value conversions, "Null" handling, rounding rules, and implicit interpretations of expression in certain contexts.

Expressions can be used in a number of different places within an Access database. When enabled, Jackcess supports the following usage:

• Default Values: When a row is added which has a null value for a field which has a default value expression defined, that expression will be evaluated and the result will be inserted for that field. Like an auto-generated id, the generated default value will be returned in the input row array.
• Calculated Fields: In databases which support calculated fields, any input value for a calculated field will be ignored. Instead, the result of evaluating the calculated field expression will be inserted. Like an auto-generated id, the calculated value will be returned in the input row array.
• Field Validation: Field validation rules will be evaluated whenever a field value is updated. If the rule fails, the update operation will fail. The failure message will specify which field's validation rule failed and include the custom validation rule message if defined.
• Record Validation: Similar to field validation rules, record validation rules will be run for the entire record before update. Failures are handled in a similar manner.

Supporting Classes

The classes in this package make up the public api for expression handling in Jackcess. They generally fall into two categories:

General Use Classes

• EvalConfig allows for customization of the expression evaluation context for a given Database instance.
• TemporalConfig encapsulates date/time formatting options for expression evaluation.
• NumericConfig encapsulates number formatting options for expression evaluation.
• FunctionLookup provides a source for Function instances used during expression evaluation.
• EvalException wrapper exception thrown for failures which occur during expression evaluation.
• ParseException wrapper exception thrown for failures which occur during expression parsing.

Advanced Use Classes

• EvalContext encapsulates all shared state for expression parsing and evaluation.
• Expression provides an executable handle to an actual Access expression.
• Function provides an invokable handle to external functionality to an expression.
• Identifier identifies a database entity (e.g. the name of a database field).
• Value represents a typed primitive value.

Function Support

Jackcess supports many of the standard Access functions. The following tables list the (hopefully) current status of support built into Jackcess.

Conversion

Function	Supported
Asc	Y
AscW	Y
Chr	Y
ChrW	Y
EuroConvert
FormatCurrency	Y
FormatDateTime	Y
FormatNumber	Y
FormatPercent	Y
GUIDFromString
Hex[$]	Y
Nz	Y
Oct[$]	Y
Str[$]	Y
StringFromGUID
Val	Y
CBool	Y
CByte	Y
CCur	Y
CDate	Y
CVDate	Y
CDbl	Y
CDec	Y
CInt	Y
CLng	Y
CSng	Y
CStr	Y
CVar	Y

Date/Time

Function	Supported
Day	Y
Date	Y
DateAdd	Y
DateDiff	Y
DatePart	Y
DateSerial	Y
DateValue	Y
Hour	Y
Minute	Y
Month	Y
MonthName	Y
Now	Y
Second	Y
Time	Y
Timer	Y
TimeSerial	Y
TimeValue	Y
Weekday	Y
WeekdayName	Y
Year	Y

Financial

Function	Supported
DDB	Y
FV	Y
IPmt	Y
NPer	Y
Pmt	Y
PPmt	Y
PV	Y
Rate	Y
SLN	Y
SYD	Y

Inspection

Function	Supported
IsDate	Partial
IsEmpty
IsError
IsMissing
IsNull	Y
IsNumeric	Y
IsObject
TypeName	Y
VarType	Y

Math

Function	Supported
Abs	Y
Atn	Y
Cos	Y
Exp	Y
Int	Y
Fix	Y
Log	Y
Rnd	Y
Round	Y
Sgn	Y
Sin	Y
Sqr	Y
Tan	Y

Program Flow

Function	Supported
Choose	Y
IIf	Y
Switch	Y

Text

Function	Supported
Format[$]	Y
InStr	Y
InStrRev	Y
LCase[$]	Y
Left[$]	Y
Len	Y
LTrim[$]	Y
RTrim[$]	Y
Trim[$]	Y
Mid[$]	Y
Replace	Y
Right[$]	Y
Space[$]	Y
StrComp	Y
StrConv[$]	Partial
String[$]	Y
StrReverse	Y
UCase[$]	Y

Interface Summary

Interface	Description
EvalConfig	The EvalConfig allows for customization of the expression evaluation context for a given Database instance.
EvalContext	EvalContext encapsulates all shared state for expression parsing and evaluation.
Expression	An Expression is an executable handle to an Access expression.
Function	A Function provides an invokable handle to external functionality to an expression.
FunctionLookup	A FunctionLookup provides a source for Function instances used during expression evaluation.
LocaleContext	LocaleContext encapsulates all shared localization state for expression parsing and evaluation.
Value	Wrapper for a typed primitive value used within the expression evaluation engine.

Class Summary

Class	Description
Identifier	identifies a database entity (e.g. the name of a database field).
NumericConfig	A NumericConfig encapsulates number formatting options for expression evaluation.
TemporalConfig	A TemporalConfig encapsulates date/time formatting options for expression evaluation.

Enum Summary

Enum	Description
NumericConfig.Type
TemporalConfig.Type
Value.Type	the types supported within the expression evaluation engine

Exception Summary

Exception	Description
EvalException	Base class for exceptions thrown during expression evaluation.
ParseException	Exception thrown when expression parsing fails.