Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

Written by: David E. Jones
Minor corrections by Pawel H Debski and Les Austin

Table of Contents

Related Documents

Entity Engine Guide

Framework Configuration Guide

Service Engine Configuration Guide

Configuring Read-Only Datasource Access for Reporting

Introduction

This document describes the configuration of the Entity Engine. It starts with an introduction of general ideas and then goes through each part of the entityengine.xml file and explains the available elements and their usage. The entityengine.xml file used for OFBiz applications has examples of a number of different options and is located in

framework/entity/config/entityengine.xml

The configuration of the Entity Engine is done through a simple XML file called entityengine.xml that must exist somewhere on the classpath. This file is used to define parameters for persistence servers such as EJB server parameters or JDBC server parameters. It is also used to specify which XML entity model, entity group, and field type model files will be used for that server. The default file for the OFBiz distribution can be found in

framework/entity/config/entityengine.xml

Each application that uses the Entity Engine does so through a Delegator instance. The delegator name must be passed to the static factory method that is then passed to the constructor if a new instance is needed. This delegator name is used to look up settings for that delegator in the entityengine.xml file. Each delegator uses an entity model reader and an entity group reader that specifies a group name for each named entity in the entity model file. The entityengine.xml file contains the settings that map each group name to a GenericHelper for that group. GenericHelper is an interface that must be implemented for each type of data source. In practice, only JDBC-based implementations exist today: org.apache.ofbiz.entity.datasource.GenericHelperDAO (the standard one) and ReadOnlyHelperDAO.

The settings for each named GenericHelper are specified in datasource elements in the entityengine.xml file. For a JDBC helper these would include database connection parameters such as either the JNDI data source parameters or the JDBC parameters including the driver name, the JDBC URI, and the username and password for the database. An EJB helper would contain JNDI parameters such as the context provider URL, the initial context factory, and the URL package prefixes.

The Delegator is the primary access method for Entity Engine services. Each service request is dispatched to the helper that corresponds to the entity that the service is requested for according to the group name of the entity specified in the entity group XML file and the helper for that group specified in the entityengine.xml file. There is no single default entity group XML file — each component declares its own via an <entity-resource type="group" reader-name="main" .../> entry in its ofbiz-component.xml (e.g. framework/entity/ofbiz-component.xml declares entitydef/entitygroup.xml for its own entities). These are all auto-aggregated at runtime under the main entity-group-reader named in entityengine.xml.

Resource Loaders


The resource-loader tag is used to configure a named resource loader that can be used elsewhere to load XML and other resources. It has the following attributes.

Attribute NameRequired?Description
nameYThe name of the resource loader. Used in other tags in the "loader" attribute.
classYThe class to use that extends org.apache.ofbiz.base.config.ResourceLoader. Available classes today are FileLoader and UrlLoader, both in the same package as ResourceLoader.
prepend-envNThe name of a Java environment property to put at the very beginning of the full location, before the prefix. This is optional.
prefixNA string to put before the location when making the full location. This is optional. If used will go after the prepended environment property and before the location specified for each resource.

JTA Elements


For JTA support the Entity Engine needs access to the javax.transaction.UserTransaction and optionally the javax.transaction.TransactionManager interface implementations for the TX Manager being used. These are retrieved through the org.apache.ofbiz.entity.transaction.TransactionFactory interface. The implementation used is specified with the class attribute of the transaction-factory element, and may be changed depending on which transaction manager you are running OFBiz on.

The default TX Manager is Apache Geronimo's, and the factory class is org.apache.ofbiz.entity.transaction.GeronimoTransactionFactory — this is what ships enabled by default in entityengine.xml.

For deployments that need to look up the UserTransaction/TransactionManager objects from an external JNDI provider (e.g. when running under an external application server) instead, use org.apache.ofbiz.entity.transaction.JNDITransactionFactory. This class uses the user-transaction-jndi and transaction-manager-jndi sub-elements of transaction-factory to locate those objects in JNDI. Both elements require two attributes: jndi-server-name and jndi-name. Common jndi-name values are java:comp/UserTransaction for the UserTransaction and java:comp/TransactionManager for the TransactionManager — see the commented-out example already in entityengine.xml for the exact syntax.

Delegator Elements


The GenericDelagator is created through a factory method that takes a String argument containing the delegator name. This delegator name is used to look up a delegator tag in the entityengine.xml file.

Attribute NameRequired?Description
nameYThe name of the Delegator.
entity-model-readerYThe entity-model-reader to use.
entity-group-readerYThe entity-group-reader to use.
entity-eca-readerNThe entity-eca-reader to use. If not specified, no Entity ECAs will be used.
entity-eca-enabledNWhether Entity ECAs are enabled. Defaults to true.
entity-eca-handler-class-nameNThe ECA handler implementation. Defaults to org.apache.ofbiz.entityext.eca.DelegatorEcaHandler.
distributed-cache-clear-enabledNWhether distributed cache clear is enabled. Defaults to false.
distributed-cache-clear-class-nameNThe class implementing the distributed cache clear interface. Defaults to org.apache.ofbiz.entityext.cache.EntityCacheServices, which uses the Service Engine for remote calls.
distributed-cache-clear-user-login-idNThe userLoginId used for security checks on distributed cache clear operations. Defaults to system. (The old wiki said this defaults to admin — it doesn't.)
sequenced-id-prefixNAn optional prefix prepended to sequenced (auto-generated) IDs created through this delegator.
default-group-nameNThe entity group name assumed when an entity isn't explicitly mapped elsewhere. Defaults to org.apache.ofbiz.
key-encrypting-keyNAn optional key used for encrypting sensitive entity field values.

 The delegator tag must contain one or more group-map tags specifying a datasource to use for each group of entities that the delegator will know about from the entity-group-reader. The delegator uses this file to assign a group to each entity. When an operation on an entity is performed it looks up the group and the datasource helper that corresponds to the group and uses that Helper to perform lower level Data Source operations. With this technique when the application is written it does not have to know which Helper is responsible for a given entity, and can therefore handle an entity or groups of entities assigned to different Data Sources with a simple configuration.

Entity Model XML Files


The entity-model-reader tag is used to configure each named entity model reader. The tag has a name attribute used to specify the entity model reader's name. Each reader may load from multiple resources that are each specified with a resource tag inside the main tag.

Each resource tag has two required attributes: loader which specifies which resource-loader to use and location which specifies the location that the resource-loader will use inside itself to load the resource.

Entity Group XML Files


The entity-group-reader tag is used to configure each named entity group reader. The tag has a name attribute used to specify the entity group reader's name. The group reader uses XML files to get the entity-group mappings.

The tag has two optional attributes: loader which specifies which resource-loader to use and location which specifies the location that the resource-loader will use inside itself to load the resource. There is also a sub-element named "resource" that has these same attributes and can be used to specify addition resources for addition files.

Entity ECA XML Files


The entity-eca-reader tag is used to configure each named entity ECA reader. The tag has a name attribute used to specify the entity ECA reader's name. The ECA reader uses XML files to get the entity ECA rule definitions. Each reader may load from multiple resources that are each specified with a resource tag inside the main tag.

Each resource tag has two required attributes: loader which specifies which resource-loader to use and location which specifies the location that the resource-loader will use inside itself to load the resource.

Field Type XML Files


The field-type tag is used to configure each named field type. The tag has a name attribute used to specify the field type's name. The group reader uses a single XML file to get the field type information.

The tag has two required attributes: loader which specifies which resource-loader to use and location which specifies the location that the resource-loader will use inside itself to load the resource.

Data Source Elements


Many datasources can be configured using one datasource tag for each datasource. This tag has the following attributes, and may contain the following sub-elements:

AttributeRequired?Type/ValuesDefaultDescription
nameYstring—The name of the datasource.
helper-classYstring—The datasource helper implementation. The JDBC/DAO helper is org.apache.ofbiz.entity.datasource.GenericHelperDAO.
field-type-nameYstring—Must match the name of an existing field-type definition.
use-schemasNbooleantrueWhether to use/qualify by schema name.
schema-nameNstring—The schema to use in the database. Case-sensitive; not all databases behave the same way.
check-on-startNbooleantrueCheck the datasource on startup.
add-missing-on-startNbooleanfalseAdd missing entities/fields to the datasource on startup when checking is done.
check-pks-on-startNbooleantrueCheck primary keys at startup and add missing as needed.
use-pk-constraint-namesNbooleantrueUse constraint names for primary keys. Some databases have trouble with this.
constraint-name-clip-lengthNnon-negative integer30Max length a constraint name is clipped to. Watch for duplicate names if you change this.
use-proxy-cursorNbooleanfalseUse a named proxy cursor for result sets (mainly relevant to Postgres).
proxy-cursor-nameNstringp_cursorName to use for the proxy cursor, if enabled.
result-fetch-sizeNinteger-1JDBC result set fetch size hint.
use-foreign-keysNbooleantrueUse/create foreign keys for "one" relationships.
use-foreign-key-indicesNbooleantrueUse/create indices on foreign key columns.
check-fks-on-startNbooleanfalseCheck foreign keys at startup and add missing as needed. Some databases don't return a full FK list, which can cause duplicate FKs to be added.
check-fk-indices-on-startNbooleanfalseCheck foreign key indices at startup and add missing as needed.
fk-styleNname_constraint | name_fkname_constraintForeign key naming syntax style. Most databases use name_constraint.
use-fk-initially-deferredNbooleanfalseWhether to use INITIALLY DEFERRED for foreign keys where supported. (The old wiki said this defaults to true — it doesn't.)
use-indicesNbooleantrueCreate manually declared indices.
use-indices-uniqueNbooleantrueUse a unique constraint for manually declared indices, where used.
check-indices-on-startNbooleanfalseCheck indices at startup and add missing declared ones. Not all JDBC drivers support this metadata check well.
join-styleNansi | ansi-no-parenthesis | theta-oracle | theta-mssqlansiTable join syntax for view-entity operations.
alias-view-columnsNbooleanfalseCompensates for JDBC drivers returning the full alias expression instead of just the alias name in view-entity results. (The old wiki said this defaults to true — it doesn't.)
always-use-constraint-keywordNbooleanfalseAlways emit the CONSTRAINT keyword when creating constraints.
drop-fk-use-foreign-key-keywordNbooleanfalseUse the FOREIGN KEY keyword when dropping foreign keys.
use-binary-type-for-blobNbooleanfalseUse a binary column type instead of BLOB.
use-order-by-nullsNbooleanfalseEmit NULLS FIRST/NULLS LAST in ORDER BY clauses where supported.
offset-styleNnone | fetch | limitnonePagination style used for offset-based queries.
table-typeNstring—Storage engine to use, e.g. InnoDB for MySQL.
character-setNstring—Database/table character set, e.g. utf8.
collateNstring—Database/table collation.
max-worker-pool-sizeNinteger1Max size of the worker pool used for datasource maintenance tasks.
Sub-Element NameHow ManyDescription
sql-load-path0 to manySpecifies a list of full paths to directories that will be searched for XML and SQL files to import into the data source by the install page in the WebTools webapp. Each tag has two attributes: path for the path location, and prepend-env to optionally specify a Java environment property to prepend to the specified path.
read-data0 to manySpecifies a named data reader (e.g. seed, demo, ext) that this datasource should load data from on install. Has one required attribute, reader-name.
inline-jdbcexactly 1 of 3†Specifies the JDBC parameters to be used by the connection pool.
jndi-jdbcexactly 1 of 3†Specifies the jndi-server-name and jndi-name to get a Connection or XAConnection from JNDI.
tyrex-dataSourceexactly 1 of 3†A legacy alternative to inline-jdbc/jndi-jdbc using the Tyrex connection/transaction library. Rarely used in current setups — inline-jdbc with the DBCP-backed connection pool is the standard choice today.
ANY—Removed: the schema previously allowed an arbitrary xs:any child element here for custom GenericHelper implementations, but that extension point is commented out in the current schema and is not currently a valid child of datasource.


The inline-jdbc tag has the following attributes:

AttributeRequired?DefaultDescription
jdbc-driverY—The JDBC driver class for the database.
jdbc-uriY—The JDBC connection URI.
jdbc-usernameY—The database username.
jdbc-passwordN—The plaintext password. (The old wiki marked this required — it isn't, since...)
jdbc-password-lookupN—...you can use this instead: a lookup key resolved against framework/base/config/passwords.properties, which supports encrypted (ENC(...)) values. Preferred for production — see Secrets & Master Key Management in the Technical Production Setup Guide.
isolation-levelN—Standard JDBC transaction isolation level: None, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable. (The old wiki said this is "used by Tyrex" — it isn't; it's a plain JDBC/DBCP connection setting.)
pool-minsizeN2Minimum pooled connections.
pool-maxsizeN50Maximum pooled connections.
idle-maxsizeN50% of pool-maxsizeMax idle connections retained in the pool.
time-between-eviction-runs-millisN600000Milliseconds between idle-connection eviction runs.

 A number of additional pool-tuning attributes exist and are genuinely functional — verified directly against DBCPConnectionFactory, not just the schema comments: pool-jdbc-test-stmt (sets the connection validation query), test-on-create/test-on-borrow/test-on-return/test-while-idle (when to run that validation query), and soft-min-evictable-idle-time-millis (minimum idle time before a connection is eligible for eviction). Note that despite its name, pool-sleeptime doesn't control a sleep interval — it's actually wired to the pool's max-wait time (how long to wait for a connection before giving up when the pool is exhausted).

By contrast, pool-lifetime, pool-deadlock-maxwait, pool-deadlock-retrywait, and pool-xa-wrapper-class are explicitly documented in the schema itself as "currently not implemented" — confirmed accurate by checking the actual connection factory code, which never reads them. Don't bother configuring these.

The jndi-jdbc tag has the following attributes:

Attribute NameRequired?Description
jndi-server-nameYThe name of the JNDI server to use, as configured in ${ofbiz install dir}/framework/base/config/jndiservers.xml — a separate file, not part of entityengine.xml.
jndi-nameYThe name of the Connection or XAConnection object in JNDI.
isolation-levelNStandard JDBC transaction isolation level: None, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable.


The data source retrieved from JNDI should be pooled and transactional, with connections already enlisted if a JTA transaction has been started. It can be either a DataSource or an XADataSource object.

The connection factory implementation used for inline-jdbc datasources is configured separately via the top-level <connection-factory> element in entityengine.xml, which defaults to org.apache.ofbiz.entity.connection.DBCPConnectionFactory (Apache Commons DBCP). There is no automatic runtime fallback chain today — the connection factory class is explicitly declared, not selected dynamically based on what's available.


  • No labels