DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Related Documents
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 Name | Required? | Description |
|---|---|---|
| name | Y | The name of the resource loader. Used in other tags in the "loader" attribute. |
| class | Y | The 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-env | N | The name of a Java environment property to put at the very beginning of the full location, before the prefix. This is optional. |
| prefix | N | A 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 Name | Required? | Description |
|---|---|---|
| name | Y | The name of the Delegator. |
| entity-model-reader | Y | The entity-model-reader to use. |
| entity-group-reader | Y | The entity-group-reader to use. |
| entity-eca-reader | N | The entity-eca-reader to use. If not specified, no Entity ECAs will be used. |
| entity-eca-enabled | N | Whether Entity ECAs are enabled. Defaults to true. |
| entity-eca-handler-class-name | N | The ECA handler implementation. Defaults to org.apache.ofbiz.entityext.eca.DelegatorEcaHandler. |
| distributed-cache-clear-enabled | N | Whether distributed cache clear is enabled. Defaults to false. |
| distributed-cache-clear-class-name | N | The 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-id | N | The 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-prefix | N | An optional prefix prepended to sequenced (auto-generated) IDs created through this delegator. |
| default-group-name | N | The entity group name assumed when an entity isn't explicitly mapped elsewhere. Defaults to org.apache.ofbiz. |
| key-encrypting-key | N | An 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:
| Attribute | Required? | Type/Values | Default | Description |
|---|---|---|---|---|
| name | Y | string | — | The name of the datasource. |
| helper-class | Y | string | — | The datasource helper implementation. The JDBC/DAO helper is org.apache.ofbiz.entity.datasource.GenericHelperDAO. |
| field-type-name | Y | string | — | Must match the name of an existing field-type definition. |
| use-schemas | N | boolean | true | Whether to use/qualify by schema name. |
| schema-name | N | string | — | The schema to use in the database. Case-sensitive; not all databases behave the same way. |
| check-on-start | N | boolean | true | Check the datasource on startup. |
| add-missing-on-start | N | boolean | false | Add missing entities/fields to the datasource on startup when checking is done. |
| check-pks-on-start | N | boolean | true | Check primary keys at startup and add missing as needed. |
| use-pk-constraint-names | N | boolean | true | Use constraint names for primary keys. Some databases have trouble with this. |
| constraint-name-clip-length | N | non-negative integer | 30 | Max length a constraint name is clipped to. Watch for duplicate names if you change this. |
| use-proxy-cursor | N | boolean | false | Use a named proxy cursor for result sets (mainly relevant to Postgres). |
| proxy-cursor-name | N | string | p_cursor | Name to use for the proxy cursor, if enabled. |
| result-fetch-size | N | integer | -1 | JDBC result set fetch size hint. |
| use-foreign-keys | N | boolean | true | Use/create foreign keys for "one" relationships. |
| use-foreign-key-indices | N | boolean | true | Use/create indices on foreign key columns. |
| check-fks-on-start | N | boolean | false | Check 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-start | N | boolean | false | Check foreign key indices at startup and add missing as needed. |
| fk-style | N | name_constraint | name_fk | name_constraint | Foreign key naming syntax style. Most databases use name_constraint. |
| use-fk-initially-deferred | N | boolean | false | Whether to use INITIALLY DEFERRED for foreign keys where supported. (The old wiki said this defaults to true — it doesn't.) |
| use-indices | N | boolean | true | Create manually declared indices. |
| use-indices-unique | N | boolean | true | Use a unique constraint for manually declared indices, where used. |
| check-indices-on-start | N | boolean | false | Check indices at startup and add missing declared ones. Not all JDBC drivers support this metadata check well. |
| join-style | N | ansi | ansi-no-parenthesis | theta-oracle | theta-mssql | ansi | Table join syntax for view-entity operations. |
| alias-view-columns | N | boolean | false | Compensates 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-keyword | N | boolean | false | Always emit the CONSTRAINT keyword when creating constraints. |
| drop-fk-use-foreign-key-keyword | N | boolean | false | Use the FOREIGN KEY keyword when dropping foreign keys. |
| use-binary-type-for-blob | N | boolean | false | Use a binary column type instead of BLOB. |
| use-order-by-nulls | N | boolean | false | Emit NULLS FIRST/NULLS LAST in ORDER BY clauses where supported. |
| offset-style | N | none | fetch | limit | none | Pagination style used for offset-based queries. |
| table-type | N | string | — | Storage engine to use, e.g. InnoDB for MySQL. |
| character-set | N | string | — | Database/table character set, e.g. utf8. |
| collate | N | string | — | Database/table collation. |
| max-worker-pool-size | N | integer | 1 | Max size of the worker pool used for datasource maintenance tasks. |
| Sub-Element Name | How Many | Description |
|---|---|---|
| sql-load-path | 0 to many | Specifies 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-data | 0 to many | Specifies 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-jdbc | exactly 1 of 3† | Specifies the JDBC parameters to be used by the connection pool. |
| jndi-jdbc | exactly 1 of 3† | Specifies the jndi-server-name and jndi-name to get a Connection or XAConnection from JNDI. |
| tyrex-dataSource | exactly 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:
| Attribute | Required? | Default | Description |
|---|---|---|---|
| jdbc-driver | Y | — | The JDBC driver class for the database. |
| jdbc-uri | Y | — | The JDBC connection URI. |
| jdbc-username | Y | — | The database username. |
| jdbc-password | N | — | The plaintext password. (The old wiki marked this required — it isn't, since...) |
| jdbc-password-lookup | N | — | ...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-level | N | — | 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-minsize | N | 2 | Minimum pooled connections. |
| pool-maxsize | N | 50 | Maximum pooled connections. |
| idle-maxsize | N | 50% of pool-maxsize | Max idle connections retained in the pool. |
| time-between-eviction-runs-millis | N | 600000 | Milliseconds 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 Name | Required? | Description |
|---|---|---|
| jndi-server-name | Y | The 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-name | Y | The name of the Connection or XAConnection object in JNDI. |
| isolation-level | N | Standard 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.